# 機能設計書 72-Easings

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるイージング関数機能（Easings）の設計仕様を記述する。イージング関数は、アニメーションの進行度を時間に対して非線形に変換することで、より自然で魅力的なアニメーション効果を実現する。

### 本機能の処理概要

Easingsは、アニメーションの加速・減速曲線を定義する数学関数群を提供する。線形（Linear）から3次関数（Cubic）、弾性（Elastic）、バウンス（Bounce）、スプリング（Spring）まで、多様なイージングパターンをサポートし、UIアニメーションに物理的なリアリティと視覚的な魅力を付加する。

**業務上の目的・背景**：人間の目は等速運動を機械的・不自然に感じる傾向がある。イージング関数を使用することで、物理法則に従った自然な動きや、注目を集めるダイナミックな効果を実現できる。これはユーザー体験の質を大幅に向上させ、プロフェッショナルなアプリケーション外観を実現する。

**機能の利用シーン**：アニメーション定義時のEasingプロパティ設定、トランジション効果のカスタマイズ、XAMLでのイージング指定、プログラムによる動的アニメーション制御など、すべてのアニメーション機能で使用される。

**主要な処理内容**：
1. 進行度（0.0〜1.0）の入力受付
2. イージング関数による変換計算
3. 変換後の進行度（イーズ後の値）の出力
4. XAML文字列からのイージングインスタンス生成

**関連システム・外部連携**：Avaloniaのアニメーションシステム（Animation、Transition、CrossFade、PageSlide）と密接に連携し、すべてのアニメーション効果の時間特性を制御する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 68 | Animations | 主画面 | アニメーションのイージング設定デモ |
| 71 | Spring Animation | 主画面 | スプリングイージングのデモ |

## 機能種別

計算処理 / アニメーション補助

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| progress | double | Yes | アニメーション進行度（0.0〜1.0） | 範囲外も許容（extrapolation） |

### SplineEasing追加パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| X1 | double | No | 第1制御点のX座標 | 0.0〜1.0推奨 |
| Y1 | double | No | 第1制御点のY座標 | 制限なし |
| X2 | double | No | 第2制御点のX座標 | 0.0〜1.0推奨 |
| Y2 | double | No | 第2制御点のY座標 | 制限なし |

### SpringEasing追加パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Mass | double | No | バネの質量 | 正の値 |
| Stiffness | double | No | バネの剛性 | 正の値 |
| Damping | double | No | 減衰係数 | 正の値 |
| InitialVelocity | double | No | 初期速度 | 任意 |

### 入力データソース

- アニメーションのEasingプロパティ
- XAMLマークアップでのイージング指定
- Easing.Parse()メソッドによる文字列解析

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| easedProgress | double | イージング適用後の進行度 |

### 出力先

- アニメーション補間計算への入力値として使用

## 処理フロー

### 処理シーケンス

```
1. Ease メソッド呼び出し
   └─ progress (0.0〜1.0) を受け取る
2. イージング計算
   └─ 各イージング関数固有の数式を適用
3. 結果返却
   └─ 変換後の進行度を返す
```

### フローチャート

```mermaid
flowchart TD
    A[Ease呼び出し] --> B{イージングタイプ}
    B -->|Linear| C[progress をそのまま返す]
    B -->|Quadratic| D[2次関数計算]
    B -->|Cubic| E[3次関数計算]
    B -->|Elastic| F[弾性関数計算]
    B -->|Bounce| G[バウンス関数計算]
    B -->|Spring| H[スプリング物理計算]
    B -->|Spline| I[ベジェ曲線計算]
    C --> Z[結果返却]
    D --> Z
    E --> Z
    F --> Z
    G --> Z
    H --> Z
    I --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-01 | 進行度範囲 | 入力は通常0.0〜1.0だが、範囲外も許容 | 常時 |
| BR-72-02 | 出力範囲 | 出力は1.0を超える場合がある（Elastic、Back等） | イージングタイプによる |
| BR-72-03 | In/Out/InOut | 各イージングにIn（開始時）、Out（終了時）、InOut（両方）バリアントが存在 | Quadratic〜Quintic、Elastic、Bounce、Back |

### 計算ロジック

**LinearEasing**:
```
ease(p) = p
```

**QuadraticEaseIn**:
```
ease(p) = p^2
```

**QuadraticEaseOut**:
```
ease(p) = -(p * (p - 2))
```

**CubicEaseInOut**:
```
if (p < 0.5):
    ease(p) = 4 * p^3
else:
    ease(p) = 0.5 * (2*(p-1))^3 + 1
```

**SpringEasing**:
- 減衰振動の物理シミュレーションに基づく
- Mass、Stiffness、Damping、InitialVelocityパラメータで挙動を制御

**SplineEasing**:
- 3次ベジェ曲線に基づく
- CSS cubic-bezier()と互換性あり

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FormatException | 解析エラー | Easing.Parse()で不正な文字列を指定 | 正しいイージング名または制御点を指定 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 各Easeメソッドは軽量な数学演算のみ実行
- 1フレームあたり複数回呼び出される可能性があるため、高速な実行が必須
- 三角関数（Sin、Cos）を使用するイージングはやや負荷が高い

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

本機能は数学演算のみを処理するため、特別なセキュリティ考慮事項は存在しない。

## 備考

- 全36種類のイージングクラスが提供される
- TypeConverterによりXAMLからの直接指定が可能
- SplineEasingはCSS cubic-bezier()との互換性を持つ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IEasing.cs | `src/Avalonia.Base/Animation/Easings/IEasing.cs` | イージングの契約を定義するインターフェース |
| 1-2 | Easing.cs | `src/Avalonia.Base/Animation/Easings/Easing.cs` | 抽象基底クラスとParse機能 |

**読解のコツ**: IEasingインターフェースはEase(double progress)メソッドのみを定義。Easingクラスはこれを実装し、Parse機能を提供する。

**主要処理フロー**:
- **IEasing 10-15行目**: Easeメソッドの契約
- **Easing 17行目**: 抽象Easeメソッド
- **Easing 29-43行目**: 文字列からのイージングインスタンス生成

#### Step 2: 基本的なイージング実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | LinearEasing.cs | `src/Avalonia.Base/Animation/Easings/LinearEasing.cs` | 最もシンプルな実装 |
| 2-2 | CubicEaseInOut.cs | `src/Avalonia.Base/Animation/Easings/CubicEaseInOut.cs` | 区分的な関数の実装 |

**主要処理フロー**:
- **LinearEasing 9-11行目**: progressをそのまま返す
- **CubicEaseInOut 10-22行目**: p<0.5で異なる計算式を使用

#### Step 3: 高度なイージング実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SplineEasing.cs | `src/Avalonia.Base/Animation/Easings/SplineEasing.cs` | カスタムベジェ曲線 |
| 3-2 | SpringEasing.cs | `src/Avalonia.Base/Animation/Easings/SpringEasing.cs` | 物理シミュレーション |

**主要処理フロー**:
- **SplineEasing 14-57行目**: 4つの制御点プロパティ
- **SplineEasing 82-83行目**: KeySplineによる曲線計算
- **SpringEasing 13-56行目**: Mass/Stiffness/Damping/InitialVelocityプロパティ
- **SpringEasing 74行目**: Spring物理シミュレーション呼び出し

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

```
Animation.RunAsync()
    │
    └─ Interpolator
           │
           └─ Easing.Ease(progress)
                  │
                  ├─ LinearEasing.Ease() → progress
                  │
                  ├─ CubicEaseInOut.Ease() → 3次関数計算
                  │
                  ├─ SplineEasing.Ease()
                  │      └─ KeySpline.GetSplineProgress()
                  │
                  └─ SpringEasing.Ease()
                         └─ Spring.GetSpringProgress()
```

### データフロー図

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

progress ───▶ Easing.Ease() ───▶ easedProgress
(0.0〜1.0)          │                (変換後の値)
                    │
              数学関数適用
              ・線形: y = x
              ・2次: y = x^2
              ・3次: y = x^3
              ・弾性: 三角関数
              ・物理: 減衰振動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| IEasing.cs | `src/Avalonia.Base/Animation/Easings/IEasing.cs` | ソース | イージングインターフェース |
| Easing.cs | `src/Avalonia.Base/Animation/Easings/Easing.cs` | ソース | 基底クラス・Parse機能 |
| LinearEasing.cs | `src/Avalonia.Base/Animation/Easings/LinearEasing.cs` | ソース | 線形イージング |
| QuadraticEaseIn.cs | `src/Avalonia.Base/Animation/Easings/QuadraticEaseIn.cs` | ソース | 2次EaseIn |
| QuadraticEaseOut.cs | `src/Avalonia.Base/Animation/Easings/QuadraticEaseOut.cs` | ソース | 2次EaseOut |
| QuadraticEaseInOut.cs | `src/Avalonia.Base/Animation/Easings/QuadraticEaseInOut.cs` | ソース | 2次EaseInOut |
| CubicEaseIn.cs | `src/Avalonia.Base/Animation/Easings/CubicEaseIn.cs` | ソース | 3次EaseIn |
| CubicEaseOut.cs | `src/Avalonia.Base/Animation/Easings/CubicEaseOut.cs` | ソース | 3次EaseOut |
| CubicEaseInOut.cs | `src/Avalonia.Base/Animation/Easings/CubicEaseInOut.cs` | ソース | 3次EaseInOut |
| ElasticEaseIn.cs | `src/Avalonia.Base/Animation/Easings/ElasticEaseIn.cs` | ソース | 弾性EaseIn |
| ElasticEaseOut.cs | `src/Avalonia.Base/Animation/Easings/ElasticEaseOut.cs` | ソース | 弾性EaseOut |
| ElasticEaseInOut.cs | `src/Avalonia.Base/Animation/Easings/ElasticEaseInOut.cs` | ソース | 弾性EaseInOut |
| BounceEaseIn.cs | `src/Avalonia.Base/Animation/Easings/BounceEaseIn.cs` | ソース | バウンスEaseIn |
| BounceEaseOut.cs | `src/Avalonia.Base/Animation/Easings/BounceEaseOut.cs` | ソース | バウンスEaseOut |
| BounceEaseInOut.cs | `src/Avalonia.Base/Animation/Easings/BounceEaseInOut.cs` | ソース | バウンスEaseInOut |
| BackEaseIn.cs | `src/Avalonia.Base/Animation/Easings/BackEaseIn.cs` | ソース | バックEaseIn |
| BackEaseOut.cs | `src/Avalonia.Base/Animation/Easings/BackEaseOut.cs` | ソース | バックEaseOut |
| BackEaseInOut.cs | `src/Avalonia.Base/Animation/Easings/BackEaseInOut.cs` | ソース | バックEaseInOut |
| SplineEasing.cs | `src/Avalonia.Base/Animation/Easings/SplineEasing.cs` | ソース | カスタムベジェ曲線 |
| SpringEasing.cs | `src/Avalonia.Base/Animation/Easings/SpringEasing.cs` | ソース | スプリング物理 |
| EasingTypeConverter.cs | `src/Avalonia.Base/Animation/Easings/EasingTypeConverter.cs` | ソース | 型変換 |
