六色屏与RLCD本地图像转换规划

1. 结论

图像量化、缩放和抖动已有成熟方案。CardHelper不从零发明通用算法，而是在成熟工具之上建立可重复、可比较、可追溯的产品流水线。

首版采用以下分工：

• ImageMagick：作为成熟算法基准和人工调试工具，用于缩放、调色板映射、阈值、Floyd–Steinberg及有序抖动对照。
• Python + Pillow + NumPy：作为批处理和最终资源构建入口，负责配置、裁切、安全区、调色板、格式检查、manifest和设备像素编码。
• OpenCV：只在人物和复杂插画确实需要局部对比度、降噪或锐化时启用，不作为所有资源的强制依赖步骤。
• 六色屏厂商工具：面板选型后作为视觉和编码对照基准；如果结果优于通用方案，再决定集成、调用或复现其公开参数。

ImageMagick与Python输出在同一测试集上对照。正式设备包只保留一个权威构建路径，避免两套工具产生不一致成品。

2. 不把算法当作单一全局开关

不同内容需要不同转换策略，首版固定三类配置：

配置是默认值，不是永久规则。单个资产可以声明覆盖参数，但必须记录原因，不能在图片编辑器中做无法追溯的临时调整。

3. 通用处理顺序

处理顺序固定如下：

读取RGB母版和manifest
  → 校验尺寸、方向、色彩空间、Alpha和输入哈希
  → 转换到统一sRGB工作空间
  → 按目标画布裁切和缩放
  → 应用该Profile的固定预处理
  → 量化或阈值处理
  → 抖动（如果Profile启用）
  → 校验所有像素都属于目标调色板
  → 编码为设备资源
  → 反向解码生成预览
  → 写入输出哈希、参数和工具版本

关键约束：

• 先缩放，后量化和抖动；抖动后不得再次缩放。
• 透明图进入屏幕资源前必须明确合成到底色，默认底色由 display-profile 的纸白定义。
• 六色与RLCD从同一RGB母版独立处理，互不作为输入。
• UI文字和状态优先由渲染器按原生像素生成，不通过照片处理流水线。
• 设备编码后必须反向解码预览，防止位序、stride或颜色索引正确但打包错误。

4. 六色屏转换

4.1 display-profile

最终面板确定后建立版本化配置，至少记录：

• profileId、厂商、型号、面板批次和驱动IC。
• 原生宽高、旋转方向和有效显示区。
• 六个调色板索引、颜色名称和厂商建议RGB值。
• 实测色块照片、测量条件和校正后的工作色值。
• 全刷、局刷、快刷和残影限制。
• 输出像素索引顺序、每像素位数、行对齐和字节序。

不能只写“黑、白、红、黄、绿、蓝”。不同面板和批次的实际颜色不同，转换必须引用具体 profileId。

4.2 首版成熟算法基线

首版比较三个已有方案：

1. 无抖动最近调色板颜色：边缘干净，适合UI和平涂；人物容易出现色带。
2. Floyd–Steinberg误差扩散：人物和复杂插画的默认候选，细节较丰富；可能产生颗粒和边缘彩噪。
3. Bayer有序抖动：图案稳定、结果可预期，适合大色块和纹样；可能出现可见网格。

初期用ImageMagick对自定义六色调色板执行 remap 和上述抖动，作为结果基准。只有在厂商工具或真机证明色差明显不可接受时，才进入感知色空间、定制距离函数或专用误差扩散的第二阶段。

4.3 六色输出验收

• 输出尺寸与原生画布完全一致。
• 每个像素只使用该面板六个合法索引。
• 同一输入、同一配置和同一工具版本重复生成时哈希一致。
• 面部、头盔、肩甲和武器在正常观看距离下可辨认。
• 大面积纸白没有无意义彩色噪点。
• 重要轮廓不因误差扩散与背景粘连。
• 真机结果与厂商工具结果并列比较，不只看电脑模拟。

5. RLCD转换

RLCD目标固定为300×400、逻辑1-bit。转换不绑定ST7305显存排列，先得到通用逐像素图，再由CHB编码器打包。

5.1 portrait基线

sRGB母版
  → 独立3:4裁切
  → 300×400 Lanczos缩放
  → 灰度化
  → 固定gamma/对比度与轻量锐化
  → Floyd–Steinberg 1-bit
  → 轮廓和状态覆盖区检查

全局阈值和Bayer有序抖动作为对照。Atkinson可作为后续候选，但首版不为了增加算法数量而额外引入不必要依赖。

5.2 flat_art与ui_line

• flat_art优先Bayer或固定阈值，以获得稳定纹理。
• ui_line由本地UI渲染器直接输出1-bit；导入图标必须经过硬阈值和像素检查。
• 中文、数字、边框和焦点不使用Floyd–Steinberg，避免边缘噪点。

