# image-color-utils

> Operate image pixels, such as pickup color, color contrast, etc

Latest version **1.3.5** (published 2025-04-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install image-color-utils
pnpm add image-color-utils
yarn add image-color-utils
bun add image-color-utils
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.5 |
| Published | 2025-04-18 |
| First published | 2021-03-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 50.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | AwesomeDevin |
| Maintainers | rise-devin |
| Keywords | pick, color, compare, pick color, Color similarity |

## Links

- npm: https://www.npmjs.com/package/image-color-utils
- Repository: https://github.com/o2team/image-color-utils
- Homepage: https://github.com/o2team/image-color-utils#readme
- Issues: https://github.com/o2team/image-color-utils/issues
- npm.io page: https://npm.io/package/image-color-utils

## Alternatives

- [postcss-color-hex-alpha](https://npm.io/package/postcss-color-hex-alpha.md) — 6.4M weekly downloads
- [randomcolor](https://npm.io/package/randomcolor.md) — 348.0K weekly downloads
- [bows](https://npm.io/package/bows.md) — 1.3K weekly downloads
- [ep_prefer_color_scheme](https://npm.io/package/ep_prefer_color_scheme.md) — 260 weekly downloads
- [coc-yank](https://npm.io/package/coc-yank.md) — 61 weekly downloads

## Recent versions

- 1.3.5 (latest) — 2025-04-18
- 1.3.4 — 2025-04-18
- 1.3.3 — 2025-01-08
- 1.3.2 — 2024-09-10
- 1.3.1 — 2024-09-10
- 1.2.12 — 2022-11-04
- 1.2.11 — 2022-11-03
- 1.2.10 — 2022-11-03
- 1.2.9 — 2022-11-03
- 1.2.8 — 2022-11-03
- 1.2.7 — 2022-11-03
- 1.2.6 — 2022-11-03
- 1.2.5 — 2022-11-03
- 1.2.4 — 2022-11-03
- 1.2.3 — 2022-11-03
- … 18 more at https://npm.io/package/image-color-utils/versions

## README

# image-color-utils

## DESC
Provide `pickup color`, `color similarity comparison`, `color boundary value calculation` and other capabilities。  

![](https://github.com/AwesomeDevin/ImageColorUtils/blob/master/assets/image-color-utils.gif?raw=true)

### [demo](https://awesomedevin.github.io/ImageColorUtils/)
### [codesandbox](https://codesandbox.io/s/image-color-utils-ghrvb)
![](https://raw.githubusercontent.com/o2team/image-color-utils/main/static/demo4.gif)


## Install
```
npm install image-color-utils --save
```

## Usage
##### es
```javascript
import { ImageColorUtils } from 'image-color-utils'
```
##### commonjs
```javascript
const { ImageColorUtils } = require('image-color-utils')
```

## API
- [ImageColorUtils](#-imagecolorutils)
- [pickColor](#-pickcolor---提取单个色值)
- [pickColors](#-pickcolors---提取图片色值)
- [adjust](#-adjust---色彩边缘计算)
- [compare](#-compare---色值相似度对比)
- [hex2rgb](#-hex2rgb---hex色值转rgb色值)
- [rgb2hex](#-rgb2hex---rgb色值转hex色值)


### \# ImageColorUtils
```javascript
import { ImageColorUtils } from 'image-color-utils'

const params = {
  origin: img,
  width: canvas.width,
  height: canvas.height,
  boundaryValue,
  mockMovePx,
  onload,
}
const imageColorUtils = new ImageColorUtils(params)
```
##### Arguments
Name | Desc | Type | Default | required
---- | ---- | ---- | ----- | ----
origin | 数据源(可以是 http链接 / ImageBitmap / HTMLImageElement ) | string / HTMLImageElement / ImageBitmap  /  | - | true
width | 画板宽度 | number | - | false (不传参将根据图片宽高自适应，origin 为 ImageBitmap / HTMLImageElemen，必填)
height | 画板高度 | number | - | false (不传参将根据图片宽高自适应，origin 为 ImageBitmap / HTMLImageElemen，必填)
mockMovePx |  边界扫描距离（最大边界扫描距离, 扫描方向由内向外） | number | 30 | false
boundaryValue | 色彩边界阈值（作用于色值相似度对比, 阈值越高，相似条件越高） | number | 10 | false
onload | 加载完成 | ()=>void | - | false
##### Returns
Desc  | Type 
-------- | -------- 
ImageColorUtils实例 | Object

### \# pickColor - 提取单个色值 
```javascript
import { ImageColorUtils } from 'image-color-utils'


const imageColorUtils = new ImageColorUtils({
  origin: img,
  width: canvas.width,
  height: canvas.height
})
const res = imageColorUtils.pickColor(x, y)
```
##### Arguments
Name  | Desc  | Type | Default | required
-------- | -------- | -------- | -------- | -----
x | 目标点距离画布左上角x坐标 | number | - | true
y | 目标点距离画布左上角y坐标 | number | - | true

##### Returns
Desc  | Type 
-------- | -------- 
目标点 rgb 色值 | number[] 

### \# pickColors - 提取图片色值
```javascript
import { ImageColorUtils } from 'image-color-utils'


const imageColorUtils = new ImageColorUtils({
  origin: img,
  width: canvas.width,
  height: canvas.height
})
const res = imageColorUtils.pickColors()
```
##### Returns
##### Returns
Desc  | Type 
-------- | -------- 
图片色值 | {rgb: string[], hex: string[]  }


### \# adjust - 色彩边缘计算
```javascript
import { ImageColorUtils } from 'image-color-utils'

const imageColorUtils = new ImageColorUtils({ 
  origin: img,
  width: canvas.width, 
  height: canvas.height,  
  boundaryValue,
  mockMovePx
})
imageColorUtils.adjust(leftTopPosition, rightBottomPosition)
```
##### Arguments
Name  | Desc  | Type | Default | required
-------- | -------- | -------- | -------- | -----
leftTopPosition | 图片所选区域初始左上角坐标 | number[] | [] | false
rightBottomPosition | 图片所选区域初始右下角坐标 | number[] | [] | false

##### Returns
Desc  | Type 
-------- | -------- 
边界计算后左上角坐标(x,y)及区域宽高(width,height) | Object:{x: number, y: number, width: number, height: number}

### \# compare - 色值相似度对比
```javascript
import { ImageColorUtils } from 'image-color-utils'

const res = ImageColorUtils.compare(color1, color2, boundaryValue, type)
```
##### Arguments
Name  | Desc  | Type | Default | required
-------- | -------- | -------- | -------- | -----
color1 | rgb 色值1 | number[] | - | true
color2 | rgb 色值2 | number[] | - | true
boundaryValue | 色彩边界阈值（作用于色值相似度对比, 阈值越高，相似条件越高） | number | 10 | false
type | 颜色模型 | 'rgb' or 'lab' | 'rgb' | true
##### Returns
Desc  | Type 
-------- | -------- 
是否相似 | boolean

### \# hex2rgb - HEX色值转RGB色值
```javascript
import { hex2rgb } from 'image-color-utils'

const rgb = hex2rgb(hex)
```
##### Arguments
Name  | Desc  | Type | Default | required
-------- | -------- | -------- | -------- | -----
hex | HEX色值 | String | - | true

##### Returns
Desc  | Type 
-------- | -------- 
RGB色值 | number[]

### \# rgb2hex - RGB色值转HEX色值
```javascript
import { rgb2hex } from 'image-color-utils'

const hex = rgb2hex(rgb)
```
##### Arguments
Name  | Desc  | Type | Default | required
-------- | -------- | -------- | -------- | -----
rgb | RGB色值 | number[] | - | true

##### Returns
Desc  | Type 
-------- | -------- 
HEX色值 | string


### \# isDeepColorByHsl - 基于 HSL 判断是否深色
```javascript
import { isDeepColorByHsl } from 'image-color-utils'

const isDeep = isDeepColorByHsl(hsl)
```
##### Arguments
Name  | Desc  | Type | Default | required
-------- | -------- | -------- | -------- | -----
hsl | HSL色值 | number[] | - | true

##### Returns
Desc  | Type 
-------- | -------- 
isDeep | boolean


### \# isDeepColorByHsv - 基于 HSV 判断是否深色
```javascript
import { isDeepColorByHsv } from 'image-color-utils'

const isDeep = isDeepColorByHsv(hsv)
```
##### Arguments
Name  | Desc  | Type | Default | required
-------- | -------- | -------- | -------- | -----
hsv | HSV色值 | number[] | - | true

##### Returns
Desc  | Type 
-------- | -------- 
isDeep | boolean


## Attribute
```javascript
import { ImageColorUtils } from 'image-color-utils'

const imageColorUtils = new ImageColorUtils({ 
  origin: img,
  width: canvas.width,
  height: canvas.height,
  boundaryValue,
  mockMovePx
})

console.log(imageColorUtils.canvas)
console.log(imageColorUtils.ctx)
console.log(imageColorUtils.imageData)
```

Name | Type
---  | ---
canvas | OffscreenCanvas
ctx | OffscreenCanvasRenderingContext2D
imageData | ImageData

---
_Source: https://npm.io/package/image-color-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._