nodes/HappyOnigiri-ComfyUI-Meld
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
c422033bfbd85eb100b98ba4e66c7f0e190c76f2
HappyOnigiri-ComfyUI-Meld/docs/en/ImageManager.md
T

16 KiB
Raw Blame History

Image Manager Feature Guide

Image Manager is an integrated image management system added to the ComfyUI sidebar. It streamlines browsing, searching, and organizing generated images, making it smooth to reuse past works in your workflows.

Key Features Overview

  • Gallery: Browse and organize generated images quickly.
  • Detailed Viewer: Inspect prompts, model information, and generation settings in detail.
  • Advanced Search: Flexible search using prompts, tags, dates, model names, and more.
  • Lineage (Lineage Management): Visualize "parent" and "child" relationships for images generated via img2img, etc.
  • Workflow Integration: Load past images to the canvas or restore settings with a single click.

Basic Concept: Automatic Registration and Management

Image Manager is deeply integrated into the image generation process in ComfyUI.

Automatic Registration of Generated Images

When you run a workflow and an image is generated, Image Manager automatically registers the image in the database.

  • Images generated by standard Save Image nodes (saved into the output folder) are automatically added to the gallery when execution finishes.
  • Metadata (prompt, model info, workflow) is also saved, so you can easily search or restore later.

Advanced Management with Meld Save Image

By using the dedicated Meld Save Image node, you can manage images more flexibly.

  • Automatic Tagging: Specify comma-separated tags (e.g., favorite, portrait) in the node's tags input to auto-attach tags at generation time.
  • Explicit Source (Parent) Image: Connect an image to the origin_image input to explicitly set it as the "Source (parent) image" and record it in Lineage. This is useful when you want accurate parent-child relationships without relying on automatic inference.

1. Gallery

This is the panel shown in the sidebar on the left side of the ComfyUI screen.

Changing Views

Switch the display layout using the header icons.

  • Grid Only: Shows thumbnails only in a grid (best for overview).
  • Grid & Details: Shows information like filename and date under thumbnails.

Batch Operations

Select multiple images with Ctrl + Click (Cmd + Click on macOS) or Shift + Click. An action bar appears at the bottom.

  • Edit Tags: Bulk add/remove tags on selected images.
  • Queue Workflow: Run a workflow with selected images as inputs in order (batch processing).
  • Move to Trash: Move selected images to Trash.

Image Analytics

Click the BarChart2 icon in the gallery header to open a modal showing image statistics.

  • Total Images: The total number of registered images.
  • Category Rankings: Top 5 items for Positive Prompt, Negative Prompt, Tag, Model, Created Date, and Resolution.
  • Click to Search: Click any item to switch to the search bar and run a search with the corresponding query (e.g., tag:girl, pos:1girl).
  • See All: Click "See all" for each category to view the full list. You can filter by partial match and toggle count sort (ascending/descending).
  • Refresh: Use the "Refresh" button in the modal to re-run the aggregation.

Aggregation runs in the background on app startup, and results are cached for instant display.

2. Image Detailed Viewer (Viewer)

Click an image in the gallery to open the detailed viewer.

Basic Operations

  • Close: Click outside or press Esc.
  • Navigate: Use the left/right arrow buttons or keyboard ← →.
  • Fullscreen: Toggle with F.
  • Toggle Details: Toggle the right info panel with I.
  • Thumbnails: Jump quickly using the thumbnail strip at the bottom.
  • Undo: Ctrl + Z (Cmd + Z on macOS) undoes the most recent deletion (move to trash) or shortcut-based tag operation.

Information Panel

In the right-side panel, you can view/edit:

  • Metadata: Image size, file format, created time.
  • Generation Info: Checkpoint, Seed, Steps, CFG Scale, Sampler name, etc.
  • Prompts: Positive and Negative prompts (copyable).
  • Tags: Attached tags (add/remove via edit icon).
  • Notes: Free-form user notes.
  • Lineage: A tree showing the parent image (source) and derived child images.

Image Menu Actions

From the image menu or right-click:

  • Add Unified Loader: Analyze generation settings and automatically add either a Meld Unified Loader or Meld Unified Flux Loader.
  • Send to Workflow: Send the image to a Load Image or Meld Image Loader node in the current workflow.
    • Send to Workflow (Mask): Send the image and mask to the current workflow for inpainting.
  • Queue Workflow: Execute a workflow using the image as input.
    • Queue Workflow (Mask): Open the mask editor and run an inpaint workflow.
  • Restore Full Workflow: Load embedded workflow information and overwrite/restore the entire current canvas.
  • Edit Tags: Edit tags.
  • Edit Notes: Edit notes.
  • Edit Source Image: Manually set/change the parent image (Source).
  • Delete: Move the image to Trash.

