# SmTIAS-Evaluation DNG 対応要求仕様 (DNG Support Specification for SmTIAS-Evaluation)

> **本ドキュメントについて（取り込み注記）**: SmTIAS-LightSim プロジェクトから受領した DNG 対応要求仕様（先方での名称は TECH_05）を，本プロジェクトの命名規則（GUIDE_03）に従い取り込んだもの．文中の他ドキュメント参照（TECH_01/03/04・TEST_01・SPEC_04 等）は **SmTIAS-LightSim 側のドキュメント**を指し，本プロジェクト内には存在しない．
>
> 本書は**要求の記録**である．実装の詳細（API・データ仕様・アルゴリズム）は [SPEC_01](../04_SPEC/SPEC_01_アーキテクチャ設計.md) / [SPEC_02](../04_SPEC/SPEC_02_照明均一性評価アルゴリズム.md)，コピー向け要点は [TECH_02](TECH_02_SmTIAS-LightSimへの引き継ぎ.md)，経緯の詳細は [PROGRESS.md](../PROGRESS.md) を参照．完了済みの実装計画（Phase 分割・検証手順 V1〜V4・Open Questions・関数シグネチャ案 等）は本整理で削除した（git 履歴に残る）．

SmTIAS 側で実装された定量撮影モードの出力フォーマットが PNG から DNG (RAW_SENSOR) に変更されたことに伴い，SmTIAS-Evaluation 側にも DNG 読み込み・解析機能の追加を依頼したもの．

## 概要 (Overview)

