# 照明均一性評価アルゴリズム (Illumination Uniformity Evaluation)

## 概要 (Overview)

MiniTIAS で撮影した白板画像の照明均一性を定量的に評価する．白板の白壁面領域の輝度分布を解析し，3 つの指標で均一性を定量化する．

## 輝度変換 (Luminance Conversion)

### 方法

RGB 画像を ITU-R BT.709（Rec.709）の輝度係数でグレースケールに変換する．

$$Y = 0.2126 R + 0.7152 G + 0.0722 B$$

- $Y$: 輝度（0.0〜255.0, float64）
- $R, G, B$: 各チャネルの画素値（0〜255, uint8）

### 選定理由

| 方法 | 定義 | 不採用の理由 |
| --- | --- | --- |
| **Rec.709（採用）** | 上記の加重平均 | — |
| V チャネル（HSV） | max(R, G, B) | 白板では R≈G≈B のため差は小さいが，規格に基づかない |
| L\*（CIE L\*a\*b\*） | 非線形変換 | 物理的な照明ムラと比例せず，照明均一性評価には不適 |

Rec.709 は人間の視感度に基づく標準的な輝度定義であり，照明工学・画像評価の論文で広く使用されている．

### 参照

- ITU-R BT.709-6: Parameter values for the HDTV standards for production and international programme exchange

## 均一性指標 (Uniformity Metrics)

ROI 内の全画素の輝度値から以下の 3 指標を算出する．

### CoV（変動係数）

$$\text{CoV} = \frac{\sigma}{\mu}$$

- $\mu$: 輝度の平均値
- $\sigma$: 輝度の標準偏差
- 無次元量．値が小さいほど均一
- 照明の均一性評価で最も一般的な指標

### 標準偏差

$$\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^{N} (Y_i - \mu)^2}$$

- $N$: ROI 内の総画素数
- 輝度のばらつきの絶対値を示す
- CoV と併用することで，平均輝度の影響を考慮した評価が可能

### 最大/最小比

$$\text{Max/Min Ratio} = \frac{Y_{\max}}{Y_{\min}}$$

- 極端なムラ（局所的な明暗）の検出に有効
- 理想的な均一照明では 1.0
- $Y_{\min} = 0$ の場合は計算不能（ROI 設定の誤りを示す）

## ROI 設定 (Region of Interest)

### 対象領域

MiniTIAS の開口部に白板を取り付けて撮影する．ROI は**白板の表面領域**（中央の白い四角形）とする．以下を除外する:

- 白板の外側（MiniTIAS 筐体の壁面）
- 白板のフレーム・エッジ部分
- ラベル（「SmTIAS 001」等）

### 設定方法

1. `scripts/select_roi.py` で 1 枚の画像上に矩形を描いて座標を決定
2. 座標は `config/roi_config.json` に保存
3. 同一画角の全画像に同じ ROI を適用（バッチ解析）

### 起動コマンド

```bash
python scripts/select_roi.py --image data/minitias/whiteboard/<画像ファイル名>.png --config config/roi_config.json --roi minitias.whiteboard
```

OpenCV のウィンドウが開くので，マウスで矩形を選択して Enter で確定する．ESC でキャンセル．

## バッチ解析 (Batch Analysis)

`scripts/run_uniformity.py` で白板画像を一括解析する．ROI 設定済みであること．

### 起動コマンド

```bash
# ディレクトリ内の全画像を一括解析
python scripts/run_uniformity.py --image data/minitias/whiteboard/ --config config/roi_config.json --roi minitias.whiteboard

# 単一画像の解析
python scripts/run_uniformity.py --image data/minitias/whiteboard/<画像ファイル名>.png --config config/roi_config.json --roi minitias.whiteboard
```

### 出力

- `output/results/summary_uniformity.csv` — 全画像の均一性指標一覧
- `output/results/<画像名>_uniformity.json` — 各画像の詳細結果
- `output/figures/<画像名>_luminance_map.png` — 輝度マップ
- `output/figures/<画像名>_histogram.png` — 輝度ヒストグラム

## 結果の確認 (Result Viewer)

Streamlit ベースのビューアで解析結果を確認できる．

### 起動方法

```bash
.venv\Scripts\streamlit run scripts/viewer.py
```

### 前提条件

- `scripts/run_uniformity.py` でバッチ解析が完了していること
- `output/results/summary_uniformity.csv` および `output/figures/` に画像ファイルが存在すること

### 機能

- **全体比較タブ**: 全画像の均一性指標テーブル・統計サマリー・指標の比較グラフ（2×2 棒グラフ）
- **個別画像タブ**: ドロップダウンまたは矢印ボタンで画像を切り替え，元画像（ROI オーバーレイ付き）・輝度マップ・ヒストグラムを横並びで確認

## キャリブレーション (Calibration)

照明均一性評価ではカラーキャリブレーションを行わない．輝度の相対的なばらつき（CoV 等）は画像内の比較であり，カメラの色特性のズレが全画素に等しく影響するため，指標の値に影響しない．