Document LCS Color Anchor node in both READMEs
Add feature entry, quick start guide, node table row, detailed parameter/mode descriptions, and "How It Works" section for the Color Anchor node. Also update the file structure listing with new core and node files. Both EN and ZH versions in plain language.
This commit is contained in:
facok
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user