# MAG160C 热像仪工程

MAG160C 热像仪机芯（160×120 @15fps，USB VID `0x833C`）的完整逆向工程与双端实现：

- **C 参考实现**（`csdk/`，跨平台）：官方 PC SDK 渲染/温度/USB 管线的逐像素复刻，
  含 Windows 直连演示程序与 Linux 移植模块；
- **安卓统一 App**（`android/`，Kotlin + Compose，适配 Android 16）：整合官方
  4 个 App（普通版/专业版/ThermoScope/CoreSdkSample）的功能——实时预览、
  拍照（MDT 温度容器）、录像、媒体库、离线分析、PDF 报告、任务巡检、远程预览；
- **逆向工程档案**（`analysis/`）：三条 SDK 产品线（Linux/Windows/Android）的
  反汇编、全量伪代码、协议结论与验证数据。

## 仓库结构

| 路径 | 内容 |
|---|---|
| `android/` | 安卓统一 App（Gradle 工程，package `com.mag160c.thermal`，纯 Kotlin 无 NDK）|
| `csdk/` | 纯 C SDK：USB 会话层、帧解析、温度换算、TCM 板通信、官方渲染管线复刻（见 `csdk/README.md`）|
| `analysis/` | 逆向工程总目录：三条 SDK 线的解包产物、协议规格、差分验证数据（见 `analysis/README.md`）|
| `docs/android_app/` | 安卓 App 文档：`DEVELOPMENT.md` 开发指南 / `app_manual.md` 操作手册 / `session_state.md` 开发进度与验证记录 |
| `IR_Camera_SDK-1.0.1/` | 原厂 Windows/Android/Linux SDK 原始包 |
| `app/` | 官方安卓 APK 存档（普通版/专业版/ThermoScope/demo）|
| `build-artifacts/` | 构建产物（安卓 APK、PC demo、DDT 标定数据）|
| `vendor-docs/` | 厂商资料 |
| `tools/` | 辅助脚本（会话恢复、帧数据检查）|

## 构建与测试

### 安卓 App

要求：JDK 21（Temurin）、Android SDK（API 36）、设备为 Android 12+。

```powershell
cd android
$env:JAVA_HOME = "C:\Tools\jdk-21"          # 按本机 JDK 路径调整
.\gradlew.bat :app:assembleDebug test --no-daemon
# 产物：android\app\build\outputs\apk\debug\app-debug.apk
#（仓库同步副本：build-artifacts\mag160c-app-debug.apk）
```

单元测试 123 项（渲染管线逐字节黄金比对、协议字节序、网络回环等），无硬件可跑。

### C 参考实现（demo3：官方渲染管线复刻）

```powershell
gcc -O2 -w -DMAG160C_STATIC -I"csdk\third_party\libusb\win64" -I"csdk\include" -I"csdk\src" `
    -o build-artifacts\mag160c_demo3.exe csdk\tools\mag160c_demo3.c `
    csdk\src\mag160c_display.c csdk\src\mag160c_error.c `
    csdk\third_party\libusb\win64\libusb-1.0.x64.a -lgdi32 -luser32
```

更多构建方式（CMake / Linux / CLI 工具 / 测试）见 `csdk/README.md`。

## 硬件与协议要点

- 设备：MAG160C 机芯，160×120 @15fps，FFC 快门自动校正
- USB：VID `0x833C` PID `0x0001`；端点 0x03 命令 / 0x82 响应 / 0x81 图像流 /
  0x84 标定文件 / 0x05 标定上传
- 协议：命令 4 字节小端 `{magic}`（FFC 为 8 字节）；帧格式
  `0x1bb1b11b | counter | len | type | … | u16LE 像素 | 0x1bb1b11c`
- 权威协议结论：`analysis/magcx_official_flow.md`（官方 Java 源码逐行核对版）

## 文档导航

| 文档 | 内容 |
|---|---|
| `docs/android_app/DEVELOPMENT.md` | 安卓 App 开发指南（架构/约定/构建/注意事项）|
| `docs/android_app/app_manual.md` | App 操作手册（界面/设置/方向/排障）|
| `docs/android_app/session_state.md` | 开发进度与验证记录（39 轮真机验证）|
| `docs/android_app/reverse_apk_features.md` | 官方 4 App 逆向功能总表 |
| `analysis/README.md` | 逆向工程总目录索引 |
| `analysis/magcx_official_flow.md` | 权威 USB 协议结论 |
| `csdk/README.md` | C SDK 文档（构建/API/工具/测试/对齐记录）|

## 主要成果记录

- **2026-08**：官方 PC SDK（libmagcore / CoreSDKLib）逆向完成，C 管线逐像素复刻
  （NUC/盲元与官方同帧抓帧 0/19200 误差）
- **2026-09 上旬**：安卓统一 App 完成（渲染管线 Kotlin 移植逐字节验证、USB 层
  复刻官方 Java 源码、相机式 UI、MDT 拍照/录像/媒体库/分析/PDF/任务巡检）
- **2026-09-10**：真机联调打通（根因：USB 命令字节序反转，修复后单测锁死）；
  官方安卓 App 全量解包入库（jadx + Ghidra）
- **2026-09-11~12**：真机多轮联调，修复 launchMode 重连风暴、SET_CONFIGURATION
  重枚举、软件画布掉帧（6.5fps→15.1fps）三个根因级问题；完成官方 7×7 细节
  增强移植、标注风格重做、方向跟随等
- **2026-10 上旬**：官方真机渲染链全量逆向（39 轮验证）——逐行固定图案噪声的
  来源定案：参考减除消除 98.4% 行 FPN，显示域对齐官方（暗区行交替
  0.14-0.23 ×1e-2 弧长 ≈ 官方 0.15）；7×7 细节增强的显示代价量化并写入设置说明

## 许可与使用声明

仓库包含原厂 SDK、反编译产物、二进制样本与抓帧数据。这些内容仅供本项目的
互操作性研究与设备调试使用，可能受原厂许可限制，不得用于其他用途；
不得分发账号凭据、访问令牌或私钥。工程代码（`android/`、`csdk/`、`docs/`、
`analysis/` 中自行编写的部分）按项目内部使用管理。