@freshcoat-js/for-print 0.1.0

package/src/measure.js

@@ -0,0 +1,274 @@
+// Reading a printed chart back out of a photograph.
+//
+// What this produces is CAMERA-SPACE, normalized to the bare card in the same
+// shot — not colorimetry. That is deliberate and it is enough for the questions a
+// card printer actually raises: is there a cast, where does a ramp stop
+// responding, which hues come back turned. Each of those is a comparison between
+// patches in one photograph, so the capture device's own response cancels and no
+// reference target is needed. Absolute color would need one; these do not.
+//
+// The bare-stock patches are what make it work. On a dye-sub ribbon white means
+// "lay down no dye", so those patches are the unprinted card, photographed under
+// exactly the lighting everything else was. Dividing by them cancels the camera's
+// white balance and the light's own color at once.
+// Solve Ax = b by Gaussian elimination with partial pivoting. Small and dense —
+// the system here is 8×8.
+function solve(a, b) {
+    const n = b.length;
+    const m = a.map((row, i) => [...row, b[i]]);
+    for (let col = 0; col < n; col++) {
+        let pivot = col;
+        for (let r = col + 1; r < n; r++) {
+            if (Math.abs(m[r][col]) > Math.abs(m[pivot][col]))
+                pivot = r;
+        }
+        if (Math.abs(m[pivot][col]) < 1e-12)
+            return null; // degenerate
+        [m[col], m[pivot]] = [m[pivot], m[col]];
+        for (let r = 0; r < n; r++) {
+            if (r === col)
+                continue;
+            const f = m[r][col] / m[col][col];
+            for (let c = col; c <= n; c++)
+                m[r][c] -= f * m[col][c];
+        }
+    }
+    return m.map((row, i) => row[n] / row[i]);
+}
+// Whether four points actually describe a card: a convex quadrilateral with real
+// area, taken in order.
+//
+// The linear solve is not enough on its own to reject a bad set of picks. Four
+// points on a line have a perfectly good projective map onto them — the one that
+// collapses the plane onto that line — so the system solves, every patch samples
+// somewhere inside the image, and the reader returns confident nonsense. Same for
+// corners clicked out of order: that maps the card onto a bow tie, folded through
+// itself, and again every sample lands on real pixels.
+//
+// Both are checked here instead, where "is this a card" is a question about the
+// four points rather than about a matrix.
+function isProperQuad(p) {
+    const xs = p.map((q) => q.x);
+    const ys = p.map((q) => q.y);
+    const extent = Math.max(Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys));
+    if (extent <= 0)
+        return false;
+    // Shoelace area. Scaled against the extent so the test is about shape, not
+    // about how big in the frame the card happened to be.
+    let twiceArea = 0;
+    for (let i = 0; i < 4; i++) {
+        const a = p[i];
+        const b = p[(i + 1) % 4];
+        twiceArea += a.x * b.y - b.x * a.y;
+    }
+    if (Math.abs(twiceArea) / 2 < extent * extent * 0.01)
+        return false;
+    // Every corner turning the same way — convex, and in order.
+    let winding = 0;
+    for (let i = 0; i < 4; i++) {
+        const a = p[i];
+        const b = p[(i + 1) % 4];
+        const c = p[(i + 2) % 4];
+        const cross = (b.x - a.x) * (c.y - b.y) - (b.y - a.y) * (c.x - b.x);
+        if (cross === 0)
+            return false;
+        const turn = Math.sign(cross);
+        if (winding === 0)
+            winding = turn;
+        else if (turn !== winding)
+            return false;
+    }
+    return true;
+}
+// The transform taking the chart's four registration points to the four points
+// picked in the photo, both clockwise from top-left. Null if the picks do not
+// describe a card — collinear, out of order, or two of them the same.
+export function homographyFrom(from, to) {
+    if (!isProperQuad(from) || !isProperQuad(to))
+        return null;
+    const a = [];
+    const b = [];
+    for (let i = 0; i < 4; i++) {
+        const { x, y } = from[i];
+        const { x: u, y: v } = to[i];
+        a.push([x, y, 1, 0, 0, 0, -x * u, -y * u]);
+        b.push(u);
+        a.push([0, 0, 0, x, y, 1, -x * v, -y * v]);
+        b.push(v);
+    }
+    const h = solve(a, b);
+    return h ? [...h, 1] : null;
+}
+export function applyHomography(h, p) {
+    const w = h[6] * p.x + h[7] * p.y + h[8];
+    return {
+        x: (h[0] * p.x + h[1] * p.y + h[2]) / w,
+        y: (h[3] * p.x + h[4] * p.y + h[5]) / w,
+    };
+}
+const median = (xs) => {
+    if (xs.length === 0)
+        return 0;
+    const s = [...xs].sort((p, q) => p - q);
+    const mid = s.length >> 1;
+    return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+};
+// Fraction of a patch's width/height actually sampled, centered. Keeps the
+// reader off the edges, where a patch bleeds into its neighbour and a slight
+// misregistration would otherwise mix two colors into one reading.
+const SAMPLE_INSET = 0.6;
+// Samples per axis inside that window.
+const SAMPLE_GRID = 7;
+// The median of a patch's samples. Median rather than mean because glossy PVC
+// throws specular highlights: a few blown pixels drag a mean a long way and leave
+// a median where it was.
+function samplePatch(image, h, patch) {
+    const rs = [];
+    const gs = [];
+    const bs = [];
+    const x0 = patch.x + (patch.width * (1 - SAMPLE_INSET)) / 2;
+    const y0 = patch.y + (patch.height * (1 - SAMPLE_INSET)) / 2;
+    const w = patch.width * SAMPLE_INSET;
+    const hgt = patch.height * SAMPLE_INSET;
+    for (let iy = 0; iy < SAMPLE_GRID; iy++) {
+        for (let ix = 0; ix < SAMPLE_GRID; ix++) {
+            const p = applyHomography(h, {
+                x: x0 + (w * (ix + 0.5)) / SAMPLE_GRID,
+                y: y0 + (hgt * (iy + 0.5)) / SAMPLE_GRID,
+            });
+            const px = Math.round(p.x);
+            const py = Math.round(p.y);
+            if (px < 0 || py < 0 || px >= image.width || py >= image.height)
+                continue;
+            const o = (py * image.width + px) * 4;
+            rs.push(image.data[o]);
+            gs.push(image.data[o + 1]);
+            bs.push(image.data[o + 2]);
+        }
+    }
+    if (rs.length === 0)
+        return null;
+    return [median(rs), median(gs), median(bs)];
+}
+// Read every patch of a chart out of a photograph. `corners` are the four
+// fiducial centers as picked in the image, clockwise from top-left.
+export function readChart(image, spec, corners) {
+    const h = homographyFrom(spec.registration, corners);
+    if (!h)
+        return null;
+    const raw = new Map();
+    const missed = [];
+    for (const patch of spec.patches) {
+        if (patch.role === "fiducial")
+            continue;
+        const v = samplePatch(image, h, patch);
+        if (v)
+            raw.set(patch.id, v);
+        else
+            missed.push(patch.id);
+    }
+    // The white reference: the median of the bare-stock patches, so one blown or
+    // shadowed corner doesn't set the balance for the whole card.
+    const stockValues = spec.patches
+        .filter((p) => p.role === "stock")
+        .map((p) => raw.get(p.id))
+        .filter((v) => !!v);
+    const stock = stockValues.length
+        ? [
+            median(stockValues.map((v) => v[0])),
+            median(stockValues.map((v) => v[1])),
+            median(stockValues.map((v) => v[2])),
+        ]
+        : [255, 255, 255];
+    // Per-channel gain that lands the bare card on neutral, keeping its level. Any
+    // color left in a patch after this is the print's, not the light's.
+    const level = (stock[0] + stock[1] + stock[2]) / 3;
+    const gain = stock.map((c) => (c > 0 ? level / c : 1));
+    const stockClipped = stock.some((c) => c >= 254 || c <= 1);
+    // Measured before the gain is applied: the gain is one number for the whole
+    // card, so it shifts every stock patch together and cannot change how far apart
+    // they are.
+    const lightSpread = stockValues.length
+        ? Math.max(...[0, 1, 2].map((c) => {
+            const vs = stockValues.map((v) => v[c]);
+            return Math.max(...vs) - Math.min(...vs);
+        }))
+        : 0;
+    const patches = [];
+    for (const patch of spec.patches) {
+        if (patch.role === "fiducial")
+            continue;
+        const v = raw.get(patch.id);
+        if (!v)
+            continue;
+        patches.push({
+            id: patch.id,
+            role: patch.role,
+            sent: patch.rgb,
+            raw: v,
+            measured: [v[0] * gain[0], v[1] * gain[1], v[2] * gain[2]],
+            ...(patch.repeatOf ? { repeatOf: patch.repeatOf } : {}),
+        });
+    }
+    return {
+        chartId: spec.id,
+        patches,
+        stock,
+        stockClipped,
+        lightSpread,
+        missed,
+    };
+}
+// ── Reading the reading ────────────────────────────────────────────────────
+// The color left in patches that were sent neutral, per channel, as a signed
+// deviation from their own mean. A printer with no cast reads ~0 across the
+// board; the sign says which way each channel runs. This is the number that
+// answers "why does everything look magenta".
+export function grayCast(reading) {
+    const grays = reading.patches.filter((p) => p.role === "measure" &&
+        p.sent[0] === p.sent[1] &&
+        p.sent[1] === p.sent[2]);
+    if (grays.length === 0)
+        return [0, 0, 0];
+    const sum = [0, 0, 0];
+    for (const p of grays) {
+        const mean = (p.measured[0] + p.measured[1] + p.measured[2]) / 3;
+        sum[0] += p.measured[0] - mean;
+        sum[1] += p.measured[1] - mean;
+        sum[2] += p.measured[2] - mean;
+    }
+    return [sum[0] / grays.length, sum[1] / grays.length, sum[2] / grays.length];
+}
+// The largest disagreement between any patch and a repeat of it, in levels. This
+// is the sheet's evenness, and it bounds what a profile built from the card can
+// be worth — a printer that varies more than it corrects is not ready to profile.
+export function repeatSpread(reading) {
+    const byId = new Map(reading.patches.map((p) => [p.id, p]));
+    let worst = 0;
+    for (const p of reading.patches) {
+        if (!p.repeatOf)
+            continue;
+        const base = byId.get(p.repeatOf);
+        if (!base)
+            continue;
+        for (let c = 0; c < 3; c++) {
+            worst = Math.max(worst, Math.abs(p.measured[c] - base.measured[c]));
+        }
+    }
+    return worst;
+}
+// Readings as CSV — the handoff to a spreadsheet, or to whoever is building the
+// LUT. One row per patch, what went in beside what came back.
+export function readingToCsv(reading) {
+    const rows = [
+        "patch_id,role,sent_r,sent_g,sent_b,raw_r,raw_g,raw_b,measured_r,measured_g,measured_b",
+        ...reading.patches.map((p) => [
+            p.id,
+            p.role,
+            ...p.sent,
+            ...p.raw.map((v) => v.toFixed(1)),
+            ...p.measured.map((v) => v.toFixed(1)),
+        ].join(",")),
+    ];
+    return `${rows.join("\n")}\n`;
+}