SmTIAS-Evaluation（[SmTIAS-Evaluation](https://github.com/rintoHasegawa/SmTIAS-Evaluation) リポジトリ）に対し，以下の機能追加を要求した：

1. **DNG 読み込み I/F** の新規実装（10-bit BGGR Bayer 展開）
2. **メタデータ JSON 読み込み I/F** の新規実装（撮影条件・LSC マップ・hot pixel リスト等）
3. **既存 PNG 経路と並列対応**（後方互換）
4. **既存評価指標との互換**（CoV / 勾配 / C/P / max-min 等が DNG 入力でも同じロジックで算出可能）

これらの実装は **SmTIAS-LightSim 側にコピーされる前提**で，再利用性の高い設計とする．

## 実装状況 (Implementation Status — SmTIAS-Evaluation)

要求に対する SmTIAS-Evaluation での実装結果（要求と異なる点を含む）．

| 要求 | 状況 | 実体・備考 |
| --- | --- | --- |
| 1. DNG 読み込み I/F（`dng_loader.py` / `load_image_dng`） | ✅ 実装 | `src/io/dng_loader.py`．`rgb_float32`・`luma_float32`（`output_color=raw`）・`rgb_uint8`（sRGB）を実装 |
| 2. メタデータ JSON 読み込み（`metadata_loader.py`） | 🟡 一部 | 専用モジュールは未作成．LSC マップ読み込みは `src/io/dng_pipeline.py` の `lsc_gain_rgb` に内包．`load_metadata` / `load_hot_pixel_list` は未実装 |
| 3. Hot pixel マスク（`mask_hot_pixels`） | ⬜ 未実装 | SmTIAS 側のホット画素提供待ち |
| 4. LSC 参照（`apply_lsc_inverse`） | ⚠️ 方針転換 | 実機 DNG は LSC **未補正**と判明．逆適用ではなく **順適用**（`dng_pipeline.lsc_gain_rgb` でビネット除去）．`apply_lsc_inverse` は未実装 |
| 5. PNG 経路との並列対応 | ✅ 実装 | `load_image` は無修正．DNG は `scripts/run_uniformity_dng.py` で別経路．統一 I/F `load_image_any` は未実装（任意項目） |
| 6. 評価指標との互換 | ✅ 実装 | `uniformity` / `spatial` 等は無修正で DNG 輝度（linear ×255 スケール）に適用 |

> 仕様外で新規追加: `src/io/dng_pipeline.py`（DNG の LSC 順適用・portrait 化・Rec.709 輝度化をまとめた高レベル I/F）と，動径 min/max 比指標（`spatial.calc_radial_min_max_ratio`）．Phase 4〜6（既存パイプライン統合・PNG/DNG 検証・SPEC 更新）は継続中．DNG のデータ仕様（10-bit・黒レベル・デモザイク等）は [SPEC_01](../04_SPEC/SPEC_01_アーキテクチャ設計.md) 「DNG データ仕様」に移設した．

## 背景 (Background)

### 三項プロジェクトの関係

```text
┌─────────────────────────┐      ┌──────────────────────────┐
│  SmTIAS                │      │  SmTIAS-Evaluation      │
│  (Flutter / Android)     │ ──→  │  (Python)                 │
│  撮影アプリ                │      │  実機データ評価ツール       │
│  - PNG 保存（通常モード）   │      │  - 評価指標算出           │
│  - DNG 保存（定量モード）   │      │  - 可視化                 │
└─────────────────────────┘      └──────────────────────────┘
                                          │
                                          │ コピー（uniformity.py 等）
                                          ▼
                              ┌──────────────────────────┐
                              │  SmTIAS-LightSim          │
                              │  (Python / Mitsuba 3)     │
                              │  シミュ vs 実機比較        │
                              └──────────────────────────┘
```

### 経緯のまとめ

- 2026-05-28: SmTIAS-LightSim 側 Step 8 キャリブで「実機 PNG 自体が定量データとして揺らぐ」を発見 ([TEST_01](../06_TEST/TEST_01_キャリブレーション検証履歴.md))
- 2026-05-28: SmTIAS 側に [TECH_01 定量撮影モード要求仕様](TECH_01_定量撮影モード要求仕様.md) を発行
- 2026-06-01: SmTIAS 側で実装完了．AQUOS sense3 (SH-02M) が LEVEL_3 で DNG 経路採用 ([TECH_03](TECH_03_定量モード実装報告とSHADING_MODE相談.md))
- 2026-06-01: SHADING_MODE = HIGH_QUALITY を本流維持で合意 ([TECH_04](TECH_04_SmTIASへの回答.md))
- 2026-06-01: 本要求（SmTIAS-Evaluation 側にも DNG 対応を依頼）を発行

### 役割分担 (Role Distribution)

DNG 読み込みの責務は **SmTIAS-Evaluation を一次窓口**とする．既存パターン（`uniformity.py` が SmTIAS-Evaluation から SmTIAS-LightSim にコピー）を踏襲する：

| プロジェクト | 責務 |
| --- | --- |
| **SmTIAS** | DNG + meta.json の保存（実装済） |
| **SmTIAS-Evaluation（一次窓口）** | DNG/meta.json の読み込み I/F を正規実装．既存評価指標との並列対応 |
| **SmTIAS-LightSim（コピー側）** | SmTIAS-Evaluation の DNG 読み込み I/F をコピー（`uniformity.py` パターン継承） |

## 既存ドキュメントとの整合 (Cross-References)

- [TECH_02 SmTIAS-LightSim への引き継ぎ](TECH_02_SmTIAS-LightSimへの引き継ぎ.md) — コピー対象・設計判断・引き渡し評価値
- [TECH_01 定量撮影モード要求仕様](TECH_01_定量撮影モード要求仕様.md) — 撮影モード側の要求書（SmTIAS-LightSim 側）
- [TECH_03 定量モード実装報告と SHADING_MODE 相談](TECH_03_定量モード実装報告とSHADING_MODE相談.md) — SmTIAS 側実装報告（meta.json スキーマ等）
- [TECH_04 SmTIAS への回答](TECH_04_SmTIASへの回答.md) — SHADING_MODE 判断とフェーズ A/B 分割
- [SPEC_01 アーキテクチャ設計](../04_SPEC/SPEC_01_アーキテクチャ設計.md) / [SPEC_02 照明均一性評価アルゴリズム](../04_SPEC/SPEC_02_照明均一性評価アルゴリズム.md) — 実装の正規仕様
- [Android Camera2 API DNG](https://developer.android.com/reference/android/hardware/camera2/DngCreator)
- [rawpy ドキュメント](https://letmaik.github.io/rawpy/api/)