# Image Manager 機能ガイド

Image Manager は、ComfyUI のサイドバーに追加される統合画像管理システムです。
生成した画像の閲覧、検索、整理を効率化し、過去の作品をワークフローに再利用するプロセスをスムーズにします。

## 主な機能概要

*   **ギャラリー**: 生成した画像を高速に閲覧・整理できます。
*   **詳細ビューアー**: 画像のプロンプト、モデル情報、生成設定を詳しく確認できます。
*   **高度な検索**: プロンプト、タグ、日付、モデル名などを使った柔軟な検索が可能です。
*   **系統管理 (Lineage)**: img2img などで生成された画像の「親」と「子」の関係を可視化します。
*   **ワークフロー連携**: 過去の画像をワンクリックでキャンバスに読み込んだり、設定を復元したりできます。

---

## 基本コンセプト: 自動登録と管理

Image Manager は、ComfyUI での画像生成プロセスに深く統合されています。

### 生成画像の自動登録
ワークフローを実行し、画像が生成されると、Image Manager はその画像を **自動的にデータベースに登録** します。
*   標準の `Save Image` ノードなどで生成された画像（`output` フォルダに保存されるもの）が、実行完了時に自動的にギャラリーへ追加されます。
*   メタデータ（プロンプト、モデル情報、ワークフロー）も同時に保存されるため、後から簡単に検索や復元が可能です。

### [Meld Save Image](./nodes/MeldSaveImage.md) による高度な管理
専用の **[Meld Save Image](./nodes/MeldSaveImage.md)** ノードを使用することで、さらに柔軟な管理が可能になります。
*   **タグの自動付与**: ノードの `tags` 入力にカンマ区切りでタグ（例: `favorite, portrait`）を指定すると、生成時にそのタグが自動的に付与された状態で登録されます。
*   **Source 画像（親）の明示的な指定**: `origin_image` 入力に画像を接続することで、その画像を「親画像（Source）」として明示的に指定し、系統管理（Lineage）に記録できます。自動推定に頼らず、正確な親子関係を維持したい場合に役立ちます。

---

## 1. ギャラリー (Gallery)

ComfyUI 画面左側のサイドバーに表示されるパネルです。

### ビューの変更
ヘッダーのアイコンで表示形式を切り替えられます。
*   **Grid Only**: サムネイルのみをグリッド状に並べて表示します（一覧性重視）。
*   **Grid & Details**: サムネイルの下にファイル名や日付などの情報を表示します。

### 一括操作
画像を `Ctrl + Click`（Macの場合は `Cmd + Click`）または `Shift + Click` で複数選択すると、画面下部にアクションバーが表示されます。

*   **Edit Tags**: 選択した画像にタグを一括追加・削除します。
*   **Queue Workflow**: 選択した画像を順番に入力としてワークフローを実行します（バッチ処理）。
*   **Move to Trash**: 選択した画像をゴミ箱へ移動します。

### 画像分析 (Image Analytics)

ギャラリーヘッダーの **BarChart2 アイコン** をクリックすると、画像の集計サマリを表示するモーダルが開きます。

*   **総画像数**: 登録されている画像の総数。
*   **カテゴリ別ランキング**: Positive Prompt、Negative Prompt、Tag、Model、作成日、解像度ごとに上位5件を表示。
*   **項目クリックで検索**: 各項目をクリックすると、検索窓に移動し、対応する検索クエリ（例: `tag:girl`、`pos:1girl`）で検索を実行します。
*   **全部見る**: 各カテゴリの「See all」をクリックすると、全件リストを表示。部分一致での絞り込みや、カウントの昇順/降順切り替えが可能です。
*   **更新**: モーダル内の「Refresh」ボタンで、集計を再実行できます。

集計はアプリ起動時にバックグラウンドで実行され、結果はキャッシュに保存されるため、表示は即時に行われます。

---

## 2. 画像詳細ビューアー (Viewer)

ギャラリー内の画像をクリックすると、詳細ビューアーが開きます。

### 基本操作
*   **閉じる**: 画面外をクリックするか、`Esc` キーを押します。
*   **移動**: 左右の矢印ボタン、またはキーボードの `←` `→` で前後の画像へ移動します。
*   **フルスクリーン**: `F` キーでフルスクリーンモードに切り替えます。
*   **詳細表示**: `I` キーで右側の情報パネルの表示/非表示を切り替えます。
*   **サムネイル**: 画面下部のサムネイル一覧で素早く他の画像へジャンプできます。
*   **Undo (取り消し)**: `Ctrl + Z`（Macの場合は `Cmd + Z`）で、直前の削除（ゴミ箱移動）やショートカットによるタグ操作を取り消せます。