package/src/plan.d.ts

@@ -0,0 +1,17 @@
+import type { Adjust, ImageNode, Node } from "@freshcoat-js/engine";
+import type { ChannelBalance, ImageAnalysis, PixelData, PrintOptimizeOptions } from "./types.js";
+export type LayerIntent = "photo" | "graphic" | "text" | "code" | "container";
+export type LayerIntentResolver = (node: Node) => LayerIntent | undefined;
+export declare function classifyIntent(node: Node): LayerIntent;
+export declare function printAdjust(o: PrintOptimizeOptions): Adjust;
+export type PlanPolicy = {
+    intentFor?: LayerIntentResolver;
+    photo?: PrintOptimizeOptions | null;
+    graphic?: PrintOptimizeOptions | null;
+    text?: PrintOptimizeOptions | null;
+    code?: PrintOptimizeOptions | null;
+    balance?: ChannelBalance;
+};
+export declare function planScene(root: Node, policy?: PlanPolicy): Node;
+export type ImageSampler = (image: ImageNode) => Promise<PixelData>;
+export declare function analyzeScene(sample: ImageSampler, root: Node, policy?: PlanPolicy, onAnalysis?: (analysis: ImageAnalysis, node: ImageNode) => void): Promise<Node>;

package/src/plan.js

