# MAG160C 安卓 App 操作手册

适用版本：MAG160C 统一热像版 1.0.0（`com.mag160c.thermal`）
硬件：MAG160C 热像仪机芯（160×120 @15fps），USB VID `0x833C` PID `0x0001`

> 本文中的插图：**截图**取自真机（小米 22041211AC / Android 12）；**示意图**用于说明
> 布局与标记结构。图片源文件在 `manual_images/`，可用同目录的 `MakeFigures.java`
> 重新生成（界面改动后请重新出图，避免手册与实物不一致）。

---

## 1. 安装与首次连接

1. 安装 APK（`build-artifacts/mag160c-app-debug.apk`）：
   ```
   adb install -r -d mag160c-app-debug.apk
   ```
   也可以直接把 APK 拷进手机点击安装（需允许"安装未知应用"）。
2. 把热像仪插到手机的 USB 口。系统会弹出 **"允许 App 访问该 USB 设备"** →
   勾选"始终允许"并确定。**这个授权在手机重启后会失效，需要重新确认一次**。
3. App 会自动连接并出图，通常 1~2 秒（内部流程：查设备 → 请求权限 → 握手 →
   读标定文件 → 开始出流）。

> 顶栏下方显示"未检测到热像仪"时，见第 11 节。

---

## 2. 界面总览

![实时界面示意图](manual_images/01_live_schematic.png)

| 编号 | 位置 | 作用 |
|---|---|---|
| ① | 顶栏 · FFC | 手动做一次快门校正（画面短暂冻结属正常） |
| ② | 顶栏 · 1× | 数码变倍，点一次在 1× → 2× → 3× → 4× 循环 |
| ③ | 顶栏 · 追踪 | 全画面最高/最低温标记（最高、最低、两者、关闭） |
| ④ | 顶栏 · 铁虹 | 切换调色板（12 种） |
| — | 顶栏 · 画中画 | 可见光画面叠加，三档尺寸，可拖动 |
| ⑤ | 拍摄栏 | 相册 / **拍照** / 录像 |
| ⑥ | 底部导航 | 实时 / 相册 / 分析 / 设置 |

画面里还有两个读数：左上角 **"中心 xx.x℃"** 是画面中心点温度；右侧竖条是
**温度色标**，上下端标注当前画面的最高温与最低温。

App 固定竖屏显示。转动手机时**界面和画面构图都不跟着转**（见第 8 节）。

---

## 3. 实时界面操作

- **测温点**：直接在画面上**点一下**就加一个测点；**点已有的测点**则删除它。
  测点会显示序号 + 温度，并随照片一起保存。
- **拍照**：立刻把当前画面存成照片（含温度数据、测点、最高/最低温标记）。
- **录像**：点一次开始，再点一次停止并保存；录制中按钮显示"停止"。

---

## 4. 画面上的标记怎么读

![标记结构](manual_images/02_markers.png)

| 编号 | 部位 | 说明 |
|---|---|---|
| ① | 方形准星 + 四根短臂 | 指住被测量的**那一个像素**；中心镂空，不遮挡被测区域 |
| ② | 读数 | `Pt1`/`Pt2`… 是手动测点；`MAX`/`MIN` 是全画面最高/最低温 |
| ③ | 引线 | 把读数和它自己的准星连起来，测点多时不会看错 |
| ④ | 文字样式 | 白字 + 黑描边，**没有白色底板**：冷端（黑）和热端（白）上都读得清，且不挡画面 |

温度单位统一 ℃，一位小数。

---

## 5. 相册

![相册](manual_images/07_gallery.png)

- 列出 `DCIM/MAG160C` 里的照片，按时间倒序（最新的在最前）
- **点开**：全屏查看；**双指缩放**、**拖动平移**、**双击复位**
- **删除**：右上角"删除" → 确认后从手机中移除（不可恢复）
- 返回键回到列表，不会退出 App

---

## 6. 分析（离线测温）

![分析界面](manual_images/06_analysis.png)

进入"分析"页会列出**带温度数据的照片**（早期没有温度数据的旧照片会被过滤）。

| 操作 | 说明 |
|---|---|
| **点击画面** | 在空白处加一个测点；点在已有测点上则删除该测点 |
| **底部面板** | 显示 最高 / 最低 / 中心 温度，以及测点列表 |
| **顶部 · 调色板名** | 切换显示用的调色板 |
| **顶部 · 备注** | 给这张照片写一段文字备注（写入文件本身） |
| **顶部 · 保存** | 把当前测点烧录进图像，**另存为一张新照片**（温度数据一并保留） |

分析页显示的标记与照片里已烧录的标记位置完全一致，不会出现"两个测点"。

**注意**：分析读的是照片里存的原始温度数据，所以同一张照片任何时候打开，
读数都一样（不会因为环境变化而漂移）。

---

## 7. 设置

![设置](manual_images/05_settings.png)

