# MiniTIAS 引き継ぎ手順 (Hand-off Procedure to MiniTIAS)

本ドキュメントは [TECH_01 定量撮影モード要求仕様](TECH_01_定量撮影モード要求仕様.md) を MiniTIAS リポジトリで実装する際の **作業着手ガイド** および **データ受け渡し仕様** である．SmTIAS-LightSim と MiniTias の両プロジェクトを Claude Code セッションで作業している前提に最適化している．

## 想定読者 (Intended Reader)

- **MiniTias 側 Claude セッション**: 本ドキュメントを最初に開き，次に TECH_01 を読んで実装着手する．
- **人間レビュー (rinto)**: 両セッションを行き来し，質問の橋渡しと完了確認を行う．

## プロジェクト関係図 (Project Relationship)

```text
┌─────────────────────────┐      ┌──────────────────────────┐
│  MiniTias                │      │  SmTIAS-LightSim          │
│  (Flutter / Android)     │      │  (Python / Mitsuba 3)     │
│                          │      │                           │
│  撮影アプリ                │      │  光散乱シミュレータ        │
│  - インカメラ制御         │      │  - 仮想シーン構築          │
│  - 撮影モード             │      │  - 物理光線追跡           │
│  - PNG / メタデータ保存    │ ──→ │  - sm-evaluate            │
└─────────────────────────┘      └──────────────────────────┘
                                          │
                                          │ 同じ評価指標
                                          ▼
                              ┌──────────────────────────┐
                              │  MiniTias-Evaluation      │
                              │  (Python)                 │
                              │                           │
                              │  実機 PNG → 均一性指標     │
                              └──────────────────────────┘
```

→ 3 プロジェクトで **同じ評価指標** を出し，シミュ vs 実機を比較する．本作業は MiniTias 側に **「定量撮影モード」** を追加し，定量比較可能な実機データを取得できるようにする．

## 背景の要約 (Background Digest)

詳細は SmTIAS-LightSim 側の [TEST_01](../06_TEST/TEST_01_キャリブレーション検証履歴.md) と [TEST_03](../06_TEST/TEST_03_輝度マップ形状追跡.md) を参照．要点のみ抜粋：

- SmTIAS-LightSim 側で **Step 8-1〜8-12 のキャリブ作業** を実施し，残差 2.1× で頭打ち
- 「形のずれ」を解消するため LSC モデル化を検討していたが，さらに調査した結果，**実機 PNG 自体が定量データとして揺らいでいる**ことが判明
- 既存 baseline `MiniTIAS_20260408_144434` は MiniTias の通常モード (AE/AWB/NR/EDGE/TONEMAP 全自動) で撮影されており，撮影ごとに値が変動する可能性
- → **「定量撮影モード」** の追加が必要．詳細は [TECH_01](TECH_01_定量撮影モード要求仕様.md)

## MiniTias 側 Claude セッションの最初のアクション (First Actions)

セッション開始時に以下 3 ステップを順に実施することを推奨する．

### Step A: 実機サポート状況の確認（最優先）

