nearest-color

Find the nearest color from a palette.

Given a target color and a list of available colors, nearest-color returns the closest one by Euclidean distance in RGB space — handy for snapping arbitrary colors to a theme palette, naming colors, or quantizing. Colors are given as hex (#f00, #ff0000), rgb(…) strings, or any of the 17 standard CSS color names.

A faithful Rust port of the nearest-color npm package.

Zero dependencies
Differential-tested against the reference nearest-color implementation

Install

[dependencies]
nearest-color = "0.1"

Usage

Build a reusable matcher from a named palette and get rich match info:

use nearest_color::{Matcher, Rgb};

let palette = Matcher::from_named(&[
    ("maroon", "#800"),
    ("light yellow", "rgb(255, 255, 51)"),
    ("pale blue", "#def"),
    ("white", "fff"),
]).unwrap();

let m = palette.nearest("#f00").unwrap().unwrap();
assert_eq!(m.name.as_deref(), Some("maroon"));
assert_eq!(m.value, "#800");
assert_eq!(m.rgb, Rgb { r: 136, g: 0, b: 0 });
// `m.distance` is the Euclidean RGB distance (≈119.0 here).

From an unnamed palette (or the built-in rainbow defaults), the match's name is None and value is the nearest color's source:

use nearest_color::{Matcher, nearest_color};

let bg = Matcher::from_colors(&["#eee", "#444"]).unwrap();
assert_eq!(bg.nearest("#fff").unwrap().unwrap().value, "#eee");
assert_eq!(bg.nearest("#000").unwrap().unwrap().value, "#444");

// `nearest_color` uses the default rainbow palette.
assert_eq!(nearest_color("#f88").unwrap().value, "#f80");

Combine palettes with [Matcher::or]:

use nearest_color::Matcher;
let a = Matcher::from_named(&[("maroon", "#800")]).unwrap();
let b = Matcher::from_colors(&["#444"]).unwrap();
let any = a.or(b);
assert_eq!(any.nearest("#888").unwrap().unwrap().value, "#444");

Color parsing

[parse_color] accepts:

Hex — #fff, fff, #04fbc8 (3 or 6 digits, with or without #, any case).
rgb(…) — rgb(3, 10, 100) or rgb(50%, 0%, 50%) (percentages are rounded).
Standard CSS names — the 17 in [STANDARD_COLORS] (red, aqua, gray, …).

Anything else returns an error (the matcher builders and nearest propagate it).

Contributors ✨

This project follows the all-contributors specification. Contributions of any kind are welcome — code, docs, bug reports, ideas, reviews! See the emoji key for how each contribution is recognized, and open a PR or issue to get involved.

Thanks goes to these wonderful people:

License