intvenlab/CamtraptionAnalysis
GitHub: intvenlab/CamtraptionAnalysis
一款 Windows 桌面工具，通过解析 Camtraption 相机 JPG 文件的 EXIF 和 Canon 元数据，离线推断拍摄模式、校验排程对齐并构建含固件错误的拍摄时间线。
Stars: 0 | Forks: 0
# CamtraptionAnalysis
用于离线分析 Camtraption 相机拍摄文件夹的 Windows 桌面工具。读取 JPG/JPEG 文件中的 EXIF 和 Canon maker-note 元数据，推断相机模式 (C1/C2/C3)，检查排程对齐情况，并构建包含过渡、唤醒周期和固件错误事件的拍摄时间线。
报告输出与 `camtraption_agent/analysis/detect_camera_modes.py` 中的 Python 工具兼容。
## 环境要求
- Windows x64
- [.NET 9 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/9.0)（用于运行已发布的构建版本或安装程序）
- [.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)（仅用于开发构建）
## 快速开始
在 Visual Studio 中打开解决方案，或者在仓库根目录的终端中运行：
```
dotnet run --project CamtraptionAnalysis\CamtraptionAnalysis.csproj
```
Debug 构建输出：
`CamtraptionAnalysis\bin\Debug\net9.0-windows\CamtraptionAnalysis.exe`
Release 发布（由安装脚本使用）：
```
dotnet publish CamtraptionAnalysis\CamtraptionAnalysis.csproj -c Release -r win-x64 --self-contained false
```
## 使用应用
1. **Browse…** — 选择一个包含拍摄 JPG 的文件夹（通常是设备 SD 卡的 USB 副本）。
2. **Run Analysis** — 递归发现所有 `.jpg`/`.jpeg` 文件，并行提取元数据，然后运行内存分析阶段。
3. **Summary panel** — 根路径、文件数、相机序列号、排程 artist、不匹配总数以及已保存的报告路径。
4. **Capture timeline** — 可排序的事件行和拍摄行网格。行高亮表示过渡、唤醒周期、模式更改、备注、警告和错误。
5. **Show issues only** — 过滤网格以仅显示值得关注的行（不匹配、事件、读取错误）。
6. **Open Reports Folder** — 打开保存文本报告的文件夹。
每次运行都会将完整的文本报告写入：
`%USERPROFILE%\Documents\CamtraptionAnalysis\.txt`
报告包含过渡标记、CSV 风格的拍摄行和警告 — 与网格中显示的内容相同，采用纯文本格式，便于归档或对比。
## 分析内容
- 基于 Canon 快门模式和闪光曝光补偿的**模式推断 (C1/C2/C3)**
- 基于版权/artist 戳记的**排程匹配**（artist 名称 + 时间段，+45 秒拍摄延迟）
- 版权戳记中记录的模式与推断模式的**记录值与推断值对比**
- **拍摄时间线** — 计划唤醒、pre-config、post-config 窗口、模式过渡、长间隔、过期的版权戳记、唤醒周期
- 版权戳记中的**固件 ERR 代码**，解码为人类可读的相机错误名称
- **多相机扫描** — 按序列号、拍摄时间、文件名进行分组和排序
元数据提取大约使用 75% 的逻辑 CPU 核心；分析阶段在读取所有文件后在内存中以单线程运行。
## 架构
```
AnalysisPipeline
├── JpegFileEnumerator (streaming discovery)
├── parallel MetadataFieldReader (EXIF + CanonFieldDecoder)
└── RamImageAnalysisPhase
├── ModeInference + ScheduleAnalyzer
├── CaptureTimelineBuilder
└── CameraModeReportBuilder + AnalysisSummaryBuilder
```
## 项目布局
```
CamtraptionAnalysis.sln
CamtraptionAnalysis/ WPF app (.NET 9)
Models/ ImageObservation, CaptureTimelineEntry, AnalysisSummary, …
Services/ pipeline, decoders, report builders
installer/
build-installer.ps1 publish + Inno Setup compile
CamtraptionAnalysis.iss installer definition
output/ generated setup .exe (gitignored)
```
## 核心服务
| 文件 | 职责 |
|------|------|
| `AnalysisPipeline.cs` | 文件发现、并行元数据读取、流程编排 |
| `MetadataFieldReader.cs` | 通过 MetadataExtractor 提取 EXIF |
| `CanonFieldDecoder.cs` | ShutterMode（FileInfo 索引 23）、FlashExposureComp（Canon EV） |
| `CopyrightStampParser.cs` | 从版权字段解析模式、artist 排程和 ERR 片段 |
| `ModeInference.cs` | 根据快门类型 + 闪光补偿推断 C1/C2/C3 |
| `ScheduleAnalyzer.cs` | Artist 排程解析、预期模式、匹配评估 |
| `CaptureTimelineBuilder.cs` | 事件时间线：过渡、唤醒周期、config 窗口、间隔 |
| `CameraErrorDecoder.cs` | 将固件 ERR 整数映射为命名的错误代码 |
| `CameraModeReportBuilder.cs` | 与 Python 分析工具匹配的文本报告 |
| `ReportFileWriter.cs` | 将带有时间戳的报告保存在 Documents 下 |
## 依赖项
- **MetadataExtractor** 2.9.2 (NuGet) — 读取 EXIF 和 maker-note
## 安装程序
仅为该应用构建 Windows 设置 `.exe`。安装程序**不**捆绑 .NET 运行时。
```
.\installer\build-installer.ps1
```
要求构建机器上安装有 [Inno Setup 6](https://jrsoftware.org/isdl.php)。
输出：`installer\output\CamtraptionAnalysis-Setup-1.0.0.exe`
在目标 PC 上，如果需要，请先安装 **.NET 9 Desktop Runtime (x64)**。安装程序会检查注册表，如果缺少运行时，会停止并提示下载链接。
将可选的 redistributables（例如 `windowsdesktop-runtime-*.exe`）放在本地的 `installer/redist/` 目录中 — 该文件夹已被 gitignored。
## 本地数据（不在仓库中）
以下内容通过 `.gitignore` 排除，且未提交到仓库：
- 构建输出（`bin/`、`obj/`、`installer/output/`）
- 测试拍摄文件夹（`testdata/`、`samples/`、`captures/`、…）
- 仓库内保存的分析报告（`reports/`）
- 特定于机器的注释和密钥（`cursor_notes.txt`、`.env`、…）
标签：EXIF解析, .NET 9, Windows桌面应用, 图像元数据解析, 数据分析工具