colorplate 0.5.0

Turn SVG/PNG artwork into layered, gap-free multicolor STL plates for face-down multi-material 3D printing.

Turn SVG/PNG artwork into layered, gap-free multicolor STL plates for face-down multi-material 3D printing (toolchanger / MMU).

🌐 Live demo  ·  ⚡ Quick start  ·  🖥️ Web GUI  ·  🛠️ How it works

---

It does what you'd otherwise do by hand in CAD: separate the artwork into its colors, tile them so they share one plane with no overlaps or gaps, extrude a thin colored front shell (the show face that prints against the bed), and stack a single-color backing plate behind it so the back is one clean color.

✨ What you get

• Color separation, done right — every silhouette pixel is assigned to its nearest palette color, so the regions tile with no gaps or overlaps.
• Watertight STLs — one clean, manifold mesh per filament color, plus an optional single-color backing plate so the back of the print is uniform.
• Two ways to drive it — a scriptable CLI and a live browser GUI, both on the same pipeline (no mocks, what you preview is what you print).
• Slicer-ready output — shared origin across all plates, a flat-color preview PNG, and a manifest mapping each color → file → RGB for toolhead assignment.

📸 Screenshots

Drop a logo — colors are detected, each maps to a filament, and the preview is painted with your real assigned colors.

Export — one watertight STL per color, plus the backing plate, as a .zip.	Dark mode, because of course.

⚡ Quick start

pip install colorplate                 # the CLI
pip install "colorplate[auto]"         # + auto color detection for rasters (scikit-learn)
pip install "colorplate[web]"          # + the colorplate-web browser GUI

From source (for development)

git clone https://github.com/kurenn/colorplate && cd colorplate
pip install -e ".[web]"

Requires a working cairosvg (for SVG input) which needs Cairo system libs.

# SVG: palette auto-detected from the file's fills/strokes
colorplate logo.svg -o out/ --height 180 --backing-color c0

# Explicit, named palette (recommended for clean toolhead mapping)
colorplate logo.svg -o out/ --height 180 \
  --palette "dark=#231F1D,rim=#F9CF26,white=#FEFEFE,red=#ED4324" \
  --backing-color dark

# Raster with no known palette: quantize to N colors
colorplate art.png -o out/ --colors 4 --backing-color c0

# Single extruder (no MMU): one terraced STL + a filament-swap schedule
colorplate logo.svg -o out/ --height 180 \
  --palette "dark=#231F1D,gold=#F9CF26,red=#ED4324,white=#FEFEFE" \
  --single-extruder --step 0.6

Key options

flag	meaning	default
--height	longest in-plane dimension (mm)	180
--front	colored front-shell thickness (mm)	1.0
--back	backing thickness (mm)	2.0
--backing-color	color name for the single-color back (omit = no backing)	none
--palette	name=#hex,...; omit to auto-detect	auto
--colors	target colors when quantizing a raster	4
--nozzle	nozzle line width (mm); warns about thinner features	0.4
--fill-holes	fill enclosed blank areas (e.g. letter interiors) into the design	off
--single-extruder	stack colors by height into one terraced STL + swap schedule	off
--base / --step	base-plate / per-color band height for single-extruder (mm)	0.8 / 0.6
--layer-height	layer height that filament swaps snap to (mm)	0.2

Single extruder (no MMU)

Don't have a toolchanger or MMU? A single nozzle can only print one filament per layer, so --single-extruder stacks the colors by height into one terraced relief: a full base plate in the first palette color, then each subsequent color raised one --step higher (palette order is base → top). You get one STL plus a *_swaps.txt schedule telling you which layer to insert a filament change (M600) at — printable on any single-extruder machine.

  layer 1    z 0.00mm  start  #231F1D
  layer 5    z 0.80mm  swap   #F9CF26
  layer 8    z 1.40mm  swap   #ED4324
  layer 11   z 2.00mm  swap   #F4F4F4

🖥️ Web GUI

A browser front end (the ColorPlate design) drives the same pipeline: drop a logo, see its colors detected, map each to a filament, set size/thickness/backing, preview the recolored art live, and download the generated STLs as a .zip.

pip install "colorplate[web]"
colorplate-web                 # opens http://127.0.0.1:8000 in your browser
# colorplate-web --port 9000 --no-browser

Try it without installing anything: colorplate.spoolr.io

What it does (all real, no mocks):