| 设置项 | 说明 | 是否影响画面 |
|---|---|---|
| **默认调色板** | 启动时使用的调色板 | ✔ |
| **默认发射率** | 目标发射率（0.01~1.00） | ✖ 目前仅保存，尚未参与温度修正 |
| **报警温度** | 报警阈值 | ✖ 目前仅保存，尚未接入报警 |
| **追踪** | 最高温 / 最低温 / 最高+最低 / 关闭 | ✔ |
| **语言** | 中文 / 跟随系统 | ✖ 目前仅保存（界面为中文） |
| **旋转USB画面** | 0° / 90° / 180° / 270°，画面方向整体旋转 | ✔ |
| **图像增强** | 关闭 / 1~8 级，官方同款 7×7 局部细节增强 | ✔ |
| **水平翻转** | 画面左右镜像 | ✔ |
| **竖直翻转** | 画面上下镜像 | ✔ |
| **云同步** | 占位项，需账号与接口才能对接 | ✖ |
| **远程预览服务端** | 让本机作为主机，向局域网提供画面 | ✔ |
| **远程预览客户端** | 搜索局域网内的主机并连接观看 | ✔ |
| **关于** | 版本信息 | — |

**画面方向不对怎么调**：热像仪是插在手机上的，安装姿态决定了画面朝向。
若画面上下颠倒，用"旋转USB画面"（每次 90°）；若左右镜像反了，用"水平翻转"或
"竖直翻转"。这三项是**永久生效的设置**，实时、拍照、录像都会跟着变。

**图像增强怎么选**：档位越高，纳入增强的对比度门槛越高、强边缘的增强幅度越大，
即"更锐但更挑"——弱对比区域（噪声所在处）会被排除，所以调高**不会**把噪声放大。
日常建议 2~4 级；需要看清弱纹理时再上 6~8 级。默认关闭。

---

## 8. 拍照 / 录像的方向（重要）

![竖屏握持拍出的照片](manual_images/04_photo_portrait.png)
*竖着拿手机拍 → 720×960 竖幅照片，场景是正的*

![横屏握持拍出的照片](manual_images/03_photo_landscape.png)
*横着拿手机拍 → 960×720 横幅照片，场景同样是正的*

- **文件方向跟随你拿手机的方向**（和普通相机一样），所以**不需要事后旋转**。
- **预览画面本身是锁定的**：横着拿手机时，屏幕里的画面看起来是侧的
  （因为屏幕构图固定在竖屏框架上），但保存下来的文件是正的。
  这是刻意设计：热像仪固定在手机上，锁定预览才能保证转动手机时不晃方向。
- **录像方向在按下"录像"的瞬间确定**。录制过程中转动手机不会改变文件方向
  （编码尺寸固定，所有相机都是这个行为）。

---

## 9. 文件与格式

| 类型 | 位置与命名 |
|---|---|
| 照片 | `DCIM/MAG160C/MAG160C_yyyyMMdd_HHmmss.jpg` |
| 分析另存 | `DCIM/MAG160C/MAG160C_yyyyMMdd_HHmmss_edit.jpg` |
| 录像 | `DCIM/MAG160C/MAG160C_V_yyyyMMdd_HHmmss.mp4` |

照片文件是 **MDT 容器**：文件开头就是标准 JPEG（任何看图软件都能打开），
后面追加了温度数据、测点坐标、备注、渲染参数等信息。
所以照片既能当普通图看，也能回到 App 里继续测温。

---

## 10. 远程预览（两台设备）

把手机画面投到另一台设备上看（同一局域网）：

1. **主机**（插着热像仪的那台）：设置 → **远程预览服务端** → 打开
2. **客户端**：设置 → **远程预览客户端** → 点"重新扫描"自动发现主机 →
   点主机连接；也可以手动输入 `IP:端口`
3. 客户端是**本地渲染**：主机把原始温度数据发过去，客户端自己画图，
   所以能正确显示主机端的追踪标记和 FFC 状态

退出远程查看用返回键，会回到设置页。

---

## 11. 常见问题

**显示"未检测到热像仪"**
- 确认热像仪插紧；换一个 USB 口试试
- 手机重启后 USB 授权会失效 → 重新插拔一次，在弹窗里点"允许"
- 仍不行：退出 App 重进（App 会自动重试，不用反复插拔）

**画面卡住或黑屏**
- FFC 校正时画面会短暂冻结，属正常
- 持续黑屏：退出 App 重进；确认没有别的 App 占用了热像仪

**温度看起来不准**
- 先做一次 FFC（环境温度变化后尤其需要）
- 分析页的读数来自照片里存的原始数据，不会随时间变化；实时页读数会随环境漂移

**手机息屏后回来**
- 息屏时渲染停止（省电）、USB 读取继续，已保存的文件不受影响

**想拿文件到电脑上**
```
adb pull /sdcard/DCIM/MAG160C/
```

---

## 12. 已知限制

- **云同步**为占位项，需要账号与接口文档才能对接
- **发射率 / 报警温度 / 语言**三项目前只做保存，尚未接入实际功能
- **红热调色板**是近似实现（官方该调色板的原始数据未取到）
- **相册不列录像**：录像请用系统相册/文件管理器查看
- **预览锁定**是设计如此，不是缺陷（见第 8 节）
- PDF 报告与任务巡检的代码已实现，但**尚未接入界面**，当前版本无法从 App 中使用