Extensions/LLS-node
ComfyUI Extension

LLS-node

Custom nodes package organized by functional domains with namespace support for image upscaling, utilities, image repair, inpainting, and professional editing workflows. (Description by CC)

By Gin3601·Created 3 months ago·Updated 3 months ago· 0
Gin3601/LLS-node
Nodes—
On cloudLocal install
Stars0
Updated3 months ago
Readme

LLS ComfyUI Custom Nodes

按 ComfyUI 功能域封装的自定义节点插件包。所有节点统一使用 LLS/ 命名空间， 顶层 __init__.py 自动扫描并汇总各子包的注册表，ComfyUI 只需识别一个插件入口。

安装方法

  1. 将整个 node/ 目录复制到 ComfyUI/custom_nodes/，并重命名为 LLS_Nodes/
  2. 重启 ComfyUI
  3. 在节点搜索框中搜索 LLS 即可看到所有已实现节点
ComfyUI/
└── custom_nodes/
    └── LLS_Nodes/        ← 将本目录内容放在这里
        ├── __init__.py
        ├── nodes.py
        ├── upscale/
        ├── utils/
        └── ...

目录结构

node/
├── __init__.py           ← 插件入口：自动汇总所有子包的 NODE_CLASS_MAPPINGS
├── nodes.py              ← 共享工具函数（不含节点类）
│
├── model_loader/         ← 第 1 节：模型加载与管理
├── conditioning/         ← 第 2 节：文本编码与条件生成
├── sampling/             ← 第 3 节：图像采样与去噪
├── latent/               ← 第 4 节：Latent 空间操作
├── image/                ← 第 5 节：图像处理与后处理
├── upscale/              ← 第 5 节（超分子域）：图像超分辨率放大
├── mask/                 ← 第 6 节：遮罩操作
├── controlnet/           ← 第 7 节：ControlNet / 控制引导
├── lora/                 ← 第 8 节：LoRA / Hypernetwork / Adapter
├── video/                ← 第 10 节：视频生成与帧处理
├── audio/                ← 第 11 节：音频处理
└── utils/                ← 第 14 节：数据类型与逻辑工具

已实现节点

LLS/Upscale

| 节点名 | 说明 | |--------|------| | LLS Upscale Switcher | 在 upscale_model 与 PyTorch 插值之间切换的超分节点 |

输入参数：

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | image | IMAGE | — | 输入图像 | | mode | 选项 | upscale_model | upscale_model（模型超分）或 pytorch（插值放大） | | scale | FLOAT | 2.0 | 放大倍数（仅 pytorch 模式生效） | | interpolation | 选项 | bilinear | 插值算法（仅 pytorch 模式生效） | | model_name | 选项 | — | 超分模型名（从 models/upscale_models/ 读取） | | tile | INT | 512 | 分块大小，越小显存越省（仅 upscale_model 模式生效） | | overlap | INT | 32 | 分块重叠像素（仅 upscale_model 模式生效） |

输出： IMAGE

LLS/Utils

| 节点名 | 说明 | |--------|------| | LLS String Literal | 输出一个字符串常量，可复用于多个下游节点 | | LLS Int Literal | 输出一个整数常量 | | LLS Float Literal | 输出一个浮点数常量 | | LLS Resolution Selector | 从常用分辨率预设中选择，或输入自定义宽高，返回 width 和 height |

Image Repair

LLS-node 现在提供一套面向本地工作流的修复链路，由以下节点组成：

  • LLS Simple Mask Create
  • LLS Simple Mask Draw
  • LLS Save Image
  • LLS Simple Repair Prepare
  • LLS Simple KSampler
  • LLS Simple Repair Finish

修复工作流不是从 LLS Simple Empty Latent 开始，而是从 image + mask + vae 开始。LLS Simple Repair Prepare 会把这些输入转换为带有 repair_info 的修复态 latent，再交给同一个 LLS Simple KSampler 继续采样。

LLS Simple Mask Create

LLS Simple Mask Create 是一个基础几何遮罩生成节点。它不依赖原图内容，只根据输出尺寸和几何参数直接创建 rectangle、square、circle、ellipse 四种基础 mask。

它适合放在修复准备前或手工绘制前：

  • LLS Simple Mask Create.mask_image -> Preview Image
  • LLS Simple Mask Create.mask -> LLS Save Image.mask
  • Load Image.image + LLS Simple Mask Create.mask -> LLS Simple Repair Prepare
  • LLS Simple Mask Create.mask -> LLS Simple Mask Draw.input_mask

