@logomarks/core 0.1.7 → 0.1.9

package/src/analyse/shape/symmetry.js

@@ -0,0 +1,84 @@
+/**
+ * @module @logomarks/core/analyse/shape/symmetry
+ *
+ * How well a mark maps onto itself under a mirror or a turn, measured two ways: its coverage (overlap over union,
+ * which a big solid mass dominates) and its outline (the share of outline pixels that land on the outline, which a
+ * small asymmetric detail inside a badge still breaks).
+ */
+
+import { distance } from '../../raster/distance.js';
+import { bitmap } from './ink.js';
+
+/** @typedef {(x: number, y: number) => [number, number]} PixelMap */
+
+/**
+ * Coverage at a point between pixel centres (bilinear; 0 outside).
+ *
+ * @param {Float32Array} a Coverage, `n` × `n`.
+ * @param {number} n The side.
+ * @param {number} x Pixel coordinates (centres at whole numbers).
+ * @param {number} y
+ * @returns {number} The coverage there.
+ */
+function sample(a, n, x, y) {
+	const x0 = Math.floor(x), y0 = Math.floor(y), fx = x - x0, fy = y - y0;
+	const at = (/** @type {number} */ i, /** @type {number} */ j) => (i < 0 || j < 0 || i >= n || j >= n ? 0 : a[j * n + i]);
+	return at(x0, y0) * (1 - fx) * (1 - fy) + at(x0 + 1, y0) * fx * (1 - fy) + at(x0, y0 + 1) * (1 - fx) * fy + at(x0 + 1, y0 + 1) * fx * fy;
+}
+
+/**
+ * The coverage's overlap with itself mapped by `f` (intersection over union).
+ *
+ * @param {import('./ink.js').Ink} ink The ink.
+ * @param {PixelMap} f Where each pixel centre (x + 0.5, y + 0.5) comes from.
+ * @returns {number} 0–1.
+ */
+export function coverageMatch({ a, n }, f) {
+	let i = 0, u = 0;
+	for (let y = 0; y < n; y++) for (let x = 0; x < n; x++) {
+		const [sx, sy] = f(x + 0.5, y + 0.5), p = a[y * n + x], q = sample(a, n, sx - 0.5, sy - 0.5);
+		i += Math.min(p, q); u += Math.max(p, q);
+	}
+	return u ? i / u : 0;
+}
+
+/**
+ * A matcher for the outline: maps each outline pixel and counts those landing within `tol` pixels of the outline.
+ *
+ * @param {import('./ink.js').Ink} ink The ink.
+ * @param {number[]} outline Its outline pixels (`outlineOf`).
+ * @returns {(f: PixelMap, tol: number) => number} The share matched, 0–1, for a map and a tolerance in pixels.
+ */
+export function outlineMatcher({ n }, outline) {
+	const edge = new Uint8Array(n * n);
+	for (const k of outline) edge[k] = 1;
+	const near = distance(bitmap(edge, n), 0);
+	return (f, tol) => {
+		let ok = 0;
+		for (const k of outline) {
+			const x = k % n, [X, Y] = f(x + 0.5, (k - x) / n + 0.5), i = Math.floor(X), j = Math.floor(Y);
+			if (i >= 0 && j >= 0 && i < n && j < n && near[j * n + i] <= tol) ok++;
+		}
+		return outline.length ? ok / outline.length : 0;
+	};
+}
+
+/**
+ * The mirror across the vertical line x = `cx`.
+ *
+ * @param {number} cx The axis, in pixels.
+ * @returns {PixelMap} The map.
+ */
+export const mirrorX = (cx) => (x, y) => [2 * cx - x, y];
+
+/**
+ * A turn by a whole circle over `order` about `c`.
+ *
+ * @param {number} order How many turns make the circle.
+ * @param {[number, number]} c The centre, in pixels.
+ * @returns {PixelMap} The map.
+ */
+export function turn(order, [cx, cy]) {
+	const t = 2 * Math.PI / order, co = Math.cos(t), si = Math.sin(t);
+	return (x, y) => [cx + (x - cx) * co - (y - cy) * si, cy + (x - cx) * si + (y - cy) * co];
+}

package/src/analyse/shape/thickness.d.ts

