# 機能設計書 75-Geometry

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるジオメトリ機能（Geometry）の設計仕様を記述する。Geometryは、図形の形状を定義する抽象基底クラスであり、矩形、楕円、パス、複合図形など多様な形状の共通インターフェースを提供する。

### 本機能の処理概要

Geometryは、2D図形の形状を数学的に定義するクラス階層の基盤である。境界ボックスの計算、点の包含判定、ストローク包含判定、形状の変換、パス測定など、図形処理に必要な機能を統一的に提供する。StreamGeometryを使用したパス構文解析により、SVGやXAMLでの図形定義にも対応する。

**業務上の目的・背景**：UIアプリケーションでは、単純な矩形や楕円から複雑なベクターグラフィックスまで、様々な形状を扱う必要がある。Geometryシステムにより、すべての図形を統一的に扱うことができ、Shape系コントロール、クリッピング、ヒットテストなど多様な用途に活用できる。

**機能の利用シーン**：PathコントロールのData指定、クリッピング領域の定義（Clip/GeometryClip）、ヒットテスト、図形描画、パスアニメーションの基準パスなど。

**主要な処理内容**：
1. 図形形状の定義と管理
2. 境界ボックス（Bounds）の計算
3. 点の包含判定（FillContains/StrokeContains）
4. 変換（Transform）の適用
5. 輪郭長（ContourLength）の計算
6. パス上の点・接線取得

**関連システム・外部連携**：DrawingContext、Shape系コントロール、クリッピングシステム、ヒットテストシステム、プラットフォーム描画実装と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 72 | Clipping | 主画面 | ジオメトリによるクリッピングのデモ |
| 81 | Path Measurement | 主画面 | パス測定のデモ |

## 機能種別

グラフィックス基盤 / 図形形状定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Transform | Transform? | No | ジオメトリに適用する変換 | null可 |

### Geometry.Parse入力

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| s | string | Yes | パス構文文字列 | SVG Path構文 |

### 入力データソース

- XAMLマークアップでのGeometry定義
- Geometry.Parse()によるパス構文解析
- 具象クラス（RectangleGeometry等）の直接生成

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Bounds | Rect | 図形の境界ボックス |
| ContourLength | double | 図形の輪郭長 |
| PlatformImpl | IGeometryImpl | プラットフォーム実装 |

### 出力先

- DrawingContextへの描画パラメータ
- クリッピング領域としてVisualに適用
- ヒットテスト結果として使用

## 処理フロー

### 処理シーケンス

```
1. Geometry定義
   └─ 具象クラス生成またはParse
2. プラットフォーム実装生成
   └─ CreateDefiningGeometry（遅延実行）
3. 変換適用（オプション）
   └─ Transform設定時に適用
4. 利用
   └─ 描画/クリッピング/ヒットテスト
```

### フローチャート

```mermaid
flowchart TD
    A[Geometry生成] --> B{Parse文字列?}
    B -->|Yes| C[StreamGeometry.Parse]
    C --> D[PathMarkupParser処理]
    B -->|No| E[具象クラス生成]
    E --> F[プロパティ設定]
    D --> G{PlatformImpl要求}
    F --> G
    G -->|未生成| H[CreateDefiningGeometry]
    G -->|生成済| I[キャッシュ使用]
    H --> J{Transform設定?}
    I --> J
    J -->|Yes| K[WithTransform適用]
    J -->|No| L[描画/ヒットテスト使用]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | 遅延生成 | PlatformImplは初回アクセス時に生成 | PlatformImplプロパティアクセス時 |
| BR-75-02 | 変換適用 | Transform != Identity の場合のみ変換実行 | Transform設定時 |
| BR-75-03 | 無効化伝播 | プロパティ変更時にPlatformImplを無効化 | AffectsGeometry指定プロパティ変更時 |

### 計算ロジック

境界ボックス:
```
Bounds = PlatformImpl?.Bounds ?? default(Rect)
```

ストローク境界:
```
GetRenderBounds(pen) = PlatformImpl?.GetRenderBounds(pen) ?? default(Rect)
```

パス上の点取得:
```
TryGetPointAtDistance(distance) → 指定距離の点を返す
TryGetPointAndTangentAtDistance(distance) → 点と接線を返す
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FormatException | 解析エラー | Parse()で無効なパス構文 | 有効なSVGパス構文を指定 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- PlatformImplは遅延生成でメモリ効率化
- 変更がない場合はキャッシュを再利用
- 複雑なパスは初回生成に時間がかかる可能性あり

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

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

