Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
__init__.py
__init__.py
 
 
advanced_loader.py
advanced_loader.py
 
 
dual_loader.py
dual_loader.py
 
 
image_combiner.py
image_combiner.py
 
 

Repository files navigation

ComfyUI Multi-Folder Match Loader Suite

多文件夹文件名匹配加载器套件 - 提供基础版和高级版两种强大的文件夹匹配工具

📖 功能简介

这是一套 ComfyUI 的自定义节点，提供两个版本的文件夹匹配加载器和一个图片拼接辅助工具，用于解决传统加载器无法处理"文件名相同但后缀不同"或"文件列表顺序不一致"导致的配对错误问题。

🔹 基础版 (Dual Folder Match Loader)

简单易用的双文件夹匹配加载器

核心特性:

  • ✅ 严格文件名匹配: 根据文件名（不含扩展名）进行精确匹配
  • ✅ 自动尺寸统一: 将两张图片的长边统一到较小的那个尺寸
  • ✨ 三种自动模式: manual（手动）/ sequential（顺序递增）/ loop（循环递增）
  • ✅ 批量处理支持: 配合 Primitive Node (Increment) 或使用 auto_mode 实现自动批处理
  • ✅ 稳定顺序保证: 自动排序确保每次运行顺序一致
  • ✅ 强制刷新机制: 避免缓存，确保批量处理正确执行
  • ✅ 异常容错处理: 文件夹不存在或无匹配时返回空白图，不会导致工作流崩溃

🔸 高级版 (Advanced Multi-Folder Match Loader)

功能强大的多文件夹匹配加载器

高级特性:

  • 🚀 多文件夹支持: 同时匹配 2-5 个文件夹（原图+mask+depth+normal等）
  • ✨ 三种自动模式: manual（手动）/ sequential（顺序递增）/ loop（循环递增）
  • 🎯 智能过滤器: 文件名通配符过滤 + 分辨率范围过滤
  • 🎨 7种尺寸模式: 长边/短边对齐、固定尺寸、中心裁剪等
  • 📊 批量导出: 导出完整匹配列表为 JSON 文件
  • 🎲 随机打乱: 支持可复现的随机顺序（固定种子）
  • 📍 范围批处理: 只处理指定索引范围的文件
  • 📈 详细输出: 提供当前匹配信息、文件路径等元数据

🔧 辅助工具 (Image Combiner)

图片拼接辅助节点

拼接特性:

  • 🔀 双向拼接: 支持水平（左右）或垂直（上下）拼接
  • 📏 自动居中: 尺寸不同时自动居中对齐
  • 🎨 可调间隙: 支持添加间隙（黑色/白色/灰色）
  • 👁️ 对比查看: 完美配合加载器节点，方便对比查看匹配结果

📦 安装方法

方式 1: 手动安装（推荐）

  1. 将整个 filename 文件夹重命名为 ComfyUI_Multi_Folder_Loader
  2. 复制到你的 ComfyUI 安装目录下的 custom_nodes 文件夹中 
    ComfyUI/
  └── custom_nodes/
      └── ComfyUI_Multi_Folder_Loader/    <-- 放到这里
          ├── __init__.py
          ├── dual_loader.py
          ├── advanced_loader.py
          └── README.md
  3. 重启 ComfyUI

方式 2: Git 克隆

cd ComfyUI/custom_nodes/
git clone https://github.com/Jiqize/ComfyUI-Multi-Folder-Loader.git
# 重启 ComfyUI

🎯 使用方法

📘 基础版使用说明

节点信息

  • 节点名称: Dual Folder Match Loader
  • 分类: Custom/Batching
  • 在节点列表中搜索: Dual Folder 或 Match Loader

输入参数 (基础版)

