# バッチ設計書 52-Generate-TerminalAssets

## 概要

本ドキュメントは、SVGファイルからWindows Terminalアプリ用のアイコンアセット（各サイズPNG・ICO）を生成するPowerShellスクリプト「Generate-TerminalAssets.ps1」のバッチ設計書である。

### 本バッチの処理概要

本バッチは、SVGソースファイルからInkscapeとImageMagickを使用して、Windows TerminalのAppXパッケージに必要な各サイズのPNG画像およびWin32用ICOファイルを一括生成する。標準コントラスト、ハイコントラスト（黒・白）の3モードに対応し、各種タイルサイズ・スケールファクター・altformサイズのアセットを網羅的に出力する。

**業務上の目的・背景**：Windows TerminalのAppXパッケージには、Windowsのスタートメニュー・タスクバー・タイルなど様々な場所で使用されるアイコンアセットが必要である。これらは複数のサイズ・スケール・ハイコントラストモードの組み合わせで大量に存在するため、SVGから自動生成することで一貫性と効率性を確保する。

**バッチの実行タイミング**：アイコンデザインの変更時に手動で実行される。通常のビルドプロセスでは実行されず、アセット更新が必要な場合にのみ使用する。

**主要な処理内容**：
1. SVGファイルからInkscapeで各サイズのベースPNG（中間ファイル）を並列生成
2. ハイコントラスト用SVGからblack版PNGを生成し、ImageMagickでwhite版（色反転）を自動生成
3. 中間PNGファイルからImageMagickでWin32用ICOファイルを生成
4. 中間PNGをImageMagickで各アセットサイズのキャンバスに配置（パディング付き）
5. 中間ファイルのクリーンアップ（オプションで保持可能）

**前後の処理との関連**：本バッチで生成されたアセットはAppXパッケージのビルドに使用される。SVGデザインの更新が前提条件となる。

**影響範囲**：res/terminal/images（またはimages-Pre, images-Dev等）配下のPNG・ICOファイル群。AppXパッケージのアイコン表示に影響する。

## バッチ種別

コード生成（アセット生成）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（アイコン変更時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| WSL | WSL（Windows Subsystem for Linux）が利用可能であること |
| Inkscape | WSL内にInkscapeがインストールされていること |
| ImageMagick | WSL内にImageMagick（convertコマンド）がインストールされていること |
| SVGファイル | 入力となるSVGファイルが存在すること |

### 実行可否判定

Inkscape・ImageMagickの存在チェックを起動時に実施し、インストールされていない場合はエラーをスローして終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Path | string | Yes | - | 入力SVGファイルのパス |
| Destination | string | No | カレントディレクトリ | 出力先ディレクトリ |
| Altforms | int[] | No | 16,20,24,30,32,36,40,48,60,64,72,80,96,256 | altformターゲットサイズの配列 |
| Win32IconSizes | int[] | No | 16,20,24,32,48,64,256 | Win32 ICOに含めるサイズの配列 |
| Unplated | switch | No | $true | unplated altformも生成するか |
| Scales | float[] | No | 1.0,1.25,1.5,2.0,4.0 | スケールファクターの配列 |
| HighContrastPath | string | No | "" | ハイコントラスト用SVGファイルのパス |
| UseExistingIntermediates | switch | No | $false | 既存の中間ファイルを再利用するか |
| KeepIntermediates | switch | No | $false | 中間ファイルを削除せず保持するか |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| SVGファイル（Path） | SVG | 標準コントラスト用のアイコンソース |
| SVGファイル（HighContrastPath） | SVG | ハイコントラスト用のアイコンソース（オプション） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| {Destination}/{アセット名}.png | PNG | 各サイズ・スケール・コントラストモードのアセット画像 |
| {Destination}/terminal.ico | ICO | Win32用アイコン（標準コントラスト） |
| {Destination}/terminal_contrast-{black/white}.ico | ICO | Win32用アイコン（ハイコントラスト） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | {アセットタイプ}.scale-{スケール}.png, Square44x44Logo.targetsize-{サイズ}.png 等 |
| 出力先 | -Destination で指定されたディレクトリ |
| 形式 | PNG（透過背景）/ ICO |

## 処理フロー

### 処理シーケンス

```
1. 前提条件チェック
   └─ WSL内のInkscape・ImageMagickの存在確認
2. アセットサイズの計算
   └─ 8種類のアセットタイプ x 5スケール + altformサイズ を算出
3. コントラストモードの展開
   └─ standard / black / white の3モード分に展開
4. ベースアイコンの並列生成
   └─ ForEach-Object -Parallel で全サイズをInkscapeで生成
5. ハイコントラストアイコンの生成
   └─ black版をInkscapeで生成、white版はImageMagickのnegateで生成
6. Win32 ICOファイルの生成
   └─ ImageMagick convertで中間PNGからICOを作成
7. 最終アセットの生成
   └─ 中間PNGをImageMagickでリサイズ・パディングして配置
8. 中間ファイルのクリーンアップ
   └─ KeepIntermediates=falseの場合に削除
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{Inkscape/ImageMagick存在?}
    B -->|なし| C[エラースロー]
    B -->|あり| D[アセットサイズ計算]
    D --> E[コントラストモード展開]
    E --> F[ベースアイコン並列生成 - Inkscape]
    F --> G{HighContrastPath指定?}
    G -->|あり| H[HC black版生成 - Inkscape]
    H --> I[HC white版生成 - ImageMagick negate]
    G -->|なし| J[Win32 ICO生成]
    I --> J
    J --> K[最終アセット生成 - 各サイズ配置]
    K --> L{KeepIntermediates?}
    L -->|false| M[中間ファイル削除]
    L -->|true| N[バッチ終了]
    M --> N
```

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

### 操作別データベース影響一覧

本バッチはデータベース操作を行わない。ファイルシステム上の画像ファイル生成のみを行う。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | ThrowError | WSL内にInkscapeがインストールされていない | WSLにInkscapeをインストール |
| N/A | ThrowError | WSL内にImageMagickがインストールされていない | WSLにImageMagickをインストール |
| N/A | ErrorAction Stop | 入力SVGファイルが存在しない | -Pathに正しいパスを指定 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

中間ファイルが残存する場合は手動で削除し、再実行する。-UseExistingIntermediates を指定することで、既に生成済みの中間ファイルを再利用して途中から再開可能。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（ファイル単位で独立） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数百ファイル（サイズ x スケール x コントラストの組み合わせ） |
| 目標処理時間 | 数分程度（並列処理により高速化） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

ForEach-Object -Parallel による並列処理を使用しているため、ConcurrentBagで中間ファイルリストを管理している。同一出力ディレクトリに対する複数プロセスからの同時実行は想定されていない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | 既存中間ファイル再利用時 | "Using existing {ファイルパス}" |
| 情報ログ | ICO生成時 | "Producing win32 .ico for contrast={コントラスト} as {ファイル名}" |
| 情報ログ | アセット配置時 | "Copying base icon for size={サイズ}, contrast={コントラスト} to {名前}" |
| 情報ログ | クリーンアップ時 | "Cleaning up intermediate file {パス}" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 特になし | N/A | N/A |

## 備考

- 手動ヒンティングワークフローに対応している（-KeepIntermediates → 手動調整 → -UseExistingIntermediates）
- white版ハイコントラストアイコンはblack版のRGBチャンネル反転で自動生成される
- CeilToEven関数でアイコンサイズを偶数に丸めている
- WSL環境でのパス変換（wslpath -u）を使用してWindows/Linux間のパス互換性を確保している
