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

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

想定読者 (Intended Reader)

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

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

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

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

背景の要約 (Background Digest)

詳細は SmTIAS-LightSim 側の TEST_01 と TEST_03 を参照．要点のみ抜粋：

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

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

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

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

TECH_01 開放質問 Q1〜Q4 は 実装着手前に実機で確認すべき 項目．まず簡易デバッグビルドで以下を取得：

// 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 推奨実装方針の Phase 1〜5 を順に実装．/implement パイプラインで進めることを推奨：

/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 転送後の配置先は：

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 のメタデータ要求を参照．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 スキーマ

# 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 経由で：

SmTIAS-LightSim リポジトリで該当画像の Exif / メタデータを抽出
結果を 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 を実機で実施．

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 側で以下を実施予定（参考情報）：

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

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

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

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

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

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