102 lines
4.1 KiB
Markdown
102 lines
4.1 KiB
Markdown
# LCD 图片资源优化与维护
|
|
|
|
## 目标
|
|
|
|
固件使用的 LCD 为 RGB565 显示格式，而设计工具导出的 PNG 通常是 RGB888 或 RGBA8888。原始 PNG 中包含 LCD 无法显示的颜色精度，部分图片还携带未实际使用的 Alpha 通道。
|
|
|
|
本项目在不改变 LCD 最终 RGB565 像素的前提下，将固件图片转换成 RGB565 颜色精度，并在颜色数量不超过 256 时保存为索引色 PNG，以降低 `gifpack` LittleFS 分区的占用。
|
|
|
|
正常固件编译直接使用已经提交到 Git 的优化图片，不要求开发环境安装 Pillow。只有修改或验证图片资源时才需要 Pillow。
|
|
|
|
## 目录结构
|
|
|
|
```text
|
|
components/platform/assets/
|
|
├── lcd_source/ 原始设计图片，不直接打包进固件
|
|
└── lcd_optimized/ 优化图片和 manifest.json，固件实际使用
|
|
```
|
|
|
|
两个目录中的 PNG 文件名必须一致。运行时路径仍为 `/lcd/<文件名>.png`，业务代码不需要区分原图和优化图。
|
|
|
|
`lcd_source` 中的 `OTA.gif` 是历史资源，不属于当前 PNG 优化和 `gifpack` 打包清单。
|
|
|
|
## 优化规则
|
|
|
|
脚本 `tools/optimize_lcd_assets.py` 对每张 PNG 执行以下操作：
|
|
|
|
1. 检查图片尺寸和 Alpha 范围。
|
|
2. Alpha 全部为 255 时移除无用的 Alpha 通道。
|
|
3. 将 RGB888 颜色对齐到 LCD 的 RGB565 精度。
|
|
4. RGB565 颜色不超过 256 种时保存为索引色 PNG。
|
|
5. 超过 256 种颜色时保存为普通 RGB PNG，不进行额外颜色合并。
|
|
6. 逐像素比较原图和优化图转换后的 RGB565 数值。
|
|
7. 生成包含文件哈希、尺寸、颜色数和容量的 `manifest.json`。
|
|
|
|
只要有一个 RGB565 像素不同，生成操作就会失败。发现透明或半透明图片时也会停止，避免静默删除有效透明度。
|
|
|
|
## 首次准备环境
|
|
|
|
建议使用独立 Python 虚拟环境，避免修改系统 Python：
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
. .venv/bin/activate
|
|
python -m pip install -r tools/requirements-assets.txt
|
|
python tools/optimize_lcd_assets.py check-env
|
|
```
|
|
|
|
ESP-IDF 自带的 Python 环境如果已经安装对应版本的 Pillow，也可以直接使用。
|
|
|
|
## 修改图片后的操作
|
|
|
|
只修改 `lcd_source` 中的原图，不要手动编辑 `lcd_optimized`。
|
|
|
|
生成全部优化图片：
|
|
|
|
```bash
|
|
python tools/optimize_lcd_assets.py generate
|
|
```
|
|
|
|
执行完整的 RGB565 等价验证：
|
|
|
|
```bash
|
|
python tools/optimize_lcd_assets.py verify
|
|
```
|
|
|
|
然后检查并提交以下内容：
|
|
|
|
```text
|
|
components/platform/assets/lcd_source/
|
|
components/platform/assets/lcd_optimized/
|
|
components/platform/assets/lcd_optimized/manifest.json
|
|
```
|
|
|
|
不要反复处理 `lcd_optimized` 中的图片。每次必须从 `lcd_source` 原图重新生成，避免累计颜色或压缩处理误差。
|
|
|
|
## 普通固件编译
|
|
|
|
普通构建不生成图片，也不导入 Pillow。构建系统只执行基于 Python 标准库的哈希检查，确认：
|
|
|
|
- 原图没有在生成后发生变化；
|
|
- 优化图片没有缺失或被手动修改；
|
|
- 原图、优化图和清单中的文件集合一致。
|
|
|
|
资源过期时，构建会停止并提示重新运行 `generate`。资源有效时，构建系统把 `lcd_optimized` 中的 PNG 复制到构建目录并生成 `gifpack` 分区镜像。
|
|
|
|
## 命令说明
|
|
|
|
| 命令 | 是否需要 Pillow | 用途 |
|
|
| --- | --- | --- |
|
|
| `check-env` | 是 | 检查 Python 和 Pillow 环境 |
|
|
| `generate` | 是 | 从原图重新生成全部优化图片和清单 |
|
|
| `check-current` | 否 | 通过哈希检查已提交资源是否同步 |
|
|
| `verify` | 是 | 检查哈希并逐像素验证 RGB565 等价性 |
|
|
|
|
## 注意事项
|
|
|
|
- 优化图片针对 RGB565 LCD 制作，在高色深电脑屏幕上查看时可能与原始图片有细微颜色差异。
|
|
- 对当前 LCD 而言，优化前后的输出像素完全一致。
|
|
- 该方案主要降低 Flash 占用，不改变运行时 PNG 解码流程、帧缓存大小或动画播放接口。
|
|
- 如果未来需要透明叠加效果，应先扩展转换和运行时合成方案，不能直接删除 Alpha。
|
|
- 不要使用普通的“自动量化到 256 色”工具替代本脚本，否则可能合并 LCD 原本能够区分的颜色。
|