@chestnutlabs/gcode-colors 0.3.0

package/README.md

@@ -0,0 +1,43 @@
+# @chestnutlabs/gcode-colors
+
+Renderer-agnostic **per-segment color model** for the [Chestnut Labs G-code Preview](https://github.com/ChestnutLabs/gcode-preview) toolpath stack (DD-014 D3).
+
+This package is the single home for the toolpath **color subsystem**: the `ColorMode` union and an
+honest, capability-gated mapping from a `ToolpathIR` segment to an `RGB` triple. Both the Three.js
+renderer (`@chestnutlabs/gcode-renderer-three`) and the low-resource 2D renderer
+(`@chestnutlabs/gcode-renderer-2d`) depend on it, so color and move-kind semantics never drift
+between them.
+
+It depends only on `@chestnutlabs/toolpath-core` — **no `three`, no canvas, no framework**.
+
+## Color modes
+
+| Mode | Channel | Honest fallback |
+|---|---|---|
+| `single` | — | n/a (one color) |
+| `tool` | `segments.tool` | `fallback` when no palette |
+| `feature` | `segments.feature` (0 = unknown) | `fallback` for unknown / no palette |
+| `colorChange` | `colorChanges[]` swap slot (M600, #147) | `fallback` when no changes / no palette |
+| `feedrate` | `segments.feedrate` (mm/min; NaN = unknown, #177) | `fallback` for NaN |
+| `object` | `segments.object` (1-based; 0 = none, #178) | `fallback` for none / non-`only` |
+
+Every mode degrades to its `fallback` for unknown channel values — it never fabricates a
+role/speed/object color. Modes that read an optional channel (`feature`, `object`, `feedrate`) must
+be **capability-gated by the caller** before use.
+
+## Usage
+
+```ts
+import { createSegmentColorer } from '@chestnutlabs/gcode-colors';
+
+// Build a colorer once (feedrate auto-range is resolved here), then O(1) per segment.
+const colorOf = createSegmentColorer(ir, { mode: 'feedrate', ramp: [[0, 0, 1], [1, 0, 0]], fallback: [0.7, 0.7, 0.7] });
+for (let i = 0; i < ir.segments.count; i++) {
+  const [r, g, b] = colorOf(i);
+  // …map onto your surface (WebGL vertex buffer, Canvas 2D strokeStyle, …)
+}
+```
+
+## License
+
+MIT © Chestnut Labs. See the [repository](https://github.com/ChestnutLabs/gcode-preview) for provenance and the full support policy.

package/dist/colors.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Renderer-agnostic per-segment color model (DD-014 D3, extracted from
+ * `gcode-renderer-three` so the 3D and 2D renderers single-source it).
+ *
+ * A color is a pure function of the IR's channels (`tool`/`feature`/`object`/
+ * `feedrate`/`colorChanges`) and a consumer palette — no `three`, no canvas, no
+ * geometry. Each renderer maps the returned {@link RGB} onto its own surface
+ * (a vertex-color buffer for WebGL, a `strokeStyle` for Canvas 2D).
+ *
+ * Honesty is built in: unknown channel values degrade to the mode's `fallback`
+ * (or the neutral default), never a fabricated role/speed/object color. Modes
+ * that read an optional channel (`feature`, `object`, `feedrate`) must be
+ * capability-gated by the caller before use — the IR is told, not shown nonsense.
+ */
+import type { ToolpathIR } from '@chestnutlabs/toolpath-core';
+export type RGB = [number, number, number];
+export type ColorMode = {
+    mode: 'single';
+    color: RGB;
+} | {
+    mode: 'tool';
+    palette: RGB[];
+    fallback?: RGB;
+} | {
+    mode: 'feature';
+    palette: RGB[];
+    fallback: RGB;
+} | {
+    mode: 'colorChange';
+    palette: RGB[];
+    fallback: RGB;
+} | {
+    mode: 'feedrate';
+    ramp: RGB[];
+    range?: [number, number];
+    fallback: RGB;
+} | {
+    mode: 'object';
+    palette: RGB[];
+    fallback: RGB;
+    only?: number;
+} | {
+    mode: 'layerHeight';
+    ramp: RGB[];
+    range?: [number, number];
+    fallback: RGB;
+};
+/** Neutral color used when a mode has no palette / the channel value is unknown. */
+export declare const DEFAULT_FALLBACK: RGB;
+/** Min/max of the IR's defined (non-NaN) feedrates — the auto-range for color-by-speed (#177). */
+export declare function feedrateRange(ir: ToolpathIR): [number, number];
+/**
+ * Per-layer height (mm): the Z-delta from the previous layer, indexed by layer. Layer 0's height is
+ * its absolute Z (its thickness from the bed). Negative deltas (non-monotonic Z, e.g. spiral/vase
+ * synthetic layers) clamp to 0 rather than fabricate a negative height. Derived only from `ir.layers`.
+ */
+export declare function layerHeights(ir: ToolpathIR): Float32Array;
+/** Min/max per-layer height — the auto-range for color-by-layer-height (#179). */
+export declare function layerHeightRange(ir: ToolpathIR): [number, number];
+/** Sample a color ramp at t∈[0,1] with linear interpolation between stops. */
+export declare function rampColor(ramp: RGB[], t: number): RGB;
+/** Per-segment RGB accessor — the loop-friendly form both renderers use. */
+export type SegmentColorer = (segIndex: number) => RGB;
+/**
+ * Build a per-segment color accessor for `ir` under `mode`. Feedrate auto-range (or the
+ * explicit `range`) is resolved once here, so the returned function is O(1) per segment.
+ * The returned RGB is honest: unknown channel values yield the mode's fallback.
+ */
+export declare function createSegmentColorer(ir: ToolpathIR, mode: ColorMode): SegmentColorer;
+/**
+ * The color of a single segment under `mode`. Convenience over {@link createSegmentColorer}
+ * for one-off lookups; for a loop, build a colorer once (feedrate auto-range is otherwise
+ * rescanned per call).
+ */
+export declare function segmentColor(ir: ToolpathIR, mode: ColorMode, segIndex: number): RGB;
+//# sourceMappingURL=colors.d.ts.map

package/dist/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3C,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,GAAG,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAA;CAAE,GAItD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,GAAG,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAA;CAAE,GAG1E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAKhE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,GAAG,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAA;CAAE,CAAC;AAElF,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,EAAE,GAAqB,CAAC;AAErD,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAW9D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,GAAG,YAAY,CAOzD;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CASjE;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,GAAG,CAWrD;AAkBD,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,GAAG,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,cAAc,CAwDpF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAEnF"}

package/dist/colors.js

@@ -0,0 +1,146 @@
+/** Neutral color used when a mode has no palette / the channel value is unknown. */
+export const DEFAULT_FALLBACK = [0.7, 0.7, 0.7];
+/** Min/max of the IR's defined (non-NaN) feedrates — the auto-range for color-by-speed (#177). */
+export function feedrateRange(ir) {
+    const f = ir.segments.feedrate;
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < f.length; i++) {
+        const v = f[i];
+        if (Number.isNaN(v))
+            continue;
+        if (v < min)
+            min = v;
+        if (v > max)
+            max = v;
+    }
+    return min <= max ? [min, max] : [0, 0];
+}
+/**
+ * Per-layer height (mm): the Z-delta from the previous layer, indexed by layer. Layer 0's height is
+ * its absolute Z (its thickness from the bed). Negative deltas (non-monotonic Z, e.g. spiral/vase
+ * synthetic layers) clamp to 0 rather than fabricate a negative height. Derived only from `ir.layers`.
+ */
+export function layerHeights(ir) {
+    const layers = ir.layers;
+    const h = new Float32Array(layers.length);
+    for (let i = 0; i < layers.length; i++) {
+        h[i] = i === 0 ? Math.max(0, layers[0].z) : Math.max(0, layers[i].z - layers[i - 1].z);
+    }
+    return h;
+}
+/** Min/max per-layer height — the auto-range for color-by-layer-height (#179). */
+export function layerHeightRange(ir) {
+    const h = layerHeights(ir);
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < h.length; i++) {
+        if (h[i] < min)
+            min = h[i];
+        if (h[i] > max)
+            max = h[i];
+    }
+    return min <= max ? [min, max] : [0, 0];
+}
+/** Sample a color ramp at t∈[0,1] with linear interpolation between stops. */
+export function rampColor(ramp, t) {
+    if (ramp.length === 0)
+        return DEFAULT_FALLBACK;
+    if (ramp.length === 1)
+        return ramp[0];
+    const clamped = t < 0 ? 0 : t > 1 ? 1 : t;
+    const p = clamped * (ramp.length - 1);
+    const lo = Math.floor(p);
+    const hi = Math.min(lo + 1, ramp.length - 1);
+    const frac = p - lo;
+    const a = ramp[lo];
+    const b = ramp[hi];
+    return [a[0] + (b[0] - a[0]) * frac, a[1] + (b[1] - a[1]) * frac, a[2] + (b[2] - a[2]) * frac];
+}
+/**
+ * Swap slot at a segment index (DD-009 D2, #147): the count of M600 color changes at
+ * or before it. `colorChanges` is ascending by `segIndex` (source order), so this is a
+ * binary upper-bound — decimation-safe (slots are keyed on the original segment index).
+ */
+function swapSlotAt(colorChanges, segIndex) {
+    let lo = 0;
+    let hi = colorChanges.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (colorChanges[mid].segIndex <= segIndex)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/**
+ * Build a per-segment color accessor for `ir` under `mode`. Feedrate auto-range (or the
+ * explicit `range`) is resolved once here, so the returned function is O(1) per segment.
+ * The returned RGB is honest: unknown channel values yield the mode's fallback.
+ */
+export function createSegmentColorer(ir, mode) {
+    const seg = ir.segments;
+    if (mode.mode === 'single') {
+        const c = mode.color;
+        return () => c;
+    }
+    if (mode.mode === 'tool') {
+        const fallback = mode.fallback ?? DEFAULT_FALLBACK;
+        return (i) => (mode.palette.length > 0 ? mode.palette[seg.tool[i] % mode.palette.length] : fallback);
+    }
+    if (mode.mode === 'feature') {
+        // Feature 0 = unknown (DD-001): fallback color, never a fabricated role color.
+        return (i) => {
+            const feature = seg.feature[i];
+            return feature === 0 || mode.palette.length === 0
+                ? mode.fallback
+                : mode.palette[(feature - 1) % mode.palette.length];
+        };
+    }
+    if (mode.mode === 'colorChange') {
+        // Shade by swap slot, not by seg.tool — the "reuse by-tool coloring" of DD-009 D2, keyed on the
+        // M600 count. Slot 0 = base filament = palette[0]. With no color changes (or no palette) use the
+        // neutral fallback, never a fabricated slot color.
+        return (i) => ir.colorChanges.length === 0 || mode.palette.length === 0
+            ? mode.fallback
+            : mode.palette[swapSlotAt(ir.colorChanges, i) % mode.palette.length];
+    }
+    if (mode.mode === 'feedrate') {
+        const [lo, hi] = mode.range ?? feedrateRange(ir);
+        const span = hi - lo;
+        // NaN feedrate (before the first F) → fallback, never a fabricated speed color (#177).
+        return (i) => {
+            const v = seg.feedrate[i];
+            return Number.isNaN(v) ? mode.fallback : rampColor(mode.ramp, span > 0 ? (v - lo) / span : 0);
+        };
+    }
+    if (mode.mode === 'layerHeight') {
+        // Precompute per-layer heights once → O(1) per segment (#179). An out-of-range layer index
+        // (shouldn't happen; a hostile IR) → fallback, never a fabricated height color.
+        const heights = layerHeights(ir);
+        const [lo, hi] = mode.range ?? layerHeightRange(ir);
+        const span = hi - lo;
+        return (i) => {
+            const li = seg.layer[i];
+            if (li < 0 || li >= heights.length)
+                return mode.fallback;
+            return rampColor(mode.ramp, span > 0 ? (heights[li] - lo) / span : 0);
+        };
+    }
+    // object mode: object 0 = none/unknown → fallback; `only` isolates one object, dimming the rest (#178).
+    return (i) => {
+        const obj = seg.object[i];
+        return obj === 0 || (mode.only !== undefined && obj !== mode.only) || mode.palette.length === 0
+            ? mode.fallback
+            : mode.palette[(obj - 1) % mode.palette.length];
+    };
+}
+/**
+ * The color of a single segment under `mode`. Convenience over {@link createSegmentColorer}
+ * for one-off lookups; for a loop, build a colorer once (feedrate auto-range is otherwise
+ * rescanned per call).
+ */
+export function segmentColor(ir, mode, segIndex) {
+    return createSegmentColorer(ir, mode)(segIndex);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @chestnutlabs/gcode-colors — renderer-agnostic per-segment color model (DD-014 D3).
+ *
+ * The single home for the toolpath color subsystem: the {@link ColorMode} union and an
+ * honest, capability-gated mapping from a `ToolpathIR` segment to an {@link RGB}. Both the
+ * Three.js renderer and the low-resource 2D renderer depend on this package so color/kind
+ * semantics never drift between them. Depends only on `@chestnutlabs/toolpath-core` — no
+ * `three`, no canvas, no framework.
+ */
+export type { RGB, ColorMode, SegmentColorer } from './colors.js';
+export { DEFAULT_FALLBACK, feedrateRange, layerHeights, layerHeightRange, rampColor, createSegmentColorer, segmentColor } from './colors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,YAAY,EAAE,GAAG,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,oBAAoB,EACpB,YAAY,EACb,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { DEFAULT_FALLBACK, feedrateRange, layerHeights, layerHeightRange, rampColor, createSegmentColorer, segmentColor } from './colors.js';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@chestnutlabs/gcode-colors",
+  "version": "0.3.0",
+  "description": "Renderer-agnostic per-segment color model for the Chestnut Labs G-code toolpath stack (DD-014 D3): the ColorMode union and honest, capability-gated segment coloring over ToolpathIR channels, shared by the 3D and 2D renderers.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "color",
+    "colormap",
+    "visualization"
+  ],
+  "author": "Chestnut Labs",
+  "homepage": "https://github.com/ChestnutLabs/gcode-preview#readme",
+  "bugs": "https://github.com/ChestnutLabs/gcode-preview/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChestnutLabs/gcode-preview.git",
+    "directory": "packages/gcode-colors"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chestnutlabs/toolpath-core": "0.3.0"
+  }
+}