Lumina-Layers

Lumina Studio 2.0

Flat full-colour FDM printing

Layer filaments to reproduce the colours and tonal detail of an image.

简体中文 · Run from source · Project Wiki · Features

Bring the print closer to the original

Lumina Studio 2.0 layers different filaments to reproduce an image’s colours and shading in a flat full-colour FDM print.

It uses calibration data from your materials to match layer recipes to the image. Compare the preview with the original, change colours you do not like, and adjust gradients or recipes in individual regions. Then export a 3MF for your slicer.

Use an existing LUT preset, or photograph gradient cards to build your own material profiles. Combine your materials and adjust colour layers and layer height.

Printed by users

_{Colour, shading, and detail with different filament combinations.}

What you can make

Start with a photo, illustration, or piece of pixel art. Make framed pictures, standing cut-outs, keychains, or fridge magnets, or add your own structural design and try something different.

_{With structural design and assembly, pixel characters can become jointed figures.}

_{A folding fan, perforated board, playable puzzle, and luminescent colour.}

_{If the whole picture will not fit on the bed, print it in sections and assemble or frame it.}

These are physical prints made by Lumina users; colour counts follow the makers’ labels. The photos are shown with permission for the project. Copyright in the depicted artwork remains with its respective creator. See the image record.

What is in 2.0

The interface has Chinese and English, plus light and dark themes. Use the preview while editing, then check materials, process settings, and placement in your slicer before printing.

Your first print

1. Prepare material profiles. Import profiles that match the filaments you will use, or print and photograph gradient cards, then extract and save profiles in Material Extraction.
2. Choose your filament combination. Set Source Type to Material Archive, select the filaments for this print, and set the number of colour layers and layer height.
3. Import an image or SVG. Set its physical size and modelling mode, then create a preview.
4. Edit the result. Compare it with the original and adjust local colours, recipes, and structure. To add a transparent coating, enable it and set its thickness. Save a JSON project or PNG share card to continue later.
5. Select a printer and generate. Choose the slicer, device, nozzle, and build plate in Settings, then download the 3MF or multi-plate ZIP.
6. Check it in the slicer. Confirm filament slots, temperatures, layer height, wipe tower, and bed limits before slicing and printing.

For a first try, use a few profiled filaments to print a small sample and check how closely the colours and shading match the image. Recombine existing profiles when you want a different palette; when you add a new filament, create a profile for it.

Why calibration matters

Two rolls labelled red can look quite different when layered. Layer height, stacking order, material batch, print settings, and lighting all matter too. That is why Lumina records the colours of a physical print first and uses those measurements for colour matching.

Fixed boards and LUTs

The fixed-board process is straightforward: generate a board, print it, photograph it, extract the colours, and save a LUT. Choose a preset setup for 2, 4, 6, or 8 materials. A new material set or important setting change usually means making a new calibration board.

LUT inputs include .npy, keyed .json, .npz, and .msgpack. Match the preset’s material order, layer height, and colour mode to the actual print; the filename or colour count alone is not enough.

The project Wiki has guidance on photography and colour extraction.

Gradient cards and material profiles

Gradient cards record a material’s data first, then profiles are combined to calculate colour mixing. Changing a palette does not require a complete fixed board for every combination. Organise, import, and export profiles in the material library, then use them for colour matching.

Photography and calculation both have some error, so check the colour on a real print. A small sample is a good way to check colour and thickness before starting a large piece. More finished work is in the users’ gallery.

Source Nightly

Try recent changes from the source previews. A preview is published automatically after a maintainer reviews and merges a PR and all main-branch CI workflows pass for that commit.

Each preview has its own tag, commit SHA, and release notes. Download Source code (zip) or Source code (tar.gz) from the release page, extract it, and follow the installation steps below. No installer or portable application is provided.

For a downloaded archive, open a terminal in the extracted directory and start at installation step 2. Skip the Git clone step so you keep using the selected preview commit.

Previews may still have bugs. Back up important projects and include the release’s commit SHA when reporting a problem. Failed checks do not publish a new preview; the previous one remains available.

Installation

Run the source in a browser or in the Electron desktop window.

Requirements

