506 lines
14 KiB
Markdown
506 lines
14 KiB
Markdown
# LCD PNG 存储优化实施报告
|
||
|
||
## 1. 基本信息
|
||
|
||
- 对应提交：`549f495 perf(assets): optimize LCD PNG storage`
|
||
- 目标设备：ESP32-S3
|
||
- LCD 分辨率：320×240
|
||
- LCD 像素格式：RGB565
|
||
- 资源分区：`gifpack` LittleFS，容量 2 MiB
|
||
- 优化范围：59 张 PNG 图片
|
||
|
||
本次工作的主要目标是缓解 `gifpack` 分区的存储压力，同时保证 LCD 最终显示的 RGB565 像素不发生变化。
|
||
|
||
本次工作不修改 LCD 驱动、PNG 运行时解码器、帧缓存数量和动画播放接口。
|
||
|
||
## 2. 问题现象
|
||
|
||
优化前，59 张 PNG 的总容量为：
|
||
|
||
```text
|
||
1,069,465 字节
|
||
```
|
||
|
||
将原始图片、语音资源和 LittleFS 元数据一起打包后，`gifpack` 分区的实际占用为：
|
||
|
||
```text
|
||
已使用：407 / 512 块
|
||
使用率：79.5%
|
||
剩余空间：430,080 字节
|
||
```
|
||
|
||
虽然单张图片的分辨率只有 320×240，但资源分区已经接近容量警戒线，继续增加动画帧会快速消耗剩余空间。
|
||
|
||
## 3. 问题原因
|
||
|
||
### 3.1 图片携带了未使用的 Alpha 通道
|
||
|
||
现有资源中大部分 PNG 是 RGBA 格式，每个像素在红、绿、蓝之外还带有 Alpha 透明度。
|
||
|
||
检查全部资源后发现，所有图片的 Alpha 范围均为：
|
||
|
||
```text
|
||
255～255
|
||
```
|
||
|
||
这表示所有像素都完全不透明，Alpha 通道虽然存在，但没有实际提供透明效果。
|
||
|
||
PNG 会压缩重复的 Alpha 数据，因此删除 Alpha 不会正好节省 25%，但仍然可以减少文件体积。
|
||
|
||
### 3.2 原始图片保存了 LCD 无法显示的颜色精度
|
||
|
||
普通 RGB PNG 通常使用 RGB888：
|
||
|
||
```text
|
||
红色 8 位 + 绿色 8 位 + 蓝色 8 位 = 24 位
|
||
```
|
||
|
||
LCD 实际使用 RGB565：
|
||
|
||
```text
|
||
红色 5 位 + 绿色 6 位 + 蓝色 5 位 = 16 位
|
||
```
|
||
|
||
现有固件在 PNG 解码后，本来就会丢弃 LCD 无法显示的低位颜色精度。运行时转换公式为：
|
||
|
||
```c
|
||
uint16_t rgb565 =
|
||
((red & 0xF8) << 8) |
|
||
((green & 0xFC) << 3) |
|
||
(blue >> 3);
|
||
```
|
||
|
||
因此，原始 PNG 中的一部分颜色信息虽然占用 Flash，但最终不会发送到 LCD。
|
||
|
||
### 3.3 RGB565 对齐后，实际颜色数量很少
|
||
|
||
原始图片中的 RGB888 颜色数量为每张 66～1383 种。
|
||
|
||
提前对齐到 RGB565 后，每张图片只剩：
|
||
|
||
```text
|
||
53～240 种颜色
|
||
```
|
||
|
||
全部低于索引色 PNG 的 256 色上限，因此可以使用一个字节的调色板编号表示像素，而不必为每个像素重复保存完整 RGB 数值。
|
||
|
||
### 3.4 构建系统原来直接打包原始 PNG
|
||
|
||
原构建流程直接从 `components/platform/assets/lcd` 复制 PNG 到构建目录，然后制作 `gifpack.bin`，没有区分设计原图和固件优化图，也没有资源同步检查。
|
||
|
||
## 4. 解决方案
|
||
|
||
本次采用“原图和优化图同时提交到 Git”的方案。
|
||
|
||
目录职责调整为：
|
||
|
||
```text
|
||
components/platform/assets/
|
||
├── lcd_source/ 原始设计图片，不打包进固件
|
||
└── lcd_optimized/ 优化图片，固件实际打包
|
||
```
|
||
|
||
正常固件构建只读取 `lcd_optimized`，不需要安装 Pillow。
|
||
|
||
修改图片时，从 `lcd_source` 重新生成全部优化图片，并通过清单和逐像素验证保证结果可靠。
|
||
|
||
完整处理流程为：
|
||
|
||
```text
|
||
原始 PNG
|
||
↓ 检查 Alpha
|
||
删除未使用的 Alpha
|
||
↓
|
||
颜色精度对齐到 RGB565
|
||
↓
|
||
统计 RGB565 颜色数量
|
||
↓
|
||
不超过 256 色时生成索引色 PNG
|
||
↓
|
||
逐像素验证 RGB565 等价性
|
||
↓
|
||
生成 manifest.json
|
||
↓
|
||
提交优化图片并打包到 gifpack
|
||
```
|
||
|
||
## 5. 关键代码
|
||
|
||
### 5.1 RGB888 对齐到 RGB565 精度
|
||
|
||
生成工具先截取 RGB565 有效位，再将其展开成标准 PNG 能保存的 RGB888 数值：
|
||
|
||
```python
|
||
def expand_rgb565(pixel: tuple[int, int, int]) -> tuple[int, int, int]:
|
||
red, green, blue = pixel
|
||
red5 = red >> 3
|
||
green6 = green >> 2
|
||
blue5 = blue >> 3
|
||
return (
|
||
(red5 << 3) | (red5 >> 2),
|
||
(green6 << 2) | (green6 >> 4),
|
||
(blue5 << 3) | (blue5 >> 2),
|
||
)
|
||
```
|
||
|
||
展开后的图片仍是标准 PNG，但其中每种颜色都能稳定映射回相同的 RGB565 数值。
|
||
|
||
### 5.2 防止误删有效透明度
|
||
|
||
当前方案不处理透明叠加。如果发现透明或半透明像素，生成过程会立即失败：
|
||
|
||
```python
|
||
rgba = source_image.convert("RGBA")
|
||
alpha_min, alpha_max = rgba.getchannel("A").getextrema()
|
||
|
||
if (alpha_min, alpha_max) != (255, 255):
|
||
raise AssetError(
|
||
f"Transparency is not supported by the RGB565 optimizer: "
|
||
f"{source_path.name} has alpha range "
|
||
f"({alpha_min}, {alpha_max})"
|
||
)
|
||
```
|
||
|
||
这样不会因为资源优化而静默破坏未来新增的透明图片。
|
||
|
||
### 5.3 生成无额外量化损失的索引色 PNG
|
||
|
||
脚本根据已经完成 RGB565 对齐的实际颜色建立调色板，不调用普通的自动 256 色量化：
|
||
|
||
```python
|
||
palette_colors = sorted(set(pixels))
|
||
|
||
if len(palette_colors) > 256:
|
||
raise AssetError("Indexed PNG requested with more than 256 colors")
|
||
|
||
palette_index = {
|
||
color: index
|
||
for index, color in enumerate(palette_colors)
|
||
}
|
||
|
||
indices = bytes(palette_index[pixel] for pixel in pixels)
|
||
indexed = image_module.frombytes("P", size, indices)
|
||
|
||
flat_palette = [
|
||
channel
|
||
for color in palette_colors
|
||
for channel in color
|
||
]
|
||
flat_palette.extend([0] * (768 - len(flat_palette)))
|
||
|
||
indexed.putpalette(flat_palette)
|
||
indexed.save(
|
||
output,
|
||
format="PNG",
|
||
optimize=True,
|
||
compress_level=9,
|
||
)
|
||
```
|
||
|
||
如果未来某张图片在 RGB565 对齐后仍超过 256 种颜色，工具会保存为普通 RGB PNG，而不是强行合并颜色：
|
||
|
||
```python
|
||
if color_count <= 256:
|
||
output_mode = "indexed"
|
||
save_indexed_png(
|
||
image_module,
|
||
source_rgb.size,
|
||
rgb565_pixels,
|
||
output_path,
|
||
)
|
||
else:
|
||
output_mode = "rgb"
|
||
optimized_rgb = image_module.new("RGB", source_rgb.size)
|
||
optimized_rgb.putdata(rgb565_pixels)
|
||
optimized_rgb.save(
|
||
output_path,
|
||
format="PNG",
|
||
optimize=True,
|
||
compress_level=9,
|
||
)
|
||
```
|
||
|
||
### 5.4 逐像素验证 LCD 输出一致
|
||
|
||
原图和优化图都会重新计算 RGB565 数值，并逐像素比较：
|
||
|
||
```python
|
||
def rgb565_value(pixel: tuple[int, int, int]) -> int:
|
||
red, green, blue = pixel
|
||
return (
|
||
((red & 0xF8) << 8)
|
||
| ((green & 0xFC) << 3)
|
||
| (blue >> 3)
|
||
)
|
||
|
||
|
||
for index, (source_pixel, optimized_pixel) in enumerate(
|
||
zip(
|
||
source_rgb.get_flattened_data(),
|
||
optimized_rgb.get_flattened_data(),
|
||
)
|
||
):
|
||
if rgb565_value(source_pixel) != rgb565_value(optimized_pixel):
|
||
x = index % source_rgb.width
|
||
y = index // source_rgb.width
|
||
raise AssetError(
|
||
f"RGB565 mismatch at ({x}, {y})"
|
||
)
|
||
```
|
||
|
||
这里验证的是 LCD 实际接收的 RGB565 数值，而不是电脑上查看时的 RGB888 数值。
|
||
|
||
### 5.5 通过清单检查资源是否过期
|
||
|
||
`manifest.json` 保存原图和优化图的 SHA-256、尺寸、颜色数和文件大小。
|
||
|
||
普通构建只使用 Python 标准库重新计算哈希，不导入 Pillow：
|
||
|
||
```python
|
||
for name in sorted(source_names & manifest_names):
|
||
source_path = SOURCE_DIR / name
|
||
if sha256_file(source_path) != assets[name].get("source_sha256"):
|
||
errors.append(
|
||
f"Source asset changed after optimization: {name}"
|
||
)
|
||
|
||
for name in sorted(optimized_names & manifest_names):
|
||
optimized_path = OPTIMIZED_DIR / name
|
||
if sha256_file(optimized_path) != assets[name].get("optimized_sha256"):
|
||
errors.append(
|
||
f"Optimized asset changed after generation: {name}"
|
||
)
|
||
```
|
||
|
||
原图修改后如果忘记重新生成优化图，固件构建会失败，不会继续打包过期资源。
|
||
|
||
### 5.6 构建系统只打包优化资源
|
||
|
||
CMake 中分别声明原图目录、优化图目录、清单和生成工具：
|
||
|
||
```cmake
|
||
set(
|
||
platform_lcd_asset_source_dir
|
||
"${CMAKE_CURRENT_SOURCE_DIR}/assets/lcd_source"
|
||
)
|
||
set(
|
||
platform_lcd_asset_src_dir
|
||
"${CMAKE_CURRENT_SOURCE_DIR}/assets/lcd_optimized"
|
||
)
|
||
set(
|
||
platform_lcd_asset_manifest
|
||
"${platform_lcd_asset_src_dir}/manifest.json"
|
||
)
|
||
set(
|
||
platform_lcd_asset_optimizer
|
||
"${CMAKE_CURRENT_SOURCE_DIR}/../../tools/optimize_lcd_assets.py"
|
||
)
|
||
```
|
||
|
||
制作资源镜像前执行轻量同步检查：
|
||
|
||
```cmake
|
||
add_custom_command(
|
||
OUTPUT "${platform_asset_stage_stamp}"
|
||
COMMAND
|
||
${PYTHON}
|
||
"${platform_lcd_asset_optimizer}"
|
||
check-current
|
||
COMMAND
|
||
${CMAKE_COMMAND} -E rm -rf
|
||
"${platform_asset_image_dir}"
|
||
COMMAND
|
||
${CMAKE_COMMAND} -E make_directory
|
||
"${platform_asset_image_dir}"
|
||
${platform_asset_stage_commands}
|
||
COMMAND
|
||
${CMAKE_COMMAND} -E touch
|
||
"${platform_asset_stage_stamp}"
|
||
DEPENDS
|
||
${platform_audio_prompt_files}
|
||
${platform_lcd_source_png_files}
|
||
${platform_lcd_png_asset_files}
|
||
"${platform_lcd_asset_manifest}"
|
||
"${platform_lcd_asset_optimizer}"
|
||
)
|
||
```
|
||
|
||
最终进入设备的路径仍然是：
|
||
|
||
```text
|
||
/lcd/<图片名称>.png
|
||
```
|
||
|
||
运行时代码不需要修改资源路径。
|
||
|
||
## 6. 使用方式
|
||
|
||
### 6.1 普通固件构建
|
||
|
||
正常构建不生成图片，也不需要 Pillow：
|
||
|
||
```bash
|
||
idf.py build
|
||
```
|
||
|
||
### 6.2 准备图片生成环境
|
||
|
||
```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
|
||
```
|
||
|
||
### 6.3 修改图片后重新生成
|
||
|
||
只修改 `components/platform/assets/lcd_source` 中的原图，然后执行：
|
||
|
||
```bash
|
||
python tools/optimize_lcd_assets.py generate
|
||
python tools/optimize_lcd_assets.py verify
|
||
idf.py build
|
||
```
|
||
|
||
需要同时提交：
|
||
|
||
```text
|
||
lcd_source 中修改的原图
|
||
lcd_optimized 中重新生成的图片
|
||
lcd_optimized/manifest.json
|
||
```
|
||
|
||
### 6.4 只检查资源是否同步
|
||
|
||
以下命令不需要 Pillow：
|
||
|
||
```bash
|
||
python3 tools/optimize_lcd_assets.py check-current
|
||
```
|
||
|
||
## 7. 解决成果
|
||
|
||
### 7.1 PNG 文件容量
|
||
|
||
```text
|
||
优化前：1,069,465 字节
|
||
优化后： 381,384 字节
|
||
减少： 688,081 字节
|
||
降幅： 64.3%
|
||
```
|
||
|
||
59 张图片全部成功保存为索引色 PNG。
|
||
|
||
### 7.2 LittleFS 分区占用
|
||
|
||
`gifpack` 的块大小为 4096 字节，总计 512 块。
|
||
|
||
| 状态 | 已使用块 | 使用率 | 剩余空间 |
|
||
| --- | ---: | ---: | ---: |
|
||
| 原始图片模拟打包 | 407 / 512 | 79.5% | 430,080 字节 |
|
||
| 优化图片实际构建 | 236 / 512 | 46.1% | 1,130,496 字节 |
|
||
|
||
分区内部新增可用空间：
|
||
|
||
```text
|
||
700,416 字节 = 684 KiB
|
||
```
|
||
|
||
`gifpack.bin` 的文件大小仍然固定为 2 MiB，因为它是完整分区镜像。优化释放的是 LittleFS 内部空间，不会缩小分区镜像，也不会自动把空间转移给应用程序分区。
|
||
|
||
### 7.3 显示一致性
|
||
|
||
验证结果：
|
||
|
||
```text
|
||
LCD assets are current: 59 files
|
||
RGB565 display equivalence verified: 59 files
|
||
```
|
||
|
||
59 张图片的 RGB565 输出全部逐像素一致。
|
||
|
||
### 7.4 构建验证
|
||
|
||
ESP-IDF v5.5.4 完整构建通过，并确认构建顺序为：
|
||
|
||
```text
|
||
检查资源清单
|
||
→ 复制 lcd_optimized
|
||
→ 制作 gifpack.bin
|
||
→ 完成固件构建
|
||
```
|
||
|
||
## 8. 后续影响
|
||
|
||
### 8.1 正面影响
|
||
|
||
- `gifpack` 使用率由 79.5% 降至 46.1%。
|
||
- 增加 684 KiB 可用资源空间。
|
||
- 按当前图片复杂度估算，还可安全增加约 80～100 张全屏帧。
|
||
- Flash 读取的 PNG 数据减少，首次加载可能略有改善。
|
||
- 原图被完整保留，可以随时重新生成固件资源。
|
||
- 构建会阻止过期或被手动篡改的优化图片进入固件。
|
||
|
||
### 8.2 不变的部分
|
||
|
||
- PNG 文件名和设备内路径不变。
|
||
- LCD 驱动和动画播放接口不变。
|
||
- 当前 PNG 解码器仍会先展开为 RGBA，再转换为 RGB565。
|
||
- 解码后的帧缓存大小不变。
|
||
- 帧缓存数量不变。
|
||
- SPI 传输速度不变。
|
||
- `gifpack` 分区大小仍为 2 MiB。
|
||
|
||
因此，本次优化主要解决 Flash 容量问题，不应把 64.3% 的文件缩减直接等同于 64.3% 的帧率提升或运行时内存下降。
|
||
|
||
### 8.3 开发流程影响
|
||
|
||
- 普通固件编译不依赖 Pillow。
|
||
- 修改图片的开发者需要安装 `tools/requirements-assets.txt` 中固定版本的 Pillow。
|
||
- 不应手动修改 `lcd_optimized`。
|
||
- 每次必须从 `lcd_source` 重新生成，不能反复压缩优化图。
|
||
- 添加新图片时，除了生成优化图，还需要把图片名称加入 CMake 资源清单。
|
||
- 删除图片时，需要同时删除原图并更新 CMake 资源清单。
|
||
|
||
### 8.4 仓库容量影响
|
||
|
||
原图和优化图都会提交到 Git，因此代码仓库本身会增加约 381 KiB 当前工作树容量，并产生对应的 Git 历史对象。
|
||
|
||
这是方案 B 的预期取舍：用一定的仓库容量换取普通构建不依赖 Pillow，并确保任何开发机都能直接使用已经验证过的优化资源构建固件。
|
||
|
||
### 8.5 未来透明图片
|
||
|
||
当前工具发现 Alpha 不全为 255 时会直接失败。
|
||
|
||
如果未来需要透明叠加效果，需要先明确：
|
||
|
||
- 透明度由运行时软件合成还是预先合成；
|
||
- 是否需要支持索引 PNG 的透明表；
|
||
- LCD 背景和前景的混合规则；
|
||
- 是否需要保留完整 Alpha 精度。
|
||
|
||
在透明处理方案完成前，不应绕过该检查。
|
||
|
||
### 8.6 未来高色彩图片
|
||
|
||
如果未来图片在 RGB565 对齐后超过 256 种颜色，工具会自动使用 RGB PNG，保证显示正确，但文件会比索引 PNG 更大。
|
||
|
||
普通照片、大面积渐变和噪声纹理通常比当前卡通资源更难压缩，因此新增图片数量不能只按当前平均值机械计算，应在每次资源更新后重新检查 `manifest.json` 和 LittleFS 实际块占用。
|
||
|
||
### 8.7 高色深屏幕上的查看差异
|
||
|
||
优化图已经针对 RGB565 精度制作。在电脑等高色深屏幕上直接查看时，可能与原始 RGB888 图片存在轻微颜色差异。
|
||
|
||
这不代表 LCD 显示发生退化。对当前 RGB565 LCD 而言，优化前后的最终像素完全一致。
|
||
|
||
## 9. 后续可选优化
|
||
|
||
如果未来需要继续改善加载速度或运行时内存，可以单独评估：
|
||
|
||
1. 让 PNG 解码器输出调色板索引或 RGB 数据，减少 RGBA 中间缓冲。
|
||
2. 增加索引 PNG 到 RGB565 的直接查表路径。
|
||
3. 按行解码并写入 RGB565，降低峰值内存。
|
||
4. 测量首次解码、缓存填充和 SPI 传输分别占用的时间。
|
||
|
||
这些优化会修改运行时解码路径，风险和测试范围明显大于本次 Flash 资源优化，建议作为独立提交实施。
|