Notes on Setting Parent Image (Source)

When you manually set a parent image, candidates are usually shown in these two categories (depending on settings, you may see only one):

  • Source Matches (from metadata): Candidates inferred from metadata (workflow, etc.) (when Source Matching Strategy is filename_phash).
  • Visual Matches (pHash): Candidates based on image similarity (pHash).

You can also Drag & Drop an image file into the dialog's drop zone to upload it and set it as the parent immediately.

Mask Editor

A lightweight mask creation tool is built in to speed up inpaint tasks. Launch it from the menu.

  • Tools:
    • Rect / Ellipse: Select mask areas using rectangles/ellipses.
    • Lasso: Draw freehand to create a mask region.
  • Actions:
    • Queue: Run the workflow immediately using the created mask.
    • Send: Send the created mask to the current workflow (usable as a mask output for Load Image, etc.).
    • Undo: Undo actions with Ctrl + Z.

Appendix: Shortcut Keys

Main shortcuts available in the viewer (only Custom Shortcuts (0-9) are configurable in settings).

Action Default Key
Next image →
Previous image ←
Toggle details I
Toggle fullscreen F
Close Esc
Delete / Trash Delete
Undo (undo deletion / tag shortcuts) Ctrl + Z / Cmd + Z

Custom Shortcuts (0-9)

In the shortcut settings, you can assign your own commands to 0-9. Multiple commands can be chained by separating them with spaces.

  • Tag operations: tag:NAME / -tag:NAME / tag-toggle:NAME
  • Navigation: next / prev
  • Delete: delete

Examples:

  • tag:favorite next (add favorite then go next)
  • tag-toggle:best_quality (toggle a tag)

3. Search (Search)

Use the search bar at the top of the gallery to quickly find the image you want from a large collection.

Keyword Search

Typing words in the search bar performs full-text search across prompts, filenames, notes, tags, and more. If you enter multiple words separated by spaces, images containing all words are shown (AND search).

Filtering Syntax

You can narrow results using the following syntax:

Syntax Description Example
tag: Search by tag tag:landscape tag:best_quality
model: Search by model name model:sdxl model:v1-5
id: Search by exact database ID id:123
filename: Search by filename (exact or partial match) filename:image.png filename:img
date: Search by date date:2024-01-01 (day), date:2024-01 (month)
resolution: Search by resolution resolution:1024x1024
after: Search after a date after:2024-01-01
before: Search before a date before:2024-01-01
pos: Search Positive prompt only pos:cat
neg: Search Negative prompt only neg:blurry
note: Search in user notes note:experiment
has_source: Filter by whether a parent exists has_source:yes (has), has_source:no (none)
has_derivatives: Filter by whether children exist has_derivatives:yes (has)
sort: Specify sort order sort:created_at_asc (oldest), sort:created_at_desc (newest)

Advanced Search Techniques

  • Exclude (NOT): Prefix a term with - or ! to exclude it.
    • Example: -tag:failed (does not have tag)
    • Example: !model:sdxl (model does not include sdxl)
  • Phrase search: Use double quotes " for tags/prompts containing spaces.
    • Example: pos:"blue sky"
  • Autocomplete: When you type prefixes like tag: or model:, a candidate list appears for faster input.

Favorites

Save frequently used queries by clicking the ★ icon on the right of the search bar. Saved queries can be recalled with one click from the ★ menu in the header.

4. Tag Manager

Click the Tag icon in the header to open Tag Manager.

  • Create new tags
  • Rename tags (updates tags on all associated images)
  • Delete unnecessary tags
  • Search images by tag

5. Import (Import)

Click the "Import (download icon)" button in the header to import images from outside ComfyUI or older generations into Image Manager.

Basic Usage

  1. Select Base Location (Output, Input, or Custom Path).
  2. Select/navigate to the target folder.
  3. Click Start Import to begin scanning.

Advanced Import Settings

  • Custom Path: Scan any absolute path on the server. This allows managing images on another drive as well.
  • Recursive Scan: Scan subfolders recursively.
  • Source Linking: Configure whether to auto-infer parent-child relationships (Lineage) during import.
    • New only: Infer for newly imported images only (recommended).
    • All: Re-evaluate including existing images (can take time).
  • Tags to Add: Bulk-attach the specified tags to all imported images. Useful when you want to tag by folder.

Progress, Cancel, and Cleanup

