@thi.ng/pixel-dominant-colors 1.1.49 → 2.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-06-09T17:24:08Z
+- **Last updated**: 2025-07-10T14:20:23Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,20 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [2.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-dominant-colors@2.0.0) (2025-06-24)
+
+#### 🛑 Breaking changes
+
+- update dominantColors() ([9cf7a48](https://github.com/thi-ng/umbrella/commit/9cf7a48))
+- BREAKING CHANGE: rename `dominantColors()` => `dominantColorsKmeans()`, remove `dominantColorsArray()`
+  - merge `dominantColors()` & `dominantColorsArray()` => `dominantColorsKmeans()`
+  - add `DominantColor` result type
+  - add filterSamples helper
+
+#### 🚀 Features
+
+- add dominantColorsMeanCut()/dominantColorsMedianCut() ([2ab48c7](https://github.com/thi-ng/umbrella/commit/2ab48c7))
+
 ### [1.1.2](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-dominant-colors@1.1.2) (2024-07-25)
 
 #### ♻️ Refactoring

package/README.md

@@ -33,15 +33,18 @@ extracted from the [@thi.ng/pixel](https://thi.ng/pixel) package.
 
 ### Dominant color extraction
 
-The
-[`dominantColors()`](https://docs.thi.ng/umbrella/pixel/functions/dominantColors.html)
-function applies [k-means
-clustering](https://github.com/thi-ng/umbrella/tree/develop/packages/k-means) to
-extract the dominant colors from the given image. The clustering can be
-configured. The function returns 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).
+The package provides several methods to extract the dominant colors from a given image:
+
+- [`dominantColorsKmeans()`](https://docs.thi.ng/umbrella/pixel/functions/dominantColorsKmeans.html)
+uses [k-means clustering](https://github.com/thi-ng/umbrella/tree/develop/packages/k-means)
+- [`dominantColorsMeanCut()`](https://docs.thi.ng/umbrella/pixel/functions/dominantColorsMeanCut.html)
+- [`dominantColorsMedianCut()`](https://docs.thi.ng/umbrella/pixel/functions/dominantColorsMedianCut.html)
+
+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](https://demo.thi.ng/umbrella/dominant-colors/) based on this function.
@@ -123,13 +126,14 @@ For Node.js REPL:
 const pdc = await import("@thi.ng/pixel-dominant-colors");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 223 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 381 bytes
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/k-means](https://github.com/thi-ng/umbrella/tree/develop/packages/k-means)
 - [@thi.ng/pixel](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel)
+- [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
 
 Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 

package/api.d.ts

@@ -0,0 +1,34 @@
+import type { Fn2, NumericArray } from "@thi.ng/api";
+/**
+ * Options for {@link dominantColors}, an extension of
+ * [KMeansOpts](https://docs.thi.ng/umbrella/k-means/interfaces/KMeansOpts.html).
+ */
+export interface DominantColorOpts {
+    /**
+     * Predicate used to only include pixels in the analysis for which the
+     * filter returns truthy result. E.g. to pre-exclude weakly saturated or
+     * dark colors etc. The second arg is the index of the pixel in the image's
+     * pixel buffer.
+     *
+     * If omitted, all pixels will be included (default).
+     */
+    filter: Fn2<NumericArray, number, boolean>;
+}
+/**
+ * Result type for dominant color extraction functions
+ */
+export interface DominantColor {
+    /**
+     * RGB tuple
+     */
+    color: number[];
+    /**
+     * Normalized area (based on number of samples)
+     */
+    area: number;
+    /**
+     * Sample IDs (indices) belonging to this cluster.
+     */
+    items?: number[];
+}
+//# sourceMappingURL=api.d.ts.map

package/index.d.ts

@@ -1,53 +1,4 @@
-import type { Fn2, NumericArray } from "@thi.ng/api";
-import type { KMeansOpts } from "@thi.ng/k-means";
-import type { FloatBuffer } from "@thi.ng/pixel/float";
-/**
- * Options for {@link dominantColors}, an extension of
- * [KMeansOpts](https://docs.thi.ng/umbrella/k-means/interfaces/KMeansOpts.html).
- */
-export interface DominantColorOpts extends KMeansOpts {
-    /**
-     * Predicate used to only include pixels in the analysis for which the
-     * filter returns truthy result. E.g. to pre-exclude weakly saturated or
-     * dark colors etc. The second arg is the index of the pixel in the image's
-     * pixel buffer.
-     *
-     * If omitted, all pixels will be included (default).
-     */
-    filter: Fn2<Float32Array, number, boolean>;
-}
-/**
- * Takes a {@link FloatBuffer} and applies k-means clustering to extract the
- * `num` dominant colors from the given image. The clustering can be configured
- * via optionally provided `opts`. Returns array of `{ color, area }` objects
- * (sorted by descending area), where `color` is a cluster's dominant color and
- * `area` the normalized cluster size.
- *
- * @remarks
- * This function is syntax sugar for {@link dominantColorsArray}.
- *
- * See thi.ng/k-means for details about clustering implementation & options.
- *
- * @param img -
- * @param num -
- * @param opts -
- */
-export declare const dominantColors: (img: FloatBuffer, num: number, opts?: Partial<DominantColorOpts>) => {
-    color: number[];
-    area: number;
-    ids: number[];
-}[];
-/**
- * Similar to {@link dominantColors}, but accepting an array of color samples
- * instead of a `FloatBuffer` image.
- *
- * @param num
- * @param samples
- * @param opts
- */
-export declare const dominantColorsArray: (num: number, samples: NumericArray[], opts?: Partial<KMeansOpts>) => {
-    color: number[];
-    area: number;
-    ids: number[];
-}[];
+export * from "./api.js";
+export * from "./kmeans.js";
+export * from "./mean-cut.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,20 +1,3 @@
-import { kmeans } from "@thi.ng/k-means/kmeans";
-const dominantColors = (img, num, opts) => {
-  const samples = [];
-  const filter = opts?.filter || (() => true);
-  let i = 0;
-  for (let p of img) {
-    if (filter(p, i)) samples.push(p);
-    i++;
-  }
-  return samples.length ? dominantColorsArray(num, samples, opts) : [];
-};
-const dominantColorsArray = (num, samples, opts) => kmeans(Math.min(num, samples.length), samples, opts).sort((a, b) => b.items.length - a.items.length).map((c) => ({
-  color: [...c.centroid],
-  area: c.items.length / samples.length,
-  ids: c.items
-}));
-export {
-  dominantColors,
-  dominantColorsArray
-};
+export * from "./api.js";
+export * from "./kmeans.js";
+export * from "./mean-cut.js";

package/kmeans.d.ts

@@ -0,0 +1,20 @@
+import type { NumericArray } from "@thi.ng/api";
+import type { KMeansOpts } from "@thi.ng/k-means";
+import type { FloatBuffer } from "@thi.ng/pixel/float";
+import type { DominantColor, DominantColorOpts } from "./api.js";
+/**
+ * Takes a {@link FloatBuffer} and applies k-means clustering to extract the
+ * `num` dominant colors from the given image. The clustering can be configured
+ * via optionally provided `opts`. Returns array of `{ color, area }` objects
+ * (sorted by descending area), where `color` is a cluster's dominant color and
+ * `area` the normalized cluster size.
+ *
+ * @remarks
+ * See thi.ng/k-means for details about clustering implementation & options.
+ *
+ * @param img -
+ * @param num -
+ * @param opts -
+ */
+export declare const dominantColorsKmeans: (img: FloatBuffer | NumericArray[], num: number, opts?: Partial<DominantColorOpts & KMeansOpts>) => DominantColor[];
+//# sourceMappingURL=kmeans.d.ts.map

package/kmeans.js

@@ -0,0 +1,15 @@
+import { kmeans } from "@thi.ng/k-means/kmeans";
+import { filterSamples } from "./utils.js";
+const dominantColorsKmeans = (img, num, opts) => {
+  const samples = opts?.filter ? filterSamples(opts.filter, img) : Array.isArray(img) ? img : [...img];
+  return samples.length ? kmeans(Math.min(num, samples.length), samples, opts).sort((a, b) => b.items.length - a.items.length).map(
+    (c) => ({
+      color: [...c.centroid],
+      area: c.items.length / samples.length,
+      ids: c.items
+    })
+  ) : [];
+};
+export {
+  dominantColorsKmeans
+};

package/mean-cut.d.ts

@@ -0,0 +1,6 @@
+import type { NumericArray } from "@thi.ng/api";
+import type { FloatBuffer } from "@thi.ng/pixel/float";
+import type { DominantColor, DominantColorOpts } from "./api.js";
+export declare const dominantColorsMeanCut: (img: FloatBuffer | NumericArray[], num: number, opts?: Partial<DominantColorOpts>) => DominantColor[];
+export declare const dominantColorsMedianCut: (img: FloatBuffer | NumericArray[], num: number, opts?: Partial<DominantColorOpts>) => DominantColor[];
+//# sourceMappingURL=mean-cut.d.ts.map

package/mean-cut.js

@@ -0,0 +1,19 @@
+import { computeCutWith } from "@thi.ng/k-means/mean-cut";
+import { mean, vmean } from "@thi.ng/vectors/mean";
+import { vmedian } from "@thi.ng/vectors/median";
+import { filterSamples } from "./utils.js";
+const dominantColorsMeanCut = (img, num, opts) => __dominantColors(vmean, img, num, opts);
+const dominantColorsMedianCut = (img, num, opts) => __dominantColors(vmedian, img, num, opts);
+const __dominantColors = (cut, img, num, opts) => {
+  const samples = opts?.filter ? filterSamples(opts.filter, img) : [...img];
+  return samples.length ? computeCutWith(cut, samples, samples[0].length, num).sort((a, b) => b.length - a.length).map(
+    (bin) => ({
+      color: mean([], bin),
+      area: bin.length / samples.length
+    })
+  ) : [];
+};
+export {
+  dominantColorsMeanCut,
+  dominantColorsMedianCut
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/pixel-dominant-colors",
-  "version": "1.1.49",
+  "version": "2.0.1",
   "description": "k-means based dominant color extraction from images/pixel buffers",
   "type": "module",
   "module": "./index.js",
@@ -39,13 +39,14 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.29",
-    "@thi.ng/k-means": "^1.1.1",
-    "@thi.ng/pixel": "^7.5.1"
+    "@thi.ng/api": "^8.11.30",
+    "@thi.ng/k-means": "^2.0.1",
+    "@thi.ng/pixel": "^7.5.2",
+    "@thi.ng/vectors": "^8.3.2"
   },
   "devDependencies": {
-    "esbuild": "^0.25.5",
-    "typedoc": "^0.28.5",
+    "esbuild": "^0.25.6",
+    "typedoc": "^0.28.7",
     "typescript": "^5.8.3"
   },
   "keywords": [
@@ -55,7 +56,10 @@
     "dominant",
     "image",
     "k-means",
+    "mean",
+    "median",
     "palette",
+    "quantize",
     "typescript"
   ],
   "publishConfig": {
@@ -75,6 +79,18 @@
   "exports": {
     ".": {
       "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./kmeans": {
+      "default": "./kmeans.js"
+    },
+    "./mean-cut": {
+      "default": "./mean-cut.js"
+    },
+    "./utils": {
+      "default": "./utils.js"
     }
   },
   "thi.ng": {
@@ -82,5 +98,5 @@
     "year": 2021,
     "screenshot": "pixel/dominant-colors-01.jpg"
   },
-  "gitHead": "b076434a497b291ad33e81b1a15f6a71e2c82cc2\n"
+  "gitHead": "56d8f088389b22192a06e9a395b5eecebf47697a\n"
 }

package/utils.d.ts

@@ -0,0 +1,4 @@
+import type { Fn2, NumericArray } from "@thi.ng/api";
+/** @internal */
+export declare const filterSamples: (pred: Fn2<NumericArray, number, boolean>, img: Iterable<NumericArray>) => NumericArray[];
+//# sourceMappingURL=utils.d.ts.map

package/utils.js

@@ -0,0 +1,12 @@
+const filterSamples = (pred, img) => {
+  const samples = [];
+  let i = 0;
+  for (let p of img) {
+    if (pred(p, i)) samples.push(p);
+    i++;
+  }
+  return samples;
+};
+export {
+  filterSamples
+};