参数名 类型 说明
folder_path_A STRING 文件夹 A 的绝对路径
folder_path_B STRING 文件夹 B 的绝对路径
batch_index INT 批次索引 (0-99999)，manual 模式下使用
auto_mode CHOICE 自动模式选择：
• manual: 手动模式（默认）- 使用 batch_index
• sequential: 顺序模式 - 自动递增，不循环
• loop: 循环模式 - 自动递增并循环

输出参数 (基础版)

输出名 类型 说明
image_A IMAGE 来自文件夹 A 的图片 Tensor
image_B IMAGE 来自文件夹 B 的图片 Tensor
filename_stem STRING 匹配的文件名（不含扩展名）
total_matches INT 找到的匹配文件对总数

💡 使用示例

场景 1: 基础使用

假设你有两个文件夹：

/path/to/folder_A/
  ├── image_01.png
  ├── image_02.jpg
  └── image_03.png

/path/to/folder_B/
  ├── image_01.webp
  ├── image_02.png
  └── image_04.jpg

匹配结果:

  • image_01 ✅ (A: .png, B: .webp)
  • image_02 ✅ (A: .jpg, B: .png)
  • image_03 ❌ (只在 A 中存在)
  • image_04 ❌ (只在 B 中存在)

total_matches 输出: 2

场景 2: 批量自动处理工作流

方式 1: 使用 Auto Mode（推荐，更简单）

  1. 添加 Dual Folder Match Loader 节点
  2. 设置 folder_path_A 和 folder_path_B
  3. 设置 auto_mode 为 sequential 或 loop
    • sequential: 顺序递增（0→1→2→...→停在最后一张）
    • loop: 循环递增（0→1→2→...→total-1→0→1→...）
  4. 配置你的处理流程（如图生图、放大等）
  5. 使用 filename_stem 输出来保存处理后的文件，保持命名一致

工作流示例（Auto Mode）:

       Dual Folder Match Loader (auto_mode=sequential)
              /           \
         image_A        image_B
             |              |
             v              v
        [你的处理节点...]
             |
             v
       Save Image (使用 filename_stem 作为文件名)

每次运行时，节点会自动递增索引，无需额外的 Primitive Node。

方式 2: 使用 Primitive Node（传统方式）

  1. 添加 Dual Folder Match Loader 节点
  2. 设置 folder_path_A 和 folder_path_B
  3. 保持 auto_mode 为 manual（默认）
  4. 添加 Primitive Node (设置为 INT 类型，Increment 模式)
  5. 将 Primitive Node 连接到 batch_index 输入
  6. 配置你的处理流程（如图生图、放大等）
  7. 使用 filename_stem 输出来保存处理后的文件，保持命名一致

工作流示例（Manual Mode）:

Primitive (Increment) -> batch_index
                            |
                            v
                 Dual Folder Match Loader (auto_mode=manual)
                      /           \
                 image_A        image_B
                     |              |
                     v              v
                [你的处理节点...]
                     |
                     v
               Save Image (使用 filename_stem 作为文件名)

每次运行时，Primitive Node 会自动递增索引，遍历所有匹配的图片对。

⚙️ 技术细节

支持的图片格式

  • PNG (.png)
  • JPEG (.jpg, .jpeg)
  • WebP (.webp)
  • BMP (.bmp)
  • TIFF (.tiff)
  • GIF (.gif)

图片尺寸处理逻辑

当两张图片尺寸不一致时：

  1. 计算两张图片的长边（max(宽度, 高度)）
  2. 选择较小的长边作为目标尺寸
  3. 使用高质量重采样（LANCZOS）等比例缩放图片
  4. 确保两张图片可以正常配对使用

示例:

  • 图片 A: 2048x1536 (长边 2048)
  • 图片 B: 1920x1080 (长边 1920)
  • 目标长边: 1920
  • 图片 A 缩放到: 1920x1440

强制刷新机制

节点实现了 IS_CHANGED 方法返回 float("NaN")，确保 ComfyUI 不会缓存结果，每次执行都重新加载图片。这对批量处理至关重要。

🔧 常见问题