[TECH_01 開放質問 Q1〜Q4](TECH_01_定量撮影モード要求仕様.md#開放質問-open-questions) は **実装着手前に実機で確認すべき** 項目．まず簡易デバッグビルドで以下を取得：

```kotlin
// android/app/src/main/kotlin/.../CameraDiagnostics.kt として実装提案
val characteristics = cameraManager.getCameraCharacteristics(frontCameraId)

// Q1: ハードウェアレベル
val hwLevel = characteristics.get(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL)

// Q2: 能力フラグ
val caps = characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)
val hasManualSensor = caps?.contains(REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR)
val hasManualPP = caps?.contains(REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING)
val hasRaw = caps?.contains(REQUEST_AVAILABLE_CAPABILITIES_RAW)

// Q4: LSC マップサイズ
val mapSize = characteristics.get(CameraCharacteristics.LENS_INFO_SHADING_MAP_SIZE)

// Q3: DNG 出力可否
val streamMap = characteristics.get(SCALER_STREAM_CONFIGURATION_MAP)
val rawOutputSizes = streamMap?.getOutputSizes(ImageFormat.RAW_SENSOR)
```

これらを Logcat または UI に出力し，結果を MiniTias リポジトリの新規ファイル `docs/06_TEST/TEST_xx_実機サポート判定.md` 等に記録する．

### Step B: 実装範囲の決定

Step A の結果から，**どの Phase まで実装できるか** を決定する：

| ハードウェアレベル | 実装可能範囲 | 備考 |
| --- | --- | --- |
| `LEGACY` | 定量モード **不可** | ユーザーに警告表示のみ |
| `LIMITED` + `MANUAL_SENSOR` のみ | TECH_01 Phase 1（露光・ISO 固定）まで | NR/EDGE/TONEMAP 制御は ×．SHADING_MODE は個別確認 |
| `LIMITED` + `MANUAL_POST_PROCESSING` あり | TECH_01 Phase 1〜2（露光・WB・NR・EDGE 固定）まで | LSC マップ取得は STATISTICS_LENS_SHADING_MAP_MODE 個別確認 |
| `FULL` / `LEVEL_3` | TECH_01 Phase 1〜5 全実装可能 | DNG 出力も可能なら最高 |

判定結果と「実装する Phase」を MiniTias 側 docs/ に記録．SmTIAS-LightSim 側にも反映できるよう，後述「結果の共有方法」に従う．

### Step C: Phase 1 着手

[TECH_01 推奨実装方針](TECH_01_定量撮影モード要求仕様.md#推奨実装方針-recommended-implementation) の Phase 1〜5 を順に実装．`/implement` パイプラインで進めることを推奨：

```text
/implement TECH_01 Phase 1: Camera2 詳細制御の MethodChannel 実装
```

## データ受け渡し仕様 (Data Exchange Specification)

定量撮影モードで取得したデータを SmTIAS-LightSim 側で使えるようにするための **ファイル配置・命名規則**．

### ファイル命名規則

| 種別 | 命名 |
| --- | --- |
| 画像（PNG/YUV/DNG） | `MiniTIAS_QM_YYYYMMDD_HHmmss.<ext>` |
| 撮影メタデータ | `MiniTIAS_QM_YYYYMMDD_HHmmss.meta.json` |
| LSC ゲインマップ | `MiniTIAS_QM_YYYYMMDD_HHmmss.lsc.npz` |

`QM` = Quantitative Mode．既存通常モードの `MiniTIAS_YYYYMMDD_HHmmss.png` と区別する．

### 拡張子の選択

| 拡張子 | 採用条件 |
| --- | --- |
| `.png` | YUV_420_888 → BT.601 → RGB → PNG 経路（現状継承） |
| `.yuv` または `.yuv.npz` | YUV_420_888 を直接保存（中間処理排除） |
| `.dng` | RAW_SENSOR をサポートしている場合 |

複数フォーマットを並列保存しても良い（例: 同一撮影で `.png` と `.dng` 両方を保存）．

### 端末から PC への転送

MiniTias アプリは端末ローカル `Pictures/MiniTIAS/` に保存する．PC への転送は **USB 接続でユーザーが手動コピー** する想定（既存ワークフローを継承）．

### SmTIAS-LightSim 側の配置先

PC 転送後の配置先は：

```text
SmTIAS-LightSim/
└── reference_measurement/         # .gitignore 配下（個人ローカル）
    ├── MiniTIAS_20260408_144434/  # 既存 baseline（通常モード）
    │   └── <画像 / 解析結果>
    └── quantitative/              # ← 新規・定量モード用
        ├── MiniTIAS_QM_20260601_120000.png
        ├── MiniTIAS_QM_20260601_120000.meta.json
        ├── MiniTIAS_QM_20260601_120000.lsc.npz
        └── ...
```

→ MiniTias 側で撮影 → PC に USB 転送 → `reference_measurement/quantitative/` に配置．

### メタデータ JSON スキーマ

[TECH_01 のメタデータ要求](TECH_01_定量撮影モード要求仕様.md#4-撮影メタデータの保存撮影パラメータの可視化) を参照．SmTIAS-LightSim 側の sm-evaluate で読み込み可能な形式とする．

特に **必須フィールド**：

- `capture_mode`: `"quantitative"` または `"normal"`
- `device_model`: `"SH-02M"` 等
- `hardware_level`: Step A で取得した値
- `settings`: Camera2 API の実適用値
- `image_format`: `"YUV_420_888"` / `"RAW_SENSOR"` 等

これらが揃っていれば SmTIAS-LightSim 側で読み込みロジックを実装可能．

### LSC マップ NPZ スキーマ

```python
# NPZ 内のキー
{
    "gain_map": np.ndarray,  # shape=(4, N, M), dtype=float32, channels=[R, Geven, Godd, B]
    "map_size": np.ndarray,  # shape=(2,), dtype=int32, [N=col_count, M=row_count]
    "min_gain_factor": 1.0,  # MINIMUM_GAIN_FACTOR
}
```

または等価な JSON でも可（数値桁数の精度に注意）．

## 既存 baseline 画像へのアクセス (Existing Baseline Access)

`MiniTIAS_20260408_144434` は SmTIAS-LightSim 側の `reference_measurement/` 配下に存在（.gitignore 対象，個人ローカル）．MiniTias 側からは直接参照できない．

実装中に **「既存撮影時の条件と揃えたい」** という要請が出た場合は，rinto 経由で：

1. SmTIAS-LightSim リポジトリで該当画像の Exif / メタデータを抽出
2. 結果を MiniTias 側 docs/ または本リポジトリの本ファイルに追記して共有

ただし TECH_01 に書いたとおり，**既存 baseline 自体が「定量データとして揺らいでいる」のが本作業の出発点**なので，定量モード実装後は新規 baseline（定量モードで撮ったもの）に置き換える前提でよい．

## 質問・調整事項の扱い (Open Issues Handling)

両プロジェクト Claude セッションでの作業を前提とすると，質問・調整は **ファイルベース** で行うのが追跡性が高い．

| 状況 | 対応 |
| --- | --- |
| MiniTias 側実装中に Q1〜Q7 の判断が必要になった | MiniTias 側 docs/ に `06_TEST/TEST_xx_実装判断ログ.md` 等で判断と理由を記録．rinto が SmTIAS-LightSim 側にも反映 |
| SmTIAS-LightSim 側仕様 (TECH_01) に追加要求が出た | rinto が SmTIAS-LightSim 側で TECH_01 を更新．MiniTias 側 Claude は `git pull` 相当で再読 |
| データ受け渡し仕様（ファイル命名・スキーマ）の変更要求 | rinto が SmTIAS-LightSim 側で本ファイル (TECH_02) を更新．両セッションで共有 |
| 実機 (AQUOS sense3) で予期せぬ動作 | MiniTias 側 docs/ に記録．必要なら本ファイルの「既知の制約」セクションに追記（後日反映） |

## 完了判定の方法 (Completion Criteria)

[TECH_01 検証方法 V1〜V4](TECH_01_定量撮影モード要求仕様.md#検証方法-verification) を実機で実施．

### MiniTias 側で完了とする条件

- V1（再現性 10 連射 CoV < 1%），V2（LSC マップ取得検証），V3（SHADING_MODE 切替検証）の結果ログが MiniTias 側 docs/06_TEST/ 等に残っている
- 定量モードで白板を撮影したサンプルファイル（PNG + meta.json + LSC マップ）が 1 セット以上 PC 側 `reference_measurement/quantitative/` に存在する

### SmTIAS-LightSim 側の受け入れトリガー

`reference_measurement/quantitative/` 配下にサンプルファイルが配置された時点で，SmTIAS-LightSim 側 Claude セッションは以下の受け入れ作業に着手できる：

- メタデータ JSON 読み込み I/F の実装（sm-evaluate 拡張）
- LSC マップ読み込み I/F の実装（sm-evaluate の LSC 順方向適用機能）
- 既存 baseline と新規定量モード baseline の **並列キャリブ**（両者の比較）
- TEST_01 に新規 Step（例: Step 8-13）として追加

### V4 の達成判定

V4（残差 2.1× → 1.5×）は両プロジェクトの連携でのみ達成可能：

- MiniTias 側で V1〜V3 完了
- SmTIAS-LightSim 側で sm-evaluate に定量モード対応実装完了
- 新規 baseline でキャリブ実施
- 結果を SmTIAS-LightSim 側 TEST_01 に追記

V4 達成は本ハンドオフのスコープ外（後続キャリブ作業の成果として位置付ける）．

## 後続作業 (Follow-up Work on SmTIAS-LightSim Side)

MiniTias 側完了後，SmTIAS-LightSim 側で以下を実施予定（参考情報）：

1. **`sm-evaluate` に LSC 順方向適用機能を追加**: 新規 `evaluation/lsc.py` モジュール．LSC マップを画像に掛けて補正済み画像を再現
2. **メタデータ JSON 読み込み機能**: `evaluation/metadata.py` で撮影パラメータを取得
3. **新規 baseline 設定の追加**: `configs/eval_baseline_quantitative.yaml` 等．既存 baseline と並列保持
4. **TEST_01 に Step 8-13 を追加**: 「定量モード baseline での再キャリブ」として記録
5. **TEST_03 の比較パネル更新**: 新規 baseline を含む形で再生成

これらは MiniTias 側完了後に着手するため，TECH_01 の検証 V4 とともに「本ハンドオフのスコープ外」として位置付ける．

## チェックリスト（MiniTias 側 Claude 用） (Checklist)

セッション内で以下を順に確認すると進めやすい：

- [ ] 本ファイル (TECH_02) を読了
- [ ] TECH_01 を読了
- [ ] [MiniTIAS/docs/04_SPEC/SPEC_01 画面機能仕様書](../../MiniTIAS/docs/04_SPEC/SPEC_01_画面機能仕様書.md) を読了（現状仕様）
- [ ] Step A: 実機サポート状況確認 → 結果記録
- [ ] Step B: 実装範囲決定 → 記録
- [ ] Step C: Phase 1 着手（`/implement` パイプライン）
- [ ] Phase 2 以降を順次実装
- [ ] V1〜V3 実機検証 → 結果ログを docs/06_TEST/ に残す
- [ ] 定量モード撮影サンプルを `Pictures/MiniTIAS/` に作成 → rinto が PC 転送

## 関連ドキュメント (Related Documents)

- [TECH_01 定量撮影モード要求仕様](TECH_01_定量撮影モード要求仕様.md) — 本作業の要求書（What/Why）
- [TEST_01 キャリブレーション検証履歴](../06_TEST/TEST_01_キャリブレーション検証履歴.md) — 「形のずれ」発見の経緯
- [TEST_03 輝度マップ形状追跡](../06_TEST/TEST_03_輝度マップ形状追跡.md) — シミュ vs 実機の構造的差異
- [SPEC_04 評価仕様](../04_SPEC/SPEC_04_評価仕様.md) — sm-evaluate の評価パイプライン
- [MiniTIAS/docs/04_SPEC/SPEC_01 画面機能仕様書](../../MiniTIAS/docs/04_SPEC/SPEC_01_画面機能仕様書.md) — 現状の MiniTias 撮影仕様（変更前ベースライン）
- [Android Camera2 API LensShadingMap](https://developer.android.com/reference/android/hardware/camera2/params/LensShadingMap)
- [Android Camera2 API CaptureRequest](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest)