红绿蓝白四色图像生成与3D打印处理方案

1. 文档目的

本文档用于指导项目实现一个面向3D打印的“四色图像生成模式”。用户指定红、绿、蓝、白四种实体耗材后，系统支持文生图和图生图，并自动完成固定色板转换、可打印性清理、打印预览及四色蒙版输出。

本功能不是普通的图片滤镜。其核心目标是让生成结果同时满足：

画面只使用用户指定的四种耗材颜色。
主体清晰、美观，转换前后差异可控。
色块尺寸、边界和细节适合FDM打印。
可以输出供后续建模、切片或HueForge使用的数据。

2. 核心结论

整体采用三段式处理：

AI生成适合四色化的构图
        ↓
确定性固定色板量化
        ↓
面向3D打印的色块清理与输出

不能只依靠提示词要求图像模型“仅使用四种颜色”。即使肉眼看起来只有四色，边缘抗锯齿、光影、半透明和压缩仍会产生大量中间色。因此，最终结果必须经过算法强制映射到固定色板。

3. 功能范围

3.1 输入方式

文生图：用户输入主题描述，系统生成适合四色打印的图像。
图生图：用户上传照片或插画，系统保留主体身份、轮廓、姿势和构图，重新设计为四色风格。
已有图片四色化：不调用生成模型，直接对现有图片进行固定色板转换和可打印性优化。

3.2 输出内容

每次处理至少输出：

原始生成图或风格化图。
严格四色预览图 four_color_preview.png。
红色蒙版 mask_red.png。
绿色蒙版 mask_green.png。
蓝色蒙版 mask_blue.png。
白色蒙版 mask_white.png。
处理参数及色板信息 metadata.json。

后续可选输出：

四个独立SVG区域。
四个独立网格或STL部件。
带颜色分区的3MF。
HueForge输入图及换层建议。

4. 两种打印模式

4.1 模式A：实体色块模式（默认）

适用于：

多色摆件、徽章、冰箱贴。
平面浮雕和装饰画。
卡通、公仔正面图、Logo及图标。
AMS、CFS、MMU等多色打印系统。

处理原则：

每个区域只能属于一种实体耗材颜色。
使用大面积连续封闭色块。
不使用渐变、半透明和抖动。
自动删除或合并无法打印的细碎区域。
尽量减少边界复杂度和无意义换色。

推荐视觉风格：

四色丝网印刷。
矢量海报。
剪纸或拼色玩具。
波普艺术。
赛璐璐动画。
扁平色块插画。

4.2 模式B：光学混色模式（高级）

适用于：

正面观看的平面装饰画。
HueForge浮雕画。
像素画、规律网点画。
允许通过观看距离形成视觉混色的产品。

处理原则：

使用规律半色调、网点或层叠透光形成更多视觉颜色。
优先使用确定性的有序抖动，避免随机噪点。
网点尺寸不得小于打印机的最小可打印尺寸。
HueForge模式必须引入耗材的Transmission Distance（TD）参数。

限制：

不建议用于普通立体公仔或需要近距离观看的光滑表面。
会增加细碎结构、换料次数、打印时长和废料。
红绿蓝耗材不是屏幕RGB发光像素，不能按屏幕加色混合直接预测实物颜色。

5. 耗材色板管理

5.1 色板来源

系统必须支持两种色板来源：

默认色板：用于功能体验和快速预览。
实测色板：用户根据实际耗材建立，作为正式打印的推荐方式。

不应直接把理论纯色 #FF0000、#00FF00、#0000FF、#FFFFFF 当作所有耗材的真实颜色。

5.2 实测流程

使用目标红、绿、蓝、白耗材打印标准色卡。
在固定色温、固定曝光和中性背景下拍照。
选取色卡中心区域，计算平均颜色。
保存sRGB、Lab及耗材名称、品牌、批次等信息。
HueForge模式额外保存每种耗材的TD值。

5.3 建议数据结构

{
  "paletteId": "rgbw-default-001",
  "name": "红绿蓝白测试色板",
  "colors": [
    {"id": "red", "name": "红色", "hex": "#D93632", "lab": [48.1, 57.2, 38.6], "td": null},
    {"id": "green", "name": "绿色", "hex": "#3B8C54", "lab": [52.8, -37.4, 23.1], "td": null},
    {"id": "blue", "name": "蓝色", "hex": "#315CA8", "lab": [39.6, 13.2, -45.8], "td": null},
    {"id": "white", "name": "白色", "hex": "#F2F1EA", "lab": [95.2, 0.1, 3.7], "td": null}
  ]
}

以上数值仅为结构示例，正式数据必须由实际色卡测量产生。

6. AI生成策略

6.1 总体原则

AI模型负责：

主体设计。
构图和风格化。
主动简化光影和纹理。
生成适合四色映射的大块颜色区域。

AI模型不负责：

保证像素级严格四色。
判断喷嘴能否打印某个微小区域。
最终颜色分区和蒙版输出。

6.2 无黑色条件下的明暗映射

红、绿、蓝、白色板不含黑色，写实照片的暗部和中性灰无法被准确表达。默认映射规则为：

白色：背景、留白、最亮高光。
蓝色：最暗区域和主要阴影。
红色：暖色主体及中间明度区域。
绿色：冷色主体、辅助区域及中间明度区域。

产品界面应允许用户更改“暗部承担色”，但默认使用蓝色。

6.3 文生图提示词模板

设计一幅适合四色FDM打印的色块插画。

主题：{{用户主题描述}}
表现形式：四色丝网印刷、矢量海报、剪纸式分层色块。
调色板：只表现指定的红色、绿色、蓝色和白色四种实体颜色。
构图：主体轮廓清晰，使用大面积连续色块，颜色区域彼此明确分离。
打印要求：所有细节均由封闭色块组成；避免孤立像素和细碎纹理；
重要结构的宽度应足以进行FDM打印。

颜色职责：白色承担背景、留白和高光；蓝色承担最暗区域；
红色和绿色承担主体中间色及装饰区域。

禁止：黑色、灰色、黄色、青色、紫色、渐变、半透明、柔和阴影、
照片级光照、反光高光、景深、模糊边缘、噪点、密集网点、微小色块、
文字、水印和额外装饰元素。

6.4 图生图提示词模板

保留输入图片中主体的身份、外轮廓、姿势、关键辨识特征和整体构图，
将画面重新设计为适合四色FDM打印的色块插画。

只使用指定的红、绿、蓝、白四种视觉颜色。
将原图阴影归并为蓝色，高光和背景归并为白色，
其余主体区域根据语义分配为红色或绿色。

使用大面积连续封闭色块、清晰硬边界和简化细节。
保留主体最有辨识度的结构，但删除毛发细纹、皮肤细节、复杂材质、
细碎装饰、柔和阴影、渐变、透明效果、照片噪点和背景杂物。

输出应像重新设计的矢量丝网印刷稿，而不是在原照片上叠加滤镜。
不要添加原图中不存在的角色、物体、文字或图案。

6.5 候选图策略

每个请求建议生成2至4张候选图。候选图全部经过四色量化和可打印性分析，再根据评分选择默认推荐结果。用户仍可查看和选择其他候选图。

7. 固定四色量化算法

7.1 预处理

建议处理步骤：

统一图片尺寸和色彩配置。
将透明区域合成到白色或用户指定背景色。
使用边缘保留滤波降低照片噪点。
可选执行轻度对比度和饱和度调整。
转换到Lab等感知色彩空间。

7.2 颜色映射

对每个像素计算其与四种实测耗材颜色的感知色差，并分配给最接近的颜色。

推荐方案：

快速预览：Lab欧氏距离，即Delta E 76。
最终输出：CIEDE2000或等价的感知色差算法。
实体色块模式：禁止抖动。
光学混色模式：允许有序抖动或可打印半色调。

不得使用自动选取四种代表色的普通K-means作为最终色板，因为最终颜色必须严格来自用户指定的四卷耗材。K-means只能用于图像预分析或区域简化。

7.3 区域后处理

四色映射后，对每个颜色蒙版执行：

连通域分析。
小区域合并。
小孔洞填充。
形态学开运算和闭运算。
边界平滑。
细线加粗或删除。
可选的轮廓简化。

小区域应优先合并到与其边界接触最多、同时色差代价最低的邻接区域，而不是一律合并到背景。

8. 可打印性约束

8.1 最小特征尺寸

默认最小有效宽度建议为两条挤出线宽：

minimumFeatureMm = lineWidthMm × 2

使用0.4 mm喷嘴、约0.4 mm线宽时，默认值可设为0.8 mm。用户可以根据设备情况调整。

图片中对应的最小像素宽度为：

minimumFeaturePx = imageWidthPx × minimumFeatureMm / printWidthMm

示例：图片宽度1600 px，打印宽度160 mm，最小特征0.8 mm，则小于约8 px的结构需要合并、加粗或删除。

8.2 边界和换色约束

系统需统计：

色块总数量。
小色块数量及面积占比。
四色区域总边界长度。
每种颜色面积占比。
估算的颜色切换复杂度。