• Detect — quantizes the rasterized silhouette to up to N colors (the "Max colors" selector), consolidating antialiasing fringes and folding sub-printable slivers into their nearest neighbor, so every region shown is actually printable. Each detected region is pre-mapped to its nearest filament preset.
• Preview — the right panel shows your real artwork recolored with the assigned filaments; it's built from the exact masks used for meshing, so what you see is what the STLs contain. Flip to the 3D view to rotate the actual layered plates (front shells + backing) — the same geometry that gets exported.
• Printability — flags colors with features thinner than your nozzle line width at the chosen size (set the nozzle, default 0.4 mm), highlights the at-risk areas right on the 2D preview, and offers a one-click "bump size" to fix them.
• Fill enclosed areas — for logos where blank spaces inside the design (letter interiors, the holes in an outlined mark) match the background, tick this to fold them into the silhouette so they become paintable colors instead of empty gaps.
• Generate — one watertight STL per distinct assigned filament (regions sharing a filament are merged), plus an optional single-color backing plate, a flat-color preview PNG, and a manifest — bundled into a downloadable .zip.
• Single extruder — flip the Printer toggle to Single extruder to stack the colors into a terraced relief instead (same as the CLI's --single-extruder): reorder the base→top stack, see it restack live in 3D, and export one terraced STL plus the filament-swap schedule.

Endpoints live under /api/*; the static UI is plain React-via-Babel (no build step). Tiny detail: auto-detection is quantization-based, so a very small distinct color may merge into a neighbor — bump "Max colors", or use the CLI's --palette for an exact named palette.

☁️ Deploy (Render)

The GUI + API ship as one container (Dockerfile), with a Render Blueprint (render.yaml). Render runs a live Python process, so the whole app deploys as a single web service — no static/host split, no CORS.

1. Push this repo to GitHub.
2. In Render: New ► Blueprint, pick the repo. It reads render.yaml, builds the Dockerfile, and injects $PORT (the app binds 0.0.0.0:$PORT automatically).
3. Open the service URL.

Run the same image anywhere a container runs (Fly.io, Cloud Run, a VM):

docker build -t colorplate .
docker run -p 8000:8000 colorplate          # http://localhost:8000

Notes: the free plan (512 MB, sleeps when idle) is fine for typical logos; very large rasters or many colors want more RAM (bump to a paid plan). Upload sessions are held in memory on a single instance, so keep it to one instance (don't scale out).

📦 Output

Per run you get, in the output directory:

• *_<color>.stl — one watertight plate per color (front shell, z 0..front)
• *_backing.stl — single-color backing (z front..front+back)
• *_preview.png — flat-color preview of the show face
• *_manifest.json — color → file → RGB map, for assigning toolheads

All STLs share one origin, so in the slicer: load them together, Assemble into one object, assign each part a filament, and print face-down.

🛠️ How it works

RasterLoader   SVG -> rasterize (transparent bg) | PNG -> load + bg detect
     |         => RGBA array + silhouette mask
Classifier     assign EVERY silhouette pixel to its nearest palette color
     |         => per-color masks that tile with no gaps/overlaps
MeshBuilder    each mask -> contours (with holes) -> extruded watertight mesh
     |         scaled px -> mm, at a given thickness + Z offset
PlatePipeline  front shells at z0; backing = full silhouette behind; write files

Each stage is a single-responsibility class (raster.py, classify.py, mesh.py, pipeline.py) so pieces can be swapped or tested in isolation.

🧪 Development

pip install -e ".[web,test,auto]"
pytest

The suite covers the pipeline (raster → detect → classify → mesh → generate), the CLI, the web service + HTTP API, the live 3D-preview geometry, and analytics. CI runs it on every push and pull request across Python 3.10 & 3.12.

📝 Notes

• Thin features (e.g. web strands) must be wider than your nozzle line width at the chosen --height. ColorPlate checks this for you — the GUI flags at-risk colors and highlights them on the preview (with a one-click "bump size"), and the CLI prints a warning per color (tune the nozzle with --nozzle).
• The front shell must be opaque enough that the backing color doesn't ghost through; ~1.0 mm (5 layers @ 0.2 mm) is usually fine, bump --front if not.
• Source artwork should use filled color regions. If your design has blank spaces enclosed by the outline (letter interiors, an outlined mark) that match the background, turn on Fill enclosed areas (--fill-holes) to make them paintable instead of empty gaps.

📫 Contact

Questions, bugs, or ideas? Open an issue on GitHub or email [e-mail].

License

MIT © Abraham Kuri