@thi.ng/pixel-analysis 0.4.5 → 1.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-07-21T08:21:58Z
+- **Last updated**: 2025-07-24T21:23:41Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,32 @@ 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.0.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-analysis@1.0.1) (2025-07-24)
+
+#### 🩹 Bug fixes
+
+- bail out if insufficient samples ([41ba4c3](https://github.com/thi-ng/umbrella/commit/41ba4c3))
+  - update `temperature()` to return empty result if insufficient color samples
+- update hue standard deviation ([9b0ea02](https://github.com/thi-ng/umbrella/commit/9b0ea02))
+  - return normalized hue SD (not in radians)
+
+# [1.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-analysis@1.0.0) (2025-07-24)
+
+#### 🛑 Breaking changes
+
+- major update/rewrite hue range analysis fns ([5730fea](https://github.com/thi-ng/umbrella/commit/5730fea))
+- BREAKING CHANGE: replace/update hue range analysis fns
+- major update/rewrite hue range analysis fns ([9b12898](https://github.com/thi-ng/umbrella/commit/9b12898))
+- BREAKING CHANGE: update AnalyzedImage result, update color analysis fns
+  - update structure & details of `AnalyzedImage` result type
+  - update `derivedColorsResults()`
+  - update/split `analyzeColors()`
+- replace temperature calculation ([2a23cfa](https://github.com/thi-ng/umbrella/commit/2a23cfa))
+- BREAKING CHANGE: replace temperature calculation with whole new approach
+  - replace existing `temperature()` with new method/approach
+  - add `TemperatureResult`
+  - update `analyzeColors()`, `derivedColorsResult()`
+
 ### [0.4.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/pixel-analysis@0.4.1) (2025-07-15)
 
 #### ♻️ Refactoring

package/README.md

@@ -30,23 +30,24 @@ Image color & feature analysis utilities. This is a support package for [@thi.ng
 ### Color analysis
 
 -   Dominant colors in different color modes/formats:
-    -   CSS
+    -   CSS (hex)
     -   sRGB
     -   HSV
     -   Oklch (perceptual)
 -   Normalized areas of dominant color clusters
--   Min/max HSV hue range of dominant colors
+-   Min/max HSV hue range of dominant colors (considering angular wrap-around)
 -   Min/max HSV saturation range of dominant colors
--   Min/max Oklch chroma range of dominant colors
 -   Min/max luminance range of dominant colors (obtained from SRGB)
 -   Min/max luminance range of entire grayscale image (obtained from SRGB)
--   Normalized warmth, i.e. the area-weighted intensity of "warm" colors in the image
+-   Average values for hue (circular mean), saturation, luminance
+-   Area-weighted average saturation of dominant colors
+-   Area-weighted average luminance of dominant colors
+-   Standard deviation for hue, saturation, luminance
+-   Normalized color temperature, incl. area-weighted indicator of "cold" vs
+    "warm" hues present
 -   Luminance contrast of dominant colors
 -   Luminance contrast of entire grayscale image
 -   Max. normalized WCAG color contrast of dominant colors
--   Average luminance of dominant colors, weighted by area
--   Average HSV saturation of dominant colors, weighted by area
--   Average Oklch chroma of dominant colors, weighted by area
 
 ## Status
 
@@ -80,11 +81,12 @@ For Node.js REPL:
 const pa = await import("@thi.ng/pixel-analysis");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.36 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.70 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
 - [@thi.ng/color](https://github.com/thi-ng/umbrella/tree/develop/packages/color)
 - [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
 - [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)

package/analyze-colors.d.ts

@@ -14,5 +14,5 @@ export declare const analyzeColors: (img: FloatBuffer | IntBuffer, opts?: Partia
  *
  * @param colors
  */
-export declare const derivedColorsResults: (colors: number[][]) => Pick<AnalyzedImage, "css" | "srgb" | "hsv" | "oklch" | "hueRange" | "satRange" | "chromaRange" | "lumaRange" | "contrast" | "colorContrast">;
+export declare const derivedColorsResult: (colors: number[][], minSat?: number) => Pick<AnalyzedImage, "css" | "srgb" | "hsv" | "oklch" | "mean" | "sd" | "range" | "contrast" | "colorContrast" | "temperature">;
 //# sourceMappingURL=analyze-colors.d.ts.map

package/analyze-colors.js

@@ -6,6 +6,7 @@ import { oklch } from "@thi.ng/color/oklch/oklch";
 import { srgb } from "@thi.ng/color/srgb/srgb";
 import { compareByKey } from "@thi.ng/compare/keys";
 import { compareNumDesc } from "@thi.ng/compare/numeric";
+import { TAU } from "@thi.ng/math/api";
 import { fit } from "@thi.ng/math/fit";
 import { dominantColorsKmeans } from "@thi.ng/pixel-dominant-colors/kmeans";
 import { FloatBuffer } from "@thi.ng/pixel/float";
@@ -20,30 +21,22 @@ 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 { roundN } from "@thi.ng/vectors/roundn";
-import { warmIntensityHsv } from "./hues.js";
+import { sd } from "@thi.ng/vectors/variance";
+import { temperature } from "./hues.js";
 const analyzeColors = (img, opts) => {
   let $img = img.format !== FLOAT_RGBA ? img.as(FLOAT_RGBA) : img;
-  if (opts?.size) {
-    const size = ~~opts.size;
-    let w = $img.width;
-    let h = $img.height;
-    [w, h] = w > h ? [size, ~~Math.max(1, h / w * size)] : [~~Math.max(1, w / h * size), size];
-    $img = $img.resize(w, h);
-  }
+  if (opts?.size) $img = __resize($img, opts.size);
   const imgGray = $img.as(FLOAT_GRAY);
   const imgHsv = $img.as(FLOAT_HSVA);
-  const dominantColors = opts?.dominantFn ?? dominantColorsKmeans;
-  const prec = opts?.prec ?? 1e-3;
-  const colors = dominantColors($img, opts?.numColors ?? 4).sort(compareByKey("area", compareNumDesc)).map((x) => {
-    roundN(null, x.color, prec);
-    return x;
-  });
+  const colors = __dominantColors($img, opts);
   const colorAreas = colors.map((x) => x.area);
-  const derived = derivedColorsResults(colors.map((x) => x.color));
+  const derived = derivedColorsResult(colors.map((x) => x.color));
   const lumaRangeImg = reduce(minMax(), imgGray.data);
-  const weightedLuma = dot(derived.lumaRange, colorAreas);
+  const weightedLuma = dot(derived.range.luma, colorAreas);
   const weightedChroma = dot(
     derived.oklch.map((x) => x[1]),
     colorAreas
@@ -58,7 +51,7 @@ const analyzeColors = (img, opts) => {
     imgHsv,
     ...derived,
     area: colorAreas,
-    warmth: warmIntensityHsv(imgHsv, opts?.minSat),
+    temperature: temperature(imgHsv, opts?.minSat),
     contrastImg: lumaRangeImg[1] - lumaRangeImg[0],
     lumaRangeImg,
     weightedSat,
@@ -66,42 +59,66 @@ const analyzeColors = (img, opts) => {
     weightedChroma
   };
 };
-const derivedColorsResults = (colors) => {
+const derivedColorsResult = (colors, minSat) => {
   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 satRange = transduce(pluck(1), minMax(), dominantHsv);
-  const chromaRange = transduce(pluck(1), minMax(), dominantOklch);
+  const $hueRange = transduce(pluck(0), minMax(), dominantHsv);
+  const hues = dominantHsv.map((x) => x[0] * 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 lumaRange = reduce(minMax(), dominantLuma);
-  const contrast = lumaRange[1] - lumaRange[0];
-  const colorContrast = fit(
-    transduce(
-      map((pair) => contrastWCAG(...pair)),
-      max(),
-      permutations(dominantSrgb, dominantSrgb)
-    ),
-    1,
-    21,
-    0,
-    1
-  );
   return {
     css: dominantCss,
     srgb: dominantSrgb,
     hsv: dominantHsv,
     oklch: dominantOklch,
-    hueRange,
-    satRange,
-    chromaRange,
-    lumaRange,
-    contrast,
-    colorContrast
+    mean: {
+      hue: meanHue,
+      sat: vmean(sats),
+      luma: vmean(dominantLuma)
+    },
+    sd: {
+      hue: circularSD(hues) / TAU,
+      sat: sd(sats),
+      luma: sd(dominantLuma)
+    },
+    range: {
+      hue: hueRange,
+      sat: reduce(minMax(), sats),
+      luma: lumaRange
+    },
+    contrast: lumaRange[1] - lumaRange[0],
+    colorContrast: fit(
+      transduce(
+        map((pair) => contrastWCAG(...pair)),
+        max(),
+        permutations(dominantSrgb, dominantSrgb)
+      ),
+      1,
+      21,
+      0,
+      1
+    ),
+    temperature: temperature(dominantHsv, minSat)
   };
 };
+const __dominantColors = (img, {
+  dominantFn = dominantColorsKmeans,
+  numColors = 4,
+  prec = 1e-3
+} = {}) => dominantFn(img, numColors).sort(compareByKey("area", compareNumDesc)).map((x) => (roundN(null, x.color, prec), x));
+const __resize = ($img, size) => {
+  size = ~~size;
+  let w = $img.width;
+  let h = $img.height;
+  [w, h] = w > h ? [size, ~~Math.max(1, h / w * size)] : [~~Math.max(1, w / h * size), size];
+  return $img.resize(w, h);
+};
 export {
   analyzeColors,
-  derivedColorsResults
+  derivedColorsResult
 };

package/api.d.ts

@@ -17,7 +17,7 @@ export interface AnalysisOpts {
      */
     size: number;
     /**
-     * Min. saturation to consider for computing {@link warmIntensity}.
+     * Min. saturation to consider for computing {@link temperature}.
      */
     minSat: number;
     /**
@@ -60,31 +60,60 @@ export interface AnalyzedImage {
      * Normalized areas of dominant color clusters
      */
     area: number[];
-    /**
-     * Min/max HSV hue range of dominant colors
-     */
-    hueRange: [number, number];
-    /**
-     * Min/max HSV saturation range of dominant colors
-     */
-    satRange: [number, number];
-    /**
-     * Min/max Oklch chroma range of dominant colors
-     */
-    chromaRange: [number, number];
-    /**
-     * Min/max luminance range of dominant colors (obtained from SRGB)
-     */
-    lumaRange: [number, number];
+    mean: {
+        /**
+         * Normalized mean hue (using circular mean).
+         */
+        hue: number;
+        /**
+         * Mean saturation
+         */
+        sat: number;
+        /**
+         * Mean luminance
+         */
+        luma: number;
+    };
+    sd: {
+        /**
+         * Circular standard deviation of normalized hues.
+         */
+        hue: number;
+        /**
+         * Standard deviation of normalized saturation.
+         */
+        sat: number;
+        /**
+         * Standard deviation of normalized luminance.
+         */
+        luma: number;
+    };
+    range: {
+        /**
+         * 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}.
+         */
+        hue: [number, number];
+        /**
+         * Min/max HSV saturation range of dominant colors
+         */
+        sat: [number, number];
+        /**
+         * Min/max luminance range of dominant colors (obtained from SRGB)
+         */
+        luma: [number, number];
+    };
     /**
      * Min/max luminance range of entire grayscale image (obtained from SRGB)
      */
     lumaRangeImg: [number, number];
     /**
-     * Normalized warmth, i.e. the area-weighted intensity of "warm" colors in
-     * the image (see {@link warmIntensity} and {@link AnalysisOpts.minSat}).
+     * Comprehensive {@link TemperatureResult} as produced by
+     * {@link temperature}. Also see {@link AnalysisOpts.minSat}.
      */
-    warmth: number;
+    temperature: TemperatureResult;
     /**
      * Luminance contrast of dominant colors (i.e. delta of
      * {@link AnalyzedImage.lumaRange}).
@@ -112,4 +141,34 @@ export interface AnalyzedImage {
      */
     weightedChroma: number;
 }
+/**
+ * Result type for {@link temparature}.
+ */
+export interface TemperatureResult {
+    /**
+     * Hue-based histogram (up to 12 bins), each item: `[hue, count]` (all
+     * normalized).
+     */
+    hues: [number, number][];
+    /**
+     * Normalized weighted mean hue, based on histogram distribution.
+     */
+    meanHue: number;
+    /**
+     * Normalized abstract color temperature (see {@link hueTemperature}) based
+     * on weighted {@link TemperatureResult.meanHue}. Red/orange/yellow hues
+     * produce results close to 1.0, cyan/blue/purple hues produce results
+     * closer to -1.0.
+     */
+    temp: number;
+    /**
+     * {@link TemperatureResult.temp} weighted by {@link TemperatureResult.area}
+     */
+    areaTemp: number;
+    /**
+     * Normalized area (percentage) of the filtered (sufficiently) saturated
+     * colors which were used to compute the histogram & temperature.
+     */
+    area: number;
+}
 //# sourceMappingURL=api.d.ts.map

package/hues.d.ts

@@ -1,44 +1,127 @@
-import type { FloatBuffer } from "@thi.ng/pixel/float";
-import type { IntBuffer } from "@thi.ng/pixel/int";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { TemperatureResult } from "./api.js";
 /**
- * Iterator yielding HSV pixel values/colors matching given hue range and
- * minimum saturation.
+ * Iterator consuming HSV colors and only yielding those matching given hue
+ * range and minimum saturation (all normalized in [0,1] range).
  *
- * @param img
+ * @remarks
+ * If given a pixel buffer as input, it MUST be in `FLOAT_HSVA` format.
+ *
+ * If `minHue` is greater than `maxHue`, the range will be interpreted to wrap
+ * around at 1. E.g. the range `[0.8, 0.2]` selects hues >= 0.8 and hues
+ * < 0.2.
+ *
+ * @param colors
+ * @param minHue
+ * @param maxHue
+ * @param minSat
+ */
+export declare function selectHueRange(colors: Iterable<ReadonlyVec>, minHue: number, maxHue: number, minSat: number): Generator<ReadonlyVec, void, unknown>;
+/**
+ * Similar to {@link selectHueRange}, but only yields indices/IDs of matching
+ * colors.
+ *
+ * @remarks
+ * See {@link selectHueRange} for details about hue ranges.
+ *
+ * @param colors
  * @param minHue
  * @param maxHue
  * @param minSat
  */
-export declare function selectHueRangeHsv(img: IntBuffer | FloatBuffer, minHue: number, maxHue: number, minSat: number): Generator<Uint8Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Uint8ClampedArray<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike>, void, unknown>;
+export declare function selectHueRangeIDs(colors: Iterable<ReadonlyVec>, minHue: number, maxHue: number, minSat: number): Generator<number, void, unknown>;
 /**
- * Similar to {@link selectHueRangeHsv}, but only returns a count of HSV pixel
- * values/colors matching given hue range and minimum saturation (all
- * normalized).
+ * Similar to {@link selectHueRange}, but only returns a count of inputs
+ * matching given hue range and minimum saturation (all normalized in [0,1]
+ * range).
  *
- * @param img
+ * @remarks
+ * See {@link selectHueRange} for details about hue ranges.
+ *
+ * @param colors
  * @param minHue
  * @param maxHue
  * @param minSat
  */
-export declare const countHueRangeHsv: (img: IntBuffer | FloatBuffer, minHue: number, maxHue: number, minSat: number) => number;
+export declare const countHueRange: (colors: Iterable<ReadonlyVec>, minHue: number, maxHue: number, minSat: number) => number;
+/**
+ * Takes a list of HSV colors, a list of min/max hue ranges and a min saturation
+ * (all normalized in [0,1] range). Computes the normalized area of all matching
+ * colors.
+ *
+ * @remarks
+ * If given a pixel buffer as input, it MUST be in `FLOAT_HSVA` format. Also see
+ * {@link temperature}.
+ *
+ * See {@link selectHueRange} for details about hue ranges.
+ *
+ * @param colors
+ * @param hueRanges
+ * @param minSat
+ */
+export declare const hueRangeArea: (colors: Iterable<ReadonlyVec>, hueRanges: [number, number][], minSat?: number) => number;
 /**
  * Takes a list of hue ranges and computes the area-weighted mean intensity of
- * matching pixels in the given image. Also see {@link warmIntensityHsv}.
+ * matching pixels in the given image. Also see {@link temperatureIntensity}.
  *
  * @remarks
+ * If given a pixel buffer as input, it MUST be in `FLOAT_HSVA` format.
+ *
  * Intensity here means the product of HSV `saturation * brightness`.
  *
- * @param img
- * @param hues
+ * See {@link selectHueRange} for details about hue ranges.
+ *
+ * @param colors
+ * @param hueRanges
  * @param minSat
  */
-export declare const hueRangeIntensityHsv: (img: IntBuffer | FloatBuffer, hues: [number, number][], minSat?: number) => number;
+export declare const hueRangeAreaIntensity: (colors: Iterable<ReadonlyVec>, hueRanges: [number, number][], minSat?: number) => number;
+/**
+ * Computes the average intensity of given HSV colors. Intensity here means the
+ * product of `saturation * value` (ignoring hues).
+ *
+ * @remarks
+ * If given a pixel buffer as input, it MUST be in `FLOAT_HSVA` format.
+ *
+ * @param colors
+ */
+export declare const meanIntensity: (colors: Iterable<ReadonlyVec>) => number;
 /**
- * Syntax sugar for {@link hueRangeIntensityHsv} to compute the area-weighted mean
- * intensity of pixels in the yellow/orange/red hue ranges.
+ * 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
+ * colder/blue-ish colors present.
  *
- * @param img
+ * @remarks
+ * Computation is as follows:
+ * - Discard colors with lower saturation than given `minSat`
+ * - Compute normalized area (percentage) of qualifying saturated colors
+ * - Compute the histogram for 12 evenly spread hues
+ * - Produce a weighted list of hue angles, based on histogram
+ * - Compute circular mean of hue angles
+ * - Use {@link hueTemperature} to compute normalized temperature in [-1,1] range
+ * - Scale temparature by normlized area
+ * - Return object of the various result metrics
+ *
+ * If given a pixel buffer as input, it MUST be in `FLOAT_HSVA` format.
+ *
+ * Also see {@link temperatureIntensity}.
+ *
+ * @param colors
  * @param minSat
  */
-export declare const warmIntensityHsv: (img: IntBuffer | FloatBuffer, minSat?: number) => number;
+export declare const temperature: (colors: Iterable<ReadonlyVec>, minSat?: number) => TemperatureResult;
+/**
+ * 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
+ * results close to 1.0, cyan/blue/purple-ish hues produce results closer to
+ * -1.0.
+ *
+ * @remarks
+ * Uses one of two smoothstep curves for non-linear interpolation, depending on
+ * input hue.
+ *
+ * @param hue
+ */
+export declare const hueTemperature: (hue: number) => number;
 //# sourceMappingURL=hues.d.ts.map

package/hues.js

@@ -1,56 +1,98 @@
-import { FLOAT_HSVA } from "@thi.ng/pixel/format/float-hsva";
+import { ensureArray } from "@thi.ng/arrays/ensure-array";
+import { compareByKey } from "@thi.ng/compare";
+import { roundTo, smoothStep, TAU } from "@thi.ng/math";
+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 { transduce } from "@thi.ng/transducers/transduce";
-function* selectHueRangeHsv(img, minHue, maxHue, minSat) {
-  if (img.format !== FLOAT_HSVA) img = img.as(FLOAT_HSVA);
-  const {
-    data,
-    stride: [stride]
-  } = img;
-  const pred = minHue <= maxHue ? (i) => data[i] >= minHue && data[i] < maxHue : (i) => data[i] >= minHue || data[i] < maxHue;
-  for (let i = 0, n = data.length; i < n; i += stride) {
-    if (data[i + 1] >= minSat && pred(i)) yield data.subarray(i, i + 4);
+import { circularMean } from "@thi.ng/vectors/circular";
+function* selectHueRange(colors, minHue, maxHue, minSat) {
+  const pred = __hueSelector(minHue, maxHue);
+  for (let col of colors) {
+    if (col[1] >= minSat && pred(col[0])) yield col;
   }
 }
-const countHueRangeHsv = (img, minHue, maxHue, minSat) => {
-  if (img.format !== FLOAT_HSVA) img = img.as(FLOAT_HSVA);
-  const {
-    data,
-    stride: [stride]
-  } = img;
-  const pred = minHue <= maxHue ? (i) => data[i] >= minHue && data[i] < maxHue : (i) => data[i] >= minHue || data[i] < maxHue;
+function* selectHueRangeIDs(colors, minHue, maxHue, minSat) {
+  const pred = __hueSelector(minHue, maxHue);
+  let id = 0;
+  for (let col of colors) {
+    if (col[1] >= minSat && pred(col[0])) yield id;
+    id++;
+  }
+}
+const countHueRange = (colors, minHue, maxHue, minSat) => {
+  const pred = __hueSelector(minHue, maxHue);
   let count = 0;
-  for (let i = 0, n = data.length; i < n; i += stride) {
-    if (data[i + 1] >= minSat && pred(i)) count++;
+  for (let col of colors) {
+    if (col[1] >= minSat && pred(col[0])) count++;
   }
   return count;
 };
-const hueRangeIntensityHsv = (img, hues, minSat = 0.2) => {
-  if (img.format !== FLOAT_HSVA) img = img.as(FLOAT_HSVA);
-  const selected = [
-    ...mapcat((range) => selectHueRangeHsv(img, ...range, minSat), hues)
-  ];
-  const area = selected.length / (img.data.length / 4);
+const __hueSelector = (min, max) => min <= max ? (h) => h >= min && h < max : (h) => h >= min || h < max;
+const hueRangeArea = (colors, hueRanges, minSat = 0.2) => {
+  const $img = ensureArray(colors);
+  const selected = new Set(
+    mapcat((range) => selectHueRangeIDs($img, ...range, minSat), hueRanges)
+  );
+  return selected.size / $img.length;
+};
+const hueRangeAreaIntensity = (colors, hueRanges, minSat = 0.2) => {
+  const $colors = ensureArray(colors);
+  const selected = new Set(
+    mapcat(
+      (range) => selectHueRangeIDs($colors, ...range, minSat),
+      hueRanges
+    )
+  );
+  const area = selected.size / $colors.length;
   const intensity = transduce(
-    map((x) => x[1] * x[2]),
+    map((id) => {
+      const color = $colors[id];
+      return color[1] * color[2];
+    }),
     mean(),
     selected
   );
   return intensity * area;
 };
-const warmIntensityHsv = (img, minSat) => hueRangeIntensityHsv(
-  img,
-  [
-    [345 / 360, 55 / 360]
-    // red, orange, yellow
-  ],
-  minSat
+const meanIntensity = (colors) => transduce(
+  map((x) => x[1] * x[2]),
+  mean(),
+  colors
 );
+const temperature = (colors, minSat = 0.2) => {
+  const $colors = ensureArray(colors);
+  const filtered = $colors.filter((x) => x[1] >= minSat);
+  const area = filtered.length / $colors.length;
+  const hues = [
+    ...transduce(
+      map((x) => roundTo(x[0], 1 / 12) % 1),
+      normFrequenciesAuto(),
+      filtered
+    )
+  ].sort(compareByKey(0));
+  const angles = [
+    ...mapcat(([hue, num]) => {
+      num *= 50;
+      return num >= 1 ? repeat(hue * TAU, num) : null;
+    }, hues)
+  ];
+  if (!angles.length) {
+    return { hues, meanHue: 0, temp: 0, areaTemp: 0, area: 0 };
+  }
+  const meanHue = circularMean(angles) / TAU;
+  const temp = hueTemperature(meanHue);
+  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;
 export {
-  countHueRangeHsv,
-  hueRangeIntensityHsv,
-  selectHueRangeHsv,
-  warmIntensityHsv
+  countHueRange,
+  hueRangeArea,
+  hueRangeAreaIntensity,
+  hueTemperature,
+  meanIntensity,
+  selectHueRange,
+  selectHueRangeIDs,
+  temperature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/pixel-analysis",
-  "version": "0.4.5",
+  "version": "1.0.1",
   "description": "Image color & feature analysis utilities",
   "type": "module",
   "module": "./index.js",
@@ -40,14 +40,15 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.11.32",
-    "@thi.ng/color": "^5.7.50",
+    "@thi.ng/arrays": "^2.13.5",
+    "@thi.ng/color": "^5.7.51",
     "@thi.ng/compare": "^2.4.24",
     "@thi.ng/math": "^5.11.32",
     "@thi.ng/pixel": "^7.5.4",
     "@thi.ng/pixel-convolve": "^1.1.4",
-    "@thi.ng/pixel-dominant-colors": "^2.0.5",
+    "@thi.ng/pixel-dominant-colors": "^2.0.6",
     "@thi.ng/transducers": "^9.6.3",
-    "@thi.ng/vectors": "^8.4.1"
+    "@thi.ng/vectors": "^8.5.0"
   },
   "devDependencies": {
     "esbuild": "^0.25.8",
@@ -64,10 +65,14 @@
     "gradient",
     "grayscale",
     "hsv",
+    "hue",
     "luminance",
+    "mean",
     "oklch",
     "rgb",
     "saturation",
+    "standard-deviation",
+    "statistics",
     "temperature",
     "typescript"
   ],
@@ -107,5 +112,5 @@
     "status": "beta",
     "year": 2024
   },
-  "gitHead": "11747c482773d3da03c8b7848b25a56251ccd759\n"
+  "gitHead": "98bec7f990466d4771d8580362d4bdd58ffeea63\n"
 }