推荐连接方式：

  • LLS Simple Mask Create.mask_image -> Preview Image
  • Load Image.image -> LLS Save Image.image
  • LLS Simple Mask Create.mask -> LLS Save Image.mask
  • Load Image.image -> LLS Simple Repair Prepare.image
  • LLS Simple Mask Create.mask -> LLS Simple Repair Prepare.mask
  • LLS Simple Mask Create.mask -> LLS Simple Mask Draw.input_mask
  • Load Image.image -> LLS Simple Mask Draw.image

输入：

| 名称 | 类型 | 说明 | |------|------|------| | image_width | INT | 必填，输出遮罩宽度 | | image_height | INT | 必填，输出遮罩高度 | | input_mask | MASK | 可选，已有遮罩；可与当前几何 mask 做 replace / union / subtract / intersect |

核心参数：

| 参数 | 说明 | |------|------| | shape_type | rectangle / square / circle / ellipse | | coordinate_mode | pixel / percent | | center_x, center_y | 中心点坐标；percent 模式下范围通常为 0.0 ~ 1.0 | | width, height | rectangle / square / ellipse 使用 | | radius | circle 使用 | | feather | 边缘羽化 | | blur | 整体边缘模糊 | | invert_mask | 反转最终 mask | | combine_mode | replace / union / subtract / intersect |

输出：

| 名称 | 类型 | 说明 | |------|------|------| | mask_image | IMAGE | 将 mask 直接可视化为黑白图像，方便单独预览 | | mask | MASK | 最终遮罩，白色 / 1 表示要重绘，黑色 / 0 表示不重绘 | | area_info | LLS_MASK_INFO | 包含面积、占比、bbox、坐标模式等信息的 dict |

area_info 主要包含：

  • image_size
  • shape_type
  • coordinate_mode
  • center
  • width
  • height
  • radius
  • bbox
  • geometric_area_px
  • binary_area_px
  • effective_area_px
  • area_ratio
  • feather
  • blur
  • invert_mask
  • combine_mode
  • clipped_by_image

默认行为：

  • shape_type = rectangle
  • coordinate_mode = percent
  • center_x = 0.5
  • center_y = 0.5
  • image_width = 1024
  • image_height = 1024
  • width = 0.3
  • height = 0.3
  • radius = 0.15
  • combine_mode = replace

这会在图像中心创建一个大约占宽高 30% 的矩形 mask。

示例：

  • 中心矩形：shape_type=rectangle, coordinate_mode=percent, center_x=0.5, center_y=0.5, width=0.3, height=0.3
  • 中心圆形：shape_type=circle, coordinate_mode=percent, center_x=0.5, center_y=0.5, radius=0.15
  • 左上角方形：shape_type=square, coordinate_mode=percent, center_x=0.2, center_y=0.2, width=0.2
  • 与已有 mask 合并：连接 input_mask 并将 combine_mode 设为 union

典型用途：

  • 快速创建规则删除区域
  • 快速创建规则修复区域
  • 先创建基础几何区域，再交给 LLS Simple Mask Draw 手动修边
  • 为 LLS Simple Repair Prepare 提供稳定的初始局部重绘 mask

LLS Save Image

LLS Save Image 现在支持独立保存或预览 image 和 mask。image、mask 两个端口都不是必填，但至少要连接其中一个。连上哪个端口，就输出哪个结果；两个都连时，就同时输出两份结果。

推荐工作流：

  • Load Image.image -> LLS Save Image.image
  • LLS Simple Mask Create.mask -> LLS Save Image.mask
  • LLS Simple Mask Draw.mask -> LLS Save Image.mask
  • LLS Simple Mask Create.mask_image -> Preview Image

行为说明：

  • 只连接 image：只保存或预览原图
  • 只连接 mask：只保存或预览黑白 mask
  • 同时连接 image + mask：两者都输出，mask 在保存模式下使用 <filename_prefix>_mask
  • image 与 mask 各自独立输出，互不影响

LLS Simple Image Composite

LLS Simple Image Composite 用于把一张前景图叠加到背景图上，并输出最终合成图像。背景图尺寸始终作为最终输出尺寸，前景图支持平移、缩放、旋转和透明度控制。

输入：

| 名称 | 类型 | 说明 | |------|------|------| | background_image | IMAGE | 背景图 | | overlay_image | IMAGE | 前景图 | | x_offset | INT | 前景图水平偏移 | | y_offset | INT | 前景图垂直偏移 | | anchor_mode | top_left / center | 前景图定位方式 | | rotation_origin_mode | top_left / center | 前景图旋转原点 | | opacity | FLOAT | 前景图透明度 | | scale | FLOAT | 前景图缩放倍率 | | rotation | FLOAT | 前景图旋转角度 | | blend_mode | normal | 当前只支持 normal | | keep_aspect | BOOLEAN | 当前保持等比缩放 |

输出：

