# 图像压缩编解码器：QOI 与 RLE

EmbeddedGUI 提供两种轻量级图像压缩编解码器，用于减少嵌入式系统的 ROM 占用：**QOI**（Quite OK Image）和 **RLE**（Run-Length Encoding）。两者均为无损压缩，解码端无需额外内存分配，适配 PFB 逐行渲染架构。

## 编解码架构概览

```
       编码（PC / 构建时）                    解码（MCU / 运行时）
  ┌─────────────────────────┐           ┌──────────────────────────┐
  │ PNG/JPEG 原始图 (RGB888) │           │    PFB Tile Iteration    │
  │         ↓                │           │         ↓                │
  │  Pillow 解码为 raw 像素  │           │  egui_image_xxx_draw()   │
  │         ↓                │           │         ↓                │
  │  RGB565/RGB32 量化       │  ──C数组→  │  逐行解压到共享行缓冲    │
  │         ↓                │           │         ↓                │
  │  QOI/RLE 逐行压缩        │           │  blend_row → PFB buffer  │
  └─────────────────────────┘           └──────────────────────────┘
```

两种编解码器共享相同的资源生成管线和解码基础设施：
- **编码端**：`scripts/tools/img_codec_qoi.py`、`scripts/tools/img_codec_rle.py`
- **解码端**：`src/image/egui_image_qoi.c`、`src/image/egui_image_rle.c`
- **共享行缓冲**：`src/image/egui_image_decode_utils.c`（宽度 = 屏幕宽度）

## QOI 编解码器

### 原理

QOI（Quite OK Image）是一种基于差分和哈希索引的无损图像压缩格式，由 Dominic Szablewski 于 2021 年发布。其设计目标是实现接近 PNG 的压缩率，同时保持极低的编解码复杂度。

QOI 工作在 **RGB888/RGBA8888 色彩空间**，逐像素顺序处理。解码器维护以下状态：

| 状态 | 说明 |
|------|------|
| `prev_pixel` | 上一个已解码像素的 RGBA 值 |
| `index[64]` | 64 槽哈希颜色表，哈希函数：`(r*3 + g*5 + b*7 + a*11) & 63` |
| `run` | 当前游程计数（连续相同像素）|

每个像素通过以下 6 种操作码之一编码：

| 操作码 | 位模式 | 字节数 | 含义 |
|--------|--------|--------|------|
| `QOI_OP_INDEX` | `00xxxxxx` | 1 | 从 64 槽哈希表中查找，0 字节色彩数据 |
| `QOI_OP_DIFF` | `01xxxxxx` | 1 | 与前一像素的小差分 dr,dg,db ∈ [-2, +1] |
| `QOI_OP_LUMA` | `10xxxxxx` + 1 字节 | 2 | 基于亮度的中等差分，dg ∈ [-32, +31] |
| `QOI_OP_RUN` | `11xxxxxx` | 1 | 与前一像素相同，游程 1–62 |
| `QOI_OP_RGB` | `11111110` | 4 | 完整 RGB 值 |
| `QOI_OP_RGBA` | `11111111` | 5 | 完整 RGBA 值 |

**编码优先级**：RUN → INDEX → DIFF → LUMA → RGB/RGBA。解码器按照操作码前缀位即可确定类型，无需回溯。

### EGUI 中的适配

由于 EGUI 目标平台使用 **RGB565** 而非 RGB888，QOI 编解码在编码端和解码端做了色彩空间转换：

- **编码端（Python）**：将 RGB565 像素扩展为 RGB888 后再进行 QOI 编码。对于含 Alpha 通道的图像，Alpha 作为 RGBA 的第 4 通道编入 QOI 流
- **解码端（C）**：QOI 解码为 RGB888 后立即转换为 RGB565 写入行缓冲

这意味着存在 **两次量化损失**（RGB888→RGB565→RGB888→RGB565），但对于 16 位显示设备来说，单个颜色分量最大误差为 ±1 LSB，视觉上不可感知。

### 解码资源开销

