FAST 颜色量化核心：深入解析 @microsoft/fast-colors 的 PixelBox.averageColor 代表色

• 前端
• UI组件

PixelBox.averageColor是 FAST 生态中@microsoft/fast-colors颜色量化模块里PixelBox类的核心只读属性，它以ColorRGBA64类型承载一个 RGB 色彩盒子的"代表色"。本文以 PixelBox.averageColor 属性文档 为骨架，结合同目录下 PixelBox 类、Histogram、QuantizeConfig 等 API 文档，完整梳理 averageColor 在"图片 → 直方图 → 颜色盒 → 量化调色板"链路中的位置、生成方式与调参影响。读完后，你将理解 Modified Median Cut 量化算法中代表色的计算逻辑，并能直接上手配置quantize()提取图像主色调。

PixelBox.averageColor：一个颜色盒子的代表色

在 1.x API 参考文档中，该属性的声明极其简洁：

readonly averageColor: ColorRGBA64;

• 所属类：PixelBox，官方描述为"Represents a range of colors in RGB color space"（表示 RGB 色彩空间中的一个颜色范围）。
• 属性修饰符：readonly，即该值在构造时确定、之后不可变，说明它是盒子内容的汇总性快照，而不是可随意改写的状态。
• 返回类型：ColorRGBA64，一个 RGBA 四通道均为 64 位精度的颜色类，通道值域为[0,1]，例如new ColorRGBA64(1, 0, 0, 1)即纯红色。

从类的命名与数据结构推断：averageColor是对当前PixelBox所覆盖的整个颜色范围内像素颜色求平均得到的汇总色。在量化算法的语境里，它就是"这一个色彩盒子最终对外呈现的颜色代表"。量化流程的核心目的，正是把成百上千种相近颜色压缩成一个盒子，再用盒子上的代表色去近似还原整片区域的颜色。

从直方图到颜色盒：averageColor 的诞生环境

averageColor不是凭空出现的，它的宿主PixelBox由构造函数直接绑定一张全局直方图与一组 RGB 边界。见 PixelBox 构造函数文档：

constructor( globalHistogram: Histogram, minRed: number, maxRed: number, minGreen: number, maxGreen: number, minBlue: number, maxBlue: number );

各参数含义：

也就是说，一个PixelBox= RGB 三维颜色空间中的一个轴对齐长方体 + 指向全局直方图的引用。盒子内部有多少像素、平均色是什么，都由这对边界与直方图共同决定。

作为盒子的其他只读属性（见 PixelBox 类文档），averageColor与它们的关系：

• pixelCount：盒子内像素总数，是代表色的权重基础；
• colorVolume：盒子的颜色体积（RGB 三通道范围的乘积），与像素数一起决定后续排序；
• rangeRed/rangeGreen/rangeBlue：各通道跨度，即max - min；
• globalHistogram：构造时传入的全局直方图引用。

一个值得注意的细节：averageColor是按像素加权的汇总色而非盒子几何中心的颜色——盒子内部颜色的"数量多少"会直接影响平均值，这也是它能在量化结果中近似还原原图观感的原因。

直方图：像素从"8 位"压到"5 位"的统计基础

Histogram 类文档 说明了 averageColor 依赖的底层数据如何产生：对每一种可能的颜色，统计源图像中有多少像素命中该颜色。关键点是significantBits：

如果significantBits小于 8，每个通道（红、绿、蓝）都会按位数压缩。默认值 5 时，每个通道从 8 位（0-255）压到 5 位（0-31），原本不同的颜色会被合并统计。

这意味着直方图统计的"颜色粒度"是粗糙化的：RGB 三通道各取前 5 个有效位，组成 32×32×32 个统计桶。文档同时给出两个限制前提：

• 内存占用按4 * 2^(3 * significantBits)增长，significantBits取 8 时需要 64 MB 的直方图；
• 若源图像超过 2^32 个同色像素（例如 65536×65536 的正方形图像），代码会失效。

PixelBox及其averageColor正是构建在这张压缩后的直方图之上——边界以 0-31 的桶编号表示，像素计数与平均色的计算也都读取这套数据。

量化链路：PixelBox 如何被反复切分

averageColor的"一生"贯穿于整条量化链路。入口是 quantize() 函数：

export declare function quantize( source: PixelBlob, config?: QuantizeConfig ): QuantizedColor[];

它把 PixelBlob 中的图像像素压缩为一小组颜色，同目录下还有可直接操作直方图的 quantizeHistogram()，便于复用直方图、用不同配置多次量化。两者的算法基础都是 Modified Median Cut Quantization（改进型中位数切分量化），源自 Leptonica 的colorquant2.c实现（见 fast-colors.md 函数列表描述）。

整个流程可以概括为：

1. 读取图像像素，按significantBits压缩后构建Histogram；
2. 以初始边界（全 RGB 空间）创建一个PixelBox，其pixelCount为直方图总像素数；
3. 反复调用modifiedMedianCut把最大的盒子一分为二，直到达到目标调色板大小；
4. 每个最终存活的PixelBox通过其averageColor对外提供代表色。

