# 機能設計書 80-Image

## 概要

本ドキュメントは、Avaloniaフレームワークにおける画像コントロール機能（Image）の設計仕様を記述する。Imageは、ビットマップ画像を表示するControlであり、ストレッチモード、ブレンドモードなどの表示制御機能を提供する。

### 本機能の処理概要

Imageは、Bitmap画像を画面に表示するための基本的なUIコントロールである。画像のスケーリング方法（Stretch）、スケーリング方向の制限（StretchDirection）、描画時のブレンドモード（BlendMode）を設定可能で、様々な画像表示要件に対応する。

**業務上の目的・背景**：アプリケーションにおいて画像の表示は基本的かつ重要な機能である。ロゴ、アイコン、写真、図表など多様な画像コンテンツを適切なサイズとスタイルで表示することで、視覚的に豊かなユーザー体験を提供できる。

**機能の利用シーン**：アプリケーションのロゴ表示、ユーザーアバター表示、製品画像のギャラリー、アイコン表示、背景画像など。

**主要な処理内容**：
1. 画像ソース（Source）の管理
2. ストレッチモード（Stretch）の適用
3. ストレッチ方向（StretchDirection）の制御
4. ブレンドモード（BlendMode）の適用
5. レイアウト計算（Measure/Arrange）
6. 描画（Render）

**関連システム・外部連携**：IImage、Bitmap、DrawingContext、Stretchヘルパーと連携する。

**権限による制御**：本機能は純粋な表示機能であり、特別な権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 35 | Image | 主画面 | 画像コントロールのデモ |
| 76 | WriteableBitmap | 主画面 | 動的ビットマップの表示 |

## 機能種別

UIコントロール / 画像表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | IImage? | No | 表示する画像 | null可（非表示） |
| Stretch | Stretch | No | ストレッチモード | デフォルト: Uniform |
| StretchDirection | StretchDirection | No | ストレッチ方向 | デフォルト: Both |
| BlendMode | BitmapBlendingMode | No | ブレンドモード | デフォルト: SourceOver |

### Stretch列挙値

| 値 | 説明 |
|---|------|
| None | ストレッチなし（原寸表示） |
| Fill | アスペクト比を無視して領域全体にフィット |
| Uniform | アスペクト比を維持して領域内にフィット |
| UniformToFill | アスペクト比を維持して領域を完全にカバー |

### StretchDirection列挙値

| 値 | 説明 |
|---|------|
| UpOnly | 拡大のみ許可 |
| DownOnly | 縮小のみ許可 |
| Both | 拡大・縮小両方許可 |

### 入力データソース

- XAMLマークアップでのSource指定
- プログラムによるSourceプロパティ設定
- Bindingによる動的画像切り替え

## 出力仕様

### 出力データ

本機能は直接的な出力データを持たない。画面に画像が描画される。

### 出力先

- 画面への画像表示

## 処理フロー

### 処理シーケンス

```
1. Sourceプロパティ設定
   └─ 画像データの取得
2. Measure処理
   └─ Stretch.CalculateSize()で希望サイズ計算
3. Arrange処理
   └─ 実際の表示サイズ決定
4. Render処理
   └─ DrawingContext.DrawImage()で描画
```

### フローチャート

```mermaid
flowchart TD
    A[Source設定] --> B{Source != null?}
    B -->|No| C[サイズ0で返す]
    B -->|Yes| D[MeasureOverride]
    D --> E[Stretch.CalculateSize]
    E --> F[ArrangeOverride]
    F --> G[Stretch.CalculateSize]
    G --> H[Render]
    H --> I{Bounds有効?}
    I -->|No| J[描画スキップ]
    I -->|Yes| K[スケール計算]
    K --> L[destRect計算]
    L --> M[sourceRect計算]
    M --> N[PushRenderOptions]
    N --> O[DrawImage]
    C --> P[レイアウト終了]
    J --> P
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-80-01 | デフォルトStretch | StretchのデフォルトはUniform | 常時 |
| BR-80-02 | Sourceなし時 | Sourceがnullの場合、サイズ0を返す | Measure/Arrange時 |
| BR-80-03 | FlowDirection無視 | BypassFlowDirectionPoliciesがtrue | 常時 |

### 計算ロジック

**スケール計算**:
```csharp
Vector scale = Stretch.CalculateScaling(Bounds.Size, sourceSize, StretchDirection);
Size scaledSize = sourceSize * scale;
```

**描画矩形計算**:
```csharp
Rect destRect = viewPort.CenterRect(new Rect(scaledSize)).Intersect(viewPort);
Rect sourceRect = new Rect(sourceSize).CenterRect(new Rect(destRect.Size / scale));
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | Sourceがnull | 描画をスキップ（エラーにはならない） |
| - | - | Boundsが無効 | 描画をスキップ |