@@ -0,0 +1,6 @@
+import type { Ink } from './ink.js';
+
+/** The share of the ink in parts thicker than 2r (covered by discs of radius `r` pixels inside it), 0–1. */
+export function thickShare(ink: Pick<Ink, 'bin' | 'n' | 'count'>, depth: Float32Array, r: number): number;
+/** How drawn-out the pieces are: area over width squared per piece, averaged by area (a stroke ≈ length / width). */
+export function elongation(ink: Pick<Ink, 'bin' | 'n'>, depth: Float32Array): number;

package/src/analyse/shape/thickness.js

@@ -0,0 +1,62 @@
+/**
+ * @module @logomarks/core/analyse/shape/thickness
+ *
+ * How thick a mark's ink is, from its distance transform: the share of the ink in parts thicker than a width (what
+ * an opening by a disc keeps), and how drawn-out its pieces are (a stroke is long for its width; a dot or a block
+ * isn't).
+ */
+
+import { distance } from '../../raster/distance.js';
+import { bitmap } from './ink.js';
+
+/**
+ * The share of the ink covered by discs of radius `r` that fit inside it: the ink in parts thicker than 2r.
+ *
+ * @param {import('./ink.js').Ink} ink The ink.
+ * @param {Float32Array} depth Each ink pixel's distance to the empty space (`distance(ink, 1)`).
+ * @param {number} r The radius in pixels.
+ * @returns {number} 0–1.
+ */
+export function thickShare({ bin, n, count }, depth, r) {
+	const core = new Uint8Array(n * n);
+	let any = false;
+	for (let k = 0; k < n * n; k++) if (bin[k] && depth[k] >= r) { core[k] = 1; any = true; }
+	if (!any || !count) return 0;
+	const near = distance(bitmap(core, n), 0);
+	let kept = 0;
+	for (let k = 0; k < n * n; k++) if (bin[k] && near[k] <= r) kept++;
+	return kept / count;
+}
+
+/**
+ * How drawn-out the pieces are: each 8-connected piece's area over its width squared (its width four times its mean
+ * depth, exact for a long even stroke), averaged by area. A stroke L long and w wide scores about L / w; a dot about
+ * 1.8, a square block 2.3.
+ *
+ * @param {import('./ink.js').Ink} ink The ink.
+ * @param {Float32Array} depth Each ink pixel's distance to the empty space.
+ * @returns {number} The area-weighted mean.
+ */
+export function elongation({ bin, n }, depth) {
+	const seen = new Uint8Array(n * n), stack = [];
+	let sum = 0, total = 0;
+	for (let s = 0; s < n * n; s++) {
+		if (!bin[s] || seen[s]) continue;
+		let area = 0, deep = 0;
+		seen[s] = 1;
+		stack.push(s);
+		while (stack.length) {
+			const k = /** @type {number} */ (stack.pop()), x = k % n, y = (k - x) / n;
+			area++;
+			deep += depth[k];
+			for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {
+				const X = x + dx, Y = y + dy, j = Y * n + X;
+				if (X >= 0 && Y >= 0 && X < n && Y < n && bin[j] && !seen[j]) { seen[j] = 1; stack.push(j); }
+			}
+		}
+		const width = 4 * deep / area;
+		sum += area * area / (width * width);
+		total += area;
+	}
+	return total ? sum / total : 0;
+}

package/src/analyse/tags.d.ts

@@ -1,5 +1,21 @@
+import type { ShapeMeasures } from './shape/measures.js';
+
 /** A shape tag measured from a mark's raster. */
 export type ShapeTag = 'wide' | 'tall' | 'round' | 'square' | 'solid' | 'light' | 'symmetric' | 'radial';
 
-/** A fitted mark's shape tags, from its coverage at `size` px (128) and its outline's width and height. */
+/** The thresholds the tags are decided by. */
+export const SHAPE: {
+	wide: number;
+	tall: number;
+	squarish: number;
+	round: { reach: number; ways: Partial<Record<'arc' | 'rim' | 'circularity', number>>[] };
+	square: { fill: number; corners: number };
+	symmetric: { coverage: number; outline: number };
+	radial: { coverage: number; outline: number };
+	light: { elongation: number; thick: number };
+};
+
+/** The shape tags a mark's measures earn, in a fixed order; exactly one of solid and light. */
+export function tagsOf(ms: ShapeMeasures, t?: typeof SHAPE): ShapeTag[];
+/** A fitted mark's shape tags, from its coverage at `size` px (256) and its outline's width and height. */
 export function shapeTags(a: Float32Array, m: { w: number; h: number; size?: number }): ShapeTag[];

package/src/analyse/tags.js

