@thi.ng/pixel-analysis 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-07-26T12:33:06Z
+- **Last updated**: 2025-07-27T16:56:27Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,27 @@ 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.
 
+### [1.1.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-analysis@1.1.1) (2025-07-27)
+
+#### 🩹 Bug fixes
+
+- update/fix weightedLuma result ([19d818c](https://github.com/thi-ng/umbrella/commit/19d818c))
+
+## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-analysis@1.1.0) (2025-07-27)
+
+#### 🚀 Features
+
+- make temperature()/hueTemperature() parametric ([f61955e](https://github.com/thi-ng/umbrella/commit/f61955e))
+  - add coefficients as optional arg
+  - add `DEFAULT_TEMPERATURE_COEFFS`
+- update analyzeColors() & ColorAnalysisResult ([595064d](https://github.com/thi-ng/umbrella/commit/595064d))
+  - update/rename `AnalysisOpts` => `ColorAnalysisOpts`
+  - add `ColorAnalysisOpts.tempCoeffs`
+  - rename `AnalyzedImage` => `ColorAnalysisResult`
+  - update `ColorAnalysisResult` internal structure
+  - add `computeHueRange()`
+- update `analyzeFeatures()`, add `FeatureAnalysisResult` ([e276eb8](https://github.com/thi-ng/umbrella/commit/e276eb8))
+
 ### [1.0.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-analysis@1.0.1) (2025-07-24)
 
 #### 🩹 Bug fixes

package/README.md

@@ -81,7 +81,7 @@ For Node.js REPL:
 const pa = await import("@thi.ng/pixel-analysis");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.72 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.89 KB
 
 ## Dependencies
 

package/analyze-colors.d.ts

@@ -1,18 +1,21 @@
 import { FloatBuffer } from "@thi.ng/pixel/float";
 import { IntBuffer } from "@thi.ng/pixel/int";
-import type { AnalysisOpts, AnalyzedImage } from "./api.js";
+import type { ColorAnalysisOpts, ColorAnalysisResult } from "./api.js";
+import { type DEFAULT_TEMPERATURE_COEFFS } from "./hues.js";
 /**
  * Performs a set of image/color analyses on provided pixel buffer.
  *
  * @param img
  * @param opts
  */
-export declare const analyzeColors: (img: FloatBuffer | IntBuffer, opts?: Partial<AnalysisOpts>) => AnalyzedImage;
+export declare const analyzeColors: (img: FloatBuffer | IntBuffer, opts?: Partial<ColorAnalysisOpts>) => ColorAnalysisResult;
 /**
- * Computes a number of metrics (partial {@link AnalyzedImage}) derived from
+ * Computes a number of metrics (partial {@link ColorAnalysisResult}) derived from
  * given raw SRGB colors. Helper function for {@link analyzeColors}.
  *
  * @param colors
+ * @param minSat
+ * @param tempCoeffs
  */
-export declare const derivedColorsResult: (colors: number[][], minSat?: number) => Pick<AnalyzedImage, "css" | "srgb" | "hsv" | "oklch" | "mean" | "sd" | "range" | "contrast" | "colorContrast" | "temperature">;
+export declare const derivedColorResults: (colors: number[][], minSat?: number, tempCoeffs?: typeof DEFAULT_TEMPERATURE_COEFFS) => Pick<ColorAnalysisResult, "css" | "srgb" | "hsv" | "oklch" | "hue" | "sat" | "luma" | "contrast" | "colorContrast" | "temperature">;
 //# sourceMappingURL=analyze-colors.d.ts.map

package/analyze-colors.js

@@ -18,15 +18,18 @@ import { map } from "@thi.ng/transducers/map";
 import { max } from "@thi.ng/transducers/max";
 import { minMax } from "@thi.ng/transducers/min-max";
 import { permutations } from "@thi.ng/transducers/permutations";
-import { pluck } from "@thi.ng/transducers/pluck";
 import { reduce } from "@thi.ng/transducers/reduce";
 import { transduce } from "@thi.ng/transducers/transduce";
 import { circularMean, circularSD } from "@thi.ng/vectors/circular";
 import { dot } from "@thi.ng/vectors/dot";
 import { vmean } from "@thi.ng/vectors/mean";
+import { mulN } from "@thi.ng/vectors/muln";
 import { roundN } from "@thi.ng/vectors/roundn";
 import { sd } from "@thi.ng/vectors/variance";
-import { temperature } from "./hues.js";
+import {
+  computeHueRange,
+  temperature
+} from "./hues.js";
 const analyzeColors = (img, opts) => {
   let $img = img.format !== FLOAT_RGBA ? img.as(FLOAT_RGBA) : img;
   if (opts?.size) $img = __resize($img, opts.size);
@@ -34,9 +37,13 @@ const analyzeColors = (img, opts) => {
   const imgHsv = $img.as(FLOAT_HSVA);
   const colors = __dominantColors($img, opts);
   const colorAreas = colors.map((x) => x.area);
-  const derived = derivedColorsResult(colors.map((x) => x.color));
+  const derived = derivedColorResults(
+    colors.map((x) => x.color),
+    opts?.minSat,
+    opts?.tempCoeffs
+  );
   const lumaRangeImg = reduce(minMax(), imgGray.data);
-  const weightedLuma = dot(derived.range.luma, colorAreas);
+  const weightedLuma = dot(derived.srgb.map(luminanceSrgb), colorAreas);
   const weightedChroma = dot(
     derived.oklch.map((x) => x[1]),
     colorAreas
@@ -51,7 +58,7 @@ const analyzeColors = (img, opts) => {
     imgHsv,
     ...derived,
     area: colorAreas,
-    temperature: temperature(imgHsv, opts?.minSat),
+    temperature: temperature(imgHsv, opts?.minSat, opts?.tempCoeffs),
     contrastImg: lumaRangeImg[1] - lumaRangeImg[0],
     lumaRangeImg,
     weightedSat,
@@ -59,37 +66,37 @@ const analyzeColors = (img, opts) => {
     weightedChroma
   };
 };
-const derivedColorsResult = (colors, minSat) => {
+const derivedColorResults = (colors, minSat, tempCoeffs) => {
   const dominantLuma = colors.map((x) => luminanceSrgb(x));
   const dominantSrgb = colors.map((x) => srgb(x));
   const dominantHsv = dominantSrgb.map((x) => hsv(x));
   const dominantOklch = dominantSrgb.map((x) => oklch(x));
   const dominantCss = dominantSrgb.map((x) => css(x));
-  const $hueRange = transduce(pluck(0), minMax(), dominantHsv);
-  const hues = dominantHsv.map((x) => x[0] * TAU);
+  const hues = dominantHsv.map((x) => x[0]);
+  const huesRad = mulN([], hues, TAU);
   const sats = dominantHsv.map((x) => x[1]);
-  const meanHue = circularMean(hues) / TAU;
-  const hueRange = meanHue > $hueRange[1] || meanHue < $hueRange[0] ? [$hueRange[1], $hueRange[0]] : $hueRange;
+  const meanHue = circularMean(huesRad) / TAU;
+  const hueRange = computeHueRange(hues, meanHue);
   const lumaRange = reduce(minMax(), dominantLuma);
   return {
     css: dominantCss,
     srgb: dominantSrgb,
     hsv: dominantHsv,
     oklch: dominantOklch,
-    mean: {
-      hue: meanHue,
-      sat: vmean(sats),
-      luma: vmean(dominantLuma)
+    hue: {
+      mean: meanHue,
+      range: hueRange,
+      sd: circularSD(huesRad) / TAU
     },
-    sd: {
-      hue: circularSD(hues) / TAU,
-      sat: sd(sats),
-      luma: sd(dominantLuma)
+    sat: {
+      mean: vmean(sats),
+      range: reduce(minMax(), sats),
+      sd: sd(sats)
     },
-    range: {
-      hue: hueRange,
-      sat: reduce(minMax(), sats),
-      luma: lumaRange
+    luma: {
+      mean: vmean(dominantLuma),
+      range: lumaRange,
+      sd: sd(dominantLuma)
     },
     contrast: lumaRange[1] - lumaRange[0],
     colorContrast: fit(
@@ -103,7 +110,7 @@ const derivedColorsResult = (colors, minSat) => {
       0,
       1
     ),
-    temperature: temperature(dominantHsv, minSat)
+    temperature: temperature(dominantHsv, minSat, tempCoeffs)
   };
 };
 const __dominantColors = (img, {
@@ -120,5 +127,5 @@ const __resize = ($img, size) => {
 };
 export {
   analyzeColors,
-  derivedColorsResult
+  derivedColorResults
 };

package/analyze-features.d.ts

@@ -1,10 +1,5 @@
 import { type FloatBuffer } from "@thi.ng/pixel/float";
 import type { IntBuffer } from "@thi.ng/pixel/int";
-export declare const analyzeFeatures: (img: FloatBuffer | IntBuffer) => {
-    imgEdge: FloatBuffer;
-    imgSobelX: FloatBuffer;
-    imgSobelY: FloatBuffer;
-    scoreEdge: number;
-    scoreSobel: number;
-};
+import type { FeatureAnalysisResult } from "./api.ts";
+export declare const analyzeFeatures: (img: FloatBuffer | IntBuffer) => FeatureAnalysisResult;
 //# sourceMappingURL=analyze-features.d.ts.map

package/analyze-features.js

@@ -7,6 +7,8 @@ import {
 import {} from "@thi.ng/pixel/float";
 import { FLOAT_GRAY } from "@thi.ng/pixel/format/float-gray";
 import { FLOAT_GRAY_RANGE } from "@thi.ng/pixel/format/float-gray-range";
+import { magSq } from "@thi.ng/vectors/magsq";
+const { sqrt } = Math;
 const FMT_EDGE = FLOAT_GRAY_RANGE(-24, 24);
 const FMT_SOBEL = FLOAT_GRAY_RANGE(-4, 4);
 const analyzeFeatures = (img) => {
@@ -19,15 +21,20 @@ const analyzeFeatures = (img) => {
   imgSobelX.format = FMT_SOBEL;
   const imgSobelY = convolveImage($img, { kernel: SOBEL_Y });
   imgSobelY.format = FMT_SOBEL;
-  const magSq = (img2) => img2.data.reduce((acc, x) => acc + x * x);
-  const scoreEdge = Math.sqrt(magSq(imgEdge)) / numPixels;
-  const scoreSobel = Math.sqrt(magSq(imgSobelX) + magSq(imgSobelY)) / numPixels;
+  const edge = sqrt(magSq(imgEdge.data)) / numPixels;
+  const sobX = magSq(imgSobelX.data);
+  const sobY = magSq(imgSobelY.data);
+  const sobelX = sqrt(sobX) / numPixels;
+  const sobelY = sqrt(sobY) / numPixels;
+  const sobel = sqrt(sobX + sobY) / numPixels;
   return {
     imgEdge,
     imgSobelX,
     imgSobelY,
-    scoreEdge,
-    scoreSobel
+    edge,
+    sobelX,
+    sobelY,
+    sobel
   };
 };
 export {

package/api.d.ts

@@ -2,7 +2,12 @@ import type { Fn2 } from "@thi.ng/api";
 import type { HSV, Oklch, SRGB } from "@thi.ng/color";
 import type { FloatBuffer } from "@thi.ng/pixel";
 import type { DominantColor } from "@thi.ng/pixel-dominant-colors";
-export interface AnalysisOpts {
+import type { DEFAULT_TEMPERATURE_COEFFS } from "./hues.js";
+/**
+ * 2-tuple representing a closed [min,max] value range/interval
+ */
+export type Range = [number, number];
+export interface ColorAnalysisOpts {
     /**
      * Max. number of dominant colors.
      */
@@ -20,6 +25,11 @@ export interface AnalysisOpts {
      * Min. saturation to consider for computing {@link temperature}.
      */
     minSat: number;
+    /**
+     * Temperature curve hues/coefficients for computing {@link temparature}.
+     * See {@link DEFAULT_TEMPERATURE_COEFFS} for details.
+     */
+    tempCoeffs: typeof DEFAULT_TEMPERATURE_COEFFS;
     /**
      * Channel precision for dominant colors.
      *
@@ -27,17 +37,20 @@ export interface AnalysisOpts {
      */
     prec: number;
 }
-export interface AnalyzedImage {
+/**
+ * Result data structure returned by {@link analyzeColors}.
+ */
+export interface ColorAnalysisResult {
     /**
      * Input image, possibly converted to float RGBA & resized.
      */
     img: FloatBuffer;
     /**
-     * Float grayscale version of {@link AnalyzedImage.img}.
+     * Float grayscale version of {@link ColorAnalysisResult.img}.
      */
     imgGray: FloatBuffer;
     /**
-     * Float HSV version of {@link AnalyzedImage.img}.
+     * Float HSV version of {@link ColorAnalysisResult.img}.
      */
     imgHsv: FloatBuffer;
     /**
@@ -60,72 +73,74 @@ export interface AnalyzedImage {
      * Normalized areas of dominant color clusters
      */
     area: number[];
-    mean: {
+    hue: {
         /**
          * Normalized mean hue (using circular mean).
          */
-        hue: number;
+        mean: number;
         /**
-         * Mean saturation
+         * Min/max HSV hue range of dominant colors. IMPORTANT: In case of
+         * circular overflow (360 => 0 degrees), the min hue WILL be greater
+         * than the max hue (e.g. a hue range of `[0.8, 0.2]` indicates the hue
+         * range from magenta -> orange). Also see {@link ColorAnalysisResult.hue.mean}.
          */
-        sat: number;
+        range: Range;
         /**
-         * Mean luminance
+         * Circular standard deviation of normalized hues.
          */
-        luma: number;
+        sd: number;
     };
-    sd: {
+    sat: {
         /**
-         * Circular standard deviation of normalized hues.
+         * Mean saturation
          */
-        hue: number;
+        mean: number;
         /**
-         * Standard deviation of normalized saturation.
+         * Min/max HSV saturation range of dominant colors
          */
-        sat: number;
+        range: Range;
         /**
-         * Standard deviation of normalized luminance.
+         * Standard deviation of normalized saturation.
          */
-        luma: number;
+        sd: number;
     };
-    range: {
+    luma: {
         /**
-         * Min/max HSV hue range of dominant colors. IMPORTANT: In case of
-         * circular overflow (360 => 0 degrees), the min hue WILL be greater
-         * than the max hue (e.g. a hue range of `[0.8, 0.2]` indicates the hue
-         * range from magenta -> orange). Also see {@link AnalyzedImage.mean.hue}.
+         * Mean luminance
          */
-        hue: [number, number];
+        mean: number;
         /**
-         * Min/max HSV saturation range of dominant colors
+         * Min/max luminance range of dominant colors (obtained from SRGB)
          */
-        sat: [number, number];
+        range: Range;
         /**
-         * Min/max luminance range of dominant colors (obtained from SRGB)
+         * Standard deviation of normalized luminance.
          */
-        luma: [number, number];
+        sd: number;
     };
     /**
      * Min/max luminance range of entire grayscale image (obtained from SRGB)
      */
-    lumaRangeImg: [number, number];
+    lumaRangeImg: Range;
     /**
      * Comprehensive {@link TemperatureResult} as produced by
-     * {@link temperature}. Also see {@link AnalysisOpts.minSat}.
+     * {@link temperature}. Also see {@link ColorAnalysisOpts.minSat} and
+     * {@link ColorAnalysisOpts.tempCoeffs}.
      */
     temperature: TemperatureResult;
     /**
      * Luminance contrast of dominant colors (i.e. delta of
-     * {@link AnalyzedImage.lumaRange}).
+     * {@link ColorAnalysisResult.lumaRange}).
      */
     contrast: number;
     /**
      * Luminance contrast of entire grayscale image (i.e. delta of
-     * {@link AnalyzedImage.lumaRangeImg}).
+     * {@link ColorAnalysisResult.lumaRangeImg}).
      */
     contrastImg: number;
     /**
-     * Max. normalized WCAG color contrast of dominant colors.
+     * Max. normalized WCAG color contrast of dominant colors. The original WCAG
+     * result range [1,21] is rescaled to [0,1].
      */
     colorContrast: number;
     /**
@@ -171,4 +186,13 @@ export interface TemperatureResult {
      */
     area: number;
 }
+export interface FeatureAnalysisResult {
+    imgEdge: FloatBuffer;
+    imgSobelX: FloatBuffer;
+    imgSobelY: FloatBuffer;
+    edge: number;
+    sobel: number;
+    sobelX: number;
+    sobelY: number;
+}
 //# sourceMappingURL=api.d.ts.map

package/hues.d.ts

@@ -86,10 +86,20 @@ export declare const hueRangeAreaIntensity: (colors: Iterable<ReadonlyVec>, hueR
  * @param colors
  */
 export declare const meanIntensity: (colors: Iterable<ReadonlyVec>) => number;
+/**
+ * Constructs the min/max range of given normalized `hues` around given mean hue
+ * (also normalized), considering circular wrap-around. If `min > max` in the
+ * result `[min,max]`, then the hue range is crossing 0 degrees.
+ *
+ * @param hues
+ * @param range
+ * @param mean
+ */
+export declare const computeHueRange: (hues: number[], mean: number) => [number, number];
 /**
  * Computes an abstract measure of a normalized "color temperature" of the given
  * HSV `colors` (also normalized in [0,1] range). Results closer to 1.0 indicate
- * a prevalence of warmer colors, results closer to -1.0 mean more
+ * a prevalence of warmer (red/orange) colors, results closer to -1.0 mean more
  * colder/blue-ish colors present.
  *
  * @remarks
@@ -109,8 +119,24 @@ export declare const meanIntensity: (colors: Iterable<ReadonlyVec>) => number;
  *
  * @param colors
  * @param minSat
+ * @param coeffs
+ */
+export declare const temperature: (colors: Iterable<ReadonlyVec>, minSat?: number, coeffs?: typeof DEFAULT_TEMPERATURE_COEFFS) => TemperatureResult;
+/**
+ * Default temperature curve hues/coefficients for {@link hueTemperature}.
+ *
+ * @remarks
+ * The four values (all in [0,1] range) are to be giving in this order:
+ *
+ * - A: start hue of warm falloff
+ * - B: end hue of warm falloff
+ * - C: start hue of warm rise
+ * - D: end hue of warm rise
+ *
+ * Note: The hot point is fixed at 0 (aka red) and the cold point is fixed at
+ * 2/3 (= 0.666... aka blue), meaning C & D MUST be greater.
  */
-export declare const temperature: (colors: Iterable<ReadonlyVec>, minSat?: number) => TemperatureResult;
+export declare const DEFAULT_TEMPERATURE_COEFFS: [number, number, number, number];
 /**
  * Computes an abstract measure of a normalized "color temperature" ([-1,1]
  * range) for the given `hue` (in [0,1] range). Red/orange/yellow hues produce
@@ -122,6 +148,7 @@ export declare const temperature: (colors: Iterable<ReadonlyVec>, minSat?: numbe
  * input hue.
  *
  * @param hue
+ * @param coeffs
  */
-export declare const hueTemperature: (hue: number) => number;
+export declare const hueTemperature: (hue: number, [a, b, c, d]?: [number, number, number, number]) => number;
 //# sourceMappingURL=hues.d.ts.map

package/hues.js

@@ -1,11 +1,15 @@
 import { ensureArray } from "@thi.ng/arrays/ensure-array";
 import { compareByKey } from "@thi.ng/compare";
-import { roundTo, smoothStep, TAU } from "@thi.ng/math";
+import { TAU } from "@thi.ng/math/api";
 import { normFrequenciesAuto, repeat, transduce } from "@thi.ng/transducers";
 import { map } from "@thi.ng/transducers/map";
 import { mapcat } from "@thi.ng/transducers/mapcat";
 import { mean } from "@thi.ng/transducers/mean";
+import { minMax } from "@thi.ng/transducers/min-max";
+import { reduce } from "@thi.ng/transducers/reduce";
 import { circularMean } from "@thi.ng/vectors/circular";
+import { fract, roundTo } from "@thi.ng/math/prec";
+import { smoothStep } from "@thi.ng/math/step";
 function* selectHueRange(colors, minHue, maxHue, minSat) {
   const pred = __hueSelector(minHue, maxHue);
   for (let col of colors) {
@@ -60,7 +64,30 @@ const meanIntensity = (colors) => transduce(
   mean(),
   colors
 );
-const temperature = (colors, minSat = 0.2) => {
+const computeHueRange = (hues, mean2) => {
+  const range = reduce(minMax(), hues);
+  const [min, max] = range;
+  if (mean2 < min || mean2 > max) {
+    return [
+      hues.reduce(
+        (acc, x) => {
+          const d = fract(mean2 - x);
+          return d < 0.5 && d > acc[1] ? [x, d] : acc;
+        },
+        [max, fract(mean2 - max)]
+      )[0],
+      hues.reduce(
+        (acc, x) => {
+          const d = fract(x - mean2);
+          return d < 0.5 && d > acc[1] ? [x, d] : acc;
+        },
+        [min, fract(min - mean2)]
+      )[0]
+    ];
+  }
+  return range;
+};
+const temperature = (colors, minSat = 0.2, coeffs) => {
   const $colors = ensureArray(colors);
   const filtered = $colors.filter((x) => x[1] >= minSat);
   const area = filtered.length / $colors.length;
@@ -81,12 +108,20 @@ const temperature = (colors, minSat = 0.2) => {
     return { hues, meanHue: 0, temp: 0, areaTemp: 0, area: 0 };
   }
   const meanHue = circularMean(angles) / TAU;
-  const temp = hueTemperature(meanHue);
+  const temp = hueTemperature(meanHue, coeffs);
   const areaTemp = temp * area;
   return { hues, meanHue, temp, areaTemp, area };
 };
-const hueTemperature = (hue) => 2 * (hue < 2 / 3 ? smoothStep(0.6, 0.1, hue) : smoothStep(0.72, 0.92, hue)) - 1;
+const DEFAULT_TEMPERATURE_COEFFS = [
+  0.1,
+  0.6,
+  0.72,
+  0.92
+];
+const hueTemperature = (hue, [a, b, c, d] = DEFAULT_TEMPERATURE_COEFFS) => 2 * (hue < 2 / 3 ? smoothStep(b, a, hue) : smoothStep(c, d, hue)) - 1;
 export {
+  DEFAULT_TEMPERATURE_COEFFS,
+  computeHueRange,
   countHueRange,
   hueRangeArea,
   hueRangeAreaIntensity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/pixel-analysis",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Image color & feature analysis utilities",
   "type": "module",
   "module": "./index.js",
@@ -112,5 +112,5 @@
     "status": "beta",
     "year": 2024
   },
-  "gitHead": "b138ae2fb8567acfe724cc675654878f60d26631\n"
+  "gitHead": "77f9f42528ac3c6209429fb798e3be69f52fcff2\n"
 }