During import (scan), progress is shown and you can cancel depending on the situation. Also, even if images deleted from disk remain in the DB, they are automatically cleaned up in the background after the extension loads (no manual action needed).

  • Progress: Proceeds as Scanning... (registration) → Linking... (parent/child inference), updating current / total and the progress bar.
  • Cancel: Click the stop button (■) during scanning to request cancellation (the UI becomes Cancelling..., and the process stops safely).
  • Automatic cleanup: After the extension loads, it removes DB entries for images whose files no longer exist after a short delay. If you delete/move files with external tools and the UI becomes inconsistent, reloading the page (or restarting) may resolve it.

6. Settings

Open settings from the Gear icon in the header.

System Settings (System)

Important backend settings.

  • Image Matching: Configure the logic for Lineage inference.
    • Source Matching Strategy: Select the algorithm used to find a parent image (default: pHash & Created Time).
    • Auto Linking Threshold: Similarity threshold (%) for auto-linking. Higher values reduce false links but can fail to link on small edits.
    • Inherit Tags from Source: When ON, tags from the parent image are automatically copied to child images.
  • Lineage:
    • Max Lineage Depth: How many generations to show in the tree. Reduce if performance is slow.
  • Database: From Settings -> System, you can create, rename, switch, and delete the database used by Meld.
    • Create Database: Create a new empty database. A confirmation modal is shown before creation, including a note that settings are stored per database.
    • Rename Database: Rename an existing database. After confirmation, the DB file name and database-specific runtime directory are renamed together. Because the contents stay the same, this does not trigger the soft reset used during database switching.
    • Switch Database: Switch to another database. The confirmation modal warns that Light Table contents are cleared, search suggestions and caches are reinitialized, current selection/viewer/open modal state is reset, and database-specific settings may change.
    • Delete Database: Permanently delete a database. Deletion requires both a confirmation modal and typing delete. If you delete the currently active database, Meld automatically switches to another database or recreates an empty default.db if needed.
    • Busy guard: Database switching and deletion are blocked while an import scan or analytics refresh is running.
  • Thumbnail Cache: Thumbnails are cached on disk for faster display.
    • Clear Thumbnail Cache: Delete all cached thumbnails. They will be regenerated on next view.
  • Trash: When viewing Trash, you can Restore images or Delete Permanently.
    • Trash Retention Days: How many days after moving to Trash an image can be permanently deleted. In the current implementation, 0 does not mean "never auto-delete"; it may become eligible for deletion during cleanup runs (a true "disable auto delete" option is not implemented yet).

Thumbnail API: Gallery, viewer, and lineage use the /api/meld/view-thumb endpoint for thumbnails. Query parameters: filename, subfolder, type (output/input/temp/custom/trash), and size (max edge in pixels, default 200, max 400). Cached thumbnails are isolated per database and stored under data/runtime/<database_name>/thumbnails/ (WebP format).

Gallery / View Settings

  • Gallery: Tune thumbnail size and the number of images loaded per batch for performance.
  • View: Set the number of thumbnails shown in the viewer and the maximum number of prompt lines.
  • FullScreen: Configure fullscreen behavior.
    • Delete Mode: Configure delete confirmation and whether to delete including Lineage.
    • Details Panel: Toggle details shown in fullscreen (filename, size, created time, model, prompt, etc.) individually.
  • Shortcuts: Customize keyboard shortcuts used in Image Manager.

7. Light Table

A temporary image pool feature displayed at the bottom of the screen. Used for temporarily keeping and comparing images by dragging and dropping them from the gallery.

  • Tab Management: Create multiple tabs to categorize and keep your images.
  • Clear All: Clear all images from all tabs at once.
  • Close: You can close the Light Table by clicking the close button (X) on the top right.

Q&A / Tips

Q: Images do not appear in the gallery. A: Image Manager auto-registers Output images when a workflow finishes (executed event) (Meld must be loaded). If images do not appear, check the following:

  • Is the extension loaded?: Ensure the Meld tab appears in the sidebar. If not, reload the page.
  • Is the target an Output image?: Preview Image (temp), Input, or images copied from outside ComfyUI are not auto-registered. Import them via "5. Import" or use Save Image-type nodes.
  • Feature differences: Some features such as Restore Full Workflow and Add Unified Loader require embedded metadata (workflow info, etc.). Depending on how an image was saved and whether metadata exists, restoration-related features may be limited even if the image itself is shown.

Q: Lineage is not shown correctly. A: Parent-child relationships are auto-inferred based on image similarity (pHash) and workflow information. If an image is heavily modified or metadata is missing, it may not link. You can adjust Auto Linking Threshold in settings or manually set the parent image from the viewer menu.

Q: Can I restore deleted images? A: Yes. Switch the view to "Trash" to see deleted images, select one, and press "Restore". Images past the retention period (based on settings) or images deleted with "Delete Permanently" cannot be restored.

Reference in New Issue View Git Blame Copy Permalink