@@ -2,47 +2,82 @@
  * @module @logomarks/core/analyse/tags
  *
  * Shape tags measured from a mark's coverage: wide or tall, round or square, solid or light, symmetric, radial.
+ * Tuned on the 4,040 Logomarks marks against contact sheets (about 95% read right by eye; see docs/tags.md).
  */
 
-import { remap, iou } from '../similar/signature.js';
+import { shapeMeasures } from './shape/measures.js';
+
+/** The thresholds the tags are decided by: the Logomarks settings. */
+export const SHAPE = {
+	/** Width over height beyond which a mark is wide, or below which it is tall. */
+	wide: 1.25,
+	tall: 0.8,
+	/** Round and square marks are about as wide as tall: between this and its inverse. */
+	squarish: 0.9,
+	/** Round: the ink reaches the hull all round, and the hull runs on a circle (any one way). */
+	round: {
+		reach: 0.6,
+		ways: [
+			{ arc: 0.74, circularity: 0.89 },
+			{ arc: 0.65, circularity: 0.96 },
+			{ rim: 0.8, circularity: 0.97 },
+		],
+	},
+	/** Square: the closed silhouette fills its box, every corner too (and it isn't round). */
+	square: { fill: 0.88, corners: 0.6 },
+	/** Symmetric: the left-right mirror matches, coverage and outline both. */
+	symmetric: { coverage: 0.95, outline: 0.95 },
+	/** Radial: a turn of order 3, 4 or 5 matches, coverage and outline both. */
+	radial: { coverage: 0.9, outline: 0.9 },
+	/** Light: strokes (drawn-out pieces) with little mass; every other mark is solid. */
+	light: { elongation: 3, thick: 0.3 },
+};
+
+/**
+ * Whether the measures clear every threshold in `need`.
+ *
+ * @param {import('./shape/measures.js').ShapeMeasures} ms The measures.
+ * @param {Partial<Record<'arc' | 'rim' | 'circularity', number>>} need The thresholds, by measure.
+ * @returns {boolean} All met.
+ */
+const meets = (ms, need) => Object.entries(need).every(([k, v]) => ms[/** @type {'arc' | 'rim' | 'circularity'} */ (k)] >= /** @type {number} */ (v));
+
+/**
+ * The shape tags a mark's measures earn.
+ *
+ * @param {import('./shape/measures.js').ShapeMeasures} ms The measures (`shapeMeasures`).
+ * @param {typeof SHAPE} [t] The thresholds (SHAPE by default).
+ * @returns {import('./tags.js').ShapeTag[]} The tags, in a fixed order; exactly one of solid and light.
+ */
+export function tagsOf(ms, t = SHAPE) {
+	/** @type {import('./tags.js').ShapeTag[]} */
+	const tags = [];
+	if (ms.ratio > t.wide) tags.push('wide'); else if (ms.ratio < t.tall) tags.push('tall');
+	const squarish = ms.ratio > t.squarish && ms.ratio < 1 / t.squarish;
+	if (squarish && ms.reach >= t.round.reach && t.round.ways.some((way) => meets(ms, way))) tags.push('round');
+	else if (squarish && ms.closedFill >= t.square.fill && ms.closedCorners >= t.square.corners) tags.push('square');
+	const light = ms.elongation >= t.light.elongation && Math.min(ms.thick, ms.thickRelative) < t.light.thick;
+	tags.push(light ? 'light' : 'solid');
+	if (ms.mirror.coverage >= t.symmetric.coverage && ms.mirror.outline >= t.symmetric.outline) tags.push('symmetric');
+	if (ms.turns.some((r) => r.coverage >= t.radial.coverage && r.outline >= t.radial.outline)) tags.push('radial');
+	return tags;
+}
 
 /**
- * A fitted mark's shape tags, from its coverage at `size` px (128) and its outline's size on the 512 canvas.
+ * A fitted mark's shape tags, from its coverage at `size` px (256) and its outline's size on the 512 canvas.
  * - wide / tall: wider than 1.25 or narrower than 0.8;
- * - round: about square, every corner of its box empty and the silhouette reaching the edge midpoints and diagonals;
- * - square: about square with three corners or more filled;
- * - solid / light: over 62% or under 30% of its box inked;
- * - symmetric: mirrors onto itself (IoU over 0.94); radial: a quarter turn (0.92) or a half turn (0.94) does.
+ * - round: about square (0.9–1.11), the ink reaching its convex hull all round, and the hull running on a circle;
+ * - square: about square, not round, and its silhouette (gaps up to 60 closed, holes filled) filling its box to the
+ *   corners;
+ * - solid / light: light when it's drawn in strokes with little mass (under 30% of the ink in parts thicker than 48
+ *   units, or than 12% of its short side); every other mark is solid;
+ * - symmetric: its left-right mirror matches (coverage and outline 0.95); a top-bottom mirror alone doesn't count;
+ * - radial: a turn by a third, a quarter or a fifth matches (0.9): rotational symmetry of order 3 or more.
  *
  * @param {Float32Array} a Coverage 0–1, `size` × `size`, row by row.
  * @param {{ w: number, h: number, size?: number }} m The outline's width and height (fitted), and the raster's side.
  * @returns {import('./tags.js').ShapeTag[]} The tags, in a fixed order.
  */
