@taoya7/color-pick

基于 WebAssembly 的图片主色提取库。

安装

pnpm add @taoya7/color-pick

快速开始

import { init, extractColors, rgbaToRgb } from '@taoya7/color-pick'

// 初始化 WASM（仅需一次）
await init()

// 从 canvas 获取图片像素
const canvas = document.createElement('canvas')
const ctx = canvas.getContext('2d')!
canvas.width = img.naturalWidth
canvas.height = img.naturalHeight
ctx.drawImage(img, 0, 0)
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height)

// RGBA 转 RGB，提取主色
const rgb = rgbaToRgb(imageData.data)
const colors = extractColors(rgb, canvas.width, canvas.height)

console.log(colors)
// [
//   { r: 229, g: 62,  b: 47,  hex: "#e53e2f" },
//   { r: 45,  g: 120, b: 200, hex: "#2d78c8" },
//   ...
// ]

API

init(wasmUrl?): Promise<void>

初始化 WASM 模块，必须在提取颜色前调用一次。

| 参数 | 类型 | 说明 | |------|------|------| | wasmUrl | string \| URL \| BufferSource | 可选，自定义 .wasm 文件路径 |

initSync(module): void

从 BufferSource 或 WebAssembly.Module 同步初始化。

extractColors(rgbBytes, width, height): ColorResult[]

提取最多 4 个主色，按视觉显著性排序。

| 参数 | 类型 | 说明 | |------|------|------| | rgbBytes | Uint8Array | sRGB 像素数据：[R,G,B,R,G,B,...] | | width | number | 图片宽度（最大 65535） | | height | number | 图片高度（最大 65535） |

返回值： ColorResult[]

interface ColorResult {
  r: number   // 0-255
  g: number   // 0-255
  b: number   // 0-255
  hex: string // 如 "#e53e2f"
}

extractColorsWithConfig(rgbBytes, width, height, config?): ColorResult[]

与 extractColors 相同，但支持自定义参数调优。

interface OkmainConfig {
  maskSaturatedThreshold?: number  // 中心区域阈值 [0, 0.5)，默认 0.3
  maskWeight?: number              // 中心像素优先权重 [0, 1]，默认 1.0
  maskWeightedCountsWeight?: number // 像素数量评分权重 [0, 1]，默认 0.3
  chromaWeight?: number            // 色彩饱和度评分权重 [0, 1]，默认 0.7
}

maskWeightedCountsWeight + chromaWeight 必须等于 1.0。

// 更重视像素数量，减少饱和度影响
const colors = extractColorsWithConfig(rgb, w, h, {
  maskWeightedCountsWeight: 0.6,
  chromaWeight: 0.4,
})

rgbaToRgb(rgba): Uint8Array

将 RGBA 数据（来自 canvas.getImageData()）转换为 RGB。

const imageData = ctx.getImageData(0, 0, w, h)
const rgb = rgbaToRgb(imageData.data)

Vite 集成

// vite.config.ts
import wasm from 'vite-plugin-wasm'

export default defineConfig({
  plugins: [wasm()],
  optimizeDeps: { exclude: ['@taoya7/color-pick'] },
})

工作原理

1. 降采样 — 将图片缩小到 ≤25 万像素
2. 色彩空间转换 — sRGB → Oklab（感知均匀色彩空间）
3. K-means 聚类 — 1~4 个聚类，K-means++ 初始化
4. 评分排序 — 综合像素数量（中心加权）+ 色度（chroma）
5. 返回按显著性排序的主色

百万像素图片约 100ms 完成处理。