| 名称 | 类型 | 说明 | |------|------|------| | output_image | IMAGE | 合成后的最终图像 |

典型用途：

  • Load Image(background) + Load Image(overlay) -> LLS Simple Image Composite -> Preview Image
  • 把 logo、贴纸或局部元素叠加到背景图的指定位置
  • 通过 x_offset、y_offset、scale、rotation 快速摆位

说明：

  • 前景图超出背景范围时会自动裁剪
  • 如果前景图带 alpha 通道，会优先按 alpha 合成
  • 节点内实时预览优先支持 Load Image / Load Image Output 作为上游文件来源
  • anchor_mode 与 rotation_origin_mode 相互独立，可以分别控制定位参考点和旋转参考点

LLS Simple Mask Draw

LLS Simple Mask Draw 是一个面向局部重绘的交互式遮罩输入节点，用来直接在输入图像上手动画 mask，并把结果输出给后续修复链路。

推荐工作流：

  • Load Image -> LLS Simple Mask Draw -> Preview Image
  • Load Image -> LLS Simple Mask Draw -> LLS Simple Repair Prepare
  • Load Image -> LLS Simple Mask Create -> LLS Simple Mask Draw
  • Load Image -> LLS Simple Mask Create -> LLS Simple Mask Draw -> LLS Simple Repair Prepare

推荐连接方式：

  • Load Image.image -> LLS Simple Mask Draw.image
  • LLS Simple Mask Draw.image -> LLS Simple Repair Prepare.image
  • LLS Simple Mask Draw.mask -> LLS Simple Repair Prepare.mask
  • LLS Simple Mask Draw.mask -> LLS Save Image.mask

输入：

| 名称 | 类型 | 说明 | |------|------|------| | image | IMAGE | 必填，原图输入 | | input_mask | MASK | 可选，已有遮罩；节点会在这个遮罩基础上继续编辑 |

输出：

| 名称 | 类型 | 说明 | |------|------|------| | image | IMAGE | 原图透传 | | mask | MASK | 最终遮罩，白色 / 1 表示要重绘，黑色 / 0 表示不重绘 | | preview_image | IMAGE | 原图与半透明红色遮罩叠加后的预览图 |

当前支持的交互功能：

  • 直接在图像上绘制白色遮罩
  • brush / erase 两种模式
  • 调整 brush_size
  • 调整 brush_softness
  • 调整 overlay_alpha
  • 预览半透明红色遮罩叠加
  • Clear
  • Undo
  • Redo
  • Invert
  • 在已有 input_mask 基础上继续补画或擦除

如何手动画 mask：

  1. 连接 Load Image 到 LLS Simple Mask Draw.image
  2. 如果有已有遮罩，可再连接到 input_mask
  3. 在节点预览区域直接涂抹需要修复的区域
  4. 用 erase 擦除不需要重绘的部分
  5. 用 Clear / Undo / Redo / Invert 调整最终结果
  6. 将 mask 输出接到 LLS Simple Repair Prepare.mask

典型用途：

  • 手动指定删除区域
  • 手动指定修复区域
  • 手动指定去阴影区域
  • 手动指定局部增强区域

当前版本限制：

  • 第一版只支持 brush 和 erase
  • 还没有实现 polygon、rectangle、ellipse
  • 还没有实现魔棒、自动分割、智能抠图
  • 如果需要规则几何初始化区域，请先使用 LLS Simple Mask Create

Minimal Repair Workflow

Load Image -> Load Mask -> LLS Simple Checkpoint Loader -> LLS Simple Prompt Encode -> LLS Simple Repair Prepare -> LLS Simple KSampler -> VAE Decode -> LLS Simple Repair Finish -> Preview Image

Minimal Manual Mask Workflow

Load Image -> LLS Simple Mask Draw -> LLS Simple Repair Prepare -> LLS Simple KSampler -> VAE Decode -> LLS Simple Repair Finish -> Preview Image

repair_scope

  • region：在原图边界内直接修复
  • crop：围绕 mask 裁剪局部工作区，提高局部细节修复精度
  • canvas：扩展画布后修复新增区域或缺失区域

repair_kernel

  • latent_mask：对工作图做 VAE encode，并附带 latent noise mask
  • vae_inpaint：使用兼容 VAE inpaint 的 latent 准备方式
  • native_fill：当后端原生支持 fill/inpaint 时优先请求原生能力，否则回退并发出 warning

denoise_mode

  • manual：直接使用 sampler 上的 denoise
  • auto_from_repair：使用 repair_info["recommended_denoise"]

Compatibility

  • 未连接 repair_info 时，现有 txt2img 工作流保持不变。
  • 未连接 repair_info 时，现有 img2img 工作流保持不变。
  • 同一个 LLS Simple KSampler 同时处理 txt2img、img2img 和 repair。