-export function shapeTags(a, { w: mw, h: mh, size: N = 128 }) {
-  const tags = new Set();
-  const tf = (/** @type {(x: number, y: number) => number[]} */ f) => remap(a, N, f);
-  // bbox in raster px
-  const s = N / 512, x0 = Math.round((256 - mw / 2) * s), y0 = Math.round((256 - mh / 2) * s), w = Math.round(mw * s), h = Math.round(mh * s);
-  let fill = 0; for (let y = y0; y < y0 + h; y++) for (let x = x0; x < x0 + w; x++) fill += a[y * N + x] || 0;
-  const density = fill / (w * h);
-  const ratio = mw / mh;
-  if (ratio > 1.25) tags.add('wide'); else if (ratio < 0.8) tags.add('tall');
-  // corners of the bbox: empty everywhere → round silhouette; mostly filled → square
-  const c = Math.max(2, Math.round(Math.min(w, h) * 0.1));
-  const corner = (/** @type {number} */ cx, /** @type {number} */ cy) => { let f = 0; for (let y = cy; y < cy + c; y++) for (let x = cx; x < cx + c; x++) f += a[y * N + x] || 0; return f / (c * c); };
-  const cs = [corner(x0, y0), corner(x0 + w - c, y0), corner(x0, y0 + h - c), corner(x0 + w - c, y0 + h - c)];
-  const sq = ratio > 0.92 && ratio < 1.08;
-  if (sq && cs.every((v) => v < 0.04)) {
-    // also require the silhouette to reach the edge midpoints (a disc, not a diamond or a small blob)
-    const mid = (/** @type {number} */ x, /** @type {number} */ y) => a[y * N + x] > 0.5;
-    const r = Math.round(w / 2), cxp = x0 + r, cyp = y0 + r, d = Math.round(w * 0.06);
-    const diag = Math.round(r * 0.70);
-    if ([mid(cxp, y0 + d), mid(cxp, y0 + h - 1 - d), mid(x0 + d, cyp), mid(x0 + w - 1 - d, cyp)].filter(Boolean).length >= 3 &&
-        [mid(cxp - diag + d, cyp - diag + d), mid(cxp + diag - d, cyp - diag + d), mid(cxp - diag + d, cyp + diag - d), mid(cxp + diag - d, cyp + diag - d)].filter(Boolean).length >= 3) tags.add('round');
-  }
-  if (sq && cs.filter((v) => v > 0.6).length >= 3) tags.add('square');
-  if (density > 0.62) tags.add('solid'); else if (density < 0.3) tags.add('light');
-  if (iou(a, tf((x, y) => [N - 1 - x, y])) > 0.94 || iou(a, tf((x, y) => [x, N - 1 - y])) > 0.94) tags.add('symmetric');
-  if (iou(a, tf((x, y) => [y, N - 1 - x])) > 0.92 || iou(a, tf((x, y) => [N - 1 - x, N - 1 - y])) > 0.94) tags.add('radial');
-  return /** @type {import('./tags.js').ShapeTag[]} */ ([...tags]);
+export function shapeTags(a, m) {
+	return tagsOf(shapeMeasures(a, m));
 }

package/src/index.d.ts

@@ -6,3 +6,4 @@ export * from './raster/index.js';
 export * from './analyse/index.js';
 export * from './similar/index.js';
 export * from './edit/index.js';
+export * from './stitch/index.js';

package/src/index.js

@@ -1,6 +1,6 @@
 /**
- * @logomarks/core: geometry, SVG reading, fitting, analysis, similarity and shape edits for logomarks on a 512
- * grid. Each area is also its own subpath (`/geometry`, `/svg`, `/fit`, `/raster`, `/analyse`, `/similar`, `/edit`,
+ * @logomarks/core: geometry, SVG reading, fitting, analysis, similarity, shape edits and stitch plans for logomarks
+ * on a 512 grid. Each area is also its own subpath (`/geometry`, `/svg`, `/fit`, `/raster`, `/analyse`, `/similar`, `/edit`, `/stitch`,
  * and `/parts` for the industry-symbol parts, which needs Node for its batch writer).
  */
 export * from './geometry/index.js';
@@ -10,3 +10,4 @@ export * from './raster/index.js';
 export * from './analyse/index.js';
 export * from './similar/index.js';
 export * from './edit/index.js';
+export * from './stitch/index.js';

package/src/stitch/border.d.ts

@@ -0,0 +1,2 @@
+/** A satin border, `width` pixels wide, round the wide parts where they meet the outside (pixel coordinates, flat `x0, y0, x1, y1` each, from the edge inwards). */
+export function borderStitches(wide: Uint8Array, dist: Float32Array, W: number, H: number, o: { width: number; spacing: number }): number[];

package/src/stitch/border.js

@@ -0,0 +1,40 @@
+/**
+ * @module @logomarks/core/stitch/border
+ *
+ * A satin border round the filled parts: a narrow column of threads laid
+ * over the fill's outer edge, each square to the edge, which hides the
+ * fill's ragged row ends as a real border does. It runs only where a fill
+ * meets the outside (or a hole), not where it meets a satin stroke.
+ */
+
+import { gradient, spaced } from './field.js';
+
+/**
+ * The border stitches round the wide parts.
+ *
+ * @param {Uint8Array} wide The filled parts (1 inside).
+ * @param {Float32Array} dist Each ink pixel's distance to the edge of the ink.
+ * @param {number} W The raster's width.
+ * @param {number} H Its height.
+ * @param {object} o How.
+ * @param {number} o.width The border's width, in pixels.
+ * @param {number} o.spacing The distance between threads, in pixels.
+ * @returns {number[]} The stitches, flat: `x0, y0, x1, y1` each, in pixel coordinates, from the edge inwards.
+ */
+export function borderStitches(wide, dist, W, H, { width, spacing }) {
+	if (width <= 0) return [];
+	// the edge lies half a pixel out from the outermost ink pixels (whose distance is 1): the column's middle line
+	const mid = 0.5 + width / 2;
+	const line = [];
+	for (let i = 0; i < W * H; i++) if (wide[i] && Math.abs(dist[i] - mid) <= 0.75) line.push(i);
+	const out = [];
+	for (const i of spaced(line, W, spacing)) {
+		const x = i % W, y = (i - x) / W;
+		const [gx, gy] = gradient(dist, W, H, x, y);
+		if (!gx && !gy) continue;
+		const back = dist[i] - 0.5;
+		const on = width - back;
+		out.push(x - gx * back, y - gy * back, x + gx * on, y + gy * on);
+	}
+	return out;
+}

package/src/stitch/field.d.ts

@@ -0,0 +1,14 @@
+/** A value read between pixel centres (bilinear), 0 outside the raster. */
+export function sample(f: Float32Array, W: number, H: number, x: number, y: number): number;
+/** The direction a field rises fastest at a pixel, as a unit vector (`[0, 0]` where flat). */
+export function gradient(f: Float32Array, W: number, H: number, x: number, y: number): [number, number];
+/** A box blur of radius `r`, in place. */
+export function boxBlur(f: Float32Array, W: number, H: number, r: number): void;
+/** The 4-connected regions of a mask: each pixel's region (−1 outside) and each region's size. */
+export function regions(mask: Uint8Array, W: number, H: number): { label: Int32Array; sizes: number[] };
+/** The angle across a stroke (radians) at each pixel of a mask, from the distance field's blurred structure tensor. */
+export function acrossField(dist: Float32Array, mask: Uint8Array, W: number, H: number, radius: number): Float32Array;
+/** Pixels picked from candidates, in order, so no two are closer than `spacing`; `taken` pixels are skipped. */
+export function spaced(candidates: Iterable<number>, W: number, spacing: number, taken?: (i: number) => boolean): number[];
+/** How far a ray goes before the distance field (read between pixels) falls to half a pixel: the ink's edge, or `max`. */
+export function reach(dist: Float32Array, W: number, H: number, x: number, y: number, dx: number, dy: number, max: number): number;

package/src/stitch/field.js

@@ -0,0 +1,207 @@
+/**
+ * @module @logomarks/core/stitch/field
+ *
+ * Raster helpers the stitch planner works on: values read between pixel
+ * centres, a blur, connected regions, the direction across a stroke (from a
+ * smoothed structure tensor of the distance field, so it doesn't flip on
+ * the stroke's middle line), and evenly spaced picks from a set of pixels.
+ * Coordinates are continuous pixel coordinates: pixel `i`'s centre is at `i`.
+ */
+
+/**
+ * A value read between pixel centres (bilinear), 0 outside the raster.
+ *
+ * @param {Float32Array} f The values, row by row.
+ * @param {number} W The raster's width.
+ * @param {number} H Its height.
+ * @param {number} x Where, across.
+ * @param {number} y Where, down.
+ * @returns {number} The value.
+ */
+export function sample(f, W, H, x, y) {
+	const x0 = Math.floor(x), y0 = Math.floor(y);
+	const fx = x - x0, fy = y - y0;
+	const at = (i, j) => (i < 0 || j < 0 || i >= W || j >= H ? 0 : f[j * W + i]);
+	return (at(x0, y0) * (1 - fx) + at(x0 + 1, y0) * fx) * (1 - fy) + (at(x0, y0 + 1) * (1 - fx) + at(x0 + 1, y0 + 1) * fx) * fy;
+}
+
+/**
+ * The gradient of a field at a pixel (central differences), as a unit vector, or `[0, 0]` where it is flat.
+ *
+ * @param {Float32Array} f The field.
+ * @param {number} W Its width.
+ * @param {number} H Its height.
+ * @param {number} x The pixel, across.
+ * @param {number} y The pixel, down.
+ * @returns {[number, number]} The direction it rises fastest.
+ */
+export function gradient(f, W, H, x, y) {
+	const gx = sample(f, W, H, x + 1, y) - sample(f, W, H, x - 1, y);
+	const gy = sample(f, W, H, x, y + 1) - sample(f, W, H, x, y - 1);
+	const m = Math.hypot(gx, gy);
+	return m > 1e-9 ? [gx / m, gy / m] : [0, 0];
+}
+
+/**
+ * A box blur, in place, along rows then columns.
+ *
+ * @param {Float32Array} f The values.
+ * @param {number} W The width.
+ * @param {number} H The height.
+ * @param {number} r The radius, in pixels.
+ */
+export function boxBlur(f, W, H, r) {
+	if (r < 1) return;
+	const tmp = new Float32Array(Math.max(W, H));
+	const pass = (n, count, at) => {
+		for (let k = 0; k < count; k++) {
+			let s = 0;
+			for (let i = -r; i <= r; i++) s += f[at(k, Math.min(n - 1, Math.max(0, i)))];
+			for (let i = 0; i < n; i++) {
+				tmp[i] = s / (2 * r + 1);
+				s += f[at(k, Math.min(n - 1, i + r + 1))] - f[at(k, Math.max(0, i - r))];
+			}
+			for (let i = 0; i < n; i++) f[at(k, i)] = tmp[i];
+		}
+	};
+	pass(W, H, (row, i) => row * W + i);
+	pass(H, W, (col, i) => i * W + col);
+}
+
+/**
+ * The connected regions (4-connected) of a mask.
+ *
+ * @param {Uint8Array} mask 1 inside.
+ * @param {number} W The width.
+ * @param {number} H The height.
+ * @returns {{ label: Int32Array, sizes: number[] }} Each pixel's region (−1 outside) and each region's size.
+ */
+export function regions(mask, W, H) {
+	const label = new Int32Array(W * H).fill(-1);
+	const sizes = [];
+	const stack = [];
+	for (let i = 0; i < W * H; i++) {
+		if (!mask[i] || label[i] >= 0) continue;
+		const id = sizes.length;
+		let n = 0;
+		label[i] = id;
+		stack.push(i);
+		while (stack.length) {
+			const p = /** @type {number} */ (stack.pop());
+			n++;
+			const x = p % W, y = (p - x) / W;
+			for (const q of [x > 0 ? p - 1 : -1, x < W - 1 ? p + 1 : -1, y > 0 ? p - W : -1, y < H - 1 ? p + W : -1]) {
+				if (q >= 0 && mask[q] && label[q] < 0) {
+					label[q] = id;
+					stack.push(q);
+				}
+			}
+		}
+		sizes.push(n);
+	}
+	return { label, sizes };
+}
+
+/**
+ * The direction across a stroke at each pixel of a mask: the dominant direction of the distance field's gradient
+ * (its structure tensor, blurred within the mask), which is the same on both sides of the stroke's middle line.
+ *
+ * @param {Float32Array} dist The distance to the edge, per pixel.
+ * @param {Uint8Array} mask Where to measure (the narrow parts).
+ * @param {number} W The width.
+ * @param {number} H The height.
+ * @param {number} radius The blur, in pixels.
+ * @returns {Float32Array} The angle across, in radians, per pixel (0 outside the mask).
+ */
+export function acrossField(dist, mask, W, H, radius) {
+	const n = W * H;
+	const [xx, xy, yy, w] = [new Float32Array(n), new Float32Array(n), new Float32Array(n), new Float32Array(n)];
+	for (let y = 0; y < H; y++) {
+		for (let x = 0; x < W; x++) {
+			const i = y * W + x;
+			if (!mask[i]) continue;
+			const gx = sample(dist, W, H, x + 1, y) - sample(dist, W, H, x - 1, y);
+			const gy = sample(dist, W, H, x, y + 1) - sample(dist, W, H, x, y - 1);
+			xx[i] = gx * gx;
+			xy[i] = gx * gy;
+			yy[i] = gy * gy;
+			w[i] = 1;
+		}
+	}
+	for (const f of [xx, xy, yy, w]) {
+		boxBlur(f, W, H, radius);
+		boxBlur(f, W, H, radius);
+	}
+	const out = new Float32Array(n);
+	for (let i = 0; i < n; i++) if (mask[i] && w[i] > 0) out[i] = 0.5 * Math.atan2(2 * xy[i], xx[i] - yy[i]);
+	return out;
+}
+
+/**
+ * Pixels picked from candidates so that no two are closer than `spacing`, greedily in the candidates' order.
+ *
+ * @param {Iterable<number>} candidates Pixel indices, in the order to try them.
+ * @param {number} W The raster's width.
+ * @param {number} spacing The least distance between picks, in pixels.
+ * @param {(i: number) => boolean} [taken] Pixels already covered, which are skipped.
+ * @returns {number[]} The picks.
+ */
+export function spaced(candidates, W, spacing, taken) {
+	const cell = Math.max(1, spacing / Math.SQRT2);
+	/** @type {Map<number, number[]>} */
+	const grid = new Map();
+	const key = (cx, cy) => cy * 65536 + cx;
+	const out = [];
+	const s2 = spacing * spacing;
+	for (const i of candidates) {
+		if (taken?.(i)) continue;
+		const x = i % W, y = (i - x) / W;
+		const cx = Math.floor(x / cell), cy = Math.floor(y / cell);
+		const reach = Math.ceil(spacing / cell);
+		let free = true;
+		for (let dy = -reach; dy <= reach && free; dy++) {
+			for (let dx = -reach; dx <= reach && free; dx++) {
+				const pts = grid.get(key(cx + dx, cy + dy));
+				if (pts) for (const j of pts) {
+					const jx = j % W, jy = (j - jx) / W;
+					if ((jx - x) ** 2 + (jy - y) ** 2 < s2) {
+						free = false;
+						break;
+					}
+				}
+			}
+		}
+		if (!free) continue;
+		out.push(i);
+		const k = key(cx, cy);
+		const list = grid.get(k);
+		if (list) list.push(i);
+		else grid.set(k, [i]);
+	}
+	return out;
+}
+
+/**
+ * How far a ray goes from a point before it leaves the ink: where the distance field, read between pixels, first
+ * falls to half a pixel (the edge between an ink pixel and an empty one).
+ *
+ * @param {Float32Array} dist The distance to the edge (0 on empty pixels).
+ * @param {number} W The width.
+ * @param {number} H The height.
+ * @param {number} x Where it starts, across.
+ * @param {number} y Where it starts, down.
+ * @param {number} dx Its direction, across (unit).
+ * @param {number} dy Its direction, down.
+ * @param {number} max The farthest it goes.
+ * @returns {number} The distance to the edge (or `max`).
+ */
+export function reach(dist, W, H, x, y, dx, dy, max) {
+	const step = 0.5;
+	let prev = sample(dist, W, H, x, y);
+	for (let t = step; t <= max; t += step) {
+		const v = sample(dist, W, H, x + dx * t, y + dy * t);
+		if (v < 0.5) return t - step + (step * (prev - 0.5)) / Math.max(1e-6, prev - v);
+		prev = v;
+	}
+	return max;
+}

package/src/stitch/fill.d.ts

@@ -0,0 +1,2 @@
+/** Tatami rows over a mask (pixel coordinates, flat `x0, y0, x1, y1` each), the stitch ends staggered row by row. */
+export function fillStitches(mask: Uint8Array, W: number, H: number, o: { spacing: number; length: number; angle: number; random: () => number }): number[];

package/src/stitch/fill.js

@@ -0,0 +1,67 @@
+/**
+ * @module @logomarks/core/stitch/fill
+ *
+ * Tatami (fill stitch): the wide parts covered in parallel rows at one
+ * angle, each row a run of short stitches. The needle points step along each
+ * row at the stitch length from a phase that shifts row by row (half, then a
+ * quarter, then three quarters of a stitch), so the stitch ends never line
+ * up and the surface shows the staggered brick of a real fill.
+ */
+
+/** Each row's phase, as a share of the stitch length, repeating. */
+const PHASES = Object.freeze([0, 0.5, 0.25, 0.75]);
+
+/**
+ * The fill stitches over a mask.
+ *
+ * @param {Uint8Array} mask Where to fill (1 inside).
+ * @param {number} W The raster's width.
+ * @param {number} H Its height.
+ * @param {object} o How.
+ * @param {number} o.spacing The distance between rows, in pixels.
+ * @param {number} o.length The stitch length, in pixels.
+ * @param {number} o.angle The rows' angle, in degrees (0 runs across, 90 down).
+ * @param {() => number} o.random A seeded source of numbers in [0, 1).
+ * @returns {number[]} The stitches, flat: `x0, y0, x1, y1` each, in pixel coordinates.
+ */
+export function fillStitches(mask, W, H, { spacing, length, angle, random }) {
+	const a = (angle * Math.PI) / 180;
+	const [ux, uy] = [Math.cos(a), Math.sin(a)];
+	const [vx, vy] = [-uy, ux];
+	const corners = [[0, 0], [W, 0], [0, H], [W, H]];
+	const along = corners.map(([x, y]) => x * ux + y * uy);
+	const across = corners.map(([x, y]) => x * vx + y * vy);
+	const [s0, s1] = [Math.min(...along), Math.max(...along)];
+	const [c0, c1] = [Math.min(...across), Math.max(...across)];
+	const inside = (s, c) => {
+		const x = Math.round(s * ux + c * vx), y = Math.round(s * uy + c * vy);
+		return x >= 0 && y >= 0 && x < W && y < H && mask[y * W + x] === 1;
+	};
+	const step = 0.5;
+	const shortest = length * 0.18;
+	const out = [];
+	let row = 0;
+	for (let c = c0 + spacing / 2; c < c1; c += spacing, row++) {
+		const phase = (PHASES[row % PHASES.length] + (random() - 0.5) * 0.04) * length;
+		let start = null;
+		for (let s = s0; s <= s1 + step; s += step) {
+			const on = s <= s1 && inside(s, c);
+			if (on && start === null) start = s;
+			if (on || start === null) continue;
+			// each run stops short of the edge by half a row, so its round thread end lies on it
+			const end = s - step - spacing / 2;
+			start += spacing / 2;
+			if (end - start < shortest) {
+				start = null;
+				continue;
+			}
+			// the needle points: the run's two ends, and the row's grid between them (jittered a little)
+			const pts = [start];
+			for (let g = Math.ceil((start + shortest - phase) / length) * length + phase; g < end - shortest; g += length) pts.push(g + (random() - 0.5) * length * 0.06);
+			pts.push(end);
+			for (let i = 0; i + 1 < pts.length; i++) out.push(pts[i] * ux + c * vx, pts[i] * uy + c * vy, pts[i + 1] * ux + c * vx, pts[i + 1] * uy + c * vy);
+			start = null;
+		}
+	}
+	return out;
+}

package/src/stitch/index.d.ts

@@ -0,0 +1,6 @@
+export type { StitchSettings, StitchPlan } from './plan.js';
+export { STITCH, SATIN_DENSITY, stitchPlan, stitchCount } from './plan.js';
+export { splitByWidth } from './regions.js';
+export { fillStitches } from './fill.js';
+export { satinStitches } from './satin.js';
+export { borderStitches } from './border.js';