| 资源 | 占用 |
|------|------|
| 解码状态 | ~280 字节（64×4 字节哈希表 + 控制变量） |
| 额外 ROM | 约 1.2 KB 代码 |
| 行缓冲 | 共享，屏幕宽度 × 4 字节 |

## RLE 编解码器

### 原理

RLE（Run-Length Encoding）是最经典的无损压缩算法之一。其核心思想是将连续相同的数据块替换为"计数 + 数据"的紧凑表示。

EGUI 的 RLE 实现采用 **LVGL 兼容** 的控制字节格式，直接在 **原始像素格式**（RGB565/RGB32/GRAY8）上操作，不做色彩空间转换：

| 控制字节 | 含义 |
|----------|------|
| `bit7=0` | **重复模式**：后续 `blk_size` 字节重复 `ctrl` 次 |
| `bit7=1` | **字面量模式**：后续 `(ctrl & 0x7F) × blk_size` 字节原样复制 |

`blk_size` 由像素格式决定：RGB565 = 2 字节，RGB32 = 4 字节，GRAY8 = 1 字节。每个控制字节最多编码 127 个像素块。

**编码约束**：RLE 编码 **逐行** 进行，游程不跨越行边界。这是为了适配 PFB 逐行解码——解码器每次调用恰好解压一行像素，如果游程跨行会导致解码流失同步。

Alpha 通道独立压缩为单独的 RLE 流（`blk_size=1`），解码时与像素数据分别处理。

### 编码策略

```
输入行: [A A A B C C D D D D D E]

控制字节:         解析为:
  0x03 A          重复 A × 3
  0x82 B C        字面量: B, C（2 块，bit7=1 → 0x80|2=0x82）
  0x05 D          重复 D × 5
  0x81 E          字面量: E（1 块）
```

判断逻辑：
1. 从当前位置向前扫描，统计连续相同块数
2. 若 ≥ 2 个连续相同：发出重复模式
3. 否则：收集后续不重复的块直到遇到下一段重复（≥2），发出字面量模式

### 解码资源开销

| 资源 | 占用 |
|------|------|
| 解码状态 | ~16 字节（流位置 + 行号） |
| 额外 ROM | 约 0.8 KB 代码 |
| 行缓冲 | 共享，屏幕宽度 × 4 字节 |

## 压缩率对比与分析

以下数据来自 `example/HelloBasic/image/` 的实际资源生成报告：

| 图像 | 特征 | 原始大小 | QOI | RLE |
|------|------|----------|-----|-----|
| test.png (80×80) | 自然照片，无透明 | 12,800 B | 13,781 B (**+8%**) | 10,884 B (**-15%**) |
| star.png (80×80) | 图标/图形，含透明+大面积纯色 | 19,200 B | 2,307 B (**-88%**) | 3,374 B (**-82%**) |

### 为什么 QOI 对自然照片反而膨胀？

QOI 在 RGB888 色彩空间工作，而原始数据是 RGB565（每像素 2 字节）。编码流程：

1. RGB565 像素（2 字节）→ 扩展为 RGB888（3 字节）
2. QOI 编码 RGB888 →压缩后每像素平均 > 2 字节

对于自然照片，相邻像素差异大、颜色丰富，QOI 的差分和哈希索引命中率低。此时 QOI 编码大部分像素需要使用 `QOI_OP_RGB`（4 字节/像素）或 `QOI_OP_LUMA`（2 字节），比原始 RGB565 的 2 字节/像素还多，导致 **压缩后反而变大**。

而 RLE 直接在 RGB565 上操作（`blk_size=2`），相邻像素即使只有少量重复，也能通过重复模式节省空间。自然照片中天空、地面等区域仍然有局部重复，因此 RLE 略有压缩效果（-15%）。

### 为什么 QOI 对图标可以压缩 88%？

star.png 是一个带透明通道的星形图标，具有以下特征：
- **大面积透明区域**：alpha=0 的像素占多数，颜色统一
- **纯色填充**：星形内部颜色变化极少
- **边缘锐利**：颜色跳变集中在少量像素

