diff --git a/README.md b/README.md index 9675da1..d47f0aa 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ LCS calibrates per-VAE, so it should work with any model using a compatible VAE. - **Color Steering** — Push colors toward any target color - **Batch Multi-Color** — Different colors per batch item - **Tone Adjustment** — Contrast, brightness, saturation, temperature with one-click presets +- **Color Anchor** — Zero-config color drift correction: self-anchor, reference-based, or spatial smoothing with auto mode - **Sharpness Control** — Sharpen or blur during generation via a discovered sharpness subspace (PC1 explains ~97% variance) - **Localized Control** — Optional mask for region-specific changes - **Latent Color Preview** — Visualize color structure without VAE decoding @@ -111,6 +112,28 @@ LCS Load Data → LCS Color Batch → KSampler Enter comma-separated hex colors (e.g., `#FF0000,#00FF00,#0000FF`). Each color applies to one batch item. +### Color Anchor (Zero-Config Drift Correction) + +``` +LCS Load Data → LCS Color Anchor → KSampler +``` + +1. **LCS Load Data** → **LCS Color Anchor** — connect MODEL and LCS_DATA +2. Set mode to **auto** (default) and leave intensity at default +3. Connect the output MODEL to KSampler + +That's it. In `auto` mode, the node automatically selects the correction strategy based on which optional inputs are connected: + +| Connected Inputs | Resolved Mode | Behavior | +|---|---|---| +| Nothing | self_anchor | Learns the image's color patterns early on, then prevents sudden color shifts | +| reference_image + vae | reference | Keeps generated colors close to your reference image | +| mask (no reference) | smooth | Smooths out color seams (great for inpainting) | + +Intensity is also derived automatically from measured drift — no manual tuning needed. + +> **When to use manual mode:** If you want full control, set mode to `smooth`, `reference`, or `self_anchor` explicitly and adjust the `intensity` slider (0–1). Auto mode is designed for zero-config "just works" usage. + ## Nodes ### Calibration @@ -129,6 +152,7 @@ Calibration runs once per VAE and caches automatically. Subsequent runs load ins | **LCS Color Intervene** | Steer colors toward a target. Supports Type I (LCS shift), Type II (HSL shift), or interpolated mode. | | **LCS Color Batch** | Different target colors per batch item. Outputs `batch_size` for EmptyLatentImage. | | **LCS Tone Adjust** | Contrast, brightness, saturation, temperature. Preset dropdown with real-time slider sync. | +| **LCS Color Anchor** | Correct color drift during sampling. Auto mode infers strategy and intensity from connected inputs. | | **LCS Sharpness Intervene** | Control sharpness during generation. Positive = sharper, negative = blurrier. | ### Observation @@ -160,6 +184,45 @@ Calibration runs once per VAE and caches automatically. Subsequent runs load ins > **Tip for distilled models**: Step-distilled models (e.g., z-image-turbo) use far fewer steps, so intervention should start earlier — even from step 0. +### Color Anchor + +Sometimes diffusion models produce unexpected color shifts during sampling — a blue sky suddenly turns purple, or inpainting leaves visible color seams. The Color Anchor node fixes these problems by monitoring and correcting colors as the image is being generated. + +**Modes:** + +| Mode | What it does | When to use | +|------|-------------|----------| +| **auto** (default) | Looks at what you connected and picks the best strategy for you | Just want it to work, no config needed | +| **self_anchor** | Watches how colors evolve in early steps, then prevents sudden color jumps in later steps | General color stability, no reference needed | +| **reference** | Keeps the generated image's colors close to a reference image you provide | "Make it look like this photo's color palette" | +| **smooth** | Smooths out abrupt color boundaries between regions | Fixing visible seams after inpainting | + +**How auto mode picks for you:** + +1. **Which strategy?** Based on what you plugged in: + - Connected a reference image + VAE → uses `reference` + - Connected a mask (but no reference) → uses `smooth` + - Connected nothing extra → uses `self_anchor` +2. **How strong?** The node measures how much color drift is actually happening, then sets the correction strength accordingly. Big drift → stronger fix. Small drift → gentle touch. The range is 0.15–0.6, so it never over-corrects or does nothing. + +**What happens during sampling:** + +The node runs at every sampling step but doesn't always intervene. It automatically figures out which steps are safe to correct: + +1. **Early steps** (image is mostly noise) — Too early to fix colors without creating artifacts. Skipped. In self_anchor mode, the node uses these steps to *learn* the image's color patterns. +2. **Middle steps** (image is taking shape) — The sweet spot. The node applies corrections here, ramping smoothly in and out to avoid sudden changes. +3. **Late steps** (fine details) — Corrections would disturb fine detail. Skipped. + +Only colors are modified — structure, texture, and detail are never touched. + +**Parameters:** + +- **mode**: `auto`, `smooth`, `reference`, or `self_anchor` +- **intensity** (0.0–1.0): How strong the correction is. In `auto` mode this is determined automatically. Set to 0 to disable the node entirely. +- **vae** (optional): Needed for `reference` mode to encode the reference image +- **reference_image** (optional): The image whose colors you want to match +- **mask** (optional): Only correct colors inside the masked area + ## Tone Presets Select a preset — sliders update in real-time. Tweak after selecting for fine-tuning. Select **Custom** to set values manually. @@ -196,6 +259,16 @@ Sharpness lives in a separate subspace orthogonal to color: 1. **Calibrate** — Generate grayscale noise images at multiple blur levels, VAE-encode, PCA on color-removed patch vectors. PC1 captures ~97% of sharpness variance. 2. **Intervene** — Add `strength * pc1_direction` to each patch. Since pc1_direction is orthogonal to color (calibrated with LCS removal) and DC-free (per-vector zero-mean before PCA), this modifies only spatial frequency content without affecting color or brightness. +### Color Anchor + +The Color Anchor stabilizes colors without pushing them toward a specific target — it prevents drift from what the model is already generating: + +1. **Decide when to act** — The node checks each sampling step: is the image still mostly noise (too early), taking shape (good time to correct), or nearly finished (too late)? It only corrects during the safe middle window. +2. **Learn the color pattern** (self_anchor) — During early noisy steps, the node watches how colors relate to their neighbors and builds a running average of these relationships. This is more reliable than tracking absolute colors, which shift naturally as the image forms. +3. **Measure drift** — On the first correction step, the node measures how much the colors have actually drifted (varies by mode: step-to-step jumps, distance from reference, or spatial roughness). This sets the correction strength in auto mode. +4. **Apply gentle corrections** — Corrections ramp smoothly in and out (no sudden jumps). Each mode corrects differently: self_anchor fixes patches that deviate from learned patterns, reference pulls toward the reference image's colors, smooth blurs out sharp color boundaries. +5. **Preserve everything else** — As with all LCS operations, only the 3D color coordinates change. Structure, texture, and detail are untouched. + ## File Structure ``` @@ -203,15 +276,19 @@ ComfyUI-LCS/ ├── __init__.py # Entry point (V3 + V2 compat) ├── requirements.txt ├── core/ +│ ├── adaptive.py # Adaptive scheduling (phases, envelopes, drift estimation) +│ ├── bilateral.py # Bilateral filter for LCS color smoothing │ ├── calibration.py # PCA calibration pipeline (color) │ ├── color_space.py # Bicone LCS ↔ HSL mapping │ ├── defaults.py # Alpha/beta tables from paper │ ├── lcs_data.py # LCSData dataclass │ ├── patchify.py # Patch ↔ latent conversion +│ ├── relationships.py # Local color relationship analysis & anomaly detection │ ├── sampling.py # Shared constants & step utilities │ ├── sharpness.py # Sharpness subspace calibration │ └── timestep.py # Sigma/timestep utilities ├── nodes/ +│ ├── anchor.py # LCSColorAnchor (adaptive color drift correction) │ ├── calibrate.py # LCSLoadData (auto-calibrate + cache) │ ├── intervene.py # LCSColorIntervene, LCSColorBatch, LCSToneAdjust │ ├── observe.py # LCSPreviewColors, LCSStepObserver diff --git a/README_zh.md b/README_zh.md index de04833..10c89c9 100644 --- a/README_zh.md +++ b/README_zh.md @@ -43,6 +43,7 @@ LCS 按 VAE 校准,理论上适用于任何使用兼容 VAE 架构的模型。 - **颜色引导** — 将颜色推向任意目标色 - **批量多色** — 为批次中每张图像指定不同颜色 - **色调调整** — 对比度、亮度、饱和度、色温,支持一键预设 +- **颜色锚定** — 零配置颜色漂移校正:自锚定、参考图锚定、空间平滑,支持全自动模式 - **锐度控制** — 在生成过程中增强或减弱锐度,基于发现的锐度子空间(PC1 解释 ~97% 方差) - **局部控制** — 可选遮罩,实现区域性变化 - **潜在颜色预览** — 无需 VAE 解码即可可视化颜色结构 @@ -110,6 +111,28 @@ LCS Load Data → LCS Color Batch → KSampler 输入逗号分隔的十六进制颜色(如 `#FF0000,#00FF00,#0000FF`),每个颜色对应一个批次项。 +### 颜色锚定(零配置漂移校正) + +``` +LCS Load Data → LCS Color Anchor → KSampler +``` + +1. **LCS Load Data** → **LCS Color Anchor** — 连接 MODEL 和 LCS_DATA +2. 模式设为 **auto**(默认),intensity 保持默认值 +3. 将输出 MODEL 连接到 KSampler + +完成。在 `auto` 模式下,节点根据连接的可选输入自动选择校正策略: + +| 已连接输入 | 解析模式 | 行为 | +|---|---|---| +| 无 | self_anchor | 在早期学习图像的颜色规律,然后防止突然的颜色偏移 | +| reference_image + vae | reference | 让生成的颜色贴近你的参考图 | +| mask(无参考图) | smooth | 平滑颜色接缝(很适合修复/补绘) | + +intensity 也会根据实测漂移自动推导——无需手动调参。 + +> **手动模式:** 如果需要完全控制,可以将模式设为 `smooth`、`reference` 或 `self_anchor`,并手动调节 `intensity` 滑条(0–1)。auto 模式适合零配置「开箱即用」场景。 + ## 节点一览 ### 校准 @@ -128,6 +151,7 @@ LCS Load Data → LCS Color Batch → KSampler | **LCS Color Intervene** | 将颜色引导至目标色。支持 Type I(LCS 平移)、Type II(HSL 偏移)或插值模式。 | | **LCS Color Batch** | 每个批次项施加不同目标颜色。输出 `batch_size` 可连接 EmptyLatentImage。 | | **LCS Tone Adjust** | 对比度、亮度、饱和度、色温调整。预设下拉菜单,滑条实时同步。 | +| **LCS Color Anchor** | 采样过程中校正颜色漂移。auto 模式根据连接输入自动推断策略和强度。 | | **LCS Sharpness Intervene** | 在生成过程中控制锐度。正值 = 更锐利,负值 = 更模糊。 | ### 观察 @@ -159,6 +183,45 @@ LCS Load Data → LCS Color Batch → KSampler > **步数蒸馏模型提示**:对于步数蒸馏模型(如 z-image-turbo),总步数很少,干预应从更早的步骤开始——甚至可以从第 0 步就开始干预。 +### 颜色锚定 + +扩散模型在采样过程中有时会出现意想不到的颜色偏移——蓝天突然变紫,或者修复/补绘后留下明显的颜色接缝。颜色锚定节点在图像生成过程中监控和修正这些问题。 + +**模式:** + +| 模式 | 功能 | 适用场景 | +|------|------|----------| +| **auto**(默认) | 根据你连接的输入自动选最合适的策略 | 不想调参,开箱即用 | +| **self_anchor** | 在早期步骤观察颜色变化规律,在后续步骤防止突然的颜色跳变 | 通用颜色稳定,不需要参考图 | +| **reference** | 让生成图像的颜色贴近你提供的参考图 | 「我想要这张照片的配色风格」 | +| **smooth** | 平滑区域之间的突兀颜色边界 | 修复/补绘后消除接缝 | + +**auto 模式如何自动选择:** + +1. **用哪种策略?** 看你连了什么: + - 连了参考图 + VAE → 用 `reference` + - 连了遮罩(没有参考图)→ 用 `smooth` + - 什么额外输入都没连 → 用 `self_anchor` +2. **修正多强?** 节点会测量实际的颜色漂移幅度,据此自动设置校正强度。漂移大 → 修正更强;漂移小 → 轻轻一碰。范围是 0.15–0.6,既不会矫枉过正,也不会毫无作用。 + +**采样过程中发生了什么:** + +节点在每个采样步都会运行,但不会每步都干预。它自动判断哪些步骤适合校正: + +1. **早期步骤**(图像基本是噪声)— 太早修正颜色会产生伪影,跳过。在 self_anchor 模式下,节点利用这些步骤*学习*图像的颜色规律。 +2. **中间步骤**(图像逐渐成形)— 最佳校正时机。节点在这里施加校正,平滑地渐入渐出,避免突变。 +3. **后期步骤**(精细细节)— 校正会干扰细节,跳过。 + +只修改颜色——结构、纹理、细节始终不受影响。 + +**参数:** + +- **mode**:`auto`、`smooth`、`reference` 或 `self_anchor` +- **intensity**(0.0–1.0):校正强度。auto 模式下自动决定。设为 0 可完全禁用此节点。 +- **vae**(可选):reference 模式需要用它来编码参考图 +- **reference_image**(可选):你想匹配其颜色的参考图 +- **mask**(可选):只在遮罩区域内校正颜色 + ## 色调预设 选择预设后滑条实时更新。可在预设基础上微调。选择 **Custom** 可完全手动设置。 @@ -195,6 +258,16 @@ LCS Load Data → LCS Color Batch → KSampler 1. **校准** — 生成灰度噪声图像,应用多级高斯模糊,VAE 编码后对去除颜色分量的 patch 向量做 PCA。PC1 捕获 ~97% 的锐度方差。 2. **干预** — 在每个 patch 上沿 `strength * pc1_direction` 方向添加偏移。由于 pc1_direction 与颜色正交(校准时已移除 LCS 分量)且无直流分量(PCA 前做了逐向量零均值化),因此只改变空间频率内容,不影响颜色或亮度。 +### 颜色锚定 + +颜色锚定的作用是稳定颜色,而不是把颜色推向某个特定目标——它防止模型已经在生成的颜色发生偏移: + +1. **判断何时介入** — 节点检查每个采样步:图像还是一片噪声(太早)、正在成形(适合校正)、还是快完成了(太晚)?只在安全的中间窗口进行校正。 +2. **学习颜色规律**(self_anchor)— 在早期噪声较大的步骤中,节点观察每个区域的颜色与邻居之间的关系,建立一个动态平均值。比起追踪绝对颜色值,这种「相对关系」更可靠,因为绝对颜色在图像成形过程中本来就会自然变化。 +3. **测量漂移** — 在第一个校正步,节点测量颜色实际漂移了多少(根据模式不同:步间跳变幅度、与参考图的差距、或空间粗糙程度)。这决定了 auto 模式下的校正强度。 +4. **温和地修正** — 校正平滑地渐入渐出(不会突变)。每种模式的修正方式不同:self_anchor 修复偏离已学规律的区域,reference 拉近与参考图的颜色,smooth 模糊掉尖锐的颜色边界。 +5. **保留其他一切** — 与所有 LCS 操作一样,只修改 3D 颜色坐标,结构、纹理、细节完全不受影响。 + ## 文件结构 ``` @@ -202,15 +275,19 @@ ComfyUI-LCS/ ├── __init__.py # 入口(V3 + V2 兼容) ├── requirements.txt ├── core/ +│ ├── adaptive.py # 自适应调度(阶段、包络、漂移估计) +│ ├── bilateral.py # LCS 颜色平滑的双边滤波 │ ├── calibration.py # PCA 校准流程(颜色) │ ├── color_space.py # 双锥 LCS ↔ HSL 映射 │ ├── defaults.py # 论文中的 Alpha/beta 表 │ ├── lcs_data.py # LCSData 数据类 │ ├── patchify.py # Patch ↔ 潜在空间转换 +│ ├── relationships.py # 局部颜色关系分析与异常检测 │ ├── sampling.py # 共享常量和步骤工具 │ ├── sharpness.py # 锐度子空间校准 │ └── timestep.py # Sigma/时间步工具 ├── nodes/ +│ ├── anchor.py # LCSColorAnchor(自适应颜色漂移校正) │ ├── calibrate.py # LCSLoadData(自动校准 + 缓存) │ ├── intervene.py # LCSColorIntervene, LCSColorBatch, LCSToneAdjust │ ├── observe.py # LCSPreviewColors, LCSStepObserver