Lumina Studio

A Multi-Material FDM Color System Based on Physical Calibration

📖 Chinese Version / 中文文档

Official Links & Community

GitHub : Join Discord :

Website: Wiki:

Sponsors: Patreon:

YouTube: X / Twitter:

TikTok: Bluesky: Mastodon:

Bilibili: QQ Group:

Project Status

Current Version: v1.6.9

License: GNU GPL v3.0

Nature: Non-profit Open Source Community Project

Website: https://www.luminastudio.com.cn/

Wiki: https://wiki.luminastudio.com.cn/

Sponsors & Supported Brands: https://www.luminastudio.com.cn/sponsors

Overseas Crowdfunding / Support: https://www.patreon.com/c/lumina_studio

Project Background

To simplify the steep learning curve of software such as HueForge/FlatForge and the requirement for specific filaments, Lumina uses brute-force and simplified brute-force methods based on physical calibration to obtain actual printed colors. The current mode does not involve any color theory calculations (color calculation based on color/TD values may be introduced in advanced features of version 2.0 in the future). The current approach is: Print - Capture - Extract Color - Map Stacking Formula Based on Extracted Color - Print (this is a color matching function, inspired by the default color matching in Autoforge and CMYK Lithophane).

Lumina Studio 2.0 Roadmap

Lumina Studio 1.x proved that the physical-calibration workflow works. Lumina Studio 2.0 is the next-generation rewrite of the interface, workflow and internal architecture. The color-stacking principle is the same, but the goal is a more stable, easier and more complete daily tool.

The 2.0 line is planned around these areas:

Image to full-color 3MF in one flow
- Upload an image, preprocess it, match colors, preview, and export a slicer-ready 3MF in the same workflow.
- Mainstream multi-color printers and slicers such as Bambu Lab, Snapmaker, Elegoo, Creality and others are considered in the output flow.
More accurate color matching and faster adjustment
- Newer processing paths aim for better color restoration and less visible layer loss.
- Built-in LUT presets for multiple filament brands remain open and ready to use.
- Compare the source image with the generated result, adjust unsatisfactory colors, and see changes more quickly.
- Single-select, multi-select, undo, gradient smoothing and thickness control are part of the planned daily color-editing workflow.
Creator-side model details
- Keychain holes with custom size and position.
- Fridge-magnet holes, white outline and transparent coating integrated into the main workflow.
SVG/vector input
- SVG input and vector export are part of the 2.0 direction, making logos, icons, paper-cut style works and other clean-edge models easier to handle.
Printer and slicer adaptation
- Built-in printer bed profiles constrain model size and reduce out-of-bed exports.
- Slicer choice can drive default slicing parameters.
- Large-format models can be split automatically for beds smaller than the final work.
Daily usability
- Chinese/English UI switching is supported, with more languages planned on top of the internationalization framework.
- 3D preview before export helps users inspect the model in the browser.
- Output and cache cleanup are being designed as normal one-click maintenance tasks.

2.0 FAQ

Q1: What is the relationship between 2.0 and 1.x?

2.0 is the next generation of 1.x. The physical color-calibration principle is the same, but the UI, workflow and architecture are being rebuilt. In short, 1.x proved the technical route; 2.0 is intended to become the mature daily version.

Q2: Will Lumina remain open source after crowdfunding or sponsorship?

Yes. The stable 2.0 release will remain open source for research, learning and community use. Sponsorship helps turn 2.0 from a prototype into a stable, usable and maintainable project.

Q3: Will supporters get paid-only features?

No paid-exclusive features are planned. Supporters may receive easier-to-run stable packages or development builds earlier. The open-source version and stable package are intended to keep the same functionality. Development builds are for verification; once features are stable, they will move into the stable release.

Q4: Can individual creators or small shops use Lumina commercially?

Yes. Lumina supports individual creators and small businesses selling physical prints generated with Lumina. See the license section below for the open-source license and commercial-use statement.

Features

Color Modes

2/4/5/6/8 Colors

Generation Modes

High-fidelity mode / Pixel mode / SVG mode

Other Features

Custom color card and color calibration functions

Adjust the number of generated colors

Image cutout / background removal

Independent backplate

Outline

Add transparent layer

Cloisonné enamel mode

Replace colors in the image after generating preview

Advanced Features

Color Formula Search

Merge color card function

Open Ecosystem

About .npy Calibration Files

All calibration presets (.npy files) are completely free and open, following these principles:

Vendor Lock-in Rejection: We will never force users to use specific filament brands, or require manufacturers to produce specific "compatible filaments" — past, present, or future. This violates the spirit of open source.
Community Collaboration: All users, organizations, and filament manufacturers are welcome to submit PRs to synchronize calibration presets. Your printer data can help others.
No additional testing tools required — only a 3D printer and a phone/camera.

Open Data = Community Co-creation

Support & Sponsors

Lumina Studio is a non-profit open-source project. Sponsorship only represents support for development, testing and community maintenance. It does not affect the technical roadmap, open-source license, or filament/slicer neutrality.

