# ColorChecker 検出ライブラリ

`colorchecker.py` をアプリから import できる場所に配置してください。
依存パッケージは `pip install -r requirements.txt` で導入できます。

```python
from colorchecker import ResultCode, detect_colorchecker

code, rgb, images = detect_colorchecker("sample/DSC_9657s.jpg")
if code == ResultCode.SUCCESS:
    print(rgb.shape)  # (3, 24)
    red, green, blue = rgb
    print(rgb[:, 0])  # 1番目の色票の R, G, B
else:
    print(f"処理失敗: {int(code)}")
```

入力は画像ファイルのパス（`str` または `pathlib.Path`）、または画像データ
（`numpy.ndarray`）です。配列は `uint8` 型、形状 `(高さ, 幅, 3)` の
BGR画像（OpenCVの標準形式）を指定してください。入力配列は変更しません。

```python
import cv2

image = cv2.imread("sample/DSC_9657s.jpg")
code, rgb, images = detect_colorchecker(image)
```

戻り値は `(ResultCode, numpy.ndarray, dict[str, numpy.ndarray])` で、RGB配列は常に `(3, 24)` の
`float64` です。行は R・G・B、列は `PATCH_NAMES` の順で、向き補正後の
6列×4行の色票を左上から横方向に並べます。成功時の値は0～255の平均値です。

第3の戻り値 `images` は次の処理画像を格納した辞書です（すべて `uint8`）。

| キー | 内容 | 形状 |
| --- | --- | --- |
| `warped` | 射影変換・向き補正後のBGR画像 | `(560, 840, 3)` |
| `mask` | 検出に採用した二値マスク（入力画像の座標系、値は0または255） | `(入力の高さ, 入力の幅)` |
| `debug` | `warped` に計測領域と色票番号を描画したBGR画像 | `(560, 840, 3)` |

```python
if code == ResultCode.SUCCESS:
    cv2.imwrite("warped.png", images["warped"])
    cv2.imwrite("mask.png", images["mask"])
    cv2.imwrite("debug.png", images["debug"])
```

以前の2変数へのアンパックは、`code, rgb, images = ...` に変更してください。
処理画像が不要な場合は `code, rgb, _ = ...` と書けます。

| コード | 定数 | 意味 |
| --- | --- | --- |
| 0 | `SUCCESS` | 成功 |
| 1 | `IMAGE_READ_ERROR` | ファイルの読み込み・デコード失敗、または入力配列の型・形状が不正 |
| 2 | `DETECTION_FAILED` | 色票の格子検出・射影変換の推定に失敗 |
| 3 | `PROCESSING_ERROR` | OpenCVの処理エラー、または計測値が不正 |

失敗時はRGB配列の全要素が `NaN`、処理画像は空の辞書 `{}` です。ライブラリ関数は結果を表示せず、
CSVや画像ファイルも保存しません。

従来のコマンドラインでの表示・CSVとデバッグ画像の保存は引き続き利用できます。

```powershell
python main2.py "sample/DSC_9657s.jpg"
```

テスト: `python -m unittest test_colorchecker.py`