### 情報パネル (Information Panel)
画面右側に表示されるパネルでは、以下の情報を確認・編集できます。
*   **Metadata**: 画像サイズ、ファイル形式、作成日時。
*   **Generation Info**: 生成に使用したモデル (Checkpoint)、Seed値、Steps、CFG Scale、Sampler 名など。
*   **Prompts**: Positive プロンプトと Negative プロンプト。コピーボタンでクリップボードにコピーできます。
*   **Tags**: 画像に付与されたタグ。編集アイコンからタグを追加・削除できます。
*   **Notes**: ユーザー独自のメモを記録できます。
*   **Lineage**: この画像がどの画像から生成されたか（親画像）、またはこの画像から生成された画像（子画像）のツリーを表示します。

### 画像メニューアクション
画像上のメニューや右クリックから以下のアクションを実行できます。

*   **Add Unified Loader**: 生成に使用した設定を解析し、[Meld Unified Loader](./nodes/MeldUnifiedLoader.md) または [Meld Unified Flux Loader](./nodes/MeldUnifiedFluxLoader.md) を自動選択して追加します。
*   **Send to Workflow**: 画像を現在のワークフローにある `Load Image` や [Meld Image Loader](./nodes/MeldImageLoader.md) ノードに送信します。
    *   **Send to Workflow (Mask)**: Inpaint 用に、画像とマスクを現在のワークフローに送信します。
*   **Queue Workflow**: 選択したワークフローに画像を入力して実行します。
    *   **Queue Workflow (Mask)**: マスクエディタを開き、Inpaint ワークフローを実行します。
*   **Restore Full Workflow**: 画像に埋め込まれたワークフロー情報を読み込み、現在のキャンバス全体を上書き復元します。
*   **Edit Tags**: タグを編集します。
*   **Edit Notes**: メモを編集します。
*   **Edit Source Image**: 親画像（Source）を手動で設定・変更します。
*   **Delete**: 画像をゴミ箱へ移動します。

### 親画像（Source）の設定の補足
親画像を手動設定する際、候補は概ね以下の2系統で表示されます（設定により片方のみの場合があります）。
*   **Source Matches (from metadata)**: メタデータ（ワークフロー等）から推定できる候補（`Source Matching Strategy` が `filename_phash` の場合）。
*   **Visual Matches (pHash)**: 画像の類似度（pHash）に基づく候補。

また、ダイアログのドロップゾーンへ画像ファイルを **Drag & Drop** すると、画像をアップロードして即座に親画像として設定できます。

### マスクエディタ (Mask Editor)
簡易的なマスク作成ツールを内蔵しており、Inpaint (修正) 作業を効率化します。メニューから起動できます。
*   **ツール**:
    *   **Rect / Ellipse**: 矩形や楕円でマスク領域を選択します。
    *   **Lasso**: フリーハンドで囲んでマスクを作成します。
*   **アクション**:
    *   **Queue**: 作成したマスクを使用して、即座にワークフローを実行します。
    *   **Send**: 作成したマスクを現在のワークフローに送信します（`Load Image` ノードなどのマスク出力として利用可能）。
    *   **Undo**: `Ctrl + Z` で操作を取り消せます。

### 付録: ショートカットキー一覧
ビューアー内で使用できる主なショートカットキーです（設定で変更できるのは **カスタムショートカット (0-9)** です）。

| アクション | デフォルトキー |
| :--- | :--- |
| 次の画像 | `→` |
| 前の画像 | `←` |
| 詳細表示の切り替え | `I` |
| フルスクリーンの切り替え | `F` |
| 閉じる | `Esc` |
| Delete / Trash | `Delete` |
| Undo (削除やタグ操作の取り消し) | `Ctrl + Z` / `Cmd + Z` |

#### カスタムショートカット (0-9)
設定のショートカット項目で、`0`〜`9` に独自コマンドを割り当てられます。複数コマンドはスペース区切りで連結できます。

*   **タグ操作**: `tag:NAME` / `-tag:NAME` / `tag-toggle:NAME`
*   **移動**: `next` / `prev`
*   **削除**: `delete`

例:
*   `tag:favorite next`（favorite を付けて次へ）
*   `tag-toggle:best_quality`（タグをトグル）

---

## 3. 検索機能 (Search)

ギャラリー上部の検索バーを使って、膨大なコレクションから目的の画像をすぐに見つけられます。

### キーワード検索
検索バーに単語を入力すると、プロンプト、ファイル名、ノート、タグなどを対象に全文検索を行います。
複数の単語をスペース区切りで入力すると、すべての単語を含む画像（AND検索）が表示されます。

### フィルタリング構文
特定の条件で絞り込むための構文が利用できます。

