<img align="left" height="125" width="125" src="./content/logo.png">

Kromacut

Open-source HueForge-style tool for converting images into stacked, color-layered 3D prints.

Kromacut is a browser-first app that converts images into multi-color lithophane 3D prints. It offers two powerful workflows:

Auto-paint mode — Define your actual filaments (color + Transmission Distance), and Kromacut automatically computes optimal layer stacks using physically accurate Beer-Lambert optical blending. Features include a calibration wizard, advanced optimizer (simulated annealing/genetic algorithms), and region weighting for spatial priority.

Manual mode — Reduce images to a small palette, manually tweak per-color layer heights and ordering, and fine-tune every aspect of the stack with complete control.

Both modes include live 2D/3D previews, layer-by-layer visualization, and export to STL/3MF with detailed print instructions.

Examples

A quick look at what Kromacut produces from a source image to a printable model:

• Fuji test image (2D input) → 3D preview → per-color sliced view → real print

| 2D Input | 3D Preview | |---|---| | <img src="content/fuji2d_new.png" alt="Fuji 2D Input" width="600" /> | <img src="content/fuji3d_new.png" alt="Fuji 3D Preview" width="600" /> | | Sliced by Colors | Real Print | | <img src="content/fuji3dsliced.png" alt="Fuji Sliced" width="600" /> | <img src="content/printed.jpg" alt="Printed Result" width="600" /> |

Another minimal test you can try yourself in the app header: the Transmission Distance (TD) test image.

| TD Test | |---| | <img src="src/assets/tdTest.png" alt="TD Test Image" width="600" /> |

Notable Features

• Image upload and preview (drag & drop or file picker).
• Color reduction / quantization with selectable color count.
• Inline color pickers to tweak or replace generated palette colors.
• Per-color slice heights and a configurable base slice height.
• Reorder colors with drag-and-drop to control stack order (darkest → lightest default ordering).
• Live 2D preview and a 3D stacked preview rendered with three.js.
• Layer-by-layer preview slider — Interactively visualize how the print builds up by dragging a slider to show/hide layers at specific heights.
• 3D model export to binary STL or 3MF (Preview) suitable for multi-material slicers.
• Plain-text 3D print instructions that describe layer heights and exact layers where filament swaps are required.
• Copy-to-clipboard button for the print instructions (produces a clean, copyable plain-text plan).
• Filament calibration wizard — Accurately determine Transmission Distance (TD) values through measured samples with confidence scoring.
• Advanced optimizer — Simulated annealing and genetic algorithms find optimal filament ordering for complex multi-color prints.
• Region weighting — Prioritize accuracy in specific image areas (center, edges) during auto-paint optimization.

Notable implementation details

• Frontend: React + TypeScript + Vite.
• 3D Rendering: three.js with BufferGeometry. The geometry pipeline produces per-face (non-indexed) triangles so each color slice renders as a solid block (no blended vertex colors) and vertical side walls are preserved.
• Texture sampling: we create a CanvasTexture from the preview canvas and use NearestFilter with mipmaps disabled so the texture stays crisp when mapped onto the 3D mesh. The texture UVs are adjusted (repeat/offset) so the canvas region aligns with the mesh bounding box.
• Color ordering: palette swatches are derived from image pixels, then ordered by hue/saturation/lightness and presented from darkest to lightest by default (you can reorder manually).
• Async mesh generation: The greedy meshing algorithm yields control back to the browser every 8ms during large mesh builds, keeping the UI responsive. Boundary vertex filtering uses binary search for optimal performance.

How to use

Quick start (Auto-paint mode — Recommended)

1. Upload or drag an image into the preview area.
2. Switch to the Auto-paint tab in the 3D controls panel.
3. Click Add Filament and configure your filaments:
   • Use the calibration wizard (calibrate icon) to measure accurate TD values, or
   • Enter TD values manually.
4. Enable Enhanced color matching for optimal results (auto-selects best algorithm).
5. (Optional) Set Region weighting to Center or Edge to prioritize important areas.
6. Use the layer-by-layer preview slider to verify transitions.
7. Export via Download STL or Download 3MF and follow the print plan.

