# 照明均一性評価アルゴリズム (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 でキャンセル．

## 空間分析 (Spatial Analysis)

ROI 内の輝度の空間的な偏り（中心-周辺勾配）を定量化する．

### 正規化楕円距離マップ

各ピクセルについて，ROI 中心からの正規化楕円距離 $d$ を算出する．

$$d(x, y) = \sqrt{\left(\frac{x - c_x}{c_x}\right)^2 + \left(\frac{y - c_y}{c_y}\right)^2}$$

- $c_x = W/2$, $c_y = H/2$: ROI の中心座標
- 値域を $[0, 1]$ に再正規化（$d \leftarrow d / d_{\max}$）
- 楕円距離を使用することで，縦横比が異なる ROI でも等方的な評価が可能

### 3 ゾーン分類

正規化距離の閾値で ROI を 3 つの同心楕円ゾーンに分割する．

| ゾーン | ラベル | 距離条件 |
| --- | --- | --- |
| Center（中心） | 0 | $d < 0.33$ |
| Middle（中間） | 1 | $0.33 \leq d < 0.66$ |
| Periphery（周辺） | 2 | $0.66 \leq d$ |

閾値は正規化距離の三等分点に設定し，標準的な照明評価の領域分割に対応する．

### 空間分析指標

#### ゾーン別統計

各ゾーンの平均輝度 $\mu_z$ と標準偏差 $\sigma_z$ を算出する（$z \in \{center, middle, periphery\}$）．

#### 中心/周辺比

$$\text{C/P Ratio} = \frac{\mu_{center}}{\mu_{periphery}}$$

- 1.0 に近いほど均一
- 1.0 より大 → 中心が明るい（照明の集中）
- 1.0 より小 → 周辺が明るい

#### 勾配量（%）

$$\text{Gradient} = \frac{\mu_{center} - \mu_{periphery}}{\mu_{center}} \times 100$$

- 0% に近いほど空間的ムラが小さい
- 正値 → 中心から周辺に向かって輝度が減衰

### 放射状輝度プロファイル

正規化距離を 20 等分のビンに分割し，各ビン内の平均輝度を集計する．中心から周辺にかけての輝度変化の傾向を連続的に把握できる．

- 出力: 20 × 2 の配列（列 0 = ビン中心距離，列 1 = 平均輝度）
- 最外ビンは上端を含める（$d = 1.0$ の画素を欠損させない）

## バッチ解析 (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/summary_spatial.csv` — 全画像の空間分析指標一覧
- `output/results/<画像名>_uniformity.csv` — 各画像の均一性指標
- `output/figures/<画像名>_luminance_map.png` — 輝度マップ
- `output/figures/<画像名>_histogram.png` — 輝度ヒストグラム
- `output/figures/<画像名>_radial_profile.png` — 放射状輝度プロファイル
- `output/figures/<画像名>_zone_map.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 等）は画像内の比較であり，カメラの色特性のズレが全画素に等しく影響するため，指標の値に影響しない．