# 🧬 Smart Asset Clustering User Manual

**SmartGallery DAM for ComfyUI**

The official user manual for organizing, comparing and auditing your ComfyUI generation library.

---

## 1. What is Smart Asset Clustering?

When working in ComfyUI, creating artwork is an iterative process. You often generate dozens or hundreds of images and videos while tweaking seeds, refining prompts, adjusting LoRA weights, or testing different checkpoints. Over time, your gallery can become cluttered with similar looking renders spread across multiple folders.

**Smart Asset Clustering** automatically organizes your gallery by analyzing the generation recipe embedded in your media files. Without requiring any manual tagging, it groups your renders into logical clusters based on either their **node architecture** or their **prompt text**.

![Every asset in the gallery grid displays color coded hash badges once clustering data has been indexed.](images/Gallery_Clustering_badge.png)

*Every asset in the gallery grid displays color coded hash badges once clustering data has been indexed.*

---

## 2. The Two Clustering Modes

Smart Asset Clustering offers two primary ways to group your media.

### ⚙️ Architecture Clustering (Workflow Graph)

* **What it does:** Groups all images and videos created using the exact same node connections and pipeline structure.
* **What it ignores:** Random seeds, prompts, step counts, CFG scale and noise settings.
* **When to use it:** When you want to see all outputs generated by a specific ComfyUI workflow template, regardless of the prompt or seed used.

### 💬 Prompt Text Clustering

* **What it does:** Groups all images and videos that share the exact same positive prompt text.
* **What it ignores:** Node graphs, samplers, checkpoints and LoRAs.
* **When to use it:** When you want to compare how different models, checkpoints or LoRAs render the exact same idea or prompt.

---

## 3. Search Scope & Inner Sorting

When configuring a cluster search, you can customize the scope and order.

### Search Scope

* **🌐 Global Scope:** Searches your entire library across all folders and drives. It automatically clears active search filters to ensure every matching asset is discovered.
* **📂 Current Context:** Restricts the search to your currently active folder or virtual collection, allowing you to cluster within a specific project.

### Inner Cluster Sorting

You can control how assets are ordered within each cluster group:

* **📅 Newest First:** Shows the most recently generated renders at the top of each cluster.
* **📅 Oldest First:** Shows the earliest renders at the top of each cluster.
* **⭐ Highest Rated First:** Orders items within each cluster by their DAM star rating score.

![The Smart Asset Clustering dialog: choose a clustering basis, a search scope and an inner sorting order before running the search.](images/clustering_modal.jpg)

*The Smart Asset Clustering dialog: choose a clustering basis, a search scope and an inner sorting order before running the search.*

---

## 4. How to Use Smart Asset Clustering

### Method 1: Using the Keyboard Shortcut (`Shift` + `C`)

1. In the main gallery grid or Lightbox, hover your mouse over any image or video, or highlight it with the keyboard arrows.
2. Press `Shift` + `C` on your keyboard.
3. The Smart Asset Clustering window will open, automatically targeting the selected file.
4. Choose your Clustering Basis (Architecture or Prompt Text) and Scope.
5. Click **🚀 Clusterize**.

### Method 2: From the Tools Menu

1. Click 🛠️ **Tools** in the top navigation bar.
2. Select **🧬 Smart Clustering**.
3. Configure your desired options in the dialog window.
4. Click **🚀 Clusterize**.

---

## 5. Navigating Active Cluster Mode

Once clustering is activated:

* **Active Cluster Banner:** A bright fuchsia banner appears at the top of your gallery indicating that Clustering Mode is active, showing the current basis, scope and total matching assets.
* **Cluster Badges:** Each image thumbnail displays a distinct color coded hash badge, for example 🧬 #A1F3E or 💬 #C89B1. Items sharing the same color badge belong to the same cluster.
* **Exiting Cluster Mode:** Click the red ✕ Exit Cluster Mode button on the top banner, or simply press `ESC` at any time.

![Active Cluster Mode: the fuchsia banner confirms the basis and scope in use, while matching assets share the same architecture badge.](images/Gallery_Clustering_Same_Workflow.png)

*Active Cluster Mode: the fuchsia banner confirms the basis and scope in use, while matching assets share the same architecture badge.*

