refactor(HDMI-Tool): 划分 src/assets/release 三区目录, 补齐人读/AI 读双文档与发布流水线

HDMI-Tool/README.md

@@ -1,7 +1,13 @@
-# HDMI-Tool — HDMI 源端测试工具（LT8619C/DLPC3421 转接板调试）
+# HDMI-Tool — HDMI 源端调试工具
 
-> 更新：2026-09-04。单文件 Python GUI（`hdmi_gui.py`），另附命令行分辨率/图案工具
-> `hdmi_source.bat`。已打包版直接双击 `HDMI-Tool.exe`，无需安装 Python。
+> LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板调试配套的 PC 端工具：
+> 在 HDMI **源端**（电脑显卡输出）完成 EDID 查看、分辨率切换、纯色/测试图案全屏投屏。
+>
+> - **只想用工具**：到 [Gitea Releases](https://gitea.hulk.wang/hulk/LT8619C_Debug_Tools/releases)
+>   下载 `HDMI-Tool-vX.Y.Z-win64.zip`，解压双击 `HDMI-Tool.exe` 即可（Windows 10/11 x64，免安装、无需 Python）。
+> - **要改代码/重新打包**：见 §7、§8。
+>
+> 更新：2026-09-10
 
 ---
 
@@ -9,45 +15,94 @@
 
 | 功能 | 说明 |
 |---|---|
-| EDID 查看 | 枚举各显示输出口，从注册表读取 EDID 原始数据，按 EDID 1.4/CEA-861 解算：厂商/型号/尺寸/支持模式（DTD/已建立/标准/CEA-VIC）/首选时序完整参数/校验和 |
-| EDID 逐字节解析 | "EDID 原始数据"框右上"逐字节解析"按钮：按偏移逐字段展开基础块（同步头/厂商/产品/序列/版本/输入类型/尺寸/Gamma/特性位/色度/已建立+标准时序/4×描述符/扩展块数/校验和）与 CTA-861 扩展块（tag/版本/DTD 偏移/标志位/数据块链/扩展 DTD 区/校验和），每字段附原始字节 hex，自动换行；命令行等价 `--edid-fields` |
-| 分辨率切换 | 第二行"分辨率"下拉列出显卡按该屏 EDID 提供的全部模式；**应用**=临时切换（不写注册表，重启还原），**恢复**=回到本次会话切改前的模式 |
-| 测试图案 | 全屏投到所选显示器，测试卡区域可选 `640x360 / 800x600 / full 铺满`；内置 纯红/纯绿/纯蓝/棋盘格/网格线 + R/G/B 三行纯色值按钮（55/AA/FF，与 dist 下 solid_*.png 对应）+ 3 个自定义图片栏位 |
-| 命令行模式 | 自动化测试脚本可直接调用（见 §4） |
+| EDID 查看 | 枚举各显示输出口，从注册表读取 EDID 原始数据，按 EDID 1.4/CEA-861 解算：厂商/型号/尺寸/Gamma/输入类型/支持模式（DTD/已建立/标准/CEA-VIC）/首选时序完整参数/校验和 |
+| EDID 逐字节解析 | "EDID 原始数据"框右上"逐字节解析"按钮：按偏移逐字段展开基础块与 CTA-861 扩展块，每字段附原始字节 hex；命令行等价 `--edid-fields` |
+| 分辨率切换 | "分辨率"下拉列出显卡按该屏 EDID 提供的全部模式；**应用**=临时切换（不写注册表，重启/恢复即还原），**恢复**=回到本次会话切改前的模式 |
+| 测试图案投屏 | 全屏投到所选显示器，测试卡区域可选 `640x360 / 800x600 / full 铺满`；内置 纯红/纯绿/纯蓝/黑白棋盘格/网格线 + R/G/B 三行 55/AA/FF 纯色值按钮 + 3 个自定义图片栏位 |
+| 显示拓扑控制 | 启动时强制扩展显示拓扑（复制/仅第二屏等模式下保证 demo 板屏幕独立可控） |
+| 命令行模式 | 全部功能可脚本化调用，供自动化测试（见 §5、§6） |
+| 波形分析脚本 | 逻辑分析仪 CSV 波形按占空比签名分段，输出行结构/占空比/消隐明细（见 §6.3） |
 
-## 2. 快速上手（GUI）
+## 2. 下载与安装
 
-1. 双击 `HDMI-Tool.exe`（或 `python hdmi_gui.py`，需 Python ≥3.10 + pyserial 不需要，纯标准库；自定义图片 JPG/BMP 需 Pillow）
-2. 顶部显示器下拉选择目标屏（多屏时注意别选成主屏），"刷新"重新枚举
-3. **切分辨率**：第二行选模式 → 点"应用"；测完点"恢复"
-4. **投测试图**：
-   - 先在图案按钮行右侧选**测试卡区域**（640x360 / 800x600 / full）
-   - 点图案按钮即全屏投放；按 **ESC** 退出
-   - R/G/B 三行纯色按钮（55/AA/FF）用于位交换类测试：55 与 AA 互为字节镜像对，FF 为全高基准
-   - 自定义图片：点"⚙"配置名称与图片文件（图片会复制到本目录），点栏位名投放
-5. 区域与自定义栏位配置自动保存在本目录 `pattern_slots.json`
+1. 打开 [Releases 页面](https://gitea.hulk.wang/hulk/LT8619C_Debug_Tools/releases)，取最新的
+   `HDMI-Tool-vX.Y.Z-win64.zip`；
+2. 解压到**任意可写目录**（自定义图片与栏位配置会写到 exe 旁边）；
+3. 双击 `HDMI-Tool.exe`。首次启动比脚本慢一两秒（onefile 解压），属正常现象。
 
-## 3. 典型场景（LT8619C demo 板测试）
+包内包含：
+
+```
+HDMI-Tool/
+├── HDMI-Tool.exe        主程序（单文件，自包含）
+├── pattern_slots.json   预置自定义栏位（指向下面的 bw 图案）
+├── bw_*.png  ×5         640x360 黑白测试图
+├── solid_*.png ×10      800x600 纯色测试图
+└── README.md            本说明
+```
+
+## 3. GUI 使用
+
+主窗口自上而下三块区域：
+
+```
+┌ 显示器: [GDI ... ▼] [刷新]   [拓扑: 扩展 ▼] ┐
+├ 分辨率: [800x600@60 ▼] [应用] [恢复]        ┐
+├ ── EDID 原始数据 ──────────── [逐字节解析] ─┤
+│  (hex 文本框)                               │
+├ 测试卡区域: (○640x360 ○800x600 ○full)       ┤
+├ [纯红][纯绿][纯蓝][棋盘格][网格线]           │ ← 图案按钮
+├ R: [55][AA][FF]   G: [55][AA][FF]   B: [55][AA][FF] │ ← 纯色值按钮
+├ [自定义1][自定义2][自定义3]         [⚙]      │ ← 自定义栏位
+└─────────────────────────────────────────────┘
+```
+
+1. 顶部显示器下拉选择目标屏（多屏时注意别选成主屏），"刷新"重新枚举；
+2. **切分辨率**：第二行选模式 → "应用"；测完点"恢复"；
+3. **投测试图**：
+   - 先在图案按钮行上方选**测试卡区域**（640x360 / 800x600 / full）；
+   - 点任意图案按钮即全屏投放；按 **ESC** 或点击退出；
+   - R/G/B 三行纯色按钮（55/AA/FF）用于 RGB 位交换类测试：55(01010101) 与
+     AA(10101010) 互为字节镜像对，FF(11111111) 为全高基准；
+   - 自定义图片：点"⚙"配置名称与图片文件（图片会自动复制到 exe 旁边），点栏位名投放；
+4. 测试卡区域与自定义栏位配置自动保存在 exe 旁的 `pattern_slots.json`。
+
+## 4. 典型测试场景
 
 ```
 1. HDMI 接 demo 板 → 启动 HDMI-Tool → 刷新 → 选中 demo 板显示器
 2. 分辨率切 800x600@60（demo 板 shadow EDID 首选）→ 测试卡区域选 800x600
-3. 点 R/G/B 行的纯色按钮投图 → 配合逻辑分析仪/万用表测 RGB 输出
-4. 测完"恢复"分辨率
+3. 点 R/G/B 行纯色按钮投图 → 配合逻辑分析仪/万用表测转接板 RGB888 输出
+   - 纯红/绿/蓝：验证通道映射（R=D[23:16], G=D[15:8], B=D[7:0]）
+   - 55/AA 对：验证位交换（0x606E）——图像应为 50% 灰阶占空比
+4. 换 bw 图案（西门子星/波带片）看极限分辨率与混叠
+5. 测完"恢复"分辨率
 ```
 
-## 4. 命令行模式
+寄存器语义（0x606E 位交换 / 0x606D 整组顺序）的判读基线见上游主仓库
+[LT8619C_DLPC3421_HDMI](https://gitea.hulk.wang/hulk/LT8619C_DLPC3421_HDMI) 的
+`doc/architecture/`。
+
+## 5. 命令行模式（hdmi_gui.py）
+
+exe 版不支持 `--dump/--edid-fields`（noconsole 无控制台输出），请用源码方式跑：
 
 ```
-python hdmi_gui.py --dump                          控制台输出 EDID 解算（exe 版不支持）
-python hdmi_gui.py --edid-fields                   控制台输出 EDID 逐字节字段解析表（exe 版不支持）
+python hdmi_gui.py --dump                          控制台输出 EDID 解算
+python hdmi_gui.py --edid-fields                   控制台输出 EDID 逐字节字段解析表
 python hdmi_gui.py --test-pattern Blue --area 800x600 --seconds 5
                                                    出图 5 秒自动退出
 python hdmi_gui.py --test-pattern Custom1          投自定义栏位 1
-  --area {640x360,800x600,full}  --monitor N  --seconds S
+python hdmi_gui.py --seconds 5                     GUI 冒烟测试, 5 秒自动关
+  --test-pattern {Red,Green,Blue,Checker,Grid,Custom1..3}
+  --area {640x360,800x600,full}   --monitor N   --seconds S
 ```
 
-**hdmi_source.bat**（PowerShell 源端工具，功能与 GUI 互补）：
+## 6. 辅助脚本（src/ 下）
+
+### 6.1 hdmi_source.bat / .ps1 — 源端命令行工具
+
+与 GUI 互补，适合脚本串联：
 
 ```
 tools\hdmi_source.bat -List                        枚举显示器与支持分辨率（验证 EDID）
@@ -56,23 +111,71 @@ tools\hdmi_source.bat -Mode 800x600 -Pattern -Restore
                                                    切模式→出图案→退出后自动恢复
 ```
 
-## 5. 目录内容
+### 6.2 gen_bw_patterns.py / gen_solid_colors.py — 测试图生成
 
-| 文件 | 用途 |
-|---|---|
-| `HDMI-Tool.exe` | 打包好的单文件版（--noconsole；`--dump` 请用源码方式跑） |
-| `hdmi_gui.py` | 主程序源码 |
-| `build_exe.py` | 打包脚本（`python build_exe.py`，自动装 PyInstaller；`--debug` 额外出带控制台版） |
-| `hdmi_source.ps1 / .bat` | 源端分辨率/图案命令行工具 |
-| `gen_bw_patterns.py` / `gen_solid_colors.py` | 测试图生成脚本（bw 黑白系列 640x360 / solid 纯色系列 800x600） |
-| `solid_*.png` | 9 张 800x600 纯色图（R/G/B 各 55/AA/FF，供自定义栏位或脚本使用） |
-| `bw_*.png` | 5 张 640x360 黑白测试图（西门子星/频率条纹/渐变棋盘/波带/综合卡） |
-| `logos/` | 图标源文件与 `make_ico.py`（改 logo 后重跑再打包） |
-| `pattern_slots.json` | 自定义栏位 + 测试卡区域配置（运行后自动生成/更新） |
+需 Pillow（`py -m pip install pillow`）。重新生成 `assets/` 下全部图案：
 
-## 6. 注意事项
+- `gen_bw_patterns.py` → 640x360 黑白图 ×5：
+  `bw_star.png` 西门子星（极限分辨率）、`bw_sweep.png` 频率扫描条纹（24px→3px）、
+  `bw_checker_sweep.png` 渐变棋盘（2→32px）、`bw_zoneplate.png` 波带片（各向混叠）、
+  `bw_testcard.png` 综合测试卡（灰阶/刻度/细棋盘/线宽组）；
+- `gen_solid_colors.py` → 800x600 纯色图 ×10（R/G/B 各 55/AA/FF + 三原色），
+  与 GUI 内置纯色按钮同源，供自定义栏位或其他工具加载。
 
-- 测试卡区域与自定义栏位配置按 exe/脚本所在目录各自保存，两份安装互不影响
-- 重打包后 Windows 图标缓存可能仍显示旧图标：`ie4uinit -show` 或改名即可
-- 多屏环境切分辨率前先确认显示器序号（下拉框中名称与 `-List` 输出一致）
-- 修改源码后重新打包前，先结束残留的 HDMI-Tool 进程（build_exe.py 会自动处理）
+### 6.3 la_wave_analyzer.py / la_wave_analyzer3.py — 逻辑分析仪波形判读
+
+分析 Kingst VIS 导出的边沿流 CSV（列：`Time[s], 通道A, 通道B[, 通道C]`，
+10ns 分辨率），按 50ms 窗口占空比签名自动分段，输出每段的签名（FF/55/AA/00）、
+时长、行周期/有效区宽度/消隐（按 40MHz 像素时钟折算）：
+
+```
+python la_wave_analyzer.py  <capture.csv>    # 2 通道（默认判读 B 口 D0/D1）
+python la_wave_analyzer3.py <capture.csv>    # 3 通道（RGB 三组同拍, ch8/9/10）
+```
+
+## 7. 目录结构与从源码运行
+
+```
+HDMI-Tool/
+├── src/                     # 源代码（人工维护区）
+│   ├── hdmi_gui.py          # 主程序：GUI + 命令行, 纯标准库
+│   ├── build_exe.py         # PyInstaller 打包 → release/
+│   ├── package_release.py   # 组装发布 zip（exe+图案+说明）
+│   ├── publish_gitea.py     # 上传到 Gitea Release
+│   ├── hdmi_source.ps1/.bat # 源端分辨率/图案命令行工具
+│   ├── gen_bw_patterns.py   # 生成 assets/bw_*.png
+│   ├── gen_solid_colors.py  # 生成 assets/solid_*.png
+│   ├── la_wave_analyzer*.py # 逻辑分析仪 CSV 波形判读
+│   └── logos/               # 图标源（svg/png/ico + make_ico.py）
+├── assets/                  # 生成的测试图案（gen_*.py 产物, 随发布包分发）
+│   ├── bw_*.png ×5          # 640x360 黑白系列
+│   └── solid_*.png ×10      # 800x600 纯色系列
+├── release/                 # 构建与发布产物（机器生成区, 不手改）
+│   ├── HDMI-Tool.exe        # 打包单文件版（改动跟随源码提交入库）
+│   ├── pattern_slots.json   # exe 运行配置（默认栏位预置 bw 图案）
+│   └── *.zip                # 发布包（不入库, 上传 Gitea Release）
+├── README.md                # 本说明
+└── AGENTS.md                # 面向 AI/Agent 的工程档案（结构/约定/构建规程）
+```
+
+从源码运行：`python src/hdmi_gui.py`，需 Python ≥3.10，纯标准库无第三方依赖
+（自定义图片要 JPG/BMP/WebP 时需可选 Pillow）。
+
+## 8. 构建与发布
+
+```powershell
+cd src
+python build_exe.py          # 打包 → ../release/HDMI-Tool.exe（自动装 PyInstaller）
+python build_exe.py --debug  # 额外出一个带控制台的调试变体（--dump 可用）
+python package_release.py 0.1.0        # 组装 release/HDMI-Tool-v0.1.0-win64.zip
+python publish_gitea.py HDMI-Tool-v0.1.0-win64.zip   # 上传 Gitea Release(需 GITEA_TOKEN)
+```
+
+## 9. 注意事项 / FAQ
+
+- **exe 放只读目录会怎样**：自定义图片与 `pattern_slots.json` 写在 exe 旁边，只读目录会导致栏位配置存不下；
+- **重新打包后图标没变**：Windows 图标缓存，`ie4uinit -show` 或改个名即可；
+- **多屏序号**：切分辨率前先确认显示器序号（GUI 下拉框与 `hdmi_source.bat -List` 输出一致）；
+- **残留进程**：修改源码重新打包前先结束残留的 HDMI-Tool 进程（`build_exe.py` 会自动 taskkill）；
+- **改 logo**：改 `src/logos/logo_ph_orange.svg` → `python src/logos/make_ico.py` → 重新打包；
+- **配置互不影响**：exe 与源码脚本各自按所在目录保存 `pattern_slots.json`，两份安装互不干扰。