# SmTIAS-LightSim への引き継ぎ (Hand-off to SmTIAS-LightSim)

本ドキュメントは，MiniTias-Evaluation で実装した **DNG 読み込み I/F** を SmTIAS-LightSim 側へコピー・統合するための引き継ぎ書である．要求仕様は [TECH_01](TECH_01_DNG対応要求仕様.md)（SmTIAS-LightSim 側での名称は TECH_05）．

## 1. 実装スコープ (What is done / not done)

TECH_01 の Phase 分割のうち，本引き継ぎ時点で完了しているのは **Phase 1（DNG 読み込み I/F）のみ**．

| TECH_01 Phase | 内容 | 状態 |
| --- | --- | --- |
| Phase 1 | DNG 読み込み I/F (`dng_loader.py`) | ✅ **完了**（コピー対象） |
| Phase 2 | メタデータ JSON 読み込み I/F (`metadata_loader.py`) | ❌ 未実装 |
| Phase 3 | LSC マップ参照・hot pixel マスク | △ LSC 順適用はプロトタイプのみ（`run_uniformity_dng.py` 内） |
| Phase 4〜6 | 既存パイプライン統合 / PNG vs DNG / SPEC 更新 | ❌ 未着手 |

## 2. コピー対象ファイル (Files to copy)

| コピー元（MiniTias-Evaluation） | コピー先（SmTIAS-LightSim） | 区分 |
| --- | --- | --- |
| `src/io/dng_loader.py` | `src/sm_tias_lightsim/evaluation/dng_loader.py` | ★ 正規コピー対象 |
| `scripts/run_uniformity_dng.py` | （参考）`cli/` 等に統合 | LSC 順適用・向き合わせ・評価フローの参考 |
| `src/analysis/spatial.py` の `calc_radial_min_max_ratio` | 既存 spatial/uniformity 相当へ**マージ** | 動径 min/max 比指標（追加指標） |

- **ファイル先頭にコピー元を明記**（TECH_01 指定）:
  ```python
  """DNG 読み込みモジュール．

  MiniTias-Evaluation/src/io/dng_loader.py を SmTIAS-LightSim にコピーしたもの．
  オリジナルは MiniTias-Evaluation 側で管理する．バグ修正・機能追加はそちらで行い，
  本プロジェクトに反映する形を取る．
  """
  ```
- `spatial.py` は SmTIAS-LightSim 側の既存均一性コードと競合しうるため，**丸ごとコピーせず `calc_radial_min_max_ratio` のみマージ**すること．

## 3. ★重要な設計判断・注意点（コピーだけでは伝わらない）

以下は実装の前提であり，**TECH_01（要求仕様）の記述と食い違う点を含む**．必ず反映すること．

1. **DNG は LSC 未補正 — `apply_lsc_inverse` は誤り**: RAW_SENSOR DNG はレンズシェーディング**未補正**（補正は DNG OpcodeList2 の GainMap / meta.json lscMap として付随するが rawpy は適用しない）．TECH_01 の `apply_lsc_inverse`（「DNG=補正済み」前提で逆適用）は実態と逆．照明ムラを測るには **lscMap を順方向に適用**してレンズビネットを除去する（`image × interpolate(lscMap)`）．
2. **linear 系出力は `output_color=raw`**: カラーマトリクスを通すとチャンネル混合で per-channel 比例が崩れる．`rgb_float32`/`luma_float32` は `output_color=rawpy.ColorSpace.raw` で読む（`rgb_uint8` のみ sRGB）．これにより入射光量とセンサ信号の比例（放射輝度リニアリティ）を担保．
3. **向き**: DNG はセンサ native が **landscape**．PNG/preview と同じ portrait にするには `rot90(-1)`（左右反転なし．フロントカメラ id=1 の preview はミラーされるが RAW はミラーされない）．
4. **luma の Rec.709 は固定加重プロキシ**: `output_color=raw` では Rec.709 luma は厳密な CIE 輝度ではなく，既存 PNG 経路互換の固定加重．
5. **PNG は厳密に linear 化できない**: トーンカーブ・8bit・透過関数不明のため．DNG 採用の根拠（[REPORT_02](../07_REPORT/REPORT_02_PNG_DNG評価比較報告書.md)）．

## 4. 引き渡す評価結果（暗闇＝MiniTIAS のみ）

代表結果は **外乱光に汚染されていない「MiniTIAS の照明のみ」の撮影**（`MiniTIAS_QM_20260601_124500`，室内灯 OFF）を採用する．外乱光の有無で評価はほぼ変わらない（[REPORT_03](../07_REPORT/REPORT_03_外乱光影響評価報告書.md)）が，純粋な装置照明の均一性を代表させるため暗闇条件を選定．

評価条件: linear（output_color=raw）／ portrait ／ LSC 補正あり ／ 白板 ROI．

| 指標 | 値 |
| --- | --- |
| CoV | 0.0695 |
| max/min 比 | 1.617 |
| 中心/周辺比 | 1.0911 |
| 勾配 (%) | 8.35 |
| 動径 min/max 比 | 0.8600 |

成果物（図・CSV）はハンドオフ束 `handoff_smtias_lightsim/results_dark_124500/` に同梱．

## 5. コピー後の検証 (Verification — TECH_01 V4)

- コピー後の SmTIAS-LightSim 側で**同じ DNG**（`MiniTIAS_QM_20260601_124500.dng`）を読み込み，**上表と同じ評価指標**が出ること．
- SmTIAS-LightSim の既存テストが全合格すること．
- 依存追加: `rawpy>=0.21.0`．

## 6. 参照 (References)

- [TECH_01 DNG 対応要求仕様](TECH_01_DNG対応要求仕様.md)
- [REPORT_02 PNG/DNG 評価比較報告書](../07_REPORT/REPORT_02_PNG_DNG評価比較報告書.md)
- [REPORT_03 外乱光影響評価報告書](../07_REPORT/REPORT_03_外乱光影響評価報告書.md)
- 設計判断・経緯の詳細: `docs/PROGRESS.md`