| 構文 | 説明 | 例 |
| :--- | :--- | :--- |
| `tag:` | タグで検索 | `tag:風景` `tag:best_quality` |
| `model:` | モデル名で検索 | `model:sdxl` `model:v1-5` |
| `id:` | データベースのIDで完全一致検索 | `id:123` |
| `filename:` | ファイル名で検索（完全一致、部分一致） | `filename:image.png` `filename:img` |
| `date:` | 日付で検索 | `date:2024-01-01` (特定日), `date:2024-01` (月指定) |
| `resolution:` | 解像度で検索 | `resolution:1024x1024` |
| `after:` | 指定日以降を検索 | `after:2024-01-01` |
| `before:` | 指定日以前を検索 | `before:2024-01-01` |
| `pos:` | Positive プロンプトのみ検索 | `pos:cat` |
| `neg:` | Negative プロンプトのみ検索 | `neg:blurry` |
| `note:` | ユーザーノート内を検索 | `note:実験用` |
| `has_source:` | 親画像の有無で検索 | `has_source:yes` (あり), `has_source:no` (なし) |
| `has_derivatives:`| 子画像の有無で検索 | `has_derivatives:yes` (あり) |
| `sort:` | 並び順を指定 | `sort:created_at_asc` (古い順), `sort:created_at_desc` (新しい順) |

### 高度な検索テクニック
*   **除外検索 (NOT)**: 検索語句の前に `-` または `!` を付けると、その条件を含まない画像を検索できます。
    *   例: `-tag:failed` (failedタグが付いていないもの)
    *   例: `!model:sdxl` (モデル名にsdxlを含まないもの)
*   **フレーズ検索**: スペースを含むタグやプロンプトを検索する場合、ダブルクォーテーション `"` で囲みます。
    *   例: `pos:"blue sky"`
*   **オートコンプリート**: `tag:` や `model:` などのプレフィックスを入力すると、候補リストが自動的に表示され、スムーズに入力できます。

### お気に入り検索 (Favorites)
よく使う検索条件は、検索バー右側の `★` アイコンをクリックしてお気に入りに登録できます。
登録した検索条件は、ヘッダーの `★` メニューからワンクリックで呼び出せます。

---

## 4. タグ管理 (Tag Manager)

ヘッダーの `タグアイコン` をクリックすると、タグマネージャーが開きます。
*   新しいタグの作成
*   タグ名の変更（関連付けられたすべての画像のタグも更新されます）
*   不要なタグの削除
*   タグごとの画像検索

---

## 5. データのインポート (Import)

ヘッダーの「インポート（ダウンロードアイコン）」ボタンから、ComfyUI外の画像や過去の生成物を Image Manager に取り込めます。

### 基本的な使い方
1.  **Base Location** を選択します (`Output`, `Input` ディレクトリ、または `Custom Path`)。
2.  対象のフォルダを選択・移動します。
3.  **Start Import** をクリックするとスキャンが開始されます。

### 高度なインポート設定
*   **Custom Path**: サーバー内の任意の絶対パスを指定してスキャンできます。別ドライブの画像も管理可能です。
*   **Recursive Scan**: サブフォルダも含めて再帰的にスキャンします。
*   **Source Linking**: インポート時に親子関係（Lineage）を自動推定するか設定できます。
    *   `New only`: 新規取り込み画像のみ判定（推奨）。
    *   `All`: 既存画像も含めて再判定します（時間がかかります）。
*   **Tags to Add**: インポートする画像すべてに、指定したタグを一括で付与できます。フォルダごとにタグを分けたい場合に便利です。

### 進捗表示・キャンセル・クリーンアップ
インポート（スキャン）中は進捗が表示され、状況に応じてキャンセルできます。
また、ディスク上から削除された画像がDBに残っている場合でも、拡張の読み込み後にバックグラウンドで自動的に整理されます（手動操作は不要です）。
*   **進捗**: スキャン中は `Scanning...`（登録）→ `Linking...`（親子リンク推定）の順に進み、`current / total` と進捗バーが更新されます。
*   **キャンセル**: スキャン中に停止ボタン（■）を押すと中断を要求できます（表示が `Cancelling...` になり、処理が安全に停止します）。
*   **自動クリーンアップ**: 拡張の読み込み後、少し待ってからバックグラウンドで「実ファイルが存在しない画像」をDBから除去します。外部ツールでファイルを消した/移動した後に表示が不整合な場合は、ページ再読み込み（または再起動）で整合が取れることがあります。

---

## 6. 設定 (Settings)

ヘッダーの `歯車アイコン` から設定画面を開けます。

### システム設定 (System)
重要なバックエンド設定項目です。