Q: 为什么我的图片没有匹配上？

A: 请确保：

  1. 两个文件夹中的文件名（不含扩展名）完全一致
  2. 文件名是大小写敏感的（Image_01 和 image_01 是不同的）
  3. 图片文件的扩展名在支持列表中

Q: 如何查看匹配的图片对数量？

A: 使用 total_matches 输出，它会告诉你找到了多少对匹配的文件。

Q: batch_index 超出范围会怎样?

A: 节点使用取模运算防止越界，例如 batch_index=10 且只有 5 对匹配时，会自动使用索引 0（10 % 5 = 0）。

Q: 遇到错误会崩溃吗？

A: 不会。所有异常情况（文件夹不存在、无匹配、加载失败等）都会返回 512x512 的黑色空白图，确保工作流继续运行。

📝 开发信息

  • 版本: 2.1.0
  • 作者: Claude AI
  • 许可: MIT License
  • 依赖:
    • Python 3.x
    • torch
    • numpy
    • Pillow (PIL)

💡 使用技巧

基础版 vs 高级版选择指南

使用基础版的场景:

  • ✅ 只需要匹配 2 个文件夹
  • ✅ 不需要过滤功能
  • ✅ 默认的长边对齐模式已满足需求
  • ✅ 追求简单易用

使用高级版的场景:

  • ✅ 需要同时匹配 3-5 个文件夹（如 albedo + normal + roughness + AO）
  • ✅ 需要按文件名模式或分辨率过滤
  • ✅ 需要不同的尺寸处理策略
  • ✅ 需要导出匹配列表进行分析
  • ✅ 需要随机顺序或范围处理
  • ✅ 追求最大灵活性

性能优化建议

  1. 分辨率过滤: 如果文件夹中有大量图片，使用 min_resolution 和 max_resolution 可以提前过滤，避免加载不需要的文件

  2. 导出一次即可: 匹配列表导出功能主要用于分析和调试，不需要每次运行都导出

  3. 合理使用范围: 如果只需要处理部分文件，使用 start_index 和 end_index 可以节省时间

🤝 贡献与反馈

如果遇到问题或有改进建议，欢迎提交 Issue 或 Pull Request！

📄 更新日志

v2.1.0 (2025-12-23)

  • 🎉 新增图片拼接辅助节点 (Image Combiner)
  • 🔀 支持水平/垂直两种拼接方向
  • 📏 图片尺寸不同时自动居中对齐
  • 🎨 可调间隙大小和颜色（黑/白/灰）
  • 👁️ 完美配合加载器节点进行对比查看

v2.0.0 (2025-12-23)

  • 🎉 新增 Advanced 版本节点
  • 🚀 支持 2-5 个文件夹同时匹配
  • 🎯 智能过滤器（文件名通配符 + 分辨率范围）
  • 🎨 7 种灵活的尺寸处理模式
  • 📊 批量导出匹配列表（JSON 格式）
  • 🎲 随机打乱支持（可复现）
  • 📍 范围批处理功能
  • 📈 增强的输出信息

v1.0.0 (2025-12-23)

  • ✨ 初始版本发布
  • ✅ 实现文件名匹配功能
  • ✅ 实现自动尺寸统一
  • ✅ 实现批量处理支持
  • ✅ 添加完整的中文注释

📚 高级版详细使用指南

📙 Advanced Multi-Folder Match Loader

节点信息

  • 节点名称: Advanced Multi-Folder Match Loader
  • 分类: Custom/Batching
  • 在节点列表中搜索: Advanced 或 Multi-Folder

输入参数 (高级版)

必填参数:

