# ComfyUI-LCS

基于**潜在颜色子空间**（Latent Color Subspace）的免训练颜色控制。

> **注意：** 本项目为非官方社区实现。官方代码见 [ExplainableML/LCS](https://github.com/ExplainableML/LCS)。

基于论文 ["The Latent Color Subspace"](https://arxiv.org/abs/2603.12261v1)（ICML 2026）：扩散模型潜在 patch 空间中的颜色完全存在于一个 **3 维子空间**（PCA 捕获 100% 颜色方差），剩余 61 维编码结构与细节，与颜色正交。

本插件在扩散采样过程中直接操作 3D LCS 控制颜色——无需训练、无需 LoRA、无需后处理。

> [English README](README.md)

## LCS 与传统后处理调色的区别

LCS 在扩散采样**过程中**操作，而非生成之后——这是与传统调色（Photoshop、滤镜等）的根本区别。

| | 传统后处理 | LCS |
|---|---|---|
| **时机** | VAE 解码后，像素空间 | 采样过程中，潜在空间 |
| **机制** | 对成品图像施加颜色滤镜 | 在生成中途修改 3D 颜色子空间 |
| **模型感知** | 无——结构已定型 | 模型在后续步骤中自适应颜色偏移 |
| **效果** | 颜色容易显得"涂上去的" | 颜色与内容自然融合 |

例：想要暖橙色日落，后处理会给全图叠橙色（阴影和肤色变脏），而 LCS 在采样早期推动颜色子空间，模型生成的云层、光照、反射与暖色调**内在一致**。

核心发现：颜色与结构在潜在 patch 空间中**正交**——可以单独控制颜色而不干扰结构。

## 已测试模型

| 模型 | 状态 |
|------|------|
| FLUX | 已测试 |
| z-image | 已测试 |
| z-image-turbo | 已测试 |

LCS 按 VAE 校准，理论上适用于任何使用兼容 VAE 架构的模型。欢迎反馈其他模型的测试结果。

## 功能

- **颜色引导** — 将颜色推向任意目标色
- **批量多色** — 为批次中每张图像指定不同颜色
- **色调调整** — 对比度、亮度、饱和度、色温，支持一键预设
- **局部控制** — 可选遮罩，实现区域性颜色变化
- **潜在颜色预览** — 无需 VAE 解码即可可视化颜色结构
- **步骤观察器** — 保存每步颜色预览，用于调试

## 安装

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/facok/ComfyUI-LCS.git
```

依赖（通常 ComfyUI 已自带）：

```bash
pip install einops safetensors
```

## 快速开始

### 基本颜色控制

```
LCS Load Data → LCS Color Intervene → KSampler
                       ↑
                  （选择颜色）
```

1. **LCS Load Data** — 连接 VAE（首次运行自动校准）
2. **LCS Color Intervene** — 连接 MODEL 和 LCS_DATA，选择目标颜色
3. 将输出 MODEL 连接到 KSampler

### 色调调整

```
LCS Load Data → LCS Tone Adjust → KSampler
```

1. **LCS Load Data** → **LCS Tone Adjust**
2. 选择预设（如 "Cinematic"）或手动调整滑条

![3d3c82eb0e89ed1608e40ac7a8cc3408](https://github.com/user-attachments/assets/62868e2d-0275-4801-a9bd-606bfea3ce2f)

### 批量多色生成

```
LCS Load Data → LCS Color Batch → KSampler
                      ↓
                  batch_size → EmptyLatentImage
```

输入逗号分隔的十六进制颜色（如 `#FF0000,#00FF00,#0000FF`），每个颜色对应一个批次项。

## 节点一览

### 校准

| 节点 | 说明 |
|------|------|
| **LCS Load Data** | 自动校准并按 VAE 缓存 LCS 数据。通过 VAE 权重指纹自动管理缓存——连接 VAE 即可。 |

每个 VAE 只需校准一次，结果自动缓存，后续运行瞬时加载。

### 干预

| 节点 | 说明 |
|------|------|
| **LCS Color Intervene** | 将颜色引导至目标色。支持 Type I（LCS 平移）、Type II（HSL 偏移）或插值模式。 |
| **LCS Color Batch** | 每个批次项施加不同目标颜色。输出 `batch_size` 可连接 EmptyLatentImage。 |
| **LCS Tone Adjust** | 对比度、亮度、饱和度、色温调整。预设下拉菜单，滑条实时同步。 |

### 观察

| 节点 | 说明 |
|------|------|
| **LCS Preview Colors** | 将潜在颜色解码为 RGB 预览图，无需 VAE 解码。 |
| **LCS Step Observer** | 将每步颜色预览 PNG 保存至 ComfyUI 临时目录。 |

## 干预模式

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **interpolated**（默认） | 以 sigma 为权重混合 Type I 和 Type II | 通用场景 |
| **type_i** | 3D LCS 空间中的直接平移 | 强烈的全局颜色偏移 |
| **type_ii** | 通过双锥几何进行逐 patch HSL 插值 | 精确的局部颜色控制 |

## 关键参数

- **strength**（0.0–2.0）：干预强度。1.0 = 完整干预，0.0 = 无干预。
- **start_step / end_step**：干预步骤范围。论文最优：50 步中的第 8–10 步。
- **mask**：可选。下采样至 patch 网格分辨率，用于局部控制。

## 色调预设

选择预设后滑条实时更新。可在预设基础上微调。选择 **Custom** 可完全手动设置。

| 预设 | 对比度 | 亮度 | 饱和度 | 色温 |
|------|--------|------|--------|------|
| Base | 1.0 | 0.0 | 1.0 | 0.0 |
| Cinematic | 1.20 | -0.05 | 0.90 | 0.05 |
| HDR | 1.40 | 0.0 | 1.20 | 0.0 |
| Vivid | 1.10 | 0.0 | 1.50 | 0.0 |
| Dramatic | 1.50 | -0.10 | 0.85 | 0.0 |
| Low Key | 1.30 | -0.20 | 0.80 | 0.0 |
| High Key | 0.80 | 0.20 | 0.90 | 0.0 |
| Warm | 1.05 | 0.03 | 1.10 | 0.30 |
| Cool | 1.05 | 0.0 | 1.05 | -0.30 |
| Desaturated | 1.0 | 0.0 | 0.40 | 0.0 |

## 工作原理

1. **投影** — 将去噪预测转换到 64D patch 空间，投影到 3D LCS 基底
2. **分解** — 将 3D 颜色坐标与 61D 结构残差分离
3. **归一化** — 使用学习的 alpha/beta 统计量变换至参考时间步（t=50）
4. **操作** — 在 3D LCS 中偏移颜色、调整色调或进行其他变换
5. **重建** — 反归一化，加回保留的 61D 残差，转换回潜在空间

61D 残差（结构、纹理、细节）始终不被修改——只有 3D 颜色子空间会被改变。

## 文件结构

```
ComfyUI-LCS/
├── __init__.py           # 入口（V3 + V2 兼容）
├── requirements.txt
├── core/
│   ├── calibration.py    # PCA 校准流程
│   ├── color_space.py    # 双锥 LCS ↔ HSL 映射
│   ├── defaults.py       # 论文中的 Alpha/beta 表
│   ├── lcs_data.py       # LCSData 数据类
│   ├── patchify.py       # Patch ↔ 潜在空间转换
│   └── timestep.py       # Sigma/时间步工具
├── nodes/
│   ├── calibrate.py      # LCSLoadData（自动校准 + 缓存）
│   ├── intervene.py      # LCSColorIntervene, LCSColorBatch, LCSToneAdjust
│   └── observe.py        # LCSPreviewColors, LCSStepObserver
├── data/                 # 缓存的校准文件
└── web/js/
    └── tone_preset.js    # 前端预设同步
```

## 引用

官方仓库：[ExplainableML/LCS](https://github.com/ExplainableML/LCS)

```bibtex
@article{pach2026latentcolorsubspace,
  title={The Latent Color Subspace: Emergent Order in High-Dimensional Chaos},
  author={Mateusz Pach and Jessica Bader and Quentin Bouniot and Serge Belongie and Zeynep Akata},
  journal={arxiv},
  year={2026}
}
```

## 致谢

感谢 Mateusz Pach、Jessica Bader、Quentin Bouniot、Serge Belongie 和 Zeynep Akata，他们的研究使免训练颜色控制成为可能。

## 许可证

MIT