对于普通多色打印，应惩罚过长边界、孤立色点和棋盘格式交错；对于HueForge或半色调模式则使用另一套评分，不应用实体色块模式的同一阈值。

9. 候选图自动评分

每张候选图完成四色转换后计算以下指标：

colorError：原风格化图与四色图之间的平均感知色差。
smallRegionRatio：不可打印小色块面积占比。
boundaryComplexity：归一化后的四色边界长度。
subjectSimilarity：图生图时主体特征保留程度。
paletteBalance：四色面积分配是否极端失衡。
darkLoss：无黑色条件下暗部细节损失程度。

推荐分数形式：

score =
  w1 × normalizedColorError
  + w2 × smallRegionRatio
  + w3 × boundaryComplexity
  + w4 × subjectLoss
  + w5 × paletteImbalance
  + w6 × darkLoss

分数越低越好。MVP阶段可以先实现前三项，图生图主体相似度在后续阶段加入。

10. 用户界面建议

10.1 基础参数

参数	说明	默认值
输入方式	文生图、图生图或直接四色化	文生图
打印模式	实体色块或光学混色	实体色块
耗材色板	选择默认或实测色板	默认红绿蓝白
打印宽度	用于计算最小像素尺寸	160 mm
喷嘴直径	用于推导打印约束	0.4 mm
最小特征	色块最小有效宽度	0.8 mm
风格强度	原图保真与四色重设计的权衡	60%
细节等级	控制色块数量和复杂度	中
暗部颜色	无黑色时承担阴影的颜色	蓝色
白色职责	背景、高光或同时承担	同时承担

10.2 高级参数

候选图数量。
色差算法。
小区域合并强度。
边界平滑强度。
轮廓简化强度。
是否允许有序抖动。
半色调网点尺寸。
HueForge各耗材TD及排列顺序。
四种颜色目标面积范围。

10.3 预览界面

建议同时展示：

原始生成图或输入图。
AI风格化结果。
严格四色结果。
可打印性清理结果。
四个颜色蒙版。
不可打印区域热力图。

预览必须明确区分“屏幕模拟颜色”和“最终实物可能颜色”，避免用户误认为屏幕预览等同于实际耗材效果。

11. 接口建议

11.1 请求结构

{
  "mode": "text_to_image",
  "printMode": "solid_regions",
  "prompt": "一只正在奔跑的机械麒麟",
  "sourceImage": null,
  "paletteId": "rgbw-default-001",
  "print": {
    "widthMm": 160,
    "nozzleMm": 0.4,
    "lineWidthMm": 0.4,
    "minimumFeatureMm": 0.8
  },
  "generation": {
    "candidateCount": 4,
    "styleStrength": 0.6,
    "detailLevel": "medium",
    "shadowColor": "blue"
  },
  "postProcess": {
    "colorDistance": "ciede2000",
    "dithering": "none",
    "removeSmallRegions": true,
    "smoothBoundaries": true
  }
}

11.2 响应结构

{
  "taskId": "task_xxx",
  "recommendedCandidateId": "candidate_2",
  "candidates": [
    {
      "id": "candidate_2",
      "sourceUrl": "...",
      "fourColorPreviewUrl": "...",
      "cleanPreviewUrl": "...",
      "maskUrls": {
        "red": "...",
        "green": "...",
        "blue": "...",
        "white": "..."
      },
      "metrics": {
        "score": 0.21,
        "meanColorError": 8.2,
        "smallRegionRatio": 0.014,
        "boundaryComplexity": 0.18
      },
      "warnings": []
    }
  ]
}

12. 模块划分

建议拆分为以下模块：

PaletteManager
  ├─ 色板创建、读取和校准
  └─ Lab、Hex及TD数据管理

PromptBuilder
  ├─ 文生图提示词
  ├─ 图生图提示词
  └─ 根据打印模式注入约束

ImageGenerator
  ├─ 文生图
  ├─ 图生图
  └─ 候选图批量生成

PaletteQuantizer
  ├─ Lab转换
  ├─ 固定四色映射
  └─ 可选有序抖动

PrintabilityProcessor
  ├─ 连通域分析
  ├─ 小区域合并
  ├─ 孔洞填充和边界平滑
  └─ 最小特征校验

CandidateScorer
  ├─ 色差评分
  ├─ 色块和边界评分
  └─ 候选图排序

ExportManager
  ├─ 四色PNG
  ├─ 四张蒙版
  ├─ SVG/3MF/STL扩展
  └─ metadata.json

13. 分阶段实施计划

阶段一：MVP

