@microsoft/fast-colors PixelBox 深度解析：基于直方图的 RGB 色域盒子与改良中位切分量化算法

前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载PixelBox 是microsoft/fast-colorsFAST 自适应界面系统的颜色工具库量化quantization管线中的核心数据结构它在 RGB 颜色空间中用一个盒子Box表示一段颜色范围并负责把庞大的直方图数据递归拆分成便于提取主色调的小色域。本文以仓库中 1.x 的 API 参考文档为主体逐项解析 PixelBox 的构造函数、全部只读属性与modifiedMedianCut拆分算法并串联Histogram、QuantizeConfig、quantize等周边 API帮助你从数据结构层面理解并运用图片主色调提取与调色板生成。PixelBox 是什么在 fast-colors 总览 的类清单中PixelBox 的定义只有一句话Represents a range of colors in RGB color space.即表示 RGB 颜色空间中的一段颜色范围。它是一个纯粹的颜色统计容器不保存原始像素而是记录某段 RGB 色域边界以及引用一份全局颜色直方图用于计算该色域内的像素总数、平均颜色、色域体积等信息。它在整个量化流程中扮演的角色是把图像/直方图中的全部颜色视为一个初始的PixelBox覆盖所有通道的最小到最大值通过modifiedMedianCut不断把盒子一分为二递归切分最终每个无法再拆分的盒子用其averageColor作为输出调色板中的一种代表色。类签名如下摘自 PixelBox 类参考export declare class PixelBox从源码结构看该类对外暴露的接口非常精简一个构造函数、一个拆分方法以属性形式声明、十二个只读统计属性没有任何修改内部状态的方法属于典型的不可变immutable统计对象。构造函数与六个 RGB 边界参数PixelBox 的构造函数接收一个全局直方图引用以及红、绿、蓝三个通道各自的最小值与最大值共计 8 个参数参见 构造函数文档constructor( globalHistogram: Histogram, minRed: number, maxRed: number, minGreen: number, maxGreen: number, minBlue: number, maxBlue: number );参数类型含义globalHistogramHistogram全局颜色直方图PixelBox 只持有其引用不复制数据minRed/maxRednumber红色通道的最小 / 最大边界minGreen/maxGreennumber绿色通道的最小 / 最大边界minBlue/maxBluenumber蓝色通道的最小 / 最大边界需要说明的约束边界是闭区间语义盒子覆盖[min, max]范围内的所有颜色通常保证min max边界的数值刻度与Histogram的通道刻度保持一致。根据 Histogram 文档当significantBits小于 8 时每个通道会从 8 位0-255压缩到更少的位数默认 5 位时通道范围是 0-31因此 PixelBox 的边界也相应落在压缩后的刻度上Histogram需要先被构建出来通常由图像像素统计得到PixelBox 本身不会触发直方图构建。只读属性一览PixelBox 的全部公开属性摘自 PixelBox 类参考属性类型说明averageColorColorRGBA64该色域范围内像素的平均颜色colorVolumenumber色域体积globalHistogramHistogram全局直方图引用maxBlue/maxGreen/maxRednumber各通道最大值边界minBlue/minGreen/minRednumber各通道最小值边界modifiedMedianCut() [PixelBox \| null, PixelBox \| null]把当前盒子拆分为两个更小的盒子pixelCountnumber盒子覆盖的像素总数rangeBlue/rangeGreen/rangeRednumber各通道的取值跨度属性逐一解析边界与跨度min/max/rangeminRed、maxRed、minGreen、maxGreen、minBlue、maxBlue六个属性直接保存构造时传入的通道边界是盒子的空间定义rangeRed、rangeGreen、rangeBlue表示各通道的跨度。从命名和量化算法的通行定义可以推断它们即max - min的差值代表盒子在 R、G、B 三个轴上的边长是后续计算体积和排序的依据。globalHistogram共享的直方图引用globalHistogram: Histogram是一个只读引用。这意味着所有由同一直方图切分出的 PixelBox 共享同一份统计数据盒子之间只靠边界区间相互区分。这也解释了为什么 PixelBox 构造时需要显式传入直方图它需要借助直方图回答我这个区间内有多少像素这类统计问题。pixelCount区间内的像素总数pixelCount: number表示落在该盒子 RGB 区间内的像素总数。根据 QuantizeConfig.isBoxValid 的文档示例量化过程常以pixelCount作为筛选条件例如排除像素数过少的盒子避免输出噪声颜色。colorVolume色域体积colorVolume: number描述盒子在 RGB 立方体中所占的体积。结合QuantizeConfig.fractionByPopulation的文档描述——对于其余颜色排序依据为 population × colorVolume——可以确认它参与最终代表色的排序优先级计算。按通行定义可以推断其值等于三个通道 range 的乘积体积越大的盒子代表颜色越分散。averageColor盒子的代表色averageColor: ColorRGBA64返回该盒子区间内像素的平均颜色类型为 ColorRGBA6464 位通道的 RGBA 颜色。在量化输出的最终调色板中每个保留下来的盒子正是用它作为代表色呈现给用户。modifiedMedianCut改良中位切分算法modifiedMedianCut是 PixelBox 唯一的行为属性也是整个量化算法的核心详见 modifiedMedianCut 文档modifiedMedianCut: () [PixelBox | null, PixelBox | null];它尝试把当前盒子所代表的颜色范围划分为两个更小的 PixelBox。文档对该算法的要点说明如下它并不直接在中位处切一刀而是先找到中位median然后在中位两侧各自取较大一侧盒子的一半进行切割这样做的结果是面积较小的颜色区域能在最终输出中得到更好的体现避免了直接中位切分导致的小众颜色被大色块淹没返回值为二元组两个子盒子之一在无法再切分时为null该实现基于 Leptonica 的colorquant2.c中的 Modified Median Cut Quantization 实现。算法的典型切分循环可以这样理解// 示意从初始盒子出发递归切分直到达到目标数量 let boxes: PixelBox[] [initialBox]; while (boxes.length targetPaletteSize) { const box /* 选取优先级最高的盒子 */; const [a, b] box.modifiedMedianCut(); if (a) boxes.push(a); if (b) boxes.push(b); // 无法再拆分时结束循环 }配合QuantizeConfig.isBoxValid谓词还可以在每个切分节点上筛掉不想要的颜色例如排除pixelCount低于阈值的盒子这正是 QuantizeConfig 文档 给出的典型用法。在量化管线中的位置quantize 与 quantizeHistogramPixelBox 不是独立存在的工具类它服务于microsoft/fast-colors的两个量化入口函数quantize(source: PixelBlob, config?)把PixelBlob中存储的图像缩减为一小组颜色返回QuantizedColor[]quantizeHistogram(histogram, config?)把直方图数据缩减为一小组颜色。文档特别指出手动创建 Histogram 是有用的——例如当你希望移除或修改其中的某些颜色或者希望复用同一份直方图、以不同配置多次量化时。两条入口背后都使用 PixelBox 的递归切分初始构建一个覆盖全范围的盒子按优先级反复调用modifiedMedianCut拆分最终每个盒子的averageColor即成为调色板中的一种颜色。整个管线可概括为图像 / PixelBlob → Histogram按 significantBits 压缩通道 → 初始 PixelBox覆盖全色域 → 递归 modifiedMedianCut 切分 → 输出 QuantizedColor[]取各盒子 averageColorQuantizeConfig量化行为的全部旋钮量化过程的行为由 QuantizeConfig 接口控制各字段含义如下字段类型说明targetPaletteSizenumber期望的输出调色板大小极端情况下如图像颜色很少实际输出可能不同significantBitsnumber必须在[1, 8]区间内内存占用按4 × 2^(3 × significantBits)增长设为 8 时需要 64 兆字节的直方图pixelSkippingnumber降低该值会增加 CPU 负载但会把更多像素纳入计算fractionByPopulationnumber最终调色板前fractionByPopulation × targetPaletteSize个颜色仅按像素数量排序其余颜色按population × colorVolume排序有助于让小面积的高对比度颜色出现在最终输出中isBoxValid((box: PixelBox) boolean) \| null用于从最终输出中筛除不想要的盒子例如排除pixelCount过低的颜色isHistogramPixelValid((pixel: number[]) boolean) \| null用于在构建直方图时排除像素传入[0,255]范围的 rgba 数组例如排除过于接近纯白或透明的颜色maxIterationsnumber迭代次数超过该值即中止并返回当前结果通常只在极端输入下触发注意isBoxValid谓词接收的参数类型正是本文主角PixelBox——这意味着 PixelBox 不仅是内部数据结构也是量化流程向你暴露的筛选与调试接口。实践组合手动构造 PixelBox 与提取调色板从直方图手动构造 PixelBox当你已经拥有一份Histogram可以直接构造一个指定区间的盒子并执行拆分基于 构造函数 与 modifiedMedianCut 的公开签名import { Histogram, PixelBox } from microsoft/fast-colors; // 直方图可由图像统计得到也可按 quantizeHistogram 文档所述手动构建以便修改颜色 const hist: Histogram /* ... */; // 例如以默认 5 位 significantBits 的通道刻度 [0,31] 构造覆盖全色域的盒子 const box new PixelBox(hist, 0, 31, 0, 31, 0, 31); const [left, right] box.modifiedMedianCut(); if (left) { console.log(left.averageColor, left.pixelCount, left.colorVolume); }这种手动构造方式的价值在于你可以脱离quantize的默认流程自由选择切分起点例如只关心某个色相区间并逐层观察盒子拆分的统计结果。端到端提取图片主色调使用microsoft/fast-colors公开的图像加载与量化 API可以组合出完整的调色板提取流程以下均基于文档公开签名import { loadImageData, ImageDataPixelBlob, quantize, QuantizeConfig } from microsoft/fast-colors; // 1. 加载图像取回 Canvas 的像素数据 const imageData loadImageData(image-url); // 2. 包装为 PixelBlob文档ImageDataPixelBlob 是 ImageData 的 PixelBlob 实现 const blob new ImageDataPixelBlob(imageData); // 3. 配置量化参数并执行 const config: QuantizeConfig { targetPaletteSize: 16, significantBits: 5, pixelSkipping: 1, fractionByPopulation: 0.5, maxIterations: 1000, isBoxValid: (box) box.pixelCount 10, isHistogramPixelValid: (pixel) /* 例如排除透明或接近纯白的像素 */ }; const palette quantize(blob, config);其中 loadImageData 负责把图片源加载进HTMLImageElement并经由 canvas 取出像素数据ImageDataPixelBlob 则将其包装为量化入口所需的PixelBlob。相关文档围绕 PixelBox 及其上下游仓库中的 1.x API 文档还包含以下可继续深读的材料fast-colors 模块总览全部类、枚举与函数的索引PixelBox 构造函数 与 modifiedMedianCut 的详细签名HistogramPixelBox 依赖的全局直方图含significantBits与通道压缩说明quantize 与 quantizeHistogram两个量化入口的完整签名QuantizeConfig全部量化参数与筛选谓词说明。简而言之PixelBox 是理解microsoft/fast-colors量化能力的关键钥匙掌握了它的边界定义、统计属性和modifiedMedianCut切分逻辑你就能读懂从一张图片到一组主色调的完整算法链路并在需要定制筛选或复用直方图时直接对它进行操作。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐FAST Colors 1.x 中的 PixelBox.modifiedMedianCut改良中值切分量化算法的 API 深度解析FAST Colors 1.x 中的 PixelBox.modifiedMedianCut改良中值切分量化算法的 API 深度解析 本文围绕 microso前端UI组件microsoft/fast-colors 中的 rgbToTemperature()从 RGB 颜色反算色温的 API 详解microsoft/fast colors 中的 rgbToTemperature 从 RGB 颜色反算色温的 API 详解 本文围绕 FAST 1.x 系前端UI组件FAST Colors 中的 ColorHSV 类掌握 HSV 色域模型与 microsoft/fast-colors 的颜色运算FAST Colors 中的 ColorHSV 类掌握 HSV 色域模型与 microsoft/fast colors 的颜色运算 导读 ColorHSV前端UI组件上一篇革命性马拉地语语音识别模型sumedh/wav2vec2-large-xlsr-marathi 深度解析下一篇如何使用Shotgun快速启动Rack应用5分钟上手教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考