5.3 RLCD输出验收

• 尺寸为300×400且只包含0/1两种逻辑值。
• CHB编码后反向解码与逻辑图逐像素一致。
• 面部五官、头盔、肩甲和环首刀在实际物理尺寸下可读。
• 背景抖动不会吞没人物轮廓或干扰体力等状态层。
• 文字、数字和图标边缘完整，无灰度模拟和孤立噪点。

6. 配置文件建议

命令、项目目录、配置文件之间的引用方式和构建输出契约见资源转换工具接口与目录规划。

项目已有JSON资源体系，因此转换配置也使用JSON，不额外引入YAML解析依赖。建议结构：

{
  "schemaVersion": 1,
  "profileId": "portrait-eink6-panelX-v1",
  "assetClass": "portrait",
  "targetDisplay": "eink6",
  "displayProfile": "panelX-batchA-v1",
  "crop": {
    "mode": "cover",
    "anchorX": 0.5,
    "anchorY": 0.42
  },
  "resize": {
    "filter": "lanczos"
  },
  "preprocess": {
    "gamma": 1.0,
    "contrast": 1.0,
    "sharpen": 0.0
  },
  "quantize": {
    "method": "palette-remap",
    "dither": "floyd-steinberg"
  }
}

数值只是字段示例，不是已经冻结的调参结果。

7. 可复现与版本管理

每个输出记录：

• 输入路径与SHA-256。
• 输出路径与SHA-256。
• assetId、profileId、displayProfile和配置文件哈希。
• ImageMagick、Python、Pillow、NumPy和OpenCV版本。
• 裁切坐标、目标尺寸、算法和所有覆盖参数。
• 设备编码格式、stride、字节序和反向解码检查结果。
• 生成时间、人工评审和真机结果。

工具或配置升级不覆盖旧结果。新版本使用新 profileId，通过固定回归集比较后再替换设备包默认版本。

8. 固定测试集

在批量武将前建立一组小而稳定的测试资产：

1. CHAR-ANCHOR-001 RGB母版。
2. 一张肤色、暗部金属、皮革和旗帜同时存在的人物局部。
3. 六色纯色块和相邻色边界测试图。
4. 黑白灰阶与渐变测试图。
5. 1 px、2 px、3 px线宽和常用中文/数字测试图。
6. 大面积平涂、细纹样和透明边缘测试图。
7. 体力、护盾、Token、焦点和锁定覆盖区测试图。

回归不只比较文件哈希，还输出并排预览；算法版本变化允许像素改变，但必须经过视觉和真机重新验收。

9. 首轮算法比较矩阵

为避免组合爆炸，首轮只比较：

CHAR-ANCHOR-001用于人物比较；单独的小型纹样和文字图用于 flat_art、ui_line。先选出默认Profile，再允许少量有记录的资产覆盖，不为每张图人工试完所有算法。

10. 阶段计划

C0：规划与资料

• 冻结配置字段和输出manifest字段。
• 确认ImageMagick基准命令所需能力。
• 等待六色面板资料，不提前猜测真实调色板。

C1：RLCD最小验证

• 使用 CHAR-ANCHOR-001 和线宽/文字测试图比较三种RLCD方案。
• 输出300×400逻辑图、CHB和反向解码图。
• 在真实RLCD上比较可读性与刷新效果。

C2：临时六色模拟

• 使用明确标注 SIM 的临时调色板验证工作流。
• 结果只用于发现画风结构问题，不决定最终颜色。

C3：真实六色面板校准

• 建立真实 display-profile。
• 与厂商工具并行处理固定测试集。
• 在真机上确定 portrait、flat_art、ui_line 默认方案。

C4：批量生产

• 将已确认Profile接入卡牌包构建流程。
• 批量输出预览、manifest、校验和与设备资源。
• 配置或依赖升级时运行固定测试集回归。

11. 当前冻结与待验证

已确认

• 采用成熟算法和成熟工具，不从零自研通用图像量化算法。
• ImageMagick作为转换结果基准，Python工具作为批处理和设备构建入口。
• 按 portrait、flat_art、ui_line 三类内容维护转换配置。
• 六色和RLCD分别从RGB母版生成。
• 六色厂商工具和真机结果是最终对照依据。

待验证

• 六色屏型号、真实六色值、像素编码和厂商工具。
• portrait最终使用Floyd–Steinberg、有序抖动还是无抖动。
• RLCD人物的gamma、对比度、锐化和默认抖动参数。
• 是否需要OpenCV局部对比度处理。
• 各Profile的自动验收阈值与人工评审表。