参数名 类型 默认值 说明
folder_1 STRING "" 文件夹 1 路径（必填）
folder_2 STRING "" 文件夹 2 路径（必填）
batch_index INT 0 批次索引 (0-99999)，manual 模式下使用
resize_mode DROPDOWN align_to_smallest_long 尺寸处理模式（7种可选）
filename_pattern STRING * 文件名通配符过滤
min_resolution INT 0 最小分辨率（长边，0=不限制）
max_resolution INT 0 最大分辨率（长边，0=不限制）
shuffle BOOLEAN False 是否随机打乱顺序
seed INT 0 随机种子（shuffle=True时有效）
start_index INT 0 起始索引
end_index INT -1 结束索引（-1=到末尾）
auto_mode CHOICE manual 自动模式：manual（手动）/ sequential（顺序递增）/ loop（循环递增）

可选参数:

参数名 类型 默认值 说明
folder_3 STRING "" 文件夹 3 路径（可选）
folder_4 STRING "" 文件夹 4 路径（可选）
folder_5 STRING "" 文件夹 5 路径（可选）
target_size INT 512 fixed_size 模式的目标尺寸
export_match_list BOOLEAN False 是否导出匹配列表
export_path STRING "" 导出文件路径（JSON）

尺寸处理模式详解

模式 说明 适用场景
none 保持原始尺寸 所有图片尺寸已经一致
align_to_smallest_long 长边对齐到最小值（默认） 通用场景，避免放大
align_to_largest_long 长边对齐到最大值 需要统一到最高分辨率
align_to_smallest_short 短边对齐到最小值 特殊比例需求
align_to_largest_short 短边对齐到最大值 特殊比例需求
fixed_size 统一到指定尺寸（正方形） 需要固定输出尺寸
crop_center 裁剪中心区域到最小尺寸 保持原始质量，不缩放

输出参数 (高级版)

输出名 类型 说明
image_1 ~ image_5 IMAGE 5个文件夹的图片（未使用的为黑图）
filename_stem STRING 匹配的文件名（不含扩展名）
total_matches INT 找到的匹配文件总数
current_index INT 当前实际使用的索引
matched_list STRING 当前匹配信息（JSON格式）
file_paths STRING 完整文件路径列表（JSON格式）

🌟 高级使用示例

示例 1: 三通道材质处理

假设你有三个文件夹存放材质贴图：

/materials/albedo/
  ├── brick_001.png
  ├── wood_002.jpg
  └── metal_003.png

/materials/normal/
  ├── brick_001_normal.png
  ├── wood_002_normal.png
  └── metal_003_normal.jpg

/materials/roughness/
  ├── brick_001.tiff
  ├── wood_002.webp
  └── metal_003.png

节点配置:

  • folder_1: /materials/albedo/
  • folder_2: /materials/normal/
  • folder_3: /materials/roughness/
  • filename_pattern: * (全部匹配)
  • resize_mode: align_to_smallest_long

匹配结果: 3 对文件（brick_001, wood_002, metal_003）

示例 2: 智能过滤特定文件

只处理文件名以 render_ 开头且分辨率在 1024-2048 之间的图片：

节点配置:

  • filename_pattern: render_*
  • min_resolution: 1024
  • max_resolution: 2048

示例 3: 批量导出匹配信息

导出所有匹配的文件信息到 JSON：

节点配置:

  • export_match_list: True
  • export_path: /output/matches.json

导出文件内容示例:

{
  "total_matches": 100,
  "filters_applied": {
    "filename_pattern": "*_final",
    "min_resolution": 512,
    "max_resolution": 0,
    "shuffle": false,
    "start_index": 0,
    "end_index": -1
  },
  "folders": {
    "folder_1": "/path/to/folder1",
    "folder_2": "/path/to/folder2"
  },
  "matches": [
    {
      "index": 0,
      "stem": "image_001_final",
      "files": {
        "folder_1": "image_001_final.png",
        "folder_2": "image_001_final.jpg"
      },
      "resolutions": {
        "folder_1": [1920, 1080],
        "folder_2": [1920, 1080]
      }
    }
  ]
}

示例 4: 随机训练数据集

使用固定种子随机打乱数据集顺序：

