# 機能設計書 76-Transform

## 概要

本ドキュメントは、Avaloniaフレームワークにおける変換機能（Transform）の設計仕様を記述する。Transformは、Visual要素に対する移動、回転、拡大縮小、傾斜などの2D変換を定義する抽象基底クラスである。

### 本機能の処理概要

Transformは、2Dアフィン変換を表現するクラス階層の基盤である。TranslateTransform（移動）、RotateTransform（回転）、ScaleTransform（拡大縮小）、SkewTransform（傾斜）、MatrixTransform（任意行列）、TransformGroup（複合変換）など、多様な変換タイプを統一的に扱う。最終的にはすべてMatrix（3x2行列）として表現される。

**業務上の目的・背景**：UIアプリケーションでは、要素の位置、サイズ、向きを動的に変更する必要がある。Transformシステムにより、アニメーション、レイアウト調整、視覚効果などを実現できる。特にRenderTransformプロパティを通じて、レンダリング時の見た目を変更しながらレイアウトには影響を与えない変換が可能である。

**機能の利用シーン**：Visual.RenderTransformによる描画時変換、LayoutTransformControlによるレイアウト変換、Brush.Transformによるブラシ変換、Geometry.Transformによる図形変換など。

**主要な処理内容**：
1. 変換パラメータの管理（角度、スケール、オフセット等）
2. Matrix値の計算
3. 変換変更イベントの発火
4. Compositorへのシリアライズ
5. 不変変換への変換（ToImmutable）

**関連システム・外部連携**：Visual、Brush、Geometry、アニメーションシステム、Compositorと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | LayoutTransformControl | 主画面 | レイアウト時の変換適用デモ |
| 83 | 3D Transformation | 主画面 | 3次元変換のデモ |

## 機能種別

グラフィックス基盤 / 座標変換定義

## 入力仕様

### 入力パラメータ（変換タイプ別）

#### TranslateTransform

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| X | double | No | X方向のオフセット | デフォルト: 0 |
| Y | double | No | Y方向のオフセット | デフォルト: 0 |

#### RotateTransform

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Angle | double | No | 回転角度（度） | デフォルト: 0 |
| CenterX | double | No | 回転中心X | デフォルト: 0 |
| CenterY | double | No | 回転中心Y | デフォルト: 0 |

#### ScaleTransform

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ScaleX | double | No | X方向スケール | デフォルト: 1 |
| ScaleY | double | No | Y方向スケール | デフォルト: 1 |

#### SkewTransform

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| AngleX | double | No | X方向傾斜角度 | デフォルト: 0 |
| AngleY | double | No | Y方向傾斜角度 | デフォルト: 0 |

### 入力データソース

- XAMLマークアップでの変換定義
- Transform.Parse()による文字列解析
- プログラムによる直接インスタンス化

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Value | Matrix | 変換を表す3x2行列 |
| ImmutableTransform | ImmutableTransform | 不変変換への変換 |

### 出力先

- Visual.RenderTransformとして適用
- Brush.Transformとして適用
- Geometry.Transformとして適用

## 処理フロー

### 処理シーケンス

```
1. Transform生成
   └─ コンストラクタまたはParse
2. パラメータ設定
   └─ X/Y/Angle/ScaleX/ScaleY等
3. Value計算
   └─ 各サブクラスでMatrix生成
4. 変更通知
   └─ Changedイベント発火
5. 適用
   └─ Visual/Brush/Geometry等に適用
```

### フローチャート

```mermaid
flowchart TD
    A[Transform生成] --> B{Parse文字列?}
    B -->|Yes| C[Matrix.Parse]
    C --> D[MatrixTransform生成]
    B -->|No| E[具象クラス生成]
    E --> F[パラメータ設定]
    D --> G[Valueプロパティ]
    F --> G
    G --> H[Matrix計算]
    H --> I[Changedイベント]
    I --> J[Compositorシリアライズ]
    J --> K[レンダリング適用]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-01 | 角度単位 | RotateTransform.Angleは度数法 | 常時 |
| BR-76-02 | スケールデフォルト | ScaleX/ScaleYのデフォルトは1.0 | 常時 |
| BR-76-03 | 回転中心 | CenterX/CenterYはRenderTransformOriginからの相対位置 | RotateTransform使用時 |

### 計算ロジック

**TranslateTransform**:
```
Matrix = Matrix.CreateTranslation(X, Y)
```

**RotateTransform**:
```
Matrix = Translate(-CenterX, -CenterY) × Rotate(Angle) × Translate(CenterX, CenterY)
```

**ScaleTransform**:
```
Matrix = Matrix.CreateScale(ScaleX, ScaleY)
```

**TransformGroup**:
```
Matrix = Children[0].Value × Children[1].Value × ... × Children[n].Value
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FormatException | 解析エラー | Parse()で無効な行列文字列 | 有効なMatrix形式を指定 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- TransformGroupはMatrix値をキャッシュ
- アニメーション時は毎フレームValue計算が実行される
- Changedイベントは購読者への即時通知

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