### リトライ仕様

本機能にリトライ仕様は存在しない。

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

本機能にトランザクション管理は存在しない。

## パフォーマンス要件

- 画像は一度ロードされるとキャッシュされる
- RenderはGPUアクセラレーションを使用
- 大きな画像は適切なサイズにスケーリングして表示

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

- 外部URLからの画像読み込み時はHTTPS推奨
- 悪意のある画像ファイルに注意

## 備考

- AutomationControlTypeはImageに設定
- BypassFlowDirectionPoliciesがtrueのため、RTLレイアウトでも画像は反転しない
- BlendModeはRenderOptions経由で適用

---

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

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

### 推奨読解順序

#### Step 1: メインクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Image.cs | `src/Avalonia.Controls/Image.cs` | 画像コントロール本体 |

**主要処理フロー**:
- **17-19行目**: SourceProperty定義
- **24-25行目**: BlendModeProperty定義
- **30-31行目**: StretchProperty定義（デフォルト: Uniform）
- **36-39行目**: StretchDirectionProperty定義（デフォルト: Both）
- **41-46行目**: 静的コンストラクタ（AffectsRender/AffectsMeasure設定）
- **51-56行目**: Sourceプロパティ（[Content]属性）
- **86行目**: BypassFlowDirectionPolicies = true
- **92-114行目**: Render()メソッド
- **121-132行目**: MeasureOverride()メソッド
- **135-149行目**: ArrangeOverride()メソッド

#### Step 2: 関連クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stretch.cs | `src/Avalonia.Base/Media/Stretch.cs` | ストレッチ計算 |
| 2-2 | IImage.cs | `src/Avalonia.Base/Media/IImage.cs` | 画像インターフェース |

**主要処理フロー**:
- **Stretch.CalculateScaling()**: スケール係数の計算
- **Stretch.CalculateSize()**: 表示サイズの計算
- **IImage.Draw()**: DrawingContextへの描画

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

```
Image.Render(DrawingContext context)
    │
    ├─ Stretch.CalculateScaling(boundsSize, sourceSize, stretchDirection)
    │      └─ スケール係数を計算
    │
    ├─ viewPort.CenterRect(scaledRect)
    │      └─ 中央配置の計算
    │
    ├─ context.PushRenderOptions(with BlendMode)
    │      └─ ブレンドモード適用
    │
    └─ context.DrawImage(source, sourceRect, destRect)
           └─ 画像を描画
```

### データフロー図

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

IImage (Source) ───▶ Image Control ───▶ 画面表示
                          │
Stretch ──────────▶       │
                          │
StretchDirection ──▶      │
                          │
BlendMode ────────▶       │
                          │
                    Measure/Arrange/Render
                          │
                          ▼
                    DrawingContext.DrawImage()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Image.cs | `src/Avalonia.Controls/Image.cs` | ソース | 画像コントロール本体 |
| IImage.cs | `src/Avalonia.Base/Media/IImage.cs` | ソース | 画像インターフェース |
| Bitmap.cs | `src/Avalonia.Base/Media/Imaging/Bitmap.cs` | ソース | ビットマップ画像 |
| Stretch.cs | `src/Avalonia.Base/Media/Stretch.cs` | ソース | ストレッチ列挙/計算 |
| StretchDirection.cs | `src/Avalonia.Base/Media/StretchDirection.cs` | ソース | ストレッチ方向列挙 |
| BitmapBlendingMode.cs | `src/Avalonia.Base/Media/BitmapBlendingMode.cs` | ソース | ブレンドモード列挙 |
| RenderOptions.cs | `src/Avalonia.Base/Media/RenderOptions.cs` | ソース | レンダリングオプション |
| DrawingContext.cs | `src/Avalonia.Base/Media/DrawingContext.cs` | ソース | 描画コンテキスト |
| ImageAutomationPeer.cs | `src/Avalonia.Controls/Automation/Peers/ImageAutomationPeer.cs` | ソース | オートメーションピア |
| Control.cs | `src/Avalonia.Controls/Control.cs` | ソース | コントロール基底 |