支持文生图和图片上传。
内置红绿蓝白默认色板。
实现实体色块提示词模板。
实现固定四色Lab映射。
输出四色预览和四张蒙版。
实现最小连通域删除或合并。
支持打印尺寸和喷嘴尺寸配置。

阶段一暂不包含：

HueForge TD模拟。
STL/3MF自动生成。
主体相似度评分。
自动耗材色卡校准。

阶段二：体验增强

一次生成多张候选图并自动评分。
增加图生图身份和轮廓保护。
增加不可打印区域热力图。
支持用户创建和保存实测耗材色板。
增加色块占比和边界复杂度控制。

阶段三：打印链路

输出独立SVG色层。
图像区域自动转浮雕网格。
输出多部件STL或带颜色的3MF。
接入HueForge式TD模拟或相关工作流。
根据切片结果估算换色次数、耗时和废料。

14. MVP验收标准

14.1 功能验收

文生图和图生图均可完成处理。
最终PNG中除透明通道外，唯一颜色数量必须严格等于或小于4。
最终颜色必须全部来自当前指定色板。
必须输出四张尺寸一致、互斥且能够完整覆盖有效画面的蒙版。
修改打印尺寸或最小特征参数后，清理结果应发生符合预期的变化。

14.2 质量验收

主体外轮廓清晰，主要辨识特征未因四色化完全丢失。
默认模式下无渐变、半透明和随机噪点。
不可打印小区域面积占比低于预设阈值，建议MVP默认小于2%。
不应出现大量单像素或棋盘格式交错颜色。
白色背景与白色主体区域在蒙版和后续建模时能够被明确区分或配置。

14.3 测试图片类型

至少覆盖：

单主体卡通角色。
人物半身照片。
宠物照片。
复杂背景商品照片。
Logo或图标。
高对比度黑白图。
暗部占比较大的照片。
毛发、树叶等高频细节图片。

15. 风险与注意事项

红绿蓝白不包含黑色，无法忠实表达大量暗部和中性灰；需要通过风格化规避，而不是承诺照片级还原。
屏幕颜色与打印耗材颜色存在系统性差异，正式结果应使用实际耗材色板。
AI提示词只能提高四色适配度，不能替代最终固定色板量化。
抖动虽然可以提高远距离视觉还原度，但会明显降低普通多色打印的效率和稳定性。
图生图风格化强度越高，四色效果通常越好，但人物身份和商品细节可能损失更多。
白色既作为背景又作为实体区域时，后续建模需要额外的背景/主体语义蒙版，不能只依赖颜色区分。
切片软件可能再次合并过细区域，因此必须以最终切片预览作为打印前最后验收环节。

16. 项目定位文案

推荐产品定义：

面向指定3D打印耗材色板的AI图像生成与可打印性优化工具。

推荐简短功能名：

四色打印模式
指定耗材配色
AI四色分色
可打印图像生成

不建议仅称为“四色滤镜”，因为该功能同时包含生成约束、固定色板量化、打印规则清理和打印数据输出。

17. 参考资料

ImageMagick：固定色板量化、颜色重映射及抖动原理：https://usage.imagemagick.org/quantize/
HueForge：Filament Painting与Transmission Distance说明：https://shop.thehueforge.com/blogs/news/what-is-hueforge
PrusaSlicer：多材料颜色区域及薄特征限制：https://help.prusa3d.com/article/multi-material-painting_262620

18. 当前实现状态（2026-08-14）

本轮已完成实体色块模式的正式链路，代码边界如下：

tools/ai/printable_image_pipeline.py：固定实体耗材色板、sRGB/Lab/CIEDE2000 映射、按毫米换算最小特征、连通区域合并、边界清理、遮罩、热力图、评分和元数据。
tools/ai/openai_preprocessor.py：为文字和图片输入构建适合实体色块的 Image2 提示词，并保存 AI 原图。
tools/ai/orca_ai_sidecar.py：统一文字、图片和文字+图片任务，持久化全部阶段产物并提供本地下载契约。
src/slic3r/GUI/AIModelGenerationClient.*：只负责打印参数和产物契约，不包含图像算法。
src/slic3r/GUI/ModelGenerationPanel.*：提供中文打印参数、阶段预览和确认后生成 3D 的交互。

正式任务现在输出：

AI 原图。
严格色板图。
可打印清理图。
问题热力图。
每个耗材色的互斥遮罩。
背景与主体语义遮罩。
包含物理参数、色板 Lab 值、面积比例、色差、区域和边界指标的 metadata.json。

实现保证：

