color-diff

You can import the library using either CommonJS or ESM syntax. The package exports several functions for color difference calculation, palette mapping, and color conversion.

// CommonJS
const { 
  closest, 
  furthest,
  diff, 
  mapPalette,
  paletteMapKey,
  rgbaToLab,
  mapPaletteLab,
  labPaletteMapKey,
} = require("color-diff");

// ESM
import {
  closest,
  furthest,
  diff,
  mapPalette,
  paletteMapKey,
  rgbaToLab,
  mapPaletteLab,
  labPaletteMapKey,
} from "color-diff";

To use color-diff in your project, install it using npm:

npm install color-diff --save

The diff(color1, color2, bc) function returns the CIEDE2000 difference between two LAB colors.

• color1: The first LAB color.
• color2: The second LAB color.
• bc (optional): The background color, used when one of the colors uses alpha channels.

The furthest(color, palette, bc) function returns the color from the provided palette that is most different from the input color based on the CIEDE2000 algorithm.

• color: The target color.
• palette: An array of RGBAColor objects.
• bc (optional): The background color, used when the color and/or palette contains alpha channels.

const color = { R: 255, G: 255, B: 255 };
// black, white
const palette = [ {R: 0, G: 0, B: 0 }, {R: 255, G: 255, B: 255 } ];

furthest(color, palette); // {R: 0, G: 0, B: 0 }

The closest(color, palette, bc) function returns the color from the provided palette that is most similar to the input color based on the CIEDE2000 algorithm.

• color: The target color.
• palette: An array of RGBAColor objects.
• bc (optional): The background color, used when the color and/or palette contains alpha channels.

const color = { R: 255, G: 1, B: 30 };
// red, green, blue
const palette = [ {R: 255, G: 0, B: 0 },
                {R: 0, G: 255, B: 0 },
                {R: 0, G: 0, B: 255} ];

closest(color, palette); // {R: 255, G: 0, B: 0 }

A LabColor is an object representing a color in the LAB color space.

• Properties: 'L', 'a', 'b'.

{ L: 100, a: 0.005, b: -0.010 }

An RGBAColor is an object representing a color in the RGB space. It can use either uppercase or lowercase keys.

• Properties: 'R', 'G', 'B', 'A' (or 'r', 'g', 'b', 'a').
• Alpha channel (A or a): An optional property between 0.0 and 1.0. If omitted, the color is treated as fully opaque (1.0).
• Note: Each RGBA color is transformed into an RGB color before calculating CIEDE2000 difference, using the specified background color (which defaults to white).

// Example RGBA color
{ R: 255, G: 1, B: 0 }

Use rgbaToLab() to convert a color from RGBA to the Lab color space.

Parameters:

• color (RGBAColor): The input color in RGBA format (either uppercase { R, G, B, A } or lowercase { r, g, b, a }).

Returns:

• A LabColor object { L, a, b }.

import { rgbaToLab } from 'color-diff';

const rgba = { R: 255, G: 0, B: 0 };
const lab = rgbaToLab(rgba);

Use furthestLab() to find the color in a palette furthest from a target using the Lab color space.

Parameters:

• target (LabColor): The reference color in Lab format { L, a, b }.
• relative (LabColor[]): The array of Lab colors to search through.

Returns:

• The LabColor from the relative palette that is furthest from the target.

import { furthestLab } from 'color-diff';

const target = { L: 50, a: 10, b: 10 };
const palette = [{ L: 52, a: 11, b: 11 }, { L: 10, a: -5, b: -5 }];

const result = furthestLab(target, palette);

Use closest() to find the color in a relative palette that is most similar to a target color. You can optionally provide a background color bc to account for visual perception/contrast.

Parameters:

• target (RGBAColor): The reference color.
• relative (RGBAColor[]): The array of colors to search through.
• bc (RGBAColor, optional): The background color. Defaults to { R: 255, G: 255, B: 255 } (white) if not provided.

Returns:

• The RGBAColor from the relative palette that is closest to the target.

import { closest } from 'color-diff';

const target = { R: 255, G: 0, B: 0 };
const palette = [{ R: 250, G: 10, B: 10 }, { R: 0, G: 255, B: 0 }];
const background = { R: 255, G: 255, B: 255 };

const result = closest(target, palette, background);