modifiedMedianCut：切在"中位数两侧的中点"

modifiedMedianCut 属性文档 给出了切割方法最关键的实现说明：

modifiedMedianCut: () => [PixelBox | null, PixelBox | null];

它"尝试将当前 PixelBox 表示的颜色范围分成两个更小的 PixelBox"。与教科书式的朴素中位切分不同，它并不直接在中位切，而是：

1. 先找到中位位置（沿某个通道，以像素分布为基准）；
2. 在中位两侧的"较大半边"中点处下刀。

这样做的效果是：面积较小但颜色集中的区域能在最终输出中保留更多代表色，避免小色区被大色区"吞掉"。文档还注明其算法实现参考了 Leptonica 的 Modified Median Cut Quantization 源码（colorquant2.c）。

每次调用返回一个二元组[PixelBox | null, PixelBox | null]，切不开的盒子返回null，量化循环据此决定是否继续细分。可以推断：当盒子无法再切时，它便成为最终调色板中的一员，其averageColor即被提取为量化结果中的一种颜色。

量化结果与配置：哪些参数影响 averageColor

切割与平均色计算并非无脑进行，全部受 QuantizeConfig 控制，完整参数如下：

这些参数中，significantBits直接影响直方图粒度（从而影响平均色的精度），isBoxValid可以直接决定某个盒子的averageColor能否进入最终结果，fractionByPopulation则改变了"小色区代表色"的出场机会——它们共同塑造了最终QuantizedColor[]里每种颜色的质量。仓库提供了默认值变量 defaultQuantizeConfig，类型即为QuantizeConfig，不传配置时量化直接使用它。

读取代表色：QuantizedColor 与 ColorRGBA64

quantize() 返回的是 QuantizedColor 数组，每个元素包含三个字段：

• color: ColorRGBA64：量化后的颜色；
• colorVolume: number：该颜色来源盒子的体积；
• pixelCount: number：该颜色覆盖的像素数。

从PixelBox.averageColor（类型ColorRGBA64）与QuantizedColor.color（类型同为ColorRGBA64）的数据结构对应关系看，可以推断量化输出的每种颜色即来自对应最终PixelBox的averageColor。因此读懂averageColor就等同于理解了整个调色板代表色的来源。

拿到ColorRGBA64后，可借助其公开方法（见 ColorRGBA64 类文档）输出为可用的字符串形式：toStringHexRGB()生成#RRGGBB、toStringHexRGBA()生成#RRGGBBAA、toStringHexARGB()生成#AARRGGBB、toStringWebRGB()/toStringWebRGBA()生成 CSS 的rgb()/rgba()写法，roundToPrecision(precision)可用于控制输出精度，直接满足主题色、渐变配色等前端场景的落地需要。

实战：提取一张图片的主色调

基于 1.x API 文档中的公开签名，一个最小可用的提取流程如下（函数均已在 fast-colors.md 函数清单中确认）：

import { loadImageData, quantize, defaultQuantizeConfig, QuantizeConfig, } from "@microsoft/fast-colors"; // 1. 将图片（URL 或 File 等可加载源）读取为 ImageData const imageData = await loadImageData(source); // 2. 用默认配置量化，得到一组代表色 const palette = quantize(imageData, defaultQuantizeConfig); // 3. 按像素数降序输出前几个主色 const topColors = palette .slice() .sort((a, b) => b.pixelCount - a.pixelCount) .map(q => q.color.toStringHexRGB()); console.log(topColors);

若需要更精细的控制，可自定义配置：

const config: QuantizeConfig = { ...defaultQuantizeConfig, significantBits: 6, // 直方图更细：64×64×64，内存约 4*2^18 字节 targetPaletteSize: 8, // 想要 8 个主色 isHistogramPixelValid: pixel => // 排除 alpha 太低（近乎透明）的像素 pixel[3] > 0.5 * 255, isBoxValid: box => box.pixelCount >= 100, // 扔掉像素过少的盒子 }; const customPalette = quantize(imageData, config);

注意两点实践约束（依据 QuantizeConfig 文档）：significantBits上限为 8，取 8 时直方图需要 64 MB 内存，默认的 5 是内存与精度的均衡点；targetPaletteSize是"期望值"，极端输入（如纯色图）下实际返回数量可能少于该值。

小结

PixelBox.averageColor虽然只是一行readonly averageColor: ColorRGBA64的声明，背后却承载着 FAST@microsoft/fast-colors颜色量化的核心语义：一个 RGB 颜色盒子的加权代表色。理解它需要串起整条链路——Histogram 的位数压缩、PixelBox 的边界定义、modifiedMedianCut 的中位两侧切分策略，以及 QuantizeConfig 的七项配置对"谁能进入最终调色板"的裁决。把握住 averageColor，就把握住了从任意图片提取高保真主色调的钥匙；其余 FAST 组件（如设计系统中的配色生成）也都建立在这套颜色能力之上。

• 前端
• UI组件