节点配置:

  • shuffle: True
  • seed: 42
  • 每次运行使用相同种子会得到相同的随机顺序

示例 5: 只处理部分范围

只处理第 10-50 个匹配对：

节点配置:

  • start_index: 10
  • end_index: 50
  • total_matches 输出将显示实际可用的数量（最多 41 个）

🔍 文件名通配符语法

模式 匹配规则 示例
* 匹配任意字符 * 匹配所有文件
? 匹配单个字符 image_? 匹配 image_1, image_a 等
[abc] 匹配括号内任一字符 file_[123] 匹配 file_1, file_2, file_3
*_suffix 以某后缀结尾 *_color 匹配 brick_color, wood_color 等
prefix_* 以某前缀开头 render_* 匹配 render_001, render_final 等
*_??_* 复杂模式 image_??_final 匹配 image_01_final 等

🔧 图片拼接节点使用指南

📐 Image Combiner (Match Loader)

节点信息

  • 节点名称: Image Combiner (Match Loader)
  • 分类: Custom/Batching
  • 在节点列表中搜索: Image Combiner 或 Combiner

输入参数

参数名 类型 默认值 说明
image_1 IMAGE - 第一张图片
image_2 IMAGE - 第二张图片
direction DROPDOWN horizontal 拼接方向（horizontal/vertical）
gap INT 0 图片间隙（像素，0-100）
gap_color DROPDOWN black 间隙颜色（black/white/gray）

输出参数

输出名 类型 说明
combined_image IMAGE 拼接后的图片

拼接方向说明

horizontal (水平拼接):

  • 图片左右排列
  • 高度取两张图片的最大值
  • 较小的图片垂直居中对齐

示例：

┌─────────┐  ┌─────────┐
│         │  │         │
│ Image 1 │  │ Image 2 │
│         │  │         │
└─────────┘  └─────────┘
    ↓            ↓
┌─────────────────────┐
│ Image 1 │ Image 2   │
└─────────────────────┘

vertical (垂直拼接):

  • 图片上下排列
  • 宽度取两张图片的最大值
  • 较小的图片水平居中对齐

示例：

┌─────────┐
│ Image 1 │
└─────────┘
┌─────────┐
│ Image 2 │
└─────────┘

使用示例

示例 1: 对比查看匹配结果

工作流连接：

Dual Folder Match Loader
    ↓ (image_A, image_B)
Image Combiner
    - image_1: image_A
    - image_2: image_B
    - direction: horizontal
    - gap: 10
    - gap_color: white
    ↓ (combined_image)
Preview Image / Save Image

示例 2: 垂直对比不同处理结果

Advanced Multi-Folder Match Loader
    ↓ (image_1: 原图, image_2: 处理后)
Image Combiner
    - direction: vertical
    - gap: 5
    - gap_color: gray
    ↓
对比查看处理前后效果

示例 3: 批量生成对比图

配合批量处理工作流：

Primitive (Increment) → batch_index
    ↓
Dual Folder Match Loader
    ↓ (image_A, image_B, filename_stem)
Image Combiner
    ↓ (combined_image)
Save Image
    - filename_prefix: filename_stem
    → 自动保存所有对比图

特性说明

  1. 自动居中对齐

    • 当两张图片尺寸不同时，较小的图片会在较大的画布上居中显示
    • 空白区域使用 gap_color 填充

  2. 灵活的间隙设置

    • gap=0: 图片紧密拼接，无间隙
    • gap>0: 图片之间添加指定像素的间隙
    • 间隙颜色可选：黑色（默认）、白色、灰色

  3. 批量处理友好

    • 完美配合 Match Loader 节点的批量处理模式
    • 可以一次性生成所有配对的对比图

About

🚀 ComfyUI custom nodes for matching and loading images from multiple folders by filename. Supports batch processing, smart filtering, and multiple resize modes. 多文件夹文件名匹配加载器套件

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages