@enslo/sd-metadata 2.1.0 → 2.2.0

package/docs/types.ja.md

@@ -0,0 +1,799 @@
+# 型ドキュメント
+
+`@enslo/sd-metadata` の完全な型リファレンスです。
+
+🌐 **[English version](./types.md)**
+
+## 目次
+
+- [コア型](#コア型)
+  - [`ParseResult`](#parseresult)
+  - [`BaseMetadata`](#basemetadata)
+  - [`GenerationMetadata`](#generationmetadata)
+  - [`GenerationSoftware`](#generationsoftware)
+  - [`EmbedMetadata`](#embedmetadata)
+  - [`RawMetadata`](#rawmetadata)
+  - [`WriteResult`](#writeresult)
+- [メタデータ型](#メタデータ型)
+  - [`StandardMetadata`](#standardmetadata)
+  - [`NovelAIMetadata`](#novelaimetadata)
+  - [`ComfyUIMetadata`](#comfyuimetadata)
+- [設定型](#設定型)
+  - [`ModelSettings`](#modelsettings)
+  - [`SamplingSettings`](#samplingsettings)
+  - [`HiresSettings`](#hiressettings)
+  - [`UpscaleSettings`](#upscalesettings)
+  - [`CharacterPrompt`](#characterprompt)
+- [ComfyUI型](#comfyui型)
+  - [`ComfyNodeGraph`](#comfynodegraph)
+  - [`ComfyNode`](#comfynode)
+  - [`ComfyNodeInputValue`](#comfynodeinputvalue)
+  - [`ComfyNodeReference`](#comfynodereference)
+- [フォーマット固有の型](#フォーマット固有の型)
+  - [`PngTextChunk`](#pngtextchunk)
+  - [`TExtChunk`](#textchunk)
+  - [`ITXtChunk`](#itxtchunk)
+  - [`MetadataSegment`](#metadatasegment)
+  - [`MetadataSegmentSource`](#metadatasegmentsource)
+
+---
+
+## コア型
+
+### `ParseResult`
+
+`read()` 関数が返す結果型。
+
+```typescript
+type ParseResult =
+  | { status: 'success'; metadata: GenerationMetadata; raw: RawMetadata }
+  | { status: 'unrecognized'; raw: RawMetadata }
+  | { status: 'empty' }
+  | { status: 'invalid'; message?: string };
+```
+
+**ステータス値：**
+
+- **`success`**: メタデータのパースに成功
+  - `metadata`: 統一されたメタデータオブジェクト
+  - `raw`: ラウンドトリップ変換用の元のフォーマット固有データ
+- **`unrecognized`**: 画像にメタデータがあるがフォーマットが認識できない
+  - `raw`: 元のメタデータが保持される
+- **`empty`**: 画像にメタデータが見つからない
+- **`invalid`**: 破損または非対応の画像フォーマット
+  - `message`: オプションのエラー説明
+
+**例：**
+
+```typescript
+import { read } from '@enslo/sd-metadata';
+
+const result = read(imageData);
+
+switch (result.status) {
+  case 'success':
+    console.log(`Generated by ${result.metadata.software}`);
+    console.log(`Prompt: ${result.metadata.prompt}`);
+    break;
+  
+  case 'unrecognized':
+    console.log('不明なメタデータフォーマット');
+    break;
+  
+  case 'empty':
+    console.log('メタデータなし');
+    break;
+  
+  case 'invalid':
+    console.error(`無効な画像: ${result.message}`);
+    break;
+}
+```
+
+---
+
+### `BaseMetadata`
+
+全メタデータ型で共有される共通フィールド。`GenerationMetadata` の各バリアントと `EmbedMetadata` の基盤です。
+
+```typescript
+export interface BaseMetadata {
+  /** ポジティブプロンプト */
+  prompt: string;
+  /** ネガティブプロンプト */
+  negativePrompt: string;
+  /** 画像の幅（ピクセル） */
+  width: number;
+  /** 画像の高さ（ピクセル） */
+  height: number;
+  /** モデル設定 */
+  model?: ModelSettings;
+  /** サンプリング設定 */
+  sampling?: SamplingSettings;
+  /** Hires.fix設定（適用されている場合） */
+  hires?: HiresSettings;
+  /** アップスケール設定（適用されている場合） */
+  upscale?: UpscaleSettings;
+}
+```
+
+**例：**
+
+```typescript
+import type { BaseMetadata } from '@enslo/sd-metadata';
+
+// 共通の生成フィールドのみ必要な場合にBaseMetadataを使用
+function displayMetadata(meta: BaseMetadata) {
+  console.log('Prompt:', meta.prompt);
+  console.log('Size:', meta.width, 'x', meta.height);
+  console.log('Model:', meta.model?.name);
+}
+```
+
+---
+
+### `GenerationMetadata`
+
+統一されたメタデータ構造。サポートされている全てのメタデータ型のユニオン型。全バリアントが `BaseMetadata` を拡張しています。
+
+```typescript
+type GenerationMetadata =
+  | NovelAIMetadata
+  | ComfyUIMetadata
+  | StandardMetadata;
+```
+
+**メタデータ型のマッピング：**
+
+| メタデータ型 | `software` 値 |
+| ------------- | ----------------- |
+| `StandardMetadata` | `'sd-webui'` \| `'sd-next'` \| `'forge'` \| `'forge-classic'` \| `'forge-neo'` \| `'reforge'` \| `'easy-reforge'` \| `'invokeai'` \| `'civitai'` \| `'hf-space'` \| `'easydiffusion'` \| `'fooocus'` \| `'ruined-fooocus'` \| `'draw-things'` |
+| `NovelAIMetadata` | `'novelai'` |
+| `ComfyUIMetadata` | `'comfyui'` \| `'tensorart'` \| `'stability-matrix'` \| `'swarmui'` |
+
+**型の絞り込み例：**
+
+```typescript
+if (metadata.software === 'novelai') {
+  // TypeScriptはmetadataがNovelAIMetadataであることを認識
+  console.log(metadata.characterPrompts);
+}
+
+if (metadata.software === 'comfyui' ||
+    metadata.software === 'tensorart' ||
+    metadata.software === 'stability-matrix' ||
+    metadata.software === 'swarmui') {
+  // TypeScriptはmetadataがComfyUIMetadataであることを認識
+  if (metadata.nodes) {
+    console.log('Has workflow:', Object.keys(metadata.nodes).length);
+  }
+}
+```
+
+---
+
+### `GenerationSoftware`
+
+サポートされている全ソフトウェア識別子の文字列リテラルユニオン型。`GenerationMetadata` の判別子として、また `softwareLabels` のキー型として使用します。
+
+```typescript
+type GenerationSoftware =
+  | 'novelai'
+  | 'comfyui'
+  | 'swarmui'
+  | 'tensorart'
+  | 'stability-matrix'
+  | 'invokeai'
+  | 'sd-webui'
+  | 'forge'
+  | 'forge-classic'
+  | 'forge-neo'
+  | 'reforge'
+  | 'easy-reforge'
+  | 'sd-next'
+  | 'civitai'
+  | 'hf-space'
+  | 'easydiffusion'
+  | 'fooocus'
+  | 'ruined-fooocus'
+  | 'draw-things';
+```
+
+**例：**
+
+```typescript
+import { softwareLabels } from '@enslo/sd-metadata';
+import type { GenerationSoftware } from '@enslo/sd-metadata';
+
+function displaySoftware(software: GenerationSoftware): string {
+  return softwareLabels[software];
+}
+```
+
+---
+
+### `EmbedMetadata`
+
+`embed()` と `stringify()` で使用するユーザー作成カスタムメタデータ型。`GenerationMetadata` が既知のAIツールからのパース結果を表すのに対し、`EmbedMetadata` はユーザーが独自にメタデータを組み立てるための型です。`BaseMetadata` にオプションのNovelAIキャラクタープロンプトと設定行への任意キーバリュー（`extras`）を追加。
+
+```typescript
+export type EmbedMetadata = BaseMetadata &
+  Pick<NovelAIMetadata, 'characterPrompts'> & {
+    extras?: Record<string, string | number>;
+  };
+```
+
+**例：**
+
+```typescript
+import { embed } from '@enslo/sd-metadata';
+import type { EmbedMetadata } from '@enslo/sd-metadata';
+
+const metadata: EmbedMetadata = {
+  prompt: 'masterpiece, 1girl',
+  negativePrompt: 'lowres',
+  width: 512,
+  height: 768,
+  sampling: { steps: 20, sampler: 'Euler a', cfg: 7, seed: 12345 },
+  model: { name: 'model.safetensors' },
+  extras: { Version: 'v1.0' },
+};
+
+const result = embed(imageData, metadata);
+```
+
+---
+
+### `RawMetadata`
+
+ロスレスなラウンドトリップ変換のために元のメタデータ構造を保持。
+
+```typescript
+type RawMetadata =
+  | { format: 'png'; chunks: PngTextChunk[] }
+  | { format: 'jpeg'; segments: MetadataSegment[] }
+  | { format: 'webp'; segments: MetadataSegment[] };
+```
+
+**なぜこれが必要？**
+
+画像からメタデータを読み込んで別のフォーマットに変換する場合（例：PNG → JPEG）、`RawMetadata` は元の構造を保持します。これにより、情報を失うことなく元のフォーマットに戻すことができます。
+
+**ラウンドトリップ変換例：**
+
+```typescript
+import { read, write } from '@enslo/sd-metadata';
+import { convertImageFormat } from 'some-image-library';
+
+// PNGからメタデータを読み込み
+const pngData = readFileSync('image.png');
+const parseResult = read(pngData);
+
+if (parseResult.status === 'success') {
+  // 画像をJPEGに変換
+  const jpegImageData = convertImageFormat(pngData, 'jpeg');
+  
+  // メタデータをJPEGに書き込み
+  const jpegWithMeta = write(jpegImageData, parseResult);
+  
+  // 後で：PNGに戻す
+  const pngImageData = convertImageFormat(jpegWithMeta.value, 'png');
+  const pngWithMeta = write(pngImageData, parseResult);
+  
+  // 元のPNGメタデータ構造が完全に保持される！
+}
+```
+
+`raw` がなければ、メタデータは汎用フォーマットに変換され、元に戻す際にフォーマット固有の詳細が失われます。
+
+---
+
+### `WriteResult`
+
+`write()` 関数が返す結果型。
+
+```typescript
+export type WriteResult =
+  | { ok: true; value: Uint8Array; warning?: WriteWarning }
+  | { ok: false; error: { type: string; message?: string } };
+```
+
+**成功：**
+
+```typescript
+if (result.ok) {
+  saveFile('output.png', result.value);
+  if (result.warning) {
+    console.warn('メタデータが削除されました:', result.warning.reason);
+  }
+}
+```
+
+**エラー：**
+
+```typescript
+if (!result.ok) {
+  console.error(`書き込み失敗: ${result.error.type}`);
+  if (result.error.message) {
+    console.error(result.error.message);
+  }
+}
+```
+
+**エラータイプ：**
+
+- `unsupportedFormat`: 画像フォーマットが非対応
+- `conversionFailed`: メタデータ変換に失敗
+- `writeFailed`: 画像へのメタデータ書き込みに失敗
+
+### `WriteWarning`
+
+書き込み操作の警告型。
+
+```typescript
+export type WriteWarning = {
+  type: 'metadataDropped';
+  reason: 'unrecognizedCrossFormat';
+};
+```
+
+書き込み操作中にメタデータが意図的に削除された場合に返される（例：未対応メタデータのクロスフォーマット変換）。
+
+---
+
+## メタデータ型
+
+### `StandardMetadata`
+
+ほとんどのSDツールで使用される標準パラメータフォーマット。
+
+```typescript
+export interface StandardMetadata extends BaseMetadata {
+  software:
+    | 'sd-webui'
+    | 'forge'
+    | 'forge-classic'
+    | 'forge-neo'
+    | 'reforge'
+    | 'easy-reforge'
+    | 'sd-next'
+    | 'invokeai'
+    | 'civitai'
+    | 'hf-space'
+    | 'easydiffusion'
+    | 'fooocus'
+    | 'ruined-fooocus'
+    | 'draw-things';
+}
+```
+
+`BaseMetadata` の全フィールドを継承します。最も一般的なメタデータ型で、ツール固有の拡張なしのベースライン生成メタデータを表します。SD WebUI、Forgeファミリー（Forge、Forge Classic、Forge Neo、reForge、EasyReforge）、SD.Next、InvokeAIなど多くのツールがこの構造を使用します。
+
+**例：**
+
+```typescript
+if (metadata.software === 'forge' || metadata.software === 'sd-webui') {
+  console.log('標準フォーマットのメタデータを使用');
+  console.log('Sampler:', metadata.sampling?.sampler);
+  console.log('Steps:', metadata.sampling?.steps);
+}
+```
+
+---
+
+### `NovelAIMetadata`
+
+NovelAI生成画像に固有のメタデータ。
+
+```typescript
+export interface NovelAIMetadata extends BaseMetadata {
+  software: 'novelai';
+  /** V4キャラクタープロンプト（キャラクター配置使用時） */
+  characterPrompts?: CharacterPrompt[];
+  /** 配置にキャラクター座標を使用 */
+  useCoords?: boolean;
+  /** キャラクターの順序を使用 */
+  useOrder?: boolean;
+}
+```
+
+**固有の機能：**
+
+- **キャラクター配置（V4）**: NovelAI V4は特定の座標に複数のキャラクターを配置することをサポート
+- `characterPrompts`: オプションの位置情報付きキャラクター固有プロンプトの配列
+- `useCoords`、`useOrder`: キャラクター配置の動作を制御
+
+**例：**
+
+```typescript
+if (metadata.software === 'novelai' && metadata.characterPrompts) {
+  metadata.characterPrompts.forEach(char => {
+    console.log(`Character: ${char.prompt}`);
+    if (char.center) {
+      console.log(`  Position: (${char.center.x}, ${char.center.y})`);
+    }
+  });
+}
+```
+
+---
+
+### `ComfyUIMetadata`
+
+ComfyUIおよび互換ツール（TensorArt、Stability Matrix、SwarmUI）からのメタデータ。
+
+```typescript
+export type ComfyUIMetadata =
+  | BasicComfyUIMetadata
+  | SwarmUIMetadata;
+
+// 内部型：
+interface BasicComfyUIMetadata extends BaseMetadata {
+  software: 'comfyui' | 'tensorart' | 'stability-matrix';
+  nodes: ComfyNodeGraph;  // 必須
+}
+
+interface SwarmUIMetadata extends BaseMetadata {
+  software: 'swarmui';
+  nodes?: ComfyNodeGraph;  // オプション
+}
+```
+
+**固有の機能：**
+
+- **ComfyUI/TensorArt/Stability Matrix**: `nodes` は全フォーマットで常に存在
+- **SwarmUI**: PNGから変換された場合、全フォーマットで `nodes` が存在する可能性あり（拡張対応）
+
+**例：**
+
+```typescript
+if (metadata.software === 'comfyui') {
+  // ComfyUIではnodesは必ず存在
+  console.log('Node count:', Object.keys(metadata.nodes).length);
+}
+
+if (metadata.software === 'swarmui') {
+  // ネイティブSwarmUI JPEG/WebPではnodesが存在しない可能性あり
+  // ただしPNGから変換された場合は存在
+  if (metadata.nodes) {
+    console.log('ワークフローあり（PNGまたは変換済み）');
+  } else {
+    console.log('ネイティブJPEG/WebP: パラメータのみ');
+  }
+}
+
+// 型の絞り込みは全てのComfyUI互換ツールで機能
+if (metadata.software === 'comfyui' ||
+    metadata.software === 'tensorart' ||
+    metadata.software === 'stability-matrix' ||
+    metadata.software === 'swarmui') {
+  // TypeScriptはmetadataがComfyUIMetadataであることを認識
+  // ただしmetadata.nodesは使用前にチェックが必要
+  if (metadata.nodes) {
+    // チェックポイントノードを検索
+    for (const [nodeId, node] of Object.entries(metadata.nodes)) {
+      if (node.class_type === 'CheckpointLoaderSimple') {
+        console.log('Model:', node.inputs.ckpt_name);
+      }
+    }
+  }
+}
+```
+
+## 設定型
+
+### `ModelSettings`
+
+画像生成に使用されるモデル設定。
+
+```typescript
+export interface ModelSettings {
+  /** モデル名（例："sd_xl_base_1.0.safetensors"） */
+  name?: string;
+  /** 検証用モデルハッシュ */
+  hash?: string;
+  /** VAE（Variational AutoEncoder）名 */
+  vae?: string;
+}
+```
+
+**例：**
+
+```typescript
+if (metadata.model) {
+  console.log('Model:', metadata.model.name);
+  console.log('Hash:', metadata.model.hash);
+  console.log('VAE:', metadata.model.vae || 'Default');
+}
+```
+
+---
+
+### `SamplingSettings`
+
+生成時に使用されるサンプリングパラメータ。
+
+```typescript
+export interface SamplingSettings {
+  /** サンプラーアルゴリズム（例："Euler a"、"DPM++ 2M Karras"） */
+  sampler?: string;
+  /** スケジューラータイプ（サンプラーと別の場合） */
+  scheduler?: string;
+  /** サンプリングステップ数 */
+  steps?: number;
+  /** CFG（Classifier Free Guidance）スケール */
+  cfg?: number;
+  /** 再現性のためのランダムシード */
+  seed?: number;
+  /** CLIPスキップレイヤー */
+  clipSkip?: number;
+  /** デノイズ強度（ComfyUIのみ）。1.0の場合は提供されない（txt2imgのデフォルト） */
+  denoise?: number;
+}
+```
+
+**例：**
+
+```typescript
+if (metadata.sampling) {
+  console.log('Sampler:', metadata.sampling.sampler);
+  console.log('Steps:', metadata.sampling.steps);
+  console.log('CFG Scale:', metadata.sampling.cfg);
+  console.log('Seed:', metadata.sampling.seed);
+}
+```
+
+---
+
+### `HiresSettings`
+
+Hires.fix（高解像度修正）の設定。
+
+```typescript
+export interface HiresSettings {
+  /** アップスケール倍率 */
+  scale?: number;
+  /** アップスケーラー名 */
+  upscaler?: string;
+  /** Hiresステップ数 */
+  steps?: number;
+  /** Hiresデノイズ強度 */
+  denoise?: number;
+}
+```
+
+高解像度出力の品質を向上させるために生成時に適用されます。
+
+---
+
+### `UpscaleSettings`
+
+生成後のアップスケール設定。
+
+```typescript
+export interface UpscaleSettings {
+  /** アップスケーラー名 */
+  upscaler?: string;
+  /** スケール倍率 */
+  scale?: number;
+}
+```
+
+初期生成後に別のアップスケールステップとして適用されます。
+
+---
+
+### `CharacterPrompt`
+
+NovelAI V4画像のキャラクター位置指定。
+
+```typescript
+export interface CharacterPrompt {
+  /** キャラクター固有のプロンプト */
+  prompt: string;
+  /** 画像内のキャラクター位置（正規化 0-1） */
+  center?: { x: number; y: number };
+}
+```
+
+**例：**
+
+```typescript
+const character: CharacterPrompt = {
+  prompt: "1girl, long hair, blue eyes",
+  center: { x: 0.3, y: 0.5 } // 左側、垂直方向に中央
+};
+```
+
+---
+
+## ComfyUI型
+
+### `ComfyNodeGraph`
+
+ノードIDから対応するノードデータへのマップ。
+
+```typescript
+export type ComfyNodeGraph = Record<string, ComfyNode>;
+```
+
+**例：**
+
+```typescript
+const graph: ComfyNodeGraph = {
+  "CheckpointLoader_Base": { /* ... */ },
+  "KSampler_Primary": { /* ... */ },
+  "SaveImage_Final": { /* ... */ }
+};
+```
+
+---
+
+### `ComfyNode`
+
+ComfyUIワークフローグラフ内の単一ノード。
+
+```typescript
+export interface ComfyNode {
+  /** ノードクラスタイプ（例："CheckpointLoaderSimple"、"KSampler"） */
+  class_type: string;
+  /** ノード入力 */
+  inputs: Record<string, ComfyNodeInputValue>;
+  /** ノードメタデータ（ComfyUIのみ） */
+  _meta?: {
+    /** 表示用ノードタイトル */
+    title?: string;
+  };
+  /** 変更検出ハッシュ（まれ、キャッシュ用） */
+  is_changed?: string[] | null;
+}
+```
+
+**例：**
+
+```typescript
+const ksampler: ComfyNode = {
+  class_type: "KSampler",
+  inputs: {
+    model: ["CheckpointLoader", 0],
+    seed: 12345,
+    steps: 20,
+    cfg: 7.0,
+    sampler_name: "euler_a",
+    scheduler: "normal",
+    denoise: 1.0
+  },
+  _meta: {
+    title: "Primary Sampler"
+  }
+};
+```
+
+---
+
+### `ComfyNodeInputValue`
+
+ノード入力の可能な値。
+
+```typescript
+export type ComfyNodeInputValue =
+  | string
+  | number
+  | boolean
+  | ComfyNodeReference
+  | ComfyNodeInputValue[];
+```
+
+プリミティブ値、別のノードへの参照、または配列を取ることができます。
+
+---
+
+### `ComfyNodeReference`
+
+別のノードの出力への参照。
+
+```typescript
+export type ComfyNodeReference = [nodeId: string, outputIndex: number];
+```
+
+**例：**
+
+```typescript
+const modelReference: ComfyNodeReference = ["CheckpointLoader_Base", 0];
+
+// ノード入力で使用：
+{
+  model: ["CheckpointLoader_Base", 0],  // CheckpointLoader_Baseの出力0を参照
+  positive: ["CLIPTextEncode_Positive", 0]
+}
+```
+
+---
+
+## フォーマット固有の型
+
+> **注意：** これらの型は主に高度なユースケースや内部実装の詳細用です。ほとんどのユーザーはこれらの型を直接扱う必要はありません。
+
+### `PngTextChunk`
+
+PNGテキストチャンク型（tEXtまたはiTXt）。
+
+```typescript
+export type PngTextChunk = TExtChunk | ITXtChunk;
+```
+
+---
+
+### `TExtChunk`
+
+PNG tEXtチャンク（Latin-1エンコード）。
+
+```typescript
+export interface TExtChunk {
+  type: 'tEXt';
+  /** チャンクキーワード（例："parameters"、"Comment"） */
+  keyword: string;
+  /** テキスト内容 */
+  text: string;
+}
+```
+
+---
+
+### `ITXtChunk`
+
+PNG iTXtチャンク（UTF-8国際テキスト）。
+
+```typescript
+export interface ITXtChunk {
+  type: 'iTXt';
+  /** チャンクキーワード */
+  keyword: string;
+  /** 圧縮フラグ（0=非圧縮、1=圧縮） */
+  compressionFlag: number;
+  /** 圧縮方式（0=zlib/deflate） */
+  compressionMethod: number;
+  /** 言語タグ（BCP 47） */
+  languageTag: string;
+  /** 翻訳されたキーワード */
+  translatedKeyword: string;
+  /** テキスト内容 */
+  text: string;
+}
+```
+
+---
+
+### `MetadataSegment`
+
+ソース追跡機能付きのJPEG/WebPメタデータセグメント。
+
+```typescript
+export interface MetadataSegment {
+  /** このセグメントのソース位置 */
+  source: MetadataSegmentSource;
+  /** 生のメタデータ文字列 */
+  data: string;
+}
+```
+
+メタデータを正しい位置に書き戻すためのラウンドトリップ変換に使用されます。
+
+---
+
+### `MetadataSegmentSource`
+
+メタデータセグメントのソース位置。
+
+```typescript
+export type MetadataSegmentSource =
+  | { type: 'exifUserComment' }
+  | { type: 'exifImageDescription'; prefix?: string }
+  | { type: 'exifMake'; prefix?: string }
+  | { type: 'jpegCom' }
+  | { type: 'xmpPacket' };
+```
+
+正確なラウンドトリップのために、JPEG/WebPファイル内のメタデータの出所を追跡します。
+
+---