@@ -0,0 +1,216 @@
+// The planner — for-print as a consumer of freshcoat's generic adjustment API.
+//
+// Instead of flattening a card and correcting one image, planScene walks a
+// freshcoat Node tree, classifies each layer by print intent, and attaches a
+// generic freshcoat `Adjust` so the layer is corrected PER-LAYER as freshcoat
+// paints it. Photos get dye-sub compensation; crisp vector/text/QR are left
+// pristine — the "protect text" that per-layer planning gives for free (no mask
+// needed: you simply don't adjust those layers).
+//
+// The dependency points at freshcoat only: for-print maps its policy
+// (PrintOptimizeOptions) down to freshcoat's math (color matrix + LUT + sharpen).
+// freshcoat never learns what "dye-sub" or "K panel" means.
+import { analyzePixels, correctionMatrix } from "./analyze.js";
+import { NO_PROCESSING, YMCKO_PRESET } from "./presets.js";
+// Pure channel helpers the tone LUT needs (the raster steps that once held these
+// moved to freshcoat's output path).
+const clamp = (v) => Math.max(0, Math.min(255, Math.round(v)));
+// Photoshop Overlay blend of a base channel against `blend`.
+const overlayBlendChannel = (base, blend) => base < 128
+    ? (2 * base * blend) / 255
+    : 255 - (2 * (255 - base) * (255 - blend)) / 255;
+// Classify a node by kind. Images are photographic (need dye-sub compensation);
+// text and QR/pixel bitmaps are crisp intent that must stay untouched; rect/
+// ellipse/path are flat vector graphics whose colors were chosen deliberately;
+// group/mask are containers we only recurse into.
+export function classifyIntent(node) {
+    switch (node.kind) {
+        case "image":
+            return "photo";
+        case "text":
+            return "text";
+        case "bitmap":
+            return "code";
+        case "rect":
+        case "ellipse":
+        case "path":
+            return "graphic";
+        default:
+            return "container"; // group | mask
+    }
+}
+// One channel's tone LUT, folding gamma then the darkness (Overlay-with-black)
+// step — both per-channel, so they compose into one 256-entry table. Mirrors the
+// order and math of the gamma + darkness pixel steps.
+//
+// `balance` is this channel's cast exponent and applies LAST, after the tone
+// steps: it corrects what the printer does to the finished signal, so it belongs
+// at the end of the chain rather than folded into `gamma`. At 1 the table is
+// bit-identical to what it was before balance existed.
+function toneLut(gamma, darkness, balance = 1) {
+    const t = new Uint8Array(256);
+    for (let i = 0; i < 256; i++) {
+        // gamma is a rounded integer LUT (like gammaStep); darkness then operates on
+        // that rounded value — staging the two rounds so this matches the pixel steps
+        // run in sequence to the LSB.
+        let v = clamp(255 * (i / 255) ** gamma);
+        if (darkness > 0) {
+            // darkness = Overlay(base, black) at `darkness` opacity, per channel.
+            v = clamp(v * (1 - darkness) + overlayBlendChannel(v, 0) * darkness);
+        }
+        if (balance !== 1)
+            v = clamp(255 * (v / 255) ** balance);
+        t[i] = v;
+    }
+    return t;
+}
+const NEUTRAL_BALANCE = (b) => !b || (b.r === 1 && b.g === 1 && b.b === 1);
+// Map print correction options to a generic freshcoat Adjust: saturation +
+// contrast fold into the color matrix (cross-channel/linear), gamma + darkness
+// into the per-channel LUT, sharpness passes through as sharpen. The conjunctive
+// white-clamp / black-extraction ops are NOT here — they need all three channels
+// together, so they live in freshcoat's whole-frame FrameFinish (YMCKO_FINISH).
+export function printAdjust(o) {
+    const adjust = {};
+    const m = correctionMatrix(o);
+    if (m) {
+        adjust.colorMatrix = m;
+        // Card art is largely saturated brand color, where a boost drives the leading
+        // channel past full scale. Clipping it there would rotate the hue — an indigo
+        // pins blue and drifts magenta — and flatten the gradient it came from, so the
+        // correction gives up saturation instead.
+        adjust.gamut = "preserve-hue";
+    }
+    // One table per channel only when the balance asks for it. With no cast
+    // measured, all three are the same table and the same object — the shape
+    // freshcoat has always been handed.
+    const darkness = o.darkness ?? 0;
+    if (NEUTRAL_BALANCE(o.balance)) {
+        if (o.gamma !== 1 || darkness > 0) {
+            const lut = toneLut(o.gamma, darkness);
+            adjust.lut = { r: lut, g: lut, b: lut };
+        }
+    }
+    else {
+        const b = o.balance;
+        adjust.lut = {
+            r: toneLut(o.gamma, darkness, b.r),
+            g: toneLut(o.gamma, darkness, b.g),
+            b: toneLut(o.gamma, darkness, b.b),
+        };
+    }
+    if (o.sharpness > 0)
+        adjust.sharpen = o.sharpness;
+    return adjust;
+}
+function intentFor(node, policy) {
+    return policy.intentFor?.(node) ?? classifyIntent(node);
+}
+function policyFor(intent, policy) {
+    switch (intent) {
+        case "photo":
+            return policy.photo ?? null;
+        case "graphic":
+            return policy.graphic ?? null;
+        case "text":
+            return policy.text ?? null;
+        case "code":
+            return policy.code ?? null;
+        default:
+            return null; // container
+    }
+}
+// Attach an adjust to a leaf if the options produce a non-empty one; otherwise
+// return the node untouched (no empty `adjust` field). A measured `balance`
+// reaches a layer the intent left alone as the only correction it carries.
+function withAdjust(node, opts, balance) {
+    const merged = opts
+        ? balance
+            ? { ...opts, balance }
+            : opts
+        : balance
+            ? { ...NO_PROCESSING, balance }
+            : null;
+    if (!merged)
+        return node;
+    const adjust = printAdjust(merged);
+    return Object.keys(adjust).length > 0 ? { ...node, adjust } : node;
+}
+// Walk a tree, mapping every node through `leaf` (for drawables) while recursing
+// into group/mask containers. Containers themselves are never adjusted — only
+// their leaves — so corrections apply per drawable, not to a composited subtree.
+function mapTree(node, leaf) {
+    if (node.kind === "group") {
+        return { ...node, children: node.children.map((c) => mapTree(c, leaf)) };
+    }
+    if (node.kind === "mask") {
+        return {
+            ...node,
+            mask: mapTree(node.mask, leaf),
+            children: node.children.map((c) => mapTree(c, leaf)),
+        };
+    }
+    return leaf(node);
+}
+const DEFAULT_POLICY = { photo: YMCKO_PRESET };
+// Sync planner: attach a policy-driven Adjust per layer, no image I/O. Photos get
+// the policy's photo preset (YMCKO by default); text/QR/graphics are left pristine
+// unless the policy opts them in. Returns a new tree; the input is not mutated.
+export function planScene(root, policy = {}) {
+    const p = { ...DEFAULT_POLICY, ...policy };
+    return mapTree(root, (node) => withAdjust(node, policyFor(intentFor(node, p), p), p.balance));
+}
+// Async planner: like planScene, but each photo layer is ANALYZED (per-image
+// brightness/saturation/contrast) and corrected with its own recommendation —
+// the core win over correcting one flattened card. Non-photo intents follow
+// `policy` (default: untouched). Pass `policy.photo` explicitly to override
+// analysis: `null` leaves photos alone, a preset forces a fixed correction.
+// Recommendations are cached per src.
+export async function analyzeScene(sample, root, policy = {}, 
+// Called once per analyzed photo with what analysis found — the gamut pressure
+// especially, which nothing downstream can recover once the render has clamped.
+// Not called for layers an explicit `policy.photo` opted out of analysis.
+onAnalysis) {
+    const analyzePhotos = !("photo" in policy);
+    // Cache the in-flight PROMISE, not the resolved value: children walk
+    // concurrently (Promise.all), so identical layers would otherwise both miss a
+    // value-cache and sample twice. Key on the rendered appearance (src + fit +
+    // size), since the same src cropped differently analyzes differently.
+    const cache = new Map();
+    const sampleKey = (n) => `${n.src}|${n.fit}|${Math.round(n.size?.width ?? 0)}x${Math.round(n.size?.height ?? 0)}`;
+    function photoOptions(node) {
+        if (!analyzePhotos)
+            return Promise.resolve(policy.photo ?? null);
+        const key = sampleKey(node);
+        let analysis = cache.get(key);
+        if (!analysis) {
+            // Reported on the miss, so duplicated layers are one analysis and one
+            // report — the same pixels counted twice would overstate the pressure.
+            analysis = sample(node).then((px) => {
+                const result = analyzePixels(px);
+                onAnalysis?.(result, node);
+                return result;
+            });
+            cache.set(key, analysis);
+        }
+        return analysis.then((a) => a.recommendation);
+    }
+    async function walk(node) {
+        if (node.kind === "group") {
+            return { ...node, children: await Promise.all(node.children.map(walk)) };
+        }
+        if (node.kind === "mask") {
+            const [mask, children] = await Promise.all([
+                walk(node.mask),
+                Promise.all(node.children.map(walk)),
+            ]);
+            return { ...node, mask, children };
+        }
+        const intent = intentFor(node, policy);
+        if (node.kind === "image" && intent === "photo") {
+            return withAdjust(node, await photoOptions(node), policy.balance);
+        }
+        return withAdjust(node, policyFor(intent, policy), policy.balance);
+    }
+    return walk(root);
+}