---

## 6. Deep Inspection with the Cluster Inspector

Clicking on any cluster badge on a thumbnail opens the Cluster Inspector Modal. This window gives you a complete breakdown of the cluster.

![The Architecture Inspector modal, showing matching assets, distinct prompts tested, the full node pipeline, loaded checkpoints and the asset prompt text.](images/architecture_inspector.png)

*The Architecture Inspector modal, showing matching assets, distinct prompts tested, the full node pipeline, loaded checkpoints and the asset prompt text.*

### What You Can See in the Inspector

* **Total Matching Assets:** How many files in your library share this exact workflow or prompt.
* **Distinct Counterparts:** Shows how many unique prompt variations were tested on this workflow, or vice versa.
* **Node Pipeline Sequence:** A visual chain showing the flow of nodes used to generate the asset.
* **Loaded Models & LoRAs:** An itemized list of all checkpoints, LoRAs and models used.
* **One Click Prompt Copy:** View the positive prompt text and copy it to your clipboard with a single click.

The same inspector is also available in a Prompt Text flavor, which surfaces the distinct architecture variants sharing that prompt, and lets you re-run the search from the shared cluster prompt.

![The Prompt Inspector view: matching assets and distinct architecture pipeline variants that share the same prompt text.](images/prompt_inspector.jpg)

*The Prompt Inspector view: matching assets and distinct architecture pipeline variants that share the same prompt text.*

---

## Bonus: The Info Panel Cluster Tab

The Cluster panel can also be pinned inside the asset Info Panel, letting you switch between the Overview and the Architecture & Cluster tab without leaving the current view.

![The Architecture & Cluster tab of the Info Panel, showing asset counts, the node pipeline, loaded models and prompt text side by side.](images/info_panel_cluster.png)

*The Architecture & Cluster tab of the Info Panel, showing asset counts, the node pipeline, loaded models and prompt text side by side.*

---

## 7. Practical Use Cases & Scenarios

### 🎨 Scenario 1: Model & LoRA Comparison Testing

**Goal:** You want to test how five different checkpoints render the prompt "A futuristic cyberpunk street in neon rain".

**How to do it:**
1. Generate renders across your checkpoints using that exact prompt.
2. Select one of the images and press `Shift` + `C`.
3. Choose 💬 Prompt Text as the basis and set scope to 🌐 Global.
4. Click 🚀 Clusterize.

**Result:** SmartGallery gathers all five renders together into a single cluster, letting you compare the artistic output of each checkpoint side by side.

---

### 🎲 Scenario 2: Finding Seed Variations of a Favorite Render

**Goal:** You built an amazing Flux Dev upscale pipeline three weeks ago and generated 30 seed variations, but they are scattered across different folders.

**How to do it:**
1. Open your favorite render in the Lightbox and press `Shift` + `C`.
2. Select ⚙️ Architecture as the basis and set scope to 🌐 Global.
3. Click 🚀 Clusterize.

**Result:** SmartGallery instantly locates all 30 renders across your entire hard drive that used that exact node pipeline, regardless of where the files are stored.

---

### 📂 Scenario 3: Folder Auditing & Cleaning

**Goal:** You want to clean up a project folder and organize your renders by workflow type before sending choices to a client.

**How to do it:**
1. Navigate to your project folder.
2. Open Tools → 🧬 Smart Clustering.
3. Select ⚙️ Architecture and set scope to 📂 Current Context.
4. Set Inner Cluster Sorting to ⭐ Highest Rated First.

**Result:** Renders in your active folder are grouped by workflow structure, with your top rated images displayed at the front of each cluster group.

---

## 8. Keyboard Shortcuts Summary

| Shortcut | Context | Action |
| :--- | :--- | :--- |
| `Shift` + `C` | Gallery Grid / Lightbox | Open Clustering Modal for the active or hovered asset |
| `ESC` | Active Clustering Mode | Instantly exit Clustering Mode and return to normal gallery |
| `ESC` | Modals / Inspector | Close the Cluster Inspector window |
| Click Badge | Grid Card | Open the Cluster Inspector for that specific cluster hash |

---

*SmartGallery DAM: organize your creative pipeline effortlessly.*