这些特征让 QOI 的各种操作码都能高效工作：
- 透明区域 → `QOI_OP_RUN`（1 字节编码最多 62 个相同像素）
- 纯色区域 → `QOI_OP_INDEX`（1 字节，哈希命中）
- 颜色跳变 → `QOI_OP_DIFF`/`QOI_OP_LUMA`（1-2 字节差分）

RLE 也表现优秀（-82%），主要受益于大面积连续相同像素的重复模式。但 QOI 在此场景下比 RLE 更优，因为它能在颜色变化时用差分编码，而 RLE 遇到不同像素必须切换为字面量模式（额外开销 1 字节控制字节 + 原始数据）。

## 适用场景选择指南

| 场景 | 推荐编解码器 | 原因 |
|------|-------------|------|
| **图标和 UI 图形** | QOI | 大面积纯色 + 透明，差分和哈希效率极高 |
| **含大面积透明的图片** | QOI 或 RLE | 两者都能高效压缩连续相同像素 |
| **自然照片（无透明）** | RLE | QOI 可能膨胀；RLE 至少略有压缩 |
| **自然照片（含透明）** | QOI | 透明通道内嵌流中，整体还是有良好的压缩 |
| **解码 RAM 极度受限** | RLE | 解码状态仅 16 字节 vs QOI 的 280 字节 |
| **MP4 视频帧** | 看内容而定 | 视频帧通常是自然场景，RLE 更安全 |
| **灰度图像** | RLE | `blk_size=1`，重复检测粒度最细 |

### 通用建议

1. **默认选 RLE**——它从不膨胀（最差情况每行增加 ceil(行像素/127) 个控制字节，大约 +1%），且解码资源开销最小
2. **图标/UI 元素优先试 QOI**——如果压缩率显著优于 RLE（>20%），就用 QOI
3. **自然照片慎用 QOI**——先看资源报告中的压缩率，如果显示膨胀（正数百分比），切回 RLE 或不压缩
4. **ROM 极度紧张时两者都试**——比较 `app_egui_resource_generate_report.md` 中的报告数字

## 启用方法

在应用的 `app_egui_config.h` 中添加：

```c
#define EGUI_CONFIG_FUNCTION_IMAGE_CODEC_QOI 1  /* 启用 QOI */
#define EGUI_CONFIG_FUNCTION_IMAGE_CODEC_RLE 1  /* 启用 RLE */
```

在 `app_resource_config.json` 的图像条目中指定 `compress` 字段：

```json
{
    "img": [
        {"file": "icon.png", "name": "icon_qoi", "compress": "qoi", "...": "..."},
        {"file": "photo.png", "name": "photo_rle", "compress": "rle", "...": "..."},
        {"file": "raw.png", "name": "raw_std", "compress": "none", "...": "..."}
    ]
}
```

运行 `make resource_refresh APP=<AppName>` 即可生成压缩后的 C 资源文件。

## 技术限制

| 限制 | 说明 |
|------|------|
| 不支持 resize 渲染 | 压缩图像无法在渲染时缩放，需预生成目标尺寸 |
| 不支持随机访问 get_point | 必须从头顺序解码，不适合需要单点采样的场景 |
| PFB 多 tile 重复解码 | 当图像跨越多列 PFB tile 时，后续列需 reset 重新解码（性能代价，但正确性无影响） |
| 单实例静态状态 | QOI 和 RLE 各有一个全局解码状态，同时渲染多张同类型压缩图时会频繁 reset |

## 相关文件

| 文件 | 说明 |
|------|------|
| `scripts/tools/img_codec_qoi.py` | QOI Python 编码器 |
| `scripts/tools/img_codec_rle.py` | RLE Python 编码器 |
| `scripts/tools/img2c.py` | 图像转 C 数组工具（调用上述编码器） |
| `src/image/egui_image_qoi.h/c` | QOI C 解码器 |
| `src/image/egui_image_rle.h/c` | RLE C 解码器 |
| `src/image/egui_image_decode_utils.h/c` | 共享行缓冲与 blend 函数 |
| `example/HelloBasic/image/` | 静态图像对比示例（STD / QOI / RLE） |
| `example/HelloBasic/mp4/` | MP4 视频帧对比示例（STD / QOI / RLE） |