Install Python, Node.js, and pnpm. If using Corepack, enable it and select the pnpm version above; do not assume that Node.js includes Corepack.

Precompiled dependencies for the complete application cover:

Intel Mac, Linux ARM, Alpine/musl, Windows ARM, 32-bit, and free-threaded Python are outside this complete dependency set. This is the intersection of the required dependencies, not a claim of physical printing tests on every platform or device.

1. Get the 2.0 source

git clone https://github.com/lumina-layer-studio/Lumina-Layers.git
cd Lumina-Layers

2. Create and activate a Python environment

python -m venv .venv

If macOS/Linux provides only python3, create it with python3 -m venv .venv. Activate it for your shell:

3. Install dependencies and start

From the repository root, with the environment active:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
pnpm --dir frontend install --frozen-lockfile
python start_all.py

Open the frontend address printed by the launcher, normally http://localhost:4174. The backend uses port 8000 by default. Follow the launcher’s prompt to stop it.

Source installs do not connect to an online material library by default. Local material profiles work offline. To connect a Registry you host or are authorized to use, configure its service URL separately; see the Registry connection guide.

The native 3MF dependencies are fatcat-metadata==0.1.3 and the official neroued-3mf==0.4.2 release. Both install from PyPI through requirements.txt; no custom writer wheelhouse is needed. See the native dependency guide for supported platforms. The SVG dependency remains lumina-svg-core==0.3.4.

Optional: desktop window

After installing the Python and frontend dependencies above:

pnpm --dir electron install --frozen-lockfile
pnpm --dir electron start

The desktop window starts its own Python backend and frontend, so do not also run start_all.py. Confirming exit stops the processes it started.

One more look before printing

• Check that the materials and layer height match your profile or preset. Transparent coating follows the model’s material type; mixed or unknown types default to PLA. Confirm the actual transparent filament, temperatures, and compatibility warnings in the slicer before printing.
• Model surface overlay currently cannot be exported together with large-format tiling; choose one of the two workflows.
• If a large model’s wipe tower or brim will not fit, Lumina keeps the warning and lets you download the project. You still need to arrange it in the slicer; a downloaded file has not necessarily been placed or sliced successfully.
• Prusa export currently uses the PrusaSlicer 3.0.0-alpha12 preview format. Check compatibility before using another version. Details are in 3MF export.
• Save a JSON project or PNG share card to continue editing later, and keep the original image, presets, and material profiles for important projects.

Documentation, community, and support

The project Wiki contains guides and updates; the multi-brand slicer guide covers print setup.

Share a print or ask for help through the QQ and Discord links above. For a software problem, the built-in feedback tool helps us reproduce it: include what you did, the version, and relevant files. Reports are saved under local feedback/ before submission to the official service. To keep them on your device, set LUMINA_FEEDBACK_SERVER_URL=off in .env.local. See .env.example and bug report details.

Lumina Studio is a non-profit open-source community project. If it has helped you and you would like to keep the work going, you can support it on Afdian or Patreon. Support goes towards development, testing, documentation, packaging, and community maintenance. The sponsors page lists supporters and material-brand adaptation information.

License and commercial use

Project-owned 2.0 software is licensed under AGPL-3.0-only. Independent modules, dependencies, and resources retain their own terms. See LICENSE, LICENSING.md, and third-party resource notices.

Individuals and businesses may use the software free of charge. Generated model files and physical prints may be sold commercially; public sharing or sale requires Lumina-Layers attribution under the output terms. Contact the development team for separate written closed-source integration rights or an output-attribution waiver, as described in commercial authorization.

Contributing

Contributions of reproducible issues, code, presets, material measurements, translations, and documentation are welcome. The source uses Python + FastAPI, React + TypeScript, and an Electron desktop host. Start with CONTEXT-MAP.md. Tests additionally need requirements-dev.txt. PostgreSQL is optional; ordinary local use needs no database.

• Changelog
• Development and testing
• Workshop module development and the public SDK

Thanks to HueForge, AutoForge, ChromaStack, LD_ColorLayering, ChromaPrint3D, and the wider 3D-printing community for sharing their work. Third-party code, data, and resources remain subject to their respective licences and attribution notices.

Contributors

Thank you to everyone who contributed code, test prints, presets, translations, and documentation.