Lithop

Create backlit color lithophanes locally.

Lithop is a local CMYW color lithophane generator with a CLI and browser UI. It turns a JPEG, PNG, or validated self-contained SVG image into a single-plate multipart CMYW 3MF and a White reference STL without uploading the source image or copying it into the output job.

CMYW lithophane preview generated from the bundled color chart. This is the pre-print preview, not a photograph of a physical print.

The standard profile uses:

Bambu Studio restores the generated single lithophane plate and its White/Cyan/Magenta/Yellow assignments. The bundled fine-line target has been printed successfully with the current 0.2 mm, seven-layer standard. The current 140 × 104 mm color chart has been sliced and inspected in Bambu Studio, but it has not been physically printed with the 0.2 mm standard; its 120 recipes and eight White thickness stages have not been measured numerically. Colorimetric accuracy is not guaranteed.

Before printing, inspect every layer and confirm the Cyan, Magenta, Yellow, and White assignments. Do not move, align, scale, or merge individual material parts. Lithop does not slice models, send print jobs, or control a printer or AMS.

• macOS, Ruby 4.0 or later, and Rust. CI verifies macOS with Ruby 4.0; the current measured build is Apple silicon.
• libvips with JPEG, PNG, SVG (librsvg), and ICC profile support
• For physical printing: Bambu Studio, an AMS-capable printer, and the required PLA Basic Cyan, Magenta, Yellow, and White filaments

To install Lithop 0.3.0 from RubyGems, install libvips, Rust for the native palette extension, and the matching Lithop version:

brew install vips rust
gem install lithop -v 0.3.0
lithop --version
lithop doctor

The version command must print 0.3.0. The doctor command reports "backend": "rust" and the loaded native-extension version. Set LITHOP_DISABLE_NATIVE=1 only when comparing the Ruby fallback.

To work from a source checkout instead:

bin/setup
bundle exec lithop --version

With an installed gem, generate a model from one JPEG, PNG, or SVG:

lithop path/to/image.png

From a source checkout, use the bundled sample and a coarse cell size for a faster first run:

bundle exec lithop examples/cmy-fine-line.svg --width 20 --height 15 --pixel-size 0.5

To use the local browser UI, start its loopback-only server and open the displayed URL:

lithop ui

The UI separates creation, jobs, and reusable presets into responsive panes, with drag-and-drop image selection, grouped settings, an engine-rendered input preview, persistent job progress and cancellation, side-by-side result views, and per-job artifact management. Sinatra, ERB, Puma, CSS, and JavaScript are included in the gem, so the workflow remains local and works offline after installation. Playwright is used only for source-checkout browser tests. See local browser UI.

The standard command generates the 140 × 104 × 2.14689422 mm, 0.2 mm-nozzle layout:

bundle exec lithop path/to/image.jpeg

It writes lithop.3mf with a single lithophane plate and White/Cyan/Magenta/Yellow extruders. Its layer preview and physical print still require manual verification.

Use --brightness, --contrast, and --saturation with percentages from -100 to 100 to adjust the shared sRGB input before White thickness and CMYW recipes are sampled. The resolved values are recorded in each job's settings.json.

Use --tile-count N with --tile-layout auto, columns, rows, or grid to emit exactly N local-origin 3MF tiles. Tiled jobs include assembled offsets and bounds in manifest.json plus a physical-size tile-layout.svg placement guide.

Add --separate-z-parts to place three closed CMYW color-region bands and Top White on four Bambu Studio plates inside every generated 3MF. Each color-region plate includes its own Base White carrier, and every plate is translated to start at Z=0 for independent printing; manifest.json retains the original assembly order and Z bounds.

The command reports estimated and final triangle counts and creates a new build/<job_id>/ directory. Completed jobs are never overwritten. Inspect preview.png, transmission.png, thickness.png, and the four material masks, then import lithop.3mf into Bambu Studio as a model. The 3MF contains geometry, fixed extruder numbers, and layer-height metadata. It does not select a printer, physical build plate, AMS slot, or complete slicing preset.

The bundled color chart at standard settings produces 2,660,706 CMYW 3MF triangles, below the default 5,000,000-triangle limit. Runtime and memory depend on the image and machine; use a smaller model and a coarser cell size for initial checks.

See installation and basic use, the artifact reference, and the Bambu Studio checklist before printing.

JPEG and PNG input supports EXIF orientation, transparency composited over White, and embedded ICC conversion to sRGB. SVG input is rendered in memory through librsvg and must be an uncompressed, static, self-contained document no larger than 15,000,000 bytes. External files, network URLs, data URLs, external CSS, DTDs, scripts, animation, and foreignObject are rejected.

Settings resolve in command line > JSON file > built-in defaults order. A project can keep reusable overrides in config/settings.json:

{
  "layout_profile": "standard",
  "width": 140.0,
  "height": 104.0
}

The command-line options can override individual profile values. Use --color-pixel-size to make CMYW recipe cells coarser than the White thickness grid, and --image-fit, crop, and margin options to control placement. See options and settings for the complete input schema and validation rules.

• lithop calibrate creates a 140 × 104 mm calibration SVG and matching printable 3MF with all 120 seven-layer recipes, eight White thickness stages, and a measurement-profile template. A completed measured profile can select both color recipes and the physical White height used by the 3MF, STL, previews, thickness map, and material masks. See color calibration.
• lithop ui starts the local browser UI on 127.0.0.1:4567; on macOS, completed 3MF artifacts can be handed directly to Bambu Studio from the Jobs view. See local browser UI.
• lithop doctor reports whether the Rust acceleration extension is loaded, enabled, and version-matched.
• lithop clean permanently removes the selected project's complete build/ directory, not one job. See the command reference before using it.
• lithop --help, lithop calibrate --help, lithop ui --help, and lithop clean --help show the current command syntax.

• Documentation index and verification status
• Installation and basic use
• Local browser UI
• Bambu Studio verification and printing
• Options and settings
• Artifacts and generation records
• CMYW color model and layer structure
• Optional measured calibration
• Command reference
• Troubleshooting

The RubyGem and CLI command are named lithop; the Ruby namespace is Lithop. Supported public signatures are declared in sig/lithop.rbs. Helper classes under lib/lithop/export/, lib/lithop/cli/, and lib/lithop/formats/three_mf/ are internal unless listed there.

bin/setup
bundle exec rake
bundle exec rbs validate

Before publishing, run bundle exec rake release:check and follow RELEASING.md.

MIT