# 定量モード 設計の経緯と合意 (Quantitative Mode: Rationale & Agreements)

本書は SmTIAS-LightSim 側と MiniTIAS 側の**往復書簡（旧 TECH_01 要求仕様 / TECH_03 実装報告・相談 / TECH_04 回答）を統合・要約したアーカイブ**である．定量撮影モードがなぜ・どう決まったかの記録に絞る．

- **現行の確定仕様** → [SPEC_02 カメラ撮影仕様書](../04_SPEC/SPEC_02_カメラ撮影仕様書.md)（画面は [SPEC_01](../04_SPEC/SPEC_01_画面機能仕様書.md)、設計・非機能は [SPEC_03](../04_SPEC/SPEC_03_アーキテクチャと非機能.md)）
- **実装の経緯・設計判断・失敗パターン** → [PROGRESS.md](../PROGRESS.md)
- **実機能力の生データ** → [camera_diagnostics_20260531_161734.json](../06_TEST/camera_diagnostics_20260531_161734.json)

> 原文の往復書簡には SmTIAS-LightSim リポジトリ側のファイル（検証履歴 TEST_01/03、評価仕様 SPEC_03/04 など。**本リポジトリの SPEC_03 とは別物**）への参照が含まれるが、それらは SmTIAS-LightSim 側に残り本リポジトリには存在しない．

## 背景：なぜ定量モードが必要だったか

SmTIAS-LightSim（Mitsuba 3 による光散乱シミュ）と実機撮影を定量比較する研究で、シミュ vs 実機の残差が縮まらなかった。原因は、MiniTIAS の通常撮影（PNG）が **AE/AWB/NR/EDGE/TONEMAP すべて自動**で、同じシーンを撮っても値が揺らいでいたこと。つまり「比較対象の実機データ自体が定量的に不安定」だった。

→ Camera2 API を**完全マニュアル制御**し、ISP 介入を排した **RAW（DNG）**で撮影するモードを追加して固定化する、という方針になった。

## 実機能力（AQUOS sense3 / SH-02M フロントカメラ）

実機診断（`getCameraDiagnostics`）の結果、定量モードに必要な能力をすべて満たすことを確認：

| 項目 | 値 |
|---|---|
| ハードウェアレベル | **LEVEL_3**（最上位） |
| 能力 | MANUAL_SENSOR / MANUAL_POST_PROCESSING / **RAW** 対応 |
| RAW 出力 | 3264×2448、BGGR、10-bit（white level 1023 / black level 64） |
| 露光時間レンジ | 約 1/12530 s 〜 0.87 s |
| ISO レンジ | 40〜2506 |
| AF | **OFF のみ**（固定焦点。近接ピントはアタッチメント光学系前提） |
| LSC マップサイズ | 13×17（実キャプチャ結果から判明） |

詳細は camera_diagnostics JSON を参照。

## 確定した撮影設定（要点）

全パラメータは [SPEC_02 §撮影設定](../04_SPEC/SPEC_02_カメラ撮影仕様書.md) に記載。要点のみ：

- `CONTROL_MODE=OFF` で AE/AWB/AF/NR/EDGE をすべて OFF、TONEMAP は線形
- 露光 **1/120s**・ISO **40** 固定、`BLACK_LEVEL_LOCK=true`
- フォーマットは **RAW_SENSOR → `DngCreator` で DNG 出力**
- 設定反映を確実にするため **3 枚連続キャプチャして最初の 2 枚を破棄**、3 枚目を採用
- 撮影モード切替トグル UI は採用せず、**定量モードを既定動作**とした（通常 PNG 経路 `captureFullResolutionPng` はコード温存）

## SHADING_MODE = HIGH_QUALITY の根拠（重要な合意）

定量モードの核心的な設計判断。観察と物理的整合性から **HIGH_QUALITY を本流で維持**することで合意した。

- 実装中の観察：`SHADING_MODE=OFF` だと LSC マップが**全要素 1.0**（Android 仕様）になり情報が取れない。`HIGH_QUALITY` だと ISP が LSC を適用し、**実ゲインマップ**が取得できる。
- 物理的整合性：SmTIAS-LightSim の Mitsuba **orthographic 出力**は平行光線サンプリングで cos⁴ falloff を持たず、**「ISP が完璧に LSC 補正できた場合の理想値」相当**。これと **HIGH_QUALITY DNG** を直接比較するのが物理的に最も整合する（残差＝「実機 LSC 補正の不完全度＋シミュ物理モデル誤差」＝まさに評価したい本質）。
- 逆に `OFF`（生 Bayer）を使うとシミュ側に物理 cos⁴ モデル（絞り径・口径食など）を足す必要があり、**自由度が増えて overfitting リスク**が上がる。
- 結論：**HIGH_QUALITY 維持。MiniTIAS 側の実装変更は不要**。LSC マップは検証用に meta.json へ温存する。

### 将来 SHADING_OFF を追加検証する条件（フォールバック C1–C3）

次のいずれかが起きたら「同一シーンを HQ と OFF で 1 セット撮影」する追加実装を検討する（現時点では未到達・実装不要）：

- **C1**: シミュ vs HQ DNG の残差が再現的に大きい（CoV/勾配残差 1.5× 以上 + 形が物理的に説明不能）
- **C2**: LSC マップが撮影ごとに大きく変動（中央値の変動 > 5%）→ ISP が AWB 連動で動的計算している証拠
- **C3**: シミュ側モデル精度を上げても残差が物理的に説明できない

## 露光・ISO の目安（合意値）

10-bit DNG（黒レベル 64 除去後）で：

- 白板中央の **mean = 400〜600**（中央値約 500）
- 飽和回避：**p99 < 900**（除去後 836）

→ 確定値 **1/120s + ISO 40** で mean G ≈ 461・飽和率 0% を達成（基準測定値は PROGRESS.md 参照）。

## 作業フェーズ分け（合意）

「再現性より先に、そもそもシミュと対応が取れるかを 1 ショットで確認する」二段階方式：

- **フェーズ A（1 ショット対応検証）**: MiniTIAS 側は ①画素統計を meta.json に追加 ②Hot pixel map 取得 ③白板 1 枚を試し撮りして adb pull 転送。SmTIAS 側が DNG/メタ読み込みを実装し 1 ショット突合 → 残差 2.1× がどう変化するか観察。**①②は実装済み**。
- **フェーズ B（連射 V1 再現性）**: フェーズ A で対応の見通しが立った場合のみ着手。10 連射 UI（`*_burst{0..9}.dng`）+ 再現性検証（mean CoV < 1%）。

## データ転送

**`adb pull` 推奨**。MTP は禁止しないが、16 MB 級の DNG でコピー直後にサイズが正しく見えない不整合が確認されているため非推奨。