diff --git a/CLAUDE.md b/CLAUDE.md index 9180b55..1aaf8a2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,6 +23,7 @@ 補足: **速度最適化ワーク開始**（キャリブ作業を一旦中断）．[TEST_04 シミュレーション速度最適化履歴](docs/06_TEST/TEST_04_シミュレーション速度最適化履歴.md) に試行を集約．**Speed-0 ベースライン計測完了**（`configs/scene_baseline.yaml`，3 回中央値）: **B1 sm-render = 507.86 s（≈8.46 分）/ B2 sm-visualize path bake (samples=16) = 55.97 s**．**副次発見**: `DRJIT_LIBLLVM_PATH` 環境変数の消失で sm-render が ImportError でクラッシュしていたことを発見．`C:\Program Files\LLVM\bin\LLVM-C.dll` を発見し **User scope に永続化**して復旧．sm-visualize の direct bake は内部 scalar_rgb 固定のため過去ログでも警告は出ていたが完走していた．**方向修正**: Speed-1 当初の「JIT 有効化で高速化」は既に JIT 経路に乗っているため不成立 → 「LLVM-C.dll 自動検出と診断ログ」に再定義（再発防止）．**本命の高速化レバーは Speed-2 path bake wavefront 化**（10× 以上見込み）．GPU は Intel HD Graphics 520 のみで CUDA 不可，CPU 側完結方針．精度（spp/max_depth）は不変． 補足: **Speed-1 完了**．`src/sm_tias_lightsim/runtime/llvm_init.py` に `ensure_drjit_libllvm_path()`（標準パス自動探索→ `os.environ` 設定）と `log_variant_status()`（llvm_/cuda_/scalar_ 経路を INFO 明示，要求 llvm_* で実 scalar_* なら WARNING 追加）を新規実装．`render/runner.py` で variant=llvm_* 時に自動検出を呼び、`ImportError` 時は原因明示ログ→ re-raise．`visualize/baker.py` でも `log_variant_status` 呼び出し追加＋ Speed-2 wavefront 化用に LLVM 自動探索の分岐を先取り．`cli/render.py` で import 順を制御（`sensors.py`/`lights.py` のモジュールレベル `import mitsuba` 前に検出を確実に通す）．`docs/02_ENV/ENV_02_環境構築手順.md` に LLVM インストール手順・DRJIT_LIBLLVM_PATH 説明・動作確認コマンドを追記．**速度は不変**（コード経路同等）．新規テスト 51 件追加で **606 件全通過**（仕様 A1〜E1 すべてカバー）．数値同等性: SHA256 は MC 内部シードで異なるが平均相対誤差 7.23e-05（5σ 閾値 0.4508 に対し差 0.011）で統計同等性パス．これで「環境変数が消えて沈黙クラッシュ」する事故が再発しない土台が整備された． 補足: **速度最適化ワーク一旦中断**（Speed-2 path bake wavefront 化は未着手）．**実時間の改善は実質ゼロ**（B1=508s／B2=56s で不変）．副次的成果として環境破綻問題の発見と恒久対処，JIT 診断ログ，ベンチ条件のドキュメント，テスト 51 件追加が得られた．中断理由: B2 は現状ボトルネックではなく，B1 は CPU 完結・精度据置の制約下で取れる打ち手が限定的．本筋のキャリブ作業（LSC モデル化）に戻ることがプロジェクト目的により近い．再開条件: path bake samples を増やすユースケース発生／NVIDIA GPU 利用可／クラウド計算活用判断／キャリブ反復回数増加でバッチ時間が研究進度を圧迫した場合．詳細・Speed-2 テンプレ保持は [TEST_04 中断記録](docs/06_TEST/TEST_04_シミュレーション速度最適化履歴.md#中断記録-suspension-note--2026-05-28) 参照．次のアクション: キャリブ作業（LSC モデル化）に戻る． +補足: **キャリブ方針の根本見直し（2026-05-28）**．「シミュ vs 実機 PNG の比較」を再検討した結果，**実機 PNG 自体が定量データとして揺らいでいる**ことが判明．MiniTIAS の現行撮影は AE/AWB/NR/EDGE/TONEMAP/SHADING がすべて Camera2 API のオート/デフォルトで，撮影ごとに露光・WB・補正量が変動する．既存 baseline `MiniTIAS_20260408_144434` もこのモードで取得されており，シミュ側でいくらモデルを精緻化しても比較対象が不安定．**当初考えていた「LSC モデル化」より上位の問題**として「**定量撮影モード**」を MiniTIAS 側に追加することを優先する．Android Camera2 API には `STATISTICS_LENS_SHADING_CORRECTION_MAP` (LSC ゲインマップ取得)・`SHADING_MODE=OFF` (LSC 無効化)・`MANUAL_SENSOR`/`MANUAL_POST_PROCESSING` 能力フラグが存在し，これらを活用すれば「ISP 介入を最小化した再現性ある撮影」が可能．要求仕様を [TECH_01 定量撮影モード要求仕様](docs/05_TECH/TECH_01_定量撮影モード要求仕様.md) に，MiniTias 側 Claude セッションで作業着手するためのハンドオフ手順を [TECH_02 MiniTIAS 引き継ぎ手順](docs/05_TECH/TECH_02_MiniTIAS引き継ぎ手順.md) にそれぞれ新規作成．データ受け渡しは `reference_measurement/quantitative/` 配下（gitignore 対象）で `MiniTIAS_QM_YYYYMMDD_HHmmss.{png,meta.json,lsc.npz}` 命名規則．MiniTIAS 側で実装後，定量モードで再撮影した baseline で改めてキャリブを進める方針．SmTIAS-LightSim 側のキャリブ作業は本仕様書を MiniTIAS に渡した時点で一旦停止． 実装済みモジュール: - `src/sm_tias_lightsim/uniformity.py` — Rec.709 輝度変換 + CoV/std/max-min（MiniTias-Evaluation コピー） diff --git "a/docs/05_TECH/TECH_01_\345\256\232\351\207\217\346\222\256\345\275\261\343\203\242\343\203\274\343\203\211\350\246\201\346\261\202\344\273\225\346\247\230.md" "b/docs/05_TECH/TECH_01_\345\256\232\351\207\217\346\222\256\345\275\261\343\203\242\343\203\274\343\203\211\350\246\201\346\261\202\344\273\225\346\247\230.md" new file mode 100644 index 0000000..c4c6e8d --- /dev/null +++ "b/docs/05_TECH/TECH_01_\345\256\232\351\207\217\346\222\256\345\275\261\343\203\242\343\203\274\343\203\211\350\246\201\346\261\202\344\273\225\346\247\230.md" @@ -0,0 +1,267 @@ +# 定量撮影モード要求仕様 (Quantitative Capture Mode Specification) + +本ドキュメントは SmTIAS-LightSim プロジェクトから MiniTIAS プロジェクトに対する **撮影モード拡張の要求仕様** である．SmTIAS-LightSim のキャリブレーション作業 (Step 8 系) で判明した「実機 PNG が定量データとして揺らぐ」問題を解消するための撮影アプリ側改修を依頼する． + +## 概要 (Overview) + +MiniTIAS（[MiniTias](https://github.com/rintoHasegawa/MiniTias) リポジトリ）の撮影アプリに，現状の通常撮影モードに加えて **「定量撮影モード (Quantitative Capture Mode)」** を追加することを要求する． + +定量撮影モードでは： + +- Camera2 API のオート制御 (AE/AWB/NR/EDGE/TONEMAP) を **すべて固定または OFF** にする． +- ISP が適用した **LSC ゲインマップ** を撮影ごとに同時保存する． +- 可能なら出力フォーマットを **RAW_SENSOR (DNG)** に切り替えられるようにする． + +これにより同じシーンを何度撮影しても再現性のある定量データが得られ，SmTIAS-LightSim 側のシミュレーション結果との突合が安定する． + +## 背景 (Background) + +### SmTIAS-LightSim と MiniTIAS の関係 + +- **MiniTIAS**: スマートフォンアプリ．AQUOS sense3 で白板・舌模型を撮影し PNG として保存する． +- **MiniTias-Evaluation**: PC 側．MiniTIAS が保存した PNG を読み込み照明均一性 (CoV／勾配／C/P 等) を算出する． +- **SmTIAS-LightSim**: PC 側．Mitsuba 3 で同じ筐体・LED 配置を仮想撮影し，MiniTias-Evaluation と同じ指標を計算する． + +→ 3 つのプロジェクトで **同じ評価指標** を出すことで「シミュ vs 実機」を比較する． + +### 現状の問題（Step 8 キャリブで判明） + +Step 8 キャリブレーション ([TEST_01](../06_TEST/TEST_01_キャリブレーション検証履歴.md) 参照) で，シミュと実機の比較を試みた結果，以下の現象が観測された： + +- **形状指標残差 1.6〜1.9 倍** が解消されない（OETF 順方向適用後でも） +- 輝度マップの「形」が実機（中央ピーク楕円）とシミュ（Y 軸単調勾配）で **構造的に違う** ([TEST_03](../06_TEST/TEST_03_輝度マップ形状追跡.md) 参照) +- LED 位置・反射率・配光・センサ方向 ([TEST_01](../06_TEST/TEST_01_キャリブレーション検証履歴.md) Step 8-9/8-10/8-11/8-12 系) すべてを試したが「形」は変わらず + +「形を変える唯一の道」として **LSC (Lens Shading Correction) モデル化** が候補に挙がったが，さらに調査した結果，**より根本的な問題** が判明した： + +- 既存 baseline 画像 (`MiniTIAS_20260408_144434`) は **MiniTIAS の通常撮影モード**で取得されており，**ISP がすべて自動制御**で動作している． +- 具体的には [MiniTIAS/docs/04_SPEC/SPEC_01](../../MiniTIAS/docs/04_SPEC/SPEC_01_画面機能仕様書.md) のとおり： + - AE/AF 安定 1 秒待ち → STILL_CAPTURE → YUV_420_888 取得 → BT.601 で RGB → PNG 保存 + - AE / AWB / NR / EDGE / TONEMAP / SHADING はすべて Camera2 API のデフォルト (オート/ON) のまま +- これは「人間が見て自然な画像」用設定であり，**定量解析向けではない**． +- 撮影ごとに露光・WB・補正量が変動する可能性があり，**同じシーンを 2 回撮っても同じ値にならない可能性** がある． + +つまり「定量比較の対象である実機 PNG 自体が揺らいでいる」状態．まずここを固定化しない限り，シミュ側でいくらモデルを精緻化しても比較できない． + +## 目的 (Objective) + +定量撮影モードの導入により以下を達成する： + +1. **撮影再現性の確保**: 同条件で繰り返し撮影しても mean / std / 形状指標が同じ値になる． +2. **ISP 介入の最小化**: AE/AWB/NR/EDGE/TONEMAP/SHADING を固定/OFF し，センサ出力に近い値を取得する． +3. **メタデータの可視化**: ISP が適用した LSC ゲインマップを取得して別ファイル保存する． +4. **シミュ比較の土台**: SmTIAS-LightSim 側のキャリブレーション・LSC 検証が安定したデータで進められる． + +## 要求仕様 (Requirements) + +### 1. 撮影モード切替 UI + +撮影画面 (S-01) に「定量撮影モード」のトグルスイッチを追加する． + +- デフォルト: OFF（既存通常モード） +- ON 時: 後述の Camera2 API 設定をすべて適用 +- 後方互換: 既存ユーザー・既存撮影ワークフローには影響しない + +### 2. Camera2 API 設定（定量モード ON 時） + +| キー | 値 | 目的 | +| --- | --- | --- | +| `CONTROL_MODE` | `OFF`（マニュアル全制御） | ISP オート制御の完全停止 | +| `CONTROL_AE_MODE` | `OFF` | 自動露光停止 | +| `SENSOR_EXPOSURE_TIME` | 固定値（要キャリブ，例 1/60 s） | 露光時間固定 | +| `SENSOR_SENSITIVITY` | 最低 ISO（端末依存，例 50） | ノイズ最小化 + ゲイン固定 | +| `CONTROL_AWB_MODE` | `OFF` | 自動 WB 停止 | +| `COLOR_CORRECTION_GAINS` | 固定値 (R=G=B=1.0 推奨) | チャネルゲイン固定 | +| `COLOR_CORRECTION_TRANSFORM` | 単位行列 | カラーマトリクス無効化 | +| `NOISE_REDUCTION_MODE` | `OFF` | NR 無効化（アーティファクト排除） | +| `EDGE_MODE` | `OFF` | エッジ強調無効化 | +| `TONEMAP_MODE` | `CONTRAST_CURVE` (線形カーブ) または `PRESET_CURVE` (SRGB) | トーンマッピング固定 | +| `SHADING_MODE` | **`HIGH_QUALITY`** (LSC 補正適用) または **`OFF`** (LSC 無効化) のいずれか選択可 | LSC の挙動制御（次節参照） | +| `STATISTICS_LENS_SHADING_MAP_MODE` | `ON` | LSC ゲインマップ取得有効化 | + +> ※ `SHADING_MODE = OFF` を選んだ場合は cos⁴ falloff が画像に残る．後段のシミュ側で物理 cos⁴ を加える前提なら有用．通常運用では `HIGH_QUALITY` を推奨． + +### 3. LSC ゲインマップの保存 + +撮影成功時に `CaptureResult.STATISTICS_LENS_SHADING_CORRECTION_MAP` から `LensShadingMap` を取得して保存する． + +| 項目 | 仕様 | +| --- | --- | +| 取得 API | `result.get(CaptureResult.STATISTICS_LENS_SHADING_CORRECTION_MAP)` | +| データ形状 | 4 × N × M float 配列（4 = R/Geven/Godd/B チャネル，N = 列，M = 行） | +| 値の意味 | ≥ 1.0 のゲイン係数．`corrected = raw × gain` | +| 保存形式 | NPZ（推奨）または JSON．画像ファイル名と同 prefix で `.lsc.npz` 等 | +| 保存先 | 画像と同ディレクトリ | +| マップサイズ | `CameraCharacteristics.LENS_INFO_SHADING_MAP_SIZE` から取得 | + +### 4. 撮影メタデータの保存（撮影パラメータの可視化） + +LSC マップに加えて，撮影時の Camera2 API パラメータを JSON で保存する．後段でシミュレーションの境界条件を再現するために必要． + +```json +{ + "capture_timestamp_utc": "2026-05-28T10:00:00Z", + "device_model": "SH-02M", + "android_version": "9", + "camera_id": "1", + "hardware_level": "LIMITED", + "capture_mode": "quantitative", + "settings": { + "control_mode": "OFF", + "ae_mode": "OFF", + "exposure_time_ns": 16666666, + "sensor_sensitivity_iso": 50, + "awb_mode": "OFF", + "color_correction_gains": [1.0, 1.0, 1.0, 1.0], + "color_correction_transform": "identity", + "noise_reduction_mode": "OFF", + "edge_mode": "OFF", + "tonemap_mode": "CONTRAST_CURVE", + "shading_mode": "HIGH_QUALITY", + "statistics_lens_shading_map_mode": "ON" + }, + "image_format": "YUV_420_888", + "image_size": [4000, 3000], + "yuv_to_rgb_matrix": "BT.601" +} +``` + +ファイル名規則: `.meta.json` + +### 5. 推奨出力フォーマット + +優先順位は以下： + +| 優先度 | フォーマット | 説明 | +| --- | --- | --- | +| 第 1 | **`RAW_SENSOR` (DNG)** | ISP 介入ゼロ．センサ出力そのまま．[DNG GainMap 仕様](https://www.adobe.com/content/dam/acom/en/products/photoshop/pdfs/dng_spec_1.4.0.0.pdf) と整合 | +| 第 2 | **`YUV_420_888` + 上記メタデータ + LSC マップ** | 現状フォーマットに情報追加．後段で逆処理可能 | +| 第 3 | **PNG（現状） + メタデータ + LSC マップ** | 最小実装．BT.601 YUV→RGB 経由のため情報量は最小 | + +第 1 は実機が DNG 出力をサポートしている必要がある（AQUOS sense3 で要確認）．サポートしていない場合は第 2 を採用． + +### 6. ハードウェアサポート判定 + +定量モード起動時に `CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL` を取得して以下を判定： + +- `LEGACY`: 定量モード **不可**（マニュアル制御サポートなし）→ ユーザーに警告表示 +- `LIMITED`: 部分サポート．SHADING_MODE と LSC マップ取得が可能か個別確認 +- `FULL` / `LEVEL_3`: **完全サポート** + +必要な能力フラグ： + +- `REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR` (露光・ISO 固定) +- `REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING` (NR/EDGE/TONEMAP/SHADING 固定) +- `REQUEST_AVAILABLE_CAPABILITIES_RAW` (DNG 出力，第 1 優先時のみ必須) + +判定結果は前述メタデータ JSON の `hardware_level` フィールドに記録する． + +## 推奨実装方針 (Recommended Implementation) + +### Flutter / camera パッケージの限界 + +[camera パッケージ](https://pub.dev/packages/camera) は AE/AWB/SHADING_MODE 等の詳細制御を **直接公開していない** ことが多い．定量モードを実現するには以下のいずれかが必要： + +- **Platform Channel で Camera2 API を直接制御**（推奨） + - Android Kotlin/Java 側で Camera2 API を直接叩く + - Flutter 側は MethodChannel で「定量モード撮影」要求を送る +- **camerax_android** など低レベル制御を公開した代替パッケージへの移行 +- **Native Plugin の自作** + +実装規模が大きい場合は段階的に： + +1. **Phase 1**: Camera2 詳細制御の MethodChannel 実装（露光・WB 固定，LSC マップ取得） +2. **Phase 2**: LSC マップ・メタデータ保存ロジック +3. **Phase 3**: 撮影画面 UI に定量モードトグル追加 +4. **Phase 4**: ハードウェアサポート判定とユーザー案内 +5. **Phase 5**: RAW_SENSOR (DNG) 対応（任意） + +### ディレクトリ構成提案 + +MiniTIAS 既存構造に従い： + +```text +android/app/src/main/kotlin// +└── camera/ + └── QuantitativeCameraController.kt # Camera2 直接制御 + +lib/services/ +├── quantitative_camera_service.dart # Platform Channel ラッパ +├── lsc_map_service.dart # LSC マップ NPZ 保存 +└── capture_metadata_service.dart # メタデータ JSON 保存 + +lib/providers/ +└── camera_provider.dart # 定量モード状態追加（既存 Provider 拡張） +``` + +## 期待される効果 (Expected Effects) + +| 項目 | 改善内容 | +| --- | --- | +| 撮影再現性 | 同条件 10 連射で mean / std が ±1% 以内に揃う | +| 色温度ドリフト | AWB 固定により無彩色撮影で色シフト排除 | +| LSC 補正可視化 | ISP が適用したゲインマップが取得でき，シミュ側で逆適用可能 | +| 物理 cos⁴ 検証 | SHADING_MODE = OFF モードで実機 raw 相当を取得し，シミュ + cos⁴ と比較可能 | +| RAW 比較 (任意) | DNG 経路が確立すれば，ISP 完全排除でセンサ生値 vs Mitsuba 直接比較 | +| キャリブ作業の安定化 | SmTIAS-LightSim 側で同じ baseline を繰り返し再撮影しても結果が動かない | + +## 後方互換 (Backward Compatibility) + +- 通常撮影モードは現状仕様のまま維持（既存撮影ワークフローを壊さない） +- 既存 baseline 画像 (`MiniTIAS_20260408_144434`) は **「通常モードで撮影された」** ことを SmTIAS-LightSim 側で明示記録（[TEST_03](../06_TEST/TEST_03_輝度マップ形状追跡.md) に追記予定） +- 新規定量モード撮影は別命名規則を推奨： + - 例: `MiniTIAS_QM_YYYYMMDD_HHmmss.png`（QM = Quantitative Mode） + - メタデータ: `MiniTIAS_QM_YYYYMMDD_HHmmss.meta.json` + - LSC マップ: `MiniTIAS_QM_YYYYMMDD_HHmmss.lsc.npz` + +## 検証方法 (Verification) + +定量モード実装完了後，以下を実施して受け入れ判定とする： + +### V1. 再現性検証 + +同条件（光源 ON・同じ白板・三脚固定）で **10 回連続撮影** し，全画像で： + +- mean / std の変動係数 (CoV of means) < 1% +- 形状指標 (CoV／勾配／C/P) の標準偏差 < 0.005 + +### V2. LSC マップ取得検証 + +- 全撮影で `.lsc.npz` が保存されている +- マップサイズが `CameraCharacteristics.LENS_INFO_SHADING_MAP_SIZE` と一致 +- ゲイン値がすべて ≥ 1.0 +- 中央 (col=N/2, row=M/2) のゲインが ≈ 1.0 + +### V3. SHADING_MODE 切替検証 + +- `SHADING_MODE = OFF` で撮影した画像が `HIGH_QUALITY` より周辺で明らかに暗い（cos⁴ falloff 可視化） +- `HIGH_QUALITY × (1 / LSC マップ)` ≈ `OFF` の関係性が成立する（数値差 < 5%） + +### V4. SmTIAS-LightSim 側での突合 + +- 定量モード白板撮影 (SHADING_MODE = HIGH_QUALITY) を baseline として再キャリブ +- シミュ vs 実機の残差が現状 2.1× → 1.5× 以下に縮むこと（仮目標） + +## 開放質問 (Open Questions) + +実装着手時に確認が必要な事項： + +| ID | 質問 | 確認方法 | +| --- | --- | --- | +| Q1 | AQUOS sense3 のハードウェアレベルは何か | デバッグビルドで `CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL` を読みログ出力 | +| Q2 | SH-02M のフロントカメラで `REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING` がサポートされているか | 同上．未サポートなら定量モードは部分実装 | +| Q3 | DNG (RAW_SENSOR) 出力は可能か | `REQUEST_AVAILABLE_CAPABILITIES_RAW` を確認 | +| Q4 | LSC マップサイズはどの程度か（例 13×17 等） | 実機でログ出力．データ量設計の参考 | +| Q5 | 露光時間・ISO の最適値（固定値の決定） | 白板撮影で被写体の明るさが適切かを実機で試行錯誤 | +| Q6 | 既存 `MiniTIAS_20260408_144434` を定量モードで再撮影するか | 研究方針との整合（再撮影なら現 baseline は参考扱い） | +| Q7 | 既存 PNG 保存形式 (BT.601 経由) を維持するか YUV/RAW 直接保存に変えるか | SmTIAS-LightSim 側読み込みコストとのトレードオフ | + +## 関連ドキュメント (Related Documents) + +- [TEST_01 キャリブレーション検証履歴](../06_TEST/TEST_01_キャリブレーション検証履歴.md) — Step 8-1〜8-12 で「実機 PNG が定量データとして揺らぐ」を発見した経緯 +- [TEST_03 輝度マップ形状追跡](../06_TEST/TEST_03_輝度マップ形状追跡.md) — 形のずれの定性的記録．LSC モデル化議論の出発点 +- [SPEC_04 評価仕様](../04_SPEC/SPEC_04_評価仕様.md) — sm-evaluate の OETF 適用・mean アンカー処理 +- [SPEC_03 基準設計の物理構成](../04_SPEC/SPEC_03_基準設計の物理構成.md) — シミュ側物理モデル +- [MiniTIAS/docs/04_SPEC/SPEC_01 画面機能仕様書](../../MiniTIAS/docs/04_SPEC/SPEC_01_画面機能仕様書.md) — 現状のカメラ制御仕様（変更前ベースライン） +- [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) diff --git "a/docs/05_TECH/TECH_02_MiniTIAS\345\274\225\343\201\215\347\266\231\343\201\216\346\211\213\351\240\206.md" "b/docs/05_TECH/TECH_02_MiniTIAS\345\274\225\343\201\215\347\266\231\343\201\216\346\211\213\351\240\206.md" new file mode 100644 index 0000000..1770af8 --- /dev/null +++ "b/docs/05_TECH/TECH_02_MiniTIAS\345\274\225\343\201\215\347\266\231\343\201\216\346\211\213\351\240\206.md" @@ -0,0 +1,254 @@ +# 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.` | +| 撮影メタデータ | `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)