Lumina Studio Logo

Lumina Studio

A Multi-Material FDM Color System Based on Physical Calibration

Stars   Release   License

📖 Chinese Version / 中文文档

---

Official Links & Community

GitHub : GitHub       Join Discord : Discord

Website: Website       Wiki: Wiki

Sponsors: Sponsors       Patreon: Patreon

YouTube: YouTube       X / Twitter: X / Twitter

TikTok: TikTok       Bluesky: Bluesky       Mastodon: Mastodon

Bilibili: Bilibili       QQ Group: 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: 1. **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. 2. **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. 3. **Creator-side model details** - Keychain holes with custom size and position. - Fridge-magnet holes, white outline and transparent coating integrated into the main workflow. 4. **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. 5. **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. 6. **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. ### Sponsored Filament Adaptation The sponsors page lists filament brands that have provided materials or otherwise supported adaptation work, including Aliz, Elegoo, Bing3D, BIQU, CAILAB, Snapmaker, Inslogic, CHING LEUNG, KYNIX, Mochuang, REBIRTH3D, Sailner, Bambu Lab, XYD, Antinsky and Anycubic. ### 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 ```bash 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). 1. **Build the lumina image**： ```bash docker build -t lumina-layers . ``` 2. **Run Container**： ```bash docker run -d -p 7860:7860 lumina-layers ``` 3. Open in your browser `http://localhost:7860`。 ### Option 2：Local Installation **Basic Dependencies**： ```bash pip install -r requirements.txt ``` --- ## User Guide ### Quick Start ```bash 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**: 1. 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) 2. Scan via photography and extract real RGB data 3. Build a "Lookup Table (LUT) of actual results" 4. 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: - **[Hueforge](https://shop.thehueforge.com/)** - **[AutoForge](https://github.com/AutoForgeAI/autoforge)** - **[ChromaStack](https://github.com/borealis-zhe/ChromaStack)** - **[LD_ColorLayering](https://github.com/Luban-Daddy/LD_ColorLayering)** - **[ChromaPrint3D](https://github.com/Neroued/ChromaPrint3D)** --- ## Contributors Made with care by all contributors! --- ⭐ Star this repo if you find it useful!