*   **Image Matching**: 親子関係（Lineage）の判定ロジックを設定します。
    *   **Source Matching Strategy**: 親画像の検索アルゴリズムを選択します（デフォルト: `pHash & Created Time`）。
    *   **Auto Linking Threshold**: 自動リンクの判定基準となる類似度（%）。数値を上げると誤判定が減りますが、少しの変更でリンクされなくなります。
    *   **Inherit Tags from Source**: ONにすると、親画像のタグを生成された子画像に自動的にコピーします。
*   **Lineage**:
    *   **Max Lineage Depth**: 系統図を何世代先まで表示するかを設定します。動作が重い場合は小さくしてください。
*   **Thumbnail Cache（サムネイルキャッシュ）**: サムネイルはディスク上でキャッシュされ、表示が高速化されます。
    *   **Clear Thumbnail Cache**: キャッシュされたサムネイルをすべて削除します。次回表示時に再生成されます。
*   **Trash**: ゴミ箱（Trash）表示時には、選択した画像を **Restore**（元に戻す）したり **Delete Permanently**（完全に削除）したりできます。
    *   **Trash Retention Days**: ゴミ箱に入れた画像を何日後に完全に削除するかを設定します。現状の実装では `0` は「自動削除しない」ではなく、クリーンアップ実行時に削除対象になり得ます（自動削除を無効化する設定は未実装）。

**Thumbnail API（サムネイルAPI）**: ギャラリー、ビューアー、系統図はサムネイル表示に `/api/meld/view-thumb` エンドポイントを使用します。クエリパラメータ: `filename`, `subfolder`, `type`（output/input/temp/custom/trash）, `size`（最大辺のピクセル数、デフォルト200、上限400）。キャッシュされたサムネイルは `data/thumbnails/` 以下（WebP形式）に保存され、HTTP Cache-Control により高速に配信されます。

### ギャラリー・表示設定
*   **Gallery**: サムネイルのサイズや、一度に読み込む画像の数を調整し、パフォーマンスを最適化できます。
*   **View**: ビューアーでのサムネイル表示数や、プロンプトの最大表示行数を設定できます。
*   **FullScreen**: フルスクリーンモード時の挙動を設定できます。
    *   **Delete Mode**: 削除時の確認ダイアログの有無や、系統（Lineage）を含めて削除するかを設定できます。
    *   **Details Panel**: フルスクリーン時に表示する情報（ファイル名、サイズ、作成日時、モデル、プロンプトなど）を個別にON/OFFできます。
*   **Shortcuts**: Image Manager 内で使用するキーボードショートカットを自分好みにカスタマイズできます。

---

## 7. ライトテーブル (Light Table)

画面下部に表示される一時的な画像プール機能です。
ギャラリーから画像をドラッグ＆ドロップして一時保管（キープ）したり、比較したりするのに使用します。

*   **タブ管理**: 複数のタブを作成し、画像を分類して保持できます。
*   **Clear All**: すべてのタブから画像を一度にクリアします。
*   **閉じる**: 右上のバツボタン（`X`）をクリックしてライトテーブルを閉じることができます。

---

## Q&A / Tips

**Q: 画像がギャラリーに表示されません。**
A: Image Manager は、ワークフロー実行完了時（`executed` イベント）に **Output 画像を自動登録** します（Meld が読み込まれている必要があります）。表示されない場合は、まず以下を確認してください。

*   **拡張が読み込まれているか**: サイドバーに `Meld` タブが出ているか、出ていなければ再読み込みしてください。
*   **対象が Output 以外ではないか**: `Preview Image` (temp) や `Input`、外部からコピーした画像は自動登録されません。「5. データのインポート」で手動で取り込むか、`Save Image` 系ノードを使用してください。
*   **機能差の補足**: `Restore Full Workflow` や `Add Unified Loader` など、一部機能は画像に埋め込まれたメタデータ（ワークフロー情報等）が必要です。画像の保存方法やメタデータ有無によっては、表示はできても復元系の機能が制限されることがあります。

**Q: 系統 (Lineage) が正しく表示されません。**
A: 親子関係のリンクは、画像の類似度（pHash）やワークフロー内の情報を元に自動推定されます。画像が大きく加工されて原型を留めていない場合や、メタデータが欠落している場合はリンクされないことがあります。設定の `Auto Linking Threshold` を調整するか、詳細ビューアーのメニューから手動で親画像を設定することも可能です。

**Q: 削除した画像を元に戻せますか？**
A: はい。ビューを「Trash」に切り替えると、削除した画像の一覧が表示されます。画像を選択して「Restore」ボタンを押すことで元に戻せます。ただし、保存期間（デフォルト設定による）を過ぎた画像や、「Delete Permanently」で完全削除した画像は復元できません。