Pro Image Edit / Inpaint

LLS-node 也提供一套更严格的专业局部编辑链路，针对真正支持原生 image edit / inpaint 语义的模型：

  • LLS Pro Image Edit Prepare
  • LLS Pro KSampler Bridge
  • LLS Pro Image Edit Finish

Simple vs Pro

  • Simple = lightweight masked latent resampling
  • Pro = true image edit / inpaint pipeline

当模型本身具备真实的局部编辑能力，而且你更在意遮罩区域内的提示词跟随和原生 inpaint / image-edit 行为时，用 Pro 链；如果你只是需要兼容性更高、约束更少的局部重绘流程，继续使用 Simple 链。

Professional Workflow

Load Image -> Load Mask or LLS Simple Mask Draw -> LLS Simple Checkpoint Loader -> LLS Simple Prompt Encode -> LLS Pro Image Edit Prepare -> LLS Pro KSampler Bridge -> VAE Decode -> LLS Pro Image Edit Finish -> Preview Image

Backend Selection

  • backend_mode = auto | sdxl | flux
  • auto 现在使用 profile-driven routing：先解析模型 profile，再决定是走原生编辑路径还是 fallback 局部重绘路径
  • 原生 edit/inpaint profile 走 native path；base/generation profile 不再直接报错，而是进入 fallback local repaint
  • sdxl 和 flux 会按家族强制指定后端，但仍然会验证当前模型是否兼容

Profile-Driven Routing

LLS Simple Checkpoint Loader writes the resolved model profile into runtime metadata.

  • LLS Pro Image Edit Prepare routes by backend_type
  • LLS Pro KSampler Bridge routes by sampler_strategy
  • execution_path records whether this run used native_edit or fallback_repair

重要 profile 字段：

  • profile_id
  • backend_type
  • sampler_strategy

示例：

  • sdxl_inpaint -> backend_type = sdxl_native
  • flux_edit -> backend_type = flux_edit

Base profile 不会再模糊地进入 Pro 链：

  • SDXL / FLUX / SD1.5 base profile 仍然保持官方 base profile
  • base profiles automatically fall back to a generic local repaint path
  • 原生 edit/inpaint 模型才会走 native path

Compatibility Metadata

  • model_role
  • supports_inpaint_native
  • supports_image_edit_native
  • preferred_edit_backend

这些字段可以来自：

  • model_info
  • LLS Simple Checkpoint Loader 写入到对象上的 _lls_* 元信息
  • utils/model_info.py 里的 family / name 推断逻辑
  • profile resolver 对旧 capability tags 的兼容升级

Adding new professional edit models

  1. 在 model_profiles/ 里补充或修正 profile rule
  2. 确认 LLS Simple Checkpoint Loader 会把正确的 _lls_* profile tags 写到 model / clip / vae
  3. 优先用 backend_mode=auto 验证 resolved profile 是否足以自动识别
  4. 调试阶段可通过 model_info 显式覆盖 profile_id / backend_type / sampler_strategy

Notes

  • LLSSimple* 修复链保持不变，不会被这套新链覆盖
  • LLS Pro Image Edit Finish 负责真实的区域混合、裁剪回贴和扩图 canvas 合成
  • LLS Pro KSampler Bridge 支持 denoise_mode = manual | auto_from_edit

扩展节点

在对应子包的 nodes.py 中添加节点类并注册到 NODE_CLASS_MAPPINGS，重启 ComfyUI 自动生效。

# 示例：在 sampling/nodes.py 中添加节点
class LLSKSampler:
    CATEGORY = "LLS/Sampling"
    FUNCTION = "sample"
    RETURN_TYPES = ("LATENT",)

    @classmethod
    def INPUT_TYPES(cls):
        return { "required": { ... } }

    def sample(self, ...):
        return (latent,)

NODE_CLASS_MAPPINGS = { "LLSKSampler": LLSKSampler }
NODE_DISPLAY_NAME_MAPPINGS = { "LLSKSampler": "LLS KSampler" }

新增功能域只需新建子目录 + __init__.py，并将目录名追加到顶层 __init__.py 的 _SUBPACKAGES 列表。

语法检查

python -m py_compile __init__.py nodes.py upscale/nodes.py utils/nodes.py

节点命名规范

| 范围 | 格式 | 示例 | |------|------|------| | CATEGORY（UI 分组） | LLS/<域名> | LLS/Sampling | | 类名 | LLS + PascalCase | LLSKSampler | | 显示名称（搜索） | LLS + 描述 | LLS KSampler | | 注册 Key | 与类名相同 | "LLSKSampler" |