pixel-dominant-colors

Note

This is one of 214 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
  • Dominant color extraction
• Status
• Installation
• Dependencies
• Usage examples
• API
• Authors
• License

About

k-means based dominant color extraction from images/pixel buffers. This is a support package for @thi.ng/pixel.

This package contains functionality which was previously part of and has been extracted from the @thi.ng/pixel package.

Dominant color extraction

The package provides several methods to extract the dominant colors from a given image:

• dominantColorsKmeans() uses k-means clustering
• dominantColorsMeanCut()
• dominantColorsMedianCut()

In all cases the clustering can be configured. The functions return an array of { color, area } objects (sorted by descending area), where color is a cluster's dominant color (in the format of the source image) and area the normalized cluster size (number of selected pixels over total number of pixels in the image).

Also see the dominant colors example project & online tool based on this function. Furthermore, the thi.ng/color-palettes package provides 200+ curated color themes extracted from images using this function...

Picture credit: /u/kristophershinn

import { floatBuffer, FLOAT_RGB } from "@thi.ng/pixel";
import { dominantColors } from "@thi.ng/pixel-dominant-colors";
import { read } from "@thi.ng/pixel-io-netpbm";
import { readFileSync } from "node:fs";

// read test PPM image and convert into float RGB format
const img = floatBuffer(read(readFileSync(`test.ppm`)), FLOAT_RGB);

// extract 5 dominant color clusters
const clusters = dominantColors(img, 5);

console.log(clusters);
// [
//   {
//     color: [ 0.4000000059604645, 0.30980393290519714, 0.21176470816135406 ],
//     area: 0.3141084558823529
//   },
//   {
//     color: [ 0.21960784494876862, 0.19607843458652496, 0.1411764770746231 ],
//     area: 0.2780330882352941
//   },
//   {
//     color: [ 0.4156862795352936, 0.4745098054409027, 0.5647059082984924 ],
//     area: 0.16620710784313725
//   },
//   {
//     color: [ 0.6666666865348816, 0.7568627595901489, 0.9254902005195618 ],
//     area: 0.12385110294117647
//   },
//   {
//     color: [ 0.7176470756530762, 0.4745098054409027, 0.12941177189350128 ],
//     area: 0.11780024509803921
//   }
// ]

Status

STABLE - used in production

Search or submit any issues for this package

Installation

yarn add @thi.ng/pixel-dominant-colors

ESM import:

import * as pdc from "@thi.ng/pixel-dominant-colors";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/pixel-dominant-colors"></script>

JSDelivr documentation

For Node.js REPL:

const pdc = await import("@thi.ng/pixel-dominant-colors");

Package sizes (brotli'd, pre-treeshake): ESM: 381 bytes

Dependencies

• @thi.ng/api
• @thi.ng/k-means
• @thi.ng/pixel
• @thi.ng/vectors

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

Usage examples

One project in this repo's /examples directory is using this package:

Screenshot	Description	Live demo	Source
	Color palette generation via dominant color extraction from uploaded images	Demo	Source

API

Generated API docs

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-pixel-dominant-colors,
  title = "@thi.ng/pixel-dominant-colors",
  author = "Karsten Schmidt",
  note = "https://thi.ng/pixel-dominant-colors",
  year = 2021
}

License

© 2021 - 2026 Karsten Schmidt // Apache License 2.0