# 機能設計書 227-ColorConvertRGBtoHSV

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`ColorConvertRGBtoHSV`関数の機能設計書である。この関数は、RGB色空間（赤、緑、青）の色値をHSV色空間（色相、彩度、明度）に変換するためのユーティリティ関数である。

### 本機能の処理概要

`ColorConvertRGBtoHSV`関数は、コンピュータグラフィックスで標準的に使用されるRGB表現の色を、人間の知覚により近いHSV表現に変換する機能を提供する。HSV色空間では、色の選択や調整が直感的に行えるため、カラーピッカーなどのUIコンポーネントで広く使用される。

**業務上の目的・背景**：カラーエディタやカラーピッカーでは、ユーザーが直感的に色を選択・調整できることが重要である。RGB色空間は技術的には正確だが、「少し明るくする」「同じ色相で彩度を上げる」といった操作が複雑になる。HSV色空間ではこれらの操作が単一の成分を変更するだけで実現できるため、UIの使いやすさが大幅に向上する。

**機能の利用シーン**：
- ColorPicker4/ColorEdit4ウィジェットでの内部変換
- カスタムカラーパレットの生成（色相を均等に分布させる等）
- 色の補間や調整計算
- カラーホイールUIの実装
- 彩度や明度のみを調整する色変換

**主要な処理内容**：
1. RGB成分から最大値と最小値を特定
2. 彩度（Chroma）を計算
3. 色相（Hue）を6分割で計算
4. 彩度（Saturation）と明度（Value）を算出
5. 出力参照パラメータに結果を設定

**関連システム・外部連携**：ColorConvertHSVtoRGBと対になる関数。カラーピッカーウィジェットで内部的に使用される。

**権限による制御**：特にない。いつでも呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 参照画面 | カラーピッカーでの色変換 |

## 機能種別

データ変換（計算処理）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| r | float | Yes | Red成分（0.0-1.0） | - |
| g | float | Yes | Green成分（0.0-1.0） | - |
| b | float | Yes | Blue成分（0.0-1.0） | - |
| out_h | float& | Yes | 出力：Hue（色相、0.0-1.0） | - |
| out_s | float& | Yes | 出力：Saturation（彩度、0.0-1.0） | - |
| out_v | float& | Yes | 出力：Value（明度、0.0-1.0） | - |

### 入力データソース

呼び出し元から直接渡される値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| out_h | float& | Hue（色相）。0.0-1.0の範囲。0=赤、1/3=緑、2/3=青 |
| out_s | float& | Saturation（彩度）。0.0-1.0の範囲。0=無彩色、1=純色 |
| out_v | float& | Value（明度）。0.0-1.0の範囲。0=黒、1=最大輝度 |

### 出力先

出力パラメータ（参照渡し）を通じて呼び出し元に返却

## 処理フロー

### 処理シーケンス

```
1. RGB成分のソートと最大値特定
   ├─ g < b の場合、swap(g, b)、K = -1
   └─ r < g の場合、swap(r, g)、K調整
2. Chroma（彩度幅）の計算
   └─ chroma = r - min(g, b)
3. Hue（色相）の計算
   └─ out_h = |K + (g-b) / (6*chroma + 1e-20)|
4. Saturation（彩度）の計算
   └─ out_s = chroma / (r + 1e-20)
5. Value（明度）の計算
   └─ out_v = r（RGB成分の最大値）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B["K = 0"]
    B --> C{g < b ?}
    C -->|Yes| D["swap(g, b), K = -1"]
    C -->|No| E{r < g ?}
    D --> E
    E -->|Yes| F["swap(r, g), K = -2/6 - K"]
    E -->|No| G["chroma = r - min(g, b)"]
    F --> G
    G --> H["out_h = |K + (g-b)/(6*chroma+1e-20)|"]
    H --> I["out_s = chroma / (r + 1e-20)"]
    I --> J["out_v = r"]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ゼロ除算防止 | 除算時に1e-20を加算してゼロ除算を防止 | 常時 |
| BR-002 | 色相の正規化 | 色相は0.0-1.0に正規化（0=赤、1/6=黄、1/3=緑、1/2=シアン、2/3=青、5/6=マゼンタ） | 常時 |
| BR-003 | 明度は最大RGB | Value（明度）はRGB成分の最大値 | 常時 |

### 計算ロジック

アルゴリズム出典：Foley & van Dam p592 の最適化版
参考：http://lolengine.net/blog/2013/01/13/fast-rgb-to-hsv

```cpp
float K = 0.f;
if (g < b)
{
    ImSwap(g, b);
    K = -1.f;
}
if (r < g)
{
    ImSwap(r, g);
    K = -2.f / 6.f - K;
}

const float chroma = r - (g < b ? g : b);
out_h = ImFabs(K + (g - b) / (6.f * chroma + 1e-20f));
out_s = chroma / (r + 1e-20f);
out_v = r;
```

## データベース操作仕様

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | 本関数はエラーを発生させない | - |

### リトライ仕様

なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- O(1)の時間計算量
- メモリアロケーションなし
- 最適化されたアルゴリズム（条件分岐を最小化）

## セキュリティ考慮事項

特になし

## 備考

- ColorConvertHSVtoRGBと対になる関数
- カラーピッカーウィジェット（ColorPicker4等）で内部的に使用
- ImColorクラスのSetHSVメソッドで使用される（逆変換）

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: 関連データ構造を理解する

まず、HSV関連の使用例を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImColor::HSVメソッド（2966行目）- HSV色の作成 |
| 1-2 | imgui.h | `imgui.h` | ImColor::SetHSVメソッド（2965行目）- HSV設定 |

**読解のコツ**: ImColorクラスのHSV関連メソッドはColorConvertHSVtoRGBを内部で使用している。ColorConvertRGBtoHSVは主にカラーピッカーで使用される。

#### Step 2: エントリーポイントを理解する

ColorConvertRGBtoHSV関数のAPI宣言と実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（1051行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | 関数実装（2806-2824行目） |

**主要処理フロー**:
1. **2808-2818行目**: RGB成分のソートとK値の計算
2. **2820行目**: chroma（彩度幅）の計算
3. **2821行目**: 色相（H）の計算
4. **2822行目**: 彩度（S）の計算
5. **2823行目**: 明度（V）の設定

#### Step 3: 対になる関数を理解する

逆変換関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | ColorConvertHSVtoRGB（2828-2850行目） |

### プログラム呼び出し階層図

```
ImGui::ColorConvertRGBtoHSV()
    │
    ├─ ImSwap()（ローカルソート）
    │
    └─ ImFabs()（絶対値）
```

### データフロー図

```
[入力]                    [処理]                       [出力]

r (Red)       ─┐
               ├─▶ ソート・最大値特定 ─┐
g (Green)     ─┤                       │
               │                       ├─▶ out_h (Hue)
b (Blue)      ─┘                       │
                    │                  ├─▶ out_s (Saturation)
                    │                  │
                    ├─▶ chroma計算 ────┤
                    │                  │
                    └─▶ 明度=最大値 ───┴─▶ out_v (Value)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言 |
| imgui.cpp | `imgui.cpp` | ソース | ColorConvertRGBtoHSV関数実装 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | カラーピッカーでの使用 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（1146行目：ColorConvertHSVtoRGBの逆） |
