ExtractKeyColors 主题色抽取与主导色板聚类分析节点

节点核心功能 (What is it?)

ExtractKeyColors 节点通过运行聚类分析算法（K-Means 均值聚类）或中位切分量化算法（MMCQ Median Cut），对输入图像的色彩直方图实施多维聚类，智能提炼出画面中占据统治地位的代表性核心主题色（Dominant Colors）。它能够按照像素频次自动由高到低排序，并动态生成专属的颜色选择器引脚插槽（color_1、color_2...），为自动化色板构建、品牌 VI 色彩识别与动态主题换肤提供算法支撑。

典型适用场景 (When would I use it?)

在以下情况下使用该节点：

从设计稿或摄影作品中一键提取视觉调色板（Color Palette）；
分析品牌 Logo、UI 界面或海报的主题色与辅色构成；
提取画面主导色作为网页、海报或宣传单的动态背景衬底；
基于图像色相为后续的色彩滤镜与发光光晕算子动态注入基准色；
为可视化工程提取量化色彩统计数据。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

在工作流画布中添加 ExtractKeyColors 节点。
将图像数据源接入 input_image 输入插槽。
拖动 num_colors 滑块设定所需抽取的主题色总数（2–12 色）。
选择色彩抽取算法模型（kmeans 或 median_cut）。
节点会自动动态展开并输出对应数量的十六进制颜色引脚（color_1 至 color_n）。

参数输入插槽 (Parameters)

图像源输入 (Image Input)

input_image：待提取色板的源图像工件（接受 JPG、PNG、WEBP 等主流格式）。

提取与聚类设置 (Color Settings)

num_colors（2–12，默认 3）：要提取的核心主题色数量。
- 颜色严格按照其在画面中的像素出现频次降序排列；
- 每个提取出的颜色都会独立映射为一个专用输出引脚。
algorithm：底层的色彩聚类量化算法：
- kmeans（默认）：基于 K-Means 均值聚类算法，根据人眼感知色彩相似度进行聚合，聚类精度极高；
- median_cut：基于改进型中位切分量化算法（MMCQ），在色彩空间中递归切分色块空间，兼顾色彩多样性与高计算速度。

输出引脚 (Outputs)

系统根据 num_colors 设定的数量动态创建对应引脚：

color_1, color_2, ...：标准十六进制色彩代码（格式为 #RRGGBB）。
- 每个输出项在前端属性面板中均内嵌可视化交互式调色盘；
- color_1 对应画面中物理占比最大的主导色，后续按支配地位依次递减。

典型工作流示例 (Example)

提取摄影作品前 5 大主题色并驱动海报背景：

使用 LoadImage 导入一张风景摄影图。
将其接入 ExtractKeyColors 节点的 input_image 参数。
将 num_colors 设为 5。
节点瞬间输出 5 个颜色值：
- color_1（最高频背景主色）；
- color_2（次高频主体基色）；
- color_3 至 color_5（微观高光与强调色）。
将 color_1 接入 ExtendCanvas 节点的 background_color 作为无缝背景填充色，使整体构图浑然天成。

关键技术特性 (Important Notes)

动态响应式插槽 (Dynamic Parameters)：节点根据设定的数量实时增删引脚，面板绝不堆砌无用参数。
色彩多样性保护：K-Means 与 MMCQ 均内置了色彩距离惩罚，杜绝提取出多个肉眼几乎完全相同的重复色。
像素级频次统计：各颜色不仅仅带有 RGB 值，底层均记录了真实的像素占比与直方图权重。

算法横向比对 (Algorithm Comparison)

K-Means 均值聚类：
- 基于色彩感官几何距离精确聚类，过渡色彩与复杂渐变提取效果卓越；
- 适合追求高精美学配色的设计类工作流；
Median Cut (MMCQ) 中位切分：
- 在 RGB 色彩立方体中沿极差最大维度贪婪切分，极好地保护了微弱但视觉强烈的冷暖强调色；
- 计算耗时极短，非常适合处理超大分辨率的原画素材。