本機能は座標変換のみを担当するため、特別なセキュリティ考慮事項は存在しない。

## 備考

- TransformはAnimatableを継承しており、アニメーション対応
- ICompositionRenderResourceを実装し、GPUアクセラレーション対応
- TransformGroupでは子変換の変更を監視し、自動的に再計算

---

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

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

### 推奨読解順序

#### Step 1: 基底クラスとインターフェースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ITransform.cs | `src/Avalonia.Base/Media/ITransform.cs` | 変換インターフェース |
| 1-2 | Transform.cs | `src/Avalonia.Base/Media/Transform.cs` | 変換抽象基底クラス |

**主要処理フロー**:
- **Transform 26行目**: Changedイベントの定義
- **Transform 31行目**: 抽象Valueプロパティ
- **Transform 38-41行目**: Parse()メソッド（MatrixTransform生成）
- **Transform 55-58行目**: ToImmutable()メソッド

#### Step 2: 具象実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TranslateTransform.cs | `src/Avalonia.Base/Media/TranslateTransform.cs` | 移動変換 |
| 2-2 | RotateTransform.cs | `src/Avalonia.Base/Media/RotateTransform.cs` | 回転変換 |
| 2-3 | ScaleTransform.cs | `src/Avalonia.Base/Media/ScaleTransform.cs` | 拡大縮小変換 |
| 2-4 | TransformGroup.cs | `src/Avalonia.Base/Media/TransformGroup.cs` | 複合変換 |

**主要処理フロー**:
- **TranslateTransform 64行目**: `Value => Matrix.CreateTranslation(X, Y)`
- **RotateTransform 92-94行目**: 回転中心を考慮したMatrix計算
- **ScaleTransform 64行目**: `Value => Matrix.CreateScale(ScaleX, ScaleY)`
- **TransformGroup 49-64行目**: 子変換のMatrix乗算

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

```
Transform (abstract)
    │
    ├─ TranslateTransform
    │      └─ X / Y
    │
    ├─ RotateTransform
    │      └─ Angle / CenterX / CenterY
    │
    ├─ ScaleTransform
    │      └─ ScaleX / ScaleY
    │
    ├─ SkewTransform
    │      └─ AngleX / AngleY
    │
    ├─ MatrixTransform
    │      └─ Matrix
    │
    └─ TransformGroup
           └─ Children (List<Transform>)
```

### データフロー図

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

TranslateTransform ───▶ Value計算 ───▶ Matrix
    X, Y                     │
                             │
RotateTransform ───────▶     │
    Angle, CenterX/Y         │
                             │
ScaleTransform ────────▶     │
    ScaleX, ScaleY           │
                             │
TransformGroup ────────▶ 子Matrix乗算
    Children                 │
                             ▼
                      Visual.RenderTransform適用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Transform.cs | `src/Avalonia.Base/Media/Transform.cs` | ソース | 変換抽象基底 |
| ITransform.cs | `src/Avalonia.Base/Media/ITransform.cs` | ソース | 変換インターフェース |
| TranslateTransform.cs | `src/Avalonia.Base/Media/TranslateTransform.cs` | ソース | 移動変換 |
| RotateTransform.cs | `src/Avalonia.Base/Media/RotateTransform.cs` | ソース | 回転変換 |
| ScaleTransform.cs | `src/Avalonia.Base/Media/ScaleTransform.cs` | ソース | 拡大縮小変換 |
| SkewTransform.cs | `src/Avalonia.Base/Media/SkewTransform.cs` | ソース | 傾斜変換 |
| MatrixTransform.cs | `src/Avalonia.Base/Media/MatrixTransform.cs` | ソース | 行列変換 |
| TransformGroup.cs | `src/Avalonia.Base/Media/TransformGroup.cs` | ソース | 複合変換 |
| ImmutableTransform.cs | `src/Avalonia.Base/Media/Immutable/ImmutableTransform.cs` | ソース | 不変変換 |
| Matrix.cs | `src/Avalonia.Base/Matrix.cs` | ソース | 3x2変換行列 |
