# 機能設計書 228-ColorConvertHSVtoRGB

## 概要

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

### 本機能の処理概要

`ColorConvertHSVtoRGB`関数は、人間の知覚に基づくHSV表現の色を、コンピュータグラフィックスで標準的に使用されるRGB表現に変換する機能を提供する。カラーピッカーで選択されたHSV値を、描画やスタイル設定に使用するRGB値に変換する際に使用される。

**業務上の目的・背景**：カラーピッカーUIではHSV色空間が直感的な色選択を可能にするが、最終的な描画やスタイル設定にはRGB形式が必要となる。本機能は、ユーザーがHSVベースで選択した色を、実際に使用可能なRGB形式に変換する橋渡しの役割を果たす。また、カラーパレット生成やアニメーション効果での色変化計算にも活用される。

**機能の利用シーン**：
- カラーピッカーで選択したHSV色をRGBに変換
- ImColor::HSVヘルパーでの色生成
- 色相ベースのカラーパレット生成
- 色のグラデーションやアニメーション効果
- 彩度・明度を固定して色相のみ変化させる効果

**主要な処理内容**：
1. 彩度が0の場合（無彩色）は即座にグレースケール値を返却
2. 色相を60度（1/6回転）単位の6セクターに分割
3. 各セクターに応じたRGB成分の計算
4. 出力参照パラメータに結果を設定

**関連システム・外部連携**：ColorConvertRGBtoHSVと対になる関数。ImColorクラスのHSVメソッドで使用される。

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

## 関連画面

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

## 機能種別

データ変換（計算処理）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| h | float | Yes | Hue（色相、0.0-1.0） | - |
| s | float | Yes | Saturation（彩度、0.0-1.0） | - |
| v | float | Yes | Value（明度、0.0-1.0） | - |
| out_r | float& | Yes | 出力：Red成分（0.0-1.0） | - |
| out_g | float& | Yes | 出力：Green成分（0.0-1.0） | - |
| out_b | float& | Yes | 出力：Blue成分（0.0-1.0） | - |

### HSV色空間の意味

| 成分 | 範囲 | 説明 |
|-----|------|------|
| Hue | 0.0-1.0 | 色相。0=赤、1/6=黄、1/3=緑、1/2=シアン、2/3=青、5/6=マゼンタ |
| Saturation | 0.0-1.0 | 彩度。0=無彩色（グレー）、1=純色 |
| Value | 0.0-1.0 | 明度。0=黒、1=最大輝度 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| out_r | float& | Red成分（0.0-1.0の範囲） |
| out_g | float& | Green成分（0.0-1.0の範囲） |
| out_b | float& | Blue成分（0.0-1.0の範囲） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 無彩色チェック
   └─ s == 0の場合、out_r = out_g = out_b = vを設定して終了
2. 色相のセクター計算
   └─ h = ImFmod(h, 1.0f) / (60/360)で0-6の範囲に変換
3. セクター内の位置計算
   ├─ i = (int)h（セクター番号0-5）
   └─ f = h - i（セクター内の小数部分）
4. 中間値の計算
   ├─ p = v * (1 - s)
   ├─ q = v * (1 - s * f)
   └─ t = v * (1 - s * (1 - f))
5. セクターに応じたRGB割り当て
   ├─ case 0: (v, t, p)
   ├─ case 1: (q, v, p)
   ├─ case 2: (p, v, t)
   ├─ case 3: (p, q, v)
   ├─ case 4: (t, p, v)
   └─ case 5: (v, p, q)
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{s == 0 ?}
    B -->|Yes| C["out_r = out_g = out_b = v"]
    C --> K[終了]
    B -->|No| D["h = ImFmod(h, 1.0) / (60/360)"]
    D --> E["i = (int)h, f = h - i"]
    E --> F["p = v*(1-s), q = v*(1-s*f), t = v*(1-s*(1-f))"]
    F --> G{セクター i}
    G -->|0| H0["(v, t, p)"]
    G -->|1| H1["(q, v, p)"]
    G -->|2| H2["(p, v, t)"]
    G -->|3| H3["(p, q, v)"]
    G -->|4| H4["(t, p, v)"]
    G -->|5| H5["(v, p, q)"]
    H0 --> K
    H1 --> K
    H2 --> K
    H3 --> K
    H4 --> K
    H5 --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 無彩色の早期リターン | s=0の場合は即座にグレースケール値を返す | s == 0.0f |
| BR-002 | 色相の正規化 | ImFmodで色相を0-1に正規化 | 常時 |
| BR-003 | 6セクター分割 | 色相は60度（1/6）単位で6セクターに分割 | 常時 |

### 計算ロジック

アルゴリズム出典：Foley & van Dam p593 / Wikipedia HSL and HSV

```cpp
if (s == 0.0f)
{
    // gray
    out_r = out_g = out_b = v;
    return;
}

h = ImFmod(h, 1.0f) / (60.0f / 360.0f);
int   i = (int)h;
float f = h - (float)i;
float p = v * (1.0f - s);
float q = v * (1.0f - s * f);
float t = v * (1.0f - s * (1.0f - f));

switch (i)
{
case 0: out_r = v; out_g = t; out_b = p; break;
case 1: out_r = q; out_g = v; out_b = p; break;
case 2: out_r = p; out_g = v; out_b = t; break;
case 3: out_r = p; out_g = q; out_b = v; break;
case 4: out_r = t; out_g = p; out_b = v; break;
case 5: out_r = v; out_g = p; out_b = q; break;
}
```

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

なし

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

該当なし

## パフォーマンス要件

- O(1)の時間計算量
- メモリアロケーションなし
- switch文による効率的な分岐

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

特になし

## 備考

- ColorConvertRGBtoHSVと対になる関数
- ImColor::HSVメソッドで使用されている
- 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を内部で呼び出してRGB値を取得し、ImColor構造体を構築している。

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

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

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

**主要処理フロー**:
1. **2830-2835行目**: 無彩色（s==0）の場合の早期リターン
2. **2837行目**: 色相の正規化
3. **2838-2842行目**: セクター計算と中間値計算
4. **2844-2850行目**: セクターに応じたRGB割り当て

#### Step 3: 使用例を確認する

デモコードでの使用例を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_demo.cpp | `imgui_demo.cpp` | カラーパレット生成（1146行目） |

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

```
ImGui::ColorConvertHSVtoRGB()
    │
    └─ ImFmod()（色相の正規化）

ImColor::HSV() ─┐
                ├─▶ ColorConvertHSVtoRGB()
ImColor::SetHSV() ─┘
```

### データフロー図

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

h (Hue)       ─┐
               ├─▶ 無彩色チェック ─┬─▶ グレースケール
s (Saturation) ─┤                  │
               │                   │
v (Value)     ─┘                   │
                    │              │
                    ├─▶ セクター計算
                    │       │
                    │       ├─▶ 中間値計算 ───┐
                    │       │                  │
                    │       └─▶ RGB割り当て ───┼─▶ out_r
                    │                          ├─▶ out_g
                    └──────────────────────────┴─▶ out_b
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、ImColor::HSV/SetHSV |
| imgui.cpp | `imgui.cpp` | ソース | ColorConvertHSVtoRGB関数実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | カラーパレット生成での使用例（1146行目） |