Official sponsors and supported brands: https://www.luminastudio.com.cn/sponsors
Overseas crowdfunding / support: https://www.patreon.com/c/lumina_studio
Project Wiki: https://wiki.luminastudio.com.cn/
Official Website: https://www.luminastudio.com.cn/
YouTube: https://www.youtube.com/channel/UCyP2Euw9whk1j-MT8d652Kw
X / Twitter: https://x.com/wLuF53gzlV98666
TikTok: https://www.tiktok.com/@dy6kueohw5ii
Bluesky: https://bsky.app/profile/wluf53gzlv98666.bsky.social
Mastodon: https://mastodon.social/@wluf53gzlv98666

The public repository currently hosts the 1.6.x open-source line. Lumina Studio 2.0 is being developed in a private beta and is planned to move into the public open-source workflow later. Patreon support helps fund that development, beta testing, packaging, documentation and community maintenance; it does not change the open-source license or make this project a paid closed-source product.

Product Support

Product support currently includes BIQU, dfoptix, Phaetus, Snapmaker, Antinsky and Anycubic.

Special Thanks

Additional thanks go to Aliz, Elegoo, Aoromas, CHING LEUNG Technology, Jilin University College of Mechanical and Aerospace Engineering / Jilin University Intelligent Manufacturing Innovation and Entrepreneurship Practice Demonstration Base, Snapmaker Technology and Wujing Materials.

Installation

Clone Repository

git clone https://github.com/MOVIBALE/Lumina-Layers.git
cd Lumina-Layers

Option 1：Docker

Using Docker is the easiest way to run Lumina Studio without worrying about system-level dependencies (such as cairo or pkg-config).

Build the lumina image：
```
docker build -t lumina-layers .
```

Run Container：

docker run -d -p 7860:7860 lumina-layers

Open in your browser http://localhost:7860。

Option 2：Local Installation

Basic Dependencies：

pip install -r requirements.txt

User Guide

Quick Start

python main.py

This will launch the web interface containing all three modules in a browser tab.

Tech Stack

Component	Technology
Core Logic	Python (NumPy for voxel operations)
Geometry Engine	Trimesh (mesh generation and export)
UI Framework	Gradio 4.0+
Vision Stack	OpenCV (perspective and color extraction)
Color Matching	SciPy KDTree
3D Preview	Gradio Model3D (GLB format)

License

This project is licensed under the GNU GPL v3.0 open-source license.

✅ Open Source & Freedom: You are free to run, study, modify and distribute this software.
🔄 Strong Copyleft: If you modify and distribute this software, you must publish your source code under the GPL v3.0 license.
❌ No Closed-Source: It is strictly prohibited to package and sell this software or its derivatives as closed-source products.

Commercial Use & "Small Creator" Support Statement: This project supports and encourages individual creators, small vendors and micro-enterprises to earn income through labor. You may freely use this software to generate models and sell physical printed products without additional authorization.

Technical Origin & Statement

Technical Inspiration

This project is inspired by the following works:

HueForge – The first project to commercialize FDM multi-layer stacking color mixing technology.
AutoForge – Automated color matching built on Hueforge.
CMYK Backlit Lithophane – Multi-layer stacked backlit lithophane effects in 3D printing based on transmission and subtractive color principles.

Technical Differences & Positioning

Traditional tools rely on theoretical calculations (such as TD1/TD0 transmission distance values), but these parameters often fail due to various objective variations.

Lumina Studio 1.X uses a brute-force approach:

Print physical calibration charts with 1024+ colors (full permutation for 2 colors × 5 layers, 4 colors × 5 layers; simplified brute-force for 6 colors × 5 layers, 8 colors × 5 layers)
Scan via photography and extract real RGB data
Build a "Lookup Table (LUT) of actual results"
Match using nearest-neighbor algorithm (similar to Bambu Lab's keychain generator matching)

Prior Art Statement

The core principle of FDM multi-layer color mixing was publicly disclosed by software such as HueForge between 2022 and 2023, and constitutes prior art.

The author of Hueforge has also clarified that such technical principles have entered the public domain. In most countries and regions, patents on these principles would almost certainly be rejected if rigorously examined by patent offices.

These authors chose openness to support community development, so this technology is generally not patentable.

Lumina Studio will remain open-source, collaborative, and non-profit. Public oversight is welcome.

This is an open-source non-profit project with no bundled sales, and no features will be locked behind paywalls.
If you or your company wish to support the project’s continued development, please contact us. Sponsored products will only be used for software development, testing and optimization.
Sponsorship represents support for the project and does not constitute any commercial binding.
Sponsorship arrangements that would influence technical decisions or open-source licenses are rejected.

Lumina Studio has not referenced any pending patent content, as most such patents only include specifications and do not disclose code in the short term; blind reference would hinder independent development.

Special thanks to HueForge for their support and understanding of open source!

Acknowledgments

Special Thanks to:

Contributors

Made with care by all contributors!

⭐ Star this repo if you find it useful!

Lumina-Layers