This repository is a mirror of the primary repository hosted on GitLab: https://gitlab.com/printspots/printspots. All development and contributions happen on the GitLab repository. Please submit issues and pull requests there.
PrintSpots is an open-source toolkit for creating multi-layered 3D-printed grayscale images. It enables makers, designers, and researchers to turn standard images into printable 3MF objects, calibrated for grayscale and color 3D printing.
👉 Learn more at printspots.org
- 🎨 Convert images into 3D-printable grayscale models
- �️ Alpha channel support - Use transparent images to create non-rectangular prints
- �🖤 Generate grayscale calibration patterns for printer tuning
- ⚙️ Flexible command-line interface with interactive configuration wizard
- 🔧 Cross-platform configuration management
- 📦 Distributed as binaries for easy installation (source release coming soon)
- 🖨️ Output in 3MF format, ready for slicing and printing
Prebuilt binaries will be available soon in the Releases section of this repository. Download the version for your platform and run it.
Example (Linux/macOS):
chmod +x printspots
printspots --helpBefore creating any prints, configure PrintSpots with your printer's specifications:
printspots configureThis interactive wizard will guide you through setting up:
- Base thickness: The thickness of the base layer (typically 1.0mm)
- Layer thickness: Your printer's minimal layer height (e.g., 0.05mm).
- Image size: Default size for the larger dimension of generated images (e.g., 100mm)
- Maximum layers: Maximum number of layers to stack (e.g., 19)
The configuration is saved and will be used as defaults for all subsequent commands. You can re-run configure anytime to update your settings.
Note: Other commands will work with built-in defaults even without configuration, but that is for testing purposes only. the results in real life will not match.
Create a calibration object to tune printspots to your printer and filament for accurate grayscale objects:
printspots calibrationThis generates calibration.3mf with test squares at varying thickness levels.
Printing the calibration:
- Open
calibration.3mfin your slicer - Set layer-height to the same as in Printspots configuration and infill to 100%.
- The object contains two parts:
- Bottom part: Print in black filament
- Top part: Print in white filament
- Slice and print the calibration object
After printing the calibration pattern:
-
scan the printed calibration:
-
if you do not have flatbed scanner, Photograph it
- Use a white paper background for proper white balance
- Ensure even lighting
- Photograph from directly above
-
Crop the image to include only the calibration squares
-
Generate palette file:
- Go to the Palette Generator Tool
- Upload your cropped calibration photo
- Align the image so that:
- The darkest square is labeled 1
- Squares get progressively lighter as numbers increase
- Use flip/rotate tools as needed
- Download the generated palette file
-
Edit the palette file:
- Open the downloaded
.tomlpalette file in a text editor - Remove duplicate entries where colors are basically the same
- Keep only distinct grayscale levels
Note: Automatic cutoff will be added to the web tool in a future update.
- Open the downloaded
Convert your image into a 3D-printable greyscale object:
printspots generate \
--input your-input-image.jpg \
--palette palette.toml \
--output result.3mfReview the preview:
- A
prediction.pngfile is generated in the current directory - Review this preview to see how your image will look
- If the result doesn't look good:
- Try a different source image or
- Adjust the contrast and brightness of your original image
- Re-run the generate command
Print your object:
- Open the output file (e.g.,
result.3mforout.3mf) in your slicer - The object contains parts named "black" and "white"
- Assign filament colors accordingly:
- black part → black filament
- white part → white filament
- Do not forget to set the same layer-height as for Printspots configuration
- Use 100% infill or enouth top/bottom layers so the object is printed solid
- Slice and print!
Set up your printer configuration interactively.
printspots configureGenerate a calibration pattern for printer tuning.
printspots calibration [OPTIONS]
Options:
-s, --size <SIZE> Size of single square in mm [default: 10]
--flat-top Create calibration with flat top
-f, --filename <FILE> Output filename [default: calibration.3mf]Convert an image to a 3D halftone object.
printspots generate [OPTIONS] --input <IMAGE> --palette <PALETTE> --output <OUTPUT>
Options:
-i, --input <IMAGE> Input image file (supports PNG, JPG, etc.)
-s, --size <SIZE> Size in mm (larger dimension) [default: 100]
--flat-top Create output with flat top
-p, --palette <PALETTE> Path to palette file (.toml)
-o, --output <OUTPUT> Output 3MF filenameAlpha Channel Support:
- Images with alpha channels (transparency) are fully supported
- Transparent pixels (alpha < 128) are automatically excluded from the mesh
- This allows creating non-rectangular prints that follow the shape of your image
- Works in both CLI and GUI
PrintSpots stores configuration in a platform-specific location:
- Linux/macOS:
~/.config/printspots/config.json - Windows:
%APPDATA%\printspots\config.json
You can manually edit this file if needed, though using printspots configure is recommended.
For more information and examples, visit printspots.org.
Full documentation coming soon.
- ✅ Interactive configuration wizard
- ✅ Website
- ✅ Binary releases
- ✅ Automatic palette optimization in web tool
- 🔜 Comprehensive documentation
- ✅ Open-source release of the full codebase
- ✅ GUI application
- 🔜 Additional calibration utilities
- 🔜 inform user about progress of the process
Q: The preview looks wrong or pixelated
- Try adjusting the contrast and brightness of your source image
- Use a higher resolution source image
- Ensure your source image has good tonal range
Q: Calibration squares look the same
- Check your printer's layer height settings
- Verify base and layer thickness in your configuration
- Ensure proper filament contrast (pure black and pure white work best)
Q: Output file parts aren't labeled
- Open in a slicer that supports 3MF part names (PrusaSlicer, OrcaSlicer, etc.)
- Check that you're using the latest version of PrintSpots
MIT
Contributions, bug reports, and feature requests are welcome! Please check back after the source code release for contribution guidelines.
- 🌐 Website: printspots.org
- 🐛 Issues: GitLab Issues
Made with ❤️ for the 3D printing community