## 備考

- TypeConverterによりXAMLでパス構文を直接指定可能
- Changeイベントで図形変更を監視可能
- Combine()で複数ジオメトリの結合が可能

---

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

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

### 推奨読解順序

#### Step 1: 基底クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Geometry.cs | `src/Avalonia.Base/Media/Geometry.cs` | ジオメトリ抽象基底クラス |

**主要処理フロー**:
- **20-21行目**: TransformPropertyの定義
- **50行目**: Boundsプロパティ（PlatformImplから取得）
- **55-75行目**: PlatformImplプロパティ（遅延生成）
- **91行目**: Parse()メソッド（StreamGeometry.Parseに委譲）
- **104行目**: GetRenderBounds()（ストローク込み境界）
- **111-114行目**: FillContains()（点の包含判定）
- **122-125行目**: StrokeContains()（ストローク包含判定）
- **159行目**: CreateDefiningGeometry()（抽象メソッド）
- **225行目**: ContourLength（輪郭長）
- **247-256行目**: TryGetPointAtDistance()

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | RectangleGeometry.cs | `src/Avalonia.Base/Media/RectangleGeometry.cs` | 矩形ジオメトリ |
| 2-2 | StreamGeometry.cs | `src/Avalonia.Base/Media/StreamGeometry.cs` | パスジオメトリ |

**主要処理フロー**:
- **RectangleGeometry 13-26行目**: RadiusX/RadiusY/Rectプロパティ
- **RectangleGeometry 105-126行目**: CreateDefiningGeometry実装
- **StreamGeometry 34-45行目**: Parse()実装
- **StreamGeometry 59-62行目**: Open()でStreamGeometryContext取得

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

```
Geometry (abstract)
    │
    ├─ RectangleGeometry
    │      └─ Rect / RadiusX / RadiusY
    │
    ├─ EllipseGeometry
    │      └─ Center / RadiusX / RadiusY
    │
    ├─ LineGeometry
    │      └─ StartPoint / EndPoint
    │
    ├─ StreamGeometry
    │      └─ Parse() / Open()
    │
    ├─ PathGeometry
    │      └─ Figures / FillRule
    │
    ├─ GeometryGroup
    │      └─ Children
    │
    └─ CombinedGeometry
           └─ Geometry1 / Geometry2 / CombineMode
```

### データフロー図

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

パス文字列 ───▶ StreamGeometry.Parse() ───▶ Geometry
"M 0,0 L 100,100"     │                         │
                      │                         │
              PathMarkupParser              PlatformImpl
                      │                         │
                      ▼                         ▼
              IGeometryImpl ───▶ FillContains() / StrokeContains()
                                 GetRenderBounds() / ContourLength
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Geometry.cs | `src/Avalonia.Base/Media/Geometry.cs` | ソース | ジオメトリ抽象基底 |
| RectangleGeometry.cs | `src/Avalonia.Base/Media/RectangleGeometry.cs` | ソース | 矩形ジオメトリ |
| EllipseGeometry.cs | `src/Avalonia.Base/Media/EllipseGeometry.cs` | ソース | 楕円ジオメトリ |
| LineGeometry.cs | `src/Avalonia.Base/Media/LineGeometry.cs` | ソース | 線ジオメトリ |
| StreamGeometry.cs | `src/Avalonia.Base/Media/StreamGeometry.cs` | ソース | パスジオメトリ |
| PathGeometry.cs | `src/Avalonia.Base/Media/PathGeometry.cs` | ソース | パス図形 |
| GeometryGroup.cs | `src/Avalonia.Base/Media/GeometryGroup.cs` | ソース | ジオメトリグループ |
| CombinedGeometry.cs | `src/Avalonia.Base/Media/CombinedGeometry.cs` | ソース | 結合ジオメトリ |
| StreamGeometryContext.cs | `src/Avalonia.Base/Media/StreamGeometryContext.cs` | ソース | パス構築コンテキスト |
| PathMarkupParser.cs | `src/Avalonia.Base/Media/PathMarkupParser.cs` | ソース | パス構文解析 |
| IGeometryImpl.cs | `src/Avalonia.Base/Platform/IGeometryImpl.cs` | ソース | プラットフォーム実装インターフェース |