清理图中的非透明像素只能来自用户当前指定的实际耗材色板。
默认禁用抖动，不产生棋盘格混色。
最小特征由打印宽度、图像像素宽度、线宽和用户设定的毫米值共同决定；默认最小特征不小于两条线宽。
小区域优先合并到接触边界最长的相邻区域，接触相同时再按感知色差选择。
白色背景与白色实体通过独立背景/主体遮罩区分。
关闭“使用可打印颜色”后仍走原有自然色链路，不改变 Orca 切片默认行为。

真实 Image2 样例已验证只使用指定红、绿、蓝、白四种颜色；小区域由 2523 个降至 1 个，区域总数由 2666 降至 132，清理后不可打印小区域占比约为 0.0004%。完整 Python 回归 103/103 通过，Windows Release GUI 模块编译和最终 DLL 链接通过。

以下仍属于后续阶段，不应与当前实体色块 MVP 混淆：

一次生成 2 至 4 张付费候选图并自动排序。
HueForge TD/透光叠色模拟。
SVG、STL 或 3MF 图像浮雕自动导出。
耗材品牌、批次和实测色卡的账号级同步。
以最终切片刀路计算真实换色次数、耗时和废料。

19. 设计师玩具图生图补充规则（2026-08-15）

固定三图回归后，正式图生图契约增加以下规则：

Q 版设计师玩具对真人默认采用约 92% 面部身份保持和 8% 轻度比例玩具化；主要在身体、发型体块、衣褶和材质上做简化，禁止把成年人改成大眼幼儿或通用娃娃脸。
动物必须保留原始毛色和花纹，不得凭空增加白嘴、白胸、袜子、额头白斑或其他新标记。
人物、动物、雕像和不稳定道具默认使用一体底座；鞋、相机、杯子、车辆等自身可稳定落地的完整商品不得强制增加展台，除非用户明确要求。
动态色板的已选颜色始终允许使用；禁用自然肤色、灰黑替代色等规则只针对色板之外的新颜色，不能与包含黑色或暖白的真实耗材配置冲突。
“四色”是最多四种耗材的上限，不是强制使用三种或四种的下限。纯黑猫、双色雕塑等语义正确的少色结果只显示配色多样性提示，不得阻止继续生成 3D；主体过小或主体断裂仍属于硬性质量失败。
完整人物保留头到脚并落在单一底座；只提供半身/胸像的参考图默认生成带底座半身摆件，不臆造骨盆、腿或脚。
多主体场景必须按用户文字选择唯一主角；没有明确文字时选择视觉主导前景主体，并删除景物、植物、摄影水印、相机 UI 和无关地标。
背景色不得用于外轮廓、颈部、四肢、承重连接、底座接触或建筑层间分隔。白脸等背景色实体只能作为被非背景色完全包围的封闭嵌片。
人物长发、手指、首饰、织物纹理，以及建筑砖纹和微小檐口，必须在 Image2 阶段合并为少量牢固、连续、可建模的大块结构。

确定性质量门禁新增主体连通性指标：

subject_component_count：背景剥离后的主体连通区域总数。
meaningful_subject_component_count：面积超过最小特征面积或主体面积 2% 的有效连通区域数。
largest_subject_component_ratio：最大主体连通区域占全部主体面积的比例。
largest_subject_component_ratio < 0.98 时，任务加入 printable_subject_is_disconnected 告警并禁止确认生成 3D。

该门禁用于捕获“白色四肢融入白背景”“白色层间带把塔切成多段”等仅靠颜色数量、面积比例和小区域统计无法发现的问题。

20. OBJ 拓扑与 Orca 导入约束（2026-08-15）

四色综合链路的最终交付不是“看起来闭合”的 OBJ，而是 Orca 能按自身邻接规则无错误导入的有向流形网格。正式产物在标记为可切片前必须满足：

每条表面边恰好由两个三角面共享；
两个相邻三角形在共享边上的方向必须相反；
不存在退化面、越界索引或非可定向的面邻接矛盾；
顶点色数量与顶点数量一致，且每个面最多包含两种顶点色；
保留有意义的多个部件，只清理微小漂浮碎片，不能为了“单对象”破坏颜色和拓扑。

实现采用面邻接奇偶约束遍历统一绕序。对每个连通部件计算翻转集合，并优先选择翻转面数更少的等价方向；若约束矛盾，则以 non_orientable_face_winding 阻止自动导入。拓扑报告同时记录原始/剩余的边界边、非流形边、同向绕序边和实际翻转面数。

正式验收样本中，人像原文件存在 3 条同向共享边，Orca 因而显示 6 条非流形边；规范化只翻转 1 个三角面后，Orca 错误提示消失并成功完成 500 层四色切片。