See the Auto-paint section for complete details.

Manual mode workflow

1. Upload or drag an image into the preview area.
2. Adjust quantization settings to reduce to the desired number of colors.
3. Tweak or replace swatches using the color pickers in the Swatches panel.
4. Open the 3D panel → Manual tab to configure:
   • Per-color slice heights
   • Base slice height
   • Pixel size
   • Color order (drag-and-drop)
5. Preview in 3D and use the layer slider to inspect the stack.
6. Click Download STL or Download 3MF to export your model.
7. Use the Copy button to copy the plain-text print plan with layer heights and swap instructions.

3D / printing specifics and tips

• Base slice height default: 0.20 mm
• Layer height default: 0.12 mm
• Layer height used to compute the exact layer numbers at which color swaps happen in the plain-text plan.
• Per-color slice heights are snapped/multiplied to sensible values relative to layerHeight when the swatches change or are initialized.

Layer-by-layer preview

The 3D view includes an interactive height slider at the bottom that lets you visualize how the print builds up layer by layer:

• Drag the slider to show/hide layers progressively from base (0mm) to full height
• Current height and layer information displayed in real-time
• Slider step size matches your configured layer height for accurate control
• Helps verify filament swap positions and catch potential issues before printing

This is especially useful for complex multi-color prints where you need to understand exactly when each color transition occurs.

Auto-paint

Auto-paint is an automated layer-generation mode that replaces the manual palette/swatch workflow. Instead of reducing an image to a fixed number of colors and manually tuning per-color slice heights, you define a set of filaments (each with a color and a Transmission Distance) and let the algorithm compute the optimal layer stack automatically.

Core concepts

• Filaments: Each filament has a hex color and a Transmission Distance (TD) value (in mm). TD describes how translucent the filament is — at a thickness equal to TD, only ~10% of light passes through. Dark/opaque filaments have low TD (e.g. 0.5 mm); light/translucent filaments have high TD (e.g. 6+ mm). When you add a filament without specifying a TD, Kromacut estimates one from the color's luminance and saturation.
• Beer-Lambert optical blending: The algorithm simulates how light transmits through stacked filament layers using the Beer-Lambert law: transmission = 10^(-thickness / TD). This physically models the color you see when printing thin semi-transparent layers on top of each other.
• Transition zones: Each filament in the stack needs enough vertical space to visually transition from the color below it to its own pure color. The algorithm simulates adding layers one at a time until the blended color converges (DeltaE < 2.3 — the "just noticeable difference" threshold) or opacity exceeds 85%. The result is a set of transition zones, each with a start height, end height, and the filament used.
• Luminance-to-height mapping: Once the transition zones are computed, each pixel's brightness is mapped to a target height in the model. Dark pixels get the minimum height (base layer only), bright pixels get the full height (all layers), and mid-tones fall proportionally in between. This produces the characteristic lithophane-style relief where image brightness = model thickness.

How it works (step by step)

1. Define filaments — Add your filament colors and Transmission Distances in the Auto-paint tab. Use the color picker and TD input for each filament row.
2. Filament ordering — By default filaments are sorted by luminance (darkest on the bottom, lightest on top). With Enhanced color matching enabled, the algorithm evaluates orderings to find the one that best reproduces the image's color palette.
3. Transition zone calculation — For each consecutive pair of filaments, the algorithm simulates Beer-Lambert blending layer-by-layer until the color converges. The first (darkest) filament gets a foundation zone thick enough to be ~95% opaque (TD × 1.3).
4. Height compression — If the ideal height exceeds a user-set Max Height, all zones are uniformly compressed. The UI shows which zones are compressed and by how much.
5. Virtual swatch generation — The transition zones are sampled at each layer-height increment to produce a sequence of blended colors (virtual swatches). These drive the 3D preview and the height map, where each pixel maps to the layer whose blended color best matches.

Filament Calibration

Each filament row in the Auto-paint tab includes a calibration wizard to help you determine accurate Transmission Distance values:

1. Click the calibrate icon next to any filament to open the calibration wizard.
2. Print test samples — The wizard guides you through print