diff --git a/CLAUDE.md b/CLAUDE.md index 8875cac..7e975d8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,3 +77,12 @@ ### 04_SPEC(仕様・設計) - 画面機能仕様書: docs/04_SPEC/SPEC_01_画面機能仕様書.md + +### 05_TECH(技術設計・外部要求仕様) + +- 定量撮影モード要求仕様(SmTIAS-LightSim 側からの外部要求): docs/05_TECH/TECH_01_定量撮影モード要求仕様.md +- MiniTIAS 引き継ぎ手順(SmTIAS-LightSim 側からのハンドオフ手順): docs/05_TECH/TECH_02_MiniTIAS引き継ぎ手順.md + +### 06_TEST(テスト・実機検証) + +- AQUOS sense3 カメラ能力診断結果(2026-05-31): docs/06_TEST/camera_diagnostics_20260531_161734.json 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) diff --git a/docs/06_TEST/camera_diagnostics_20260531_161734.json b/docs/06_TEST/camera_diagnostics_20260531_161734.json new file mode 100644 index 0000000..ccf9e8b --- /dev/null +++ b/docs/06_TEST/camera_diagnostics_20260531_161734.json @@ -0,0 +1,123 @@ +{ + "cameraId": "1", + "hardwareLevel": 3, + "capabilities": [ + 0, + 1, + 2, + 5, + 6, + 4, + 7, + 3 + ], + "exposureTimeRangeNs": [ + 79806, + 871614530 + ], + "sensitivityRange": [ + 40, + 2506 + ], + "lscMapSize": null, + "availableLensShadingMapModes": [ + 0, + 1 + ], + "availableNoiseReductionModes": [ + 0, + 1, + 2, + 3, + 4 + ], + "availableEdgeModes": [ + 0, + 1, + 2, + 3 + ], + "availableTonemapModes": [ + 0, + 1, + 2 + ], + "availableShadingModes": [ + 0, + 1, + 2 + ], + "availableAwbModes": [ + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 0 + ], + "availableAfModes": [ + 0 + ], + "minFocusDistance": 0.0, + "hyperfocalDistance": 0.8189331293106079, + "rawOutputSizes": [ + "3264x2448" + ], + "yuvOutputSizes": [ + "3264x2448", + "2048x1536", + "1920x1440", + "1920x1080", + "2560x800", + "1600x1200", + "1440x1080", + "1280x960", + "1280x720", + "1200x1200", + "1280x480", + "864x480", + "720x480", + "640x480", + "480x360", + "480x320", + "352x288", + "320x240", + "240x180" + ], + "jpegOutputSizes": [ + "3264x2448", + "2048x1536", + "1920x1440", + "1920x1080", + "2560x800", + "1600x1200", + "1440x1080", + "1280x960", + "1280x720", + "1200x1200", + "1280x480", + "864x480", + "720x480", + "640x480", + "480x360", + "480x320", + "352x288", + "320x240", + "240x180" + ], + "colorFilterArrangement": 3, + "blackLevelPattern": "BlackLevelPattern([64, 64], [64, 64])", + "whiteLevel": 1023, + "physicalSize": [ + 3.557760000228882, + 2.6683201789855957 + ], + "pixelArraySize": [ + 3264, + 2448 + ], + "activeArraySize": "Rect(0, 0 - 3264, 2448)" +} \ No newline at end of file