package/src/presets.d.ts

@@ -0,0 +1,5 @@
+import type { FrameFinish } from "@freshcoat-js/engine";
+import type { PrintOptimizeOptions } from "./types.js";
+export declare const YMCKO_PRESET: PrintOptimizeOptions;
+export declare const NO_PROCESSING: PrintOptimizeOptions;
+export declare const YMCKO_FINISH: FrameFinish;

package/src/presets.js

@@ -0,0 +1,26 @@
+// Tuned for YMCKO dye-sublimation ribbon printers.
+export const YMCKO_PRESET = {
+    saturation: 1.3,
+    contrast: 1.2,
+    sharpness: 0.3,
+    gamma: 0.85,
+    darkness: 0.25,
+};
+export const NO_PROCESSING = {
+    saturation: 1,
+    contrast: 1,
+    sharpness: 0,
+    gamma: 1,
+    darkness: 0,
+};
+// The whole-frame finishing for-print recommends alongside the per-layer
+// adjustments — the conjunctive/spatial output ops that aren't a per-layer Adjust.
+// Pass to freshcoat's compile/render `finish`. Mirrors the old buffer pipeline's
+// defaults: snap near-black (<30) to resin-friendly black, near-white (>248) to
+// white, and ±2 levels of deterministic monochrome dither to break dye-sub
+// gradient banding without colored grain.
+export const YMCKO_FINISH = {
+    blackExtract: 30,
+    whiteClamp: 248,
+    dither: { amount: 2, seed: 0, mode: "monochrome" },
+};

package/src/profile.d.ts

@@ -0,0 +1,37 @@
+import { type CalibrationAssessment } from "./calibration.js";
+import type { ChartReading } from "./measure.js";
+import type { ChannelBalance, PrintOptimizeOptions } from "./types.js";
+export interface PrintProfileConditions {
+    printer?: string;
+    ribbon?: string;
+    stock?: string;
+}
+export interface PrintProfile {
+    version?: 1;
+    name: string;
+    balance?: ChannelBalance;
+    measuredAt?: string;
+    notes?: string;
+    conditions?: PrintProfileConditions;
+    assessment?: CalibrationAssessment;
+}
+export type PrintProfileDetails = {
+    name: string;
+    measuredAt?: string;
+    notes?: string;
+    conditions?: PrintProfileConditions;
+};
+export type PrintProfileCreation = {
+    ok: true;
+    profile: PrintProfile;
+    assessment: CalibrationAssessment;
+} | {
+    ok: false;
+    reason: "unsafe-reading" | "missing-name" | "invalid-conditions";
+    assessment: CalibrationAssessment;
+};
+export declare const UNMEASURED_PROFILE: PrintProfile;
+export declare function createPrintProfile(reading: ChartReading, details: PrintProfileDetails): PrintProfileCreation;
+export declare function withProfile(options: PrintOptimizeOptions, profile: PrintProfile | undefined): PrintOptimizeOptions;
+export declare function profileCacheKey(profile: PrintProfile | undefined): string;
+export declare function parsePrintProfile(input: unknown): PrintProfile | Error;