iWantHue API完全手册：从安装到高级配置的一站式指南

iWantHue API完全手册：从安装到高级配置的一站式指南

【免费下载链接】iwanthueColors for data scientists.项目地址: https://gitcode.com/gh_mirrors/iw/iwanthue

iWantHue是一款专为数据科学家设计的颜色工具，能够生成和优化具有最佳区分度的色彩调色板。通过掌握色调、色度（无偏饱和度）和亮度范围，你可以生成任意大小的调色板，或为JavaScript项目获取颜色生成器。其核心算法在颜色子空间中优化感知距离，确保数据可视化的最佳可读性。

快速入门：5分钟安装与基础使用 🚀

一键安装步骤

iWantHue支持Node.js和浏览器环境，通过npm即可完成安装：

npm install iwanthue

基础使用示例

生成简单调色板只需两行代码：

var iwanthue = require('iwanthue'); var palette = iwanthue(5); // 生成包含5种颜色的调色板

带参数配置的高级用法：

var palette = iwanthue(5, { clustering: 'force-vector', // 聚类算法 seed: 'cool-palette', // 随机种子 quality: 100 // 聚类质量 });

图1：iWantHue生成的优化色彩分布示意图，展示了在CIE Lab颜色空间中均匀分布的颜色点

核心功能解析：让颜色为数据说话 🎨

两大聚类算法深度对比

iWantHue提供两种先进的颜色分布算法，适应不同的数据可视化需求：

K-means聚类

• 原理：在CIE Lab颜色空间中进行均匀采样，确保颜色分布均衡
• 适用场景：需要严格均匀分布的静态调色板
• 代码路径：npm/index.js

力向量排斥算法

• 原理：模拟电荷排斥物理模型，生成自然分散的颜色集
• 适用场景：动态数据可视化、交互式图表
• 代码路径：npm/index.js

图2：力向量算法生成的调色板示例，颜色间保持自然视觉距离

多维度颜色空间控制

通过直观的Hue/Chroma/Lightness参数控制，实现专业级调色效果：

• 色调(Hue)：0-360°颜色轮控制，支持设置[hmin, hmax]范围
• 色度(Chroma)：颜色鲜艳度调节，避免过饱和或灰暗
• 亮度(Lightness)：确保颜色在不同背景下的可读性

图3：不同色调范围设置对调色板的影响，展示100-250°色调区间的效果

高级配置指南：打造专业级调色板 🔧

完整参数配置表

颜色空间预设与自定义

iWantHue提供丰富的预设颜色空间，满足不同场景需求：

// 使用内置预设 var palette = iwanthue(8, { colorSpace: 'pastel' }); // 自定义颜色空间范围 var palette = iwanthue(8, { colorSpace: { hmin: 180, hmax: 360, cmin: 30, cmax: 70 } });

所有预设定义可查看：npm/presets.js

图4：自定义颜色空间参数生成的76色专业调色板

Palette类：智能颜色映射管理 🗺️

Palette类提供强大的颜色映射功能，轻松管理分类数据的颜色分配：

从数据值生成调色板

var Palette = require('iwanthue/palette'); // 从唯一值列表生成调色板 var palette = Palette.generateFromValues( 'cities', ['北京', '上海', '广州', '深圳'], { defaultColor: '#cccccc' } ); palette.get('北京'); // 返回对应颜色

高级映射方法

Palette类支持多种创建方式，满足不同数据格式需求：

• fromEntries：从键值对数组创建
• fromMapping：从对象映射创建
• fromJSON：从序列化数据恢复

完整API文档：npm/palette.js

预计算调色板：快速集成方案 ⚡

对于客户端应用或快速原型开发，iWantHue提供预计算调色板：

// 加载默认预计算调色板 var palettes = require('iwanthue/precomputed'); var sixColors = palettes[6]; // 获取6色调色板 // 按算法类型加载 var kmeansPalettes = require('iwanthue/precomputed/k-means'); var forceVectorPalettes = require('iwanthue/precomputed/force-vector');

预计算调色板包含2-15种颜色，支持多种风格：

• 色盲友好型：precomputed/k-means-colorblind
• 暗色主题：precomputed/force-vector-fancy-dark
• 荧光风格：precomputed/k-means-fluo

图5：不同亮度范围的预计算调色板效果对比

实用技巧与最佳实践 💡

确保颜色可访问性

• 使用distance: 'protanope'等参数生成色盲友好调色板
• 亮度范围建议设置在20-80之间，确保屏幕和打印可读性
• 代码示例：npm/test/palette.js

性能优化建议

• 对于大型项目，优先使用预计算调色板
• 质量参数建议：交互式应用30-50，静态图表80-100
• 多次尝试(attempts)设置为3-5可显著提升调色板质量

常见问题解决方案

Q: 生成的颜色过于相似怎么办？
A: 增大色度(Chroma)范围或使用force-vector算法，并提高quality值

Q: 如何确保调色板在不同背景下都清晰可见？
A: 设置较大的亮度范围(lmin=30, lmax=70)，并使用compromise距离函数

总结：释放数据的视觉潜力

iWantHue通过科学的颜色算法和直观的API，让数据科学家能够轻松创建专业级调色板。无论是简单的静态图表还是复杂的交互式可视化，iWantHue都能提供最佳的颜色解决方案，让你的数据讲述更精彩的故事。

要开始使用iWantHue，只需通过以下命令克隆仓库：

git clone https://gitcode.com/gh_mirrors/iw/iwanthue

探索更多示例和高级用法，请查看项目中的examples.php和tutorial.php文件。

【免费下载链接】iwanthueColors for data scientists.项目地址: https://gitcode.com/gh_mirrors/iw/iwanthue