@logomarks/core 0.1.7 → 0.1.9

package/src/stitch/index.js

@@ -0,0 +1,14 @@
+/**
+ * @module @logomarks/core/stitch
+ *
+ * Machine embroidery planned from a mark's outlines: the ink split by width
+ * into fill and satin, tatami rows over the fills, satin threads across the
+ * strokes, a satin border round the fills. Pure geometry, seeded; a
+ * renderer (`@logomarks/mockups`' embroidery finish) draws the stitches as
+ * thread.
+ */
+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';

package/src/stitch/plan.d.ts

@@ -0,0 +1,46 @@
+/** The planner's settings. Sizes are in millimetres. */
+export interface StitchSettings {
+	/** How far the mark's canvas (its viewBox's longer side) spans, in mm (55). */
+	size: number;
+	/** The distance between rows of fill, in mm (0.42); satin threads lie `SATIN_DENSITY` times as far apart. */
+	density: number;
+	/** The widest part stitched in satin, in mm (3.6); wider parts are filled. */
+	satin: number;
+	/** The fill's stitch length, in mm (3.5). */
+	stitch: number;
+	/** The fill rows' angle, in degrees: 0 runs across, 90 down (45). */
+	angle: number;
+	/** The satin border round each fill, in mm; 0 for none (0.9). */
+	border: number;
+	/** The raster's pitch, in pixels a mm (10). */
+	resolution: number;
+	/** Seeds the small irregularities ('1'). */
+	seed: string;
+}
+
+/** A mark's stitches. Each list is flat, four numbers a stitch (`x0, y0, x1, y1`), in the mark's own units, in the order they're sewn. */
+export interface StitchPlan {
+	/** The mark's viewBox: x, y, width, height. */
+	viewBox: [number, number, number, number];
+	/** Millimetres a unit of the mark. */
+	mm: number;
+	/** The settings it was planned with. */
+	settings: StitchSettings;
+	/** Tatami rows over the wide parts. */
+	fill: number[];
+	/** Satin threads across the narrow parts. */
+	satin: number[];
+	/** The satin border round each fill, from the edge inwards. */
+	border: number[];
+	/** How much of the mark is filled and how much is satin, in mm². */
+	area: { fill: number; satin: number };
+}
+
+/** Satin's thread spacing as a share of `density` (0.82). */
+export const SATIN_DENSITY: number;
+/** The defaults. */
+export const STITCH: Readonly<StitchSettings>;
+/** The stitches for a mark's SVG text. Throws a TypeError for a bad option or a file with nothing filled. */
+export function stitchPlan(svg: string, options?: Partial<Omit<StitchSettings, 'seed'>> & { seed?: string | number }): StitchPlan;
+/** How many stitches a plan has, of each kind and in all. */
+export function stitchCount(plan: Pick<StitchPlan, 'fill' | 'satin' | 'border'>): { fill: number; satin: number; border: number; total: number };

package/src/stitch/plan.js

@@ -0,0 +1,127 @@
+/**
+ * @module @logomarks/core/stitch/plan
+ *
+ * A mark planned as machine embroidery, from its outlines: where each
+ * stitch lies. The ink is rasterised at a fine pitch (a tenth of a
+ * millimetre by default) at the size it will be stitched, split by width
+ * into fill (wide) and satin (narrow) parts, and each part covered as an
+ * embroiderer would: tatami rows over the fills, satin threads across the
+ * strokes, and a satin border round each fill. The stitches come back in the
+ * mark's own units, for a renderer to draw as thread. Seeded: the same mark,
+ * options and seed always give the same stitches.
+ */
+
+import { rings } from '../svg/rings.js';
+import { shapes, viewBox } from '../svg/shapes.js';
+import { frameOf, fill } from '../raster/scanline.js';
+import { distance } from '../raster/distance.js';
+import { seeded } from '../geometry/random.js';
+import { splitByWidth } from './regions.js';
+import { fillStitches } from './fill.js';
+import { satinStitches } from './satin.js';
+import { borderStitches } from './border.js';
+
+/** The defaults, in millimetres and degrees: the planner's settings for a mark stitched about 55 mm across. */
+export const STITCH = Object.freeze({
+	/** How far the mark's canvas (its viewBox's longer side) spans, in mm. */
+	size: 55,
+	/** The distance between rows of fill, in mm; satin threads lie a little closer (`SATIN_DENSITY` of it). */
+	density: 0.42,
+	/** The widest part stitched in satin, in mm; wider parts are filled. */
+	satin: 3.6,
+	/** The fill's stitch length, in mm. */
+	stitch: 3.5,
+	/** The fill rows' angle, in degrees (0 runs across, 90 down). */
+	angle: 45,
+	/** The satin border round each fill, in mm (0 for none). */
+	border: 0.9,
+	/** The raster's pitch, in pixels a mm. */
+	resolution: 10,
+	/** Seeds the small irregularities. */
+	seed: '1',
+});
+
+/** Satin's thread spacing as a share of the fill's row spacing: satin is sewn denser, so its threads close up. */
+export const SATIN_DENSITY = 0.82;
+
+/**
+ * A positive number option, or its default.
+ *
+ * @param {Record<string, unknown>} o The options.
+ * @param {'size' | 'density' | 'satin' | 'stitch' | 'border' | 'resolution'} k The key.
+ * @param {boolean} [zero=false] Whether 0 is allowed too.
+ * @returns {number} The value.
+ * @throws {TypeError} When it isn't one.
+ */
+function positive(o, k, zero = false) {
+	const v = o[k] ?? STITCH[k];
+	if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || (v === 0 && !zero)) throw new TypeError(`stitchPlan: ${k} is a number over 0${zero ? ', or 0' : ''} (got ${JSON.stringify(o[k])})`);
+	return v;
+}
+
+/**
+ * The stitches for a mark.
+ *
+ * @param {string} svg The mark's SVG text (its filled paths, circles, ellipses, rects and polygons, each with its fill rule).
+ * @param {Partial<typeof STITCH>} [options] The settings (see `STITCH`).
+ * @returns {import('./plan.js').StitchPlan} The plan.
+ * @throws {TypeError} For a bad option or a file with nothing filled.
+ */
+export function stitchPlan(svg, options = {}) {
+	if (typeof svg !== 'string') throw new TypeError('stitchPlan: pass the mark\'s SVG text');
+	const o = /** @type {Record<string, unknown>} */ (options ?? {});
+	const size = positive(o, 'size');
+	const density = positive(o, 'density');
+	const satin = positive(o, 'satin');
+	const stitch = positive(o, 'stitch');
+	const border = positive(o, 'border', true);
+	const resolution = positive(o, 'resolution');
+	const angle = o.angle ?? STITCH.angle;
+	if (typeof angle !== 'number' || !Number.isFinite(angle)) throw new TypeError(`stitchPlan: angle is a number of degrees (got ${JSON.stringify(o.angle)})`);
+	const seed = String(o.seed ?? STITCH.seed);
+
+	const paths = shapes(svg).map(({ segs, evenodd }) => ({ rings: rings(segs, 0.5), evenodd }));
+	if (!paths.length) throw new TypeError('stitchPlan: the SVG has nothing filled');
+	const vb = viewBox(svg) ?? [0, 0, 512, 512];
+	const mm = size / Math.max(vb[2], vb[3]);
+	const K = resolution * mm;
+	const box = frameOf(paths, K, 2);
+	const frame = { ...box, width: Math.ceil(box.width), height: Math.ceil(box.height) };
+	const bm = fill(paths, frame);
+	const { width: W, height: H } = bm;
+	const dist = distance(bm, 1);
+	const half = (satin / 2) * resolution;
+	const { wide, narrow } = splitByWidth(bm, dist, half);
+
+	const random = seeded(`stitch:${seed}`);
+	const toUnits = (px) => px.map((v, i) => Math.round(((i % 2 ? frame.y0 : frame.x0) + (v + 0.5) / K) * 1000) / 1000);
+	const rows = fillStitches(wide, W, H, { spacing: density * resolution, length: stitch * resolution, angle, random });
+	const threads = satinStitches(narrow, dist, W, H, { spacing: density * SATIN_DENSITY * resolution, half, smooth: 0.6 * resolution });
+	const edge = borderStitches(wide, dist, W, H, { width: border * resolution, spacing: density * resolution });
+	let [wideArea, narrowArea] = [0, 0];
+	for (let i = 0; i < W * H; i++) {
+		wideArea += wide[i];
+		narrowArea += narrow[i];
+	}
+	const px2 = resolution * resolution;
+	return {
+		viewBox: /** @type {[number, number, number, number]} */ (vb.slice(0, 4)),
+		mm,
+		settings: { size, density, satin, stitch, angle, border, resolution, seed },
+		fill: toUnits(rows),
+		satin: toUnits(threads),
+		border: toUnits(edge),
+		area: { fill: Math.round((wideArea / px2) * 10) / 10, satin: Math.round((narrowArea / px2) * 10) / 10 },
+	};
+}
+
+/**
+ * How many stitches a plan has, of each kind and in all.
+ *
+ * @param {Pick<import('./plan.js').StitchPlan, 'fill' | 'satin' | 'border'>} plan The plan.
+ * @returns {{ fill: number, satin: number, border: number, total: number }} The counts.
+ */
+export function stitchCount(plan) {
+	const [f, s, b] = [plan.fill.length / 4, plan.satin.length / 4, plan.border.length / 4];
+	return { fill: f, satin: s, border: b, total: f + s + b };
+}

package/src/stitch/regions.d.ts

@@ -0,0 +1,4 @@
+import type { Bitmap } from '../raster/scanline.js';
+
+/** The ink split by width: `wide` where a disc of radius `half` (pixels) fits (the shape opened by it), `narrow` elsewhere; small corner slivers go to `wide`. */
+export function splitByWidth(bm: Bitmap, dist: Float32Array, half: number): { wide: Uint8Array; narrow: Uint8Array };

package/src/stitch/regions.js

@@ -0,0 +1,54 @@
+/**
+ * @module @logomarks/core/stitch/regions
+ *
+ * A mark's ink split by width, as an embroiderer splits it: the parts a
+ * disc wider than the longest satin stitch fits inside (the shape opened by
+ * that disc) are filled with rows of short stitches; the rest, the strokes
+ * and thin parts, are satin. The opening is two distance transforms. The
+ * slivers it leaves in a wide part's corners are small, and go back to the
+ * fill they belong to.
+ */
+
+import { distance } from '../raster/distance.js';
+import { regions } from './field.js';
+
+/**
+ * The ink's wide and narrow parts.
+ *
+ * @param {import('../raster/scanline.js').Bitmap} bm The ink.
+ * @param {Float32Array} dist Each ink pixel's distance to the edge.
+ * @param {number} half Half the widest satin, in pixels.
+ * @returns {{ wide: Uint8Array, narrow: Uint8Array }} 1 where each is.
+ */
+export function splitByWidth(bm, dist, half) {
+	const { width: W, height: H, data } = bm;
+	const n = W * H;
+	// the centres of discs wider than a satin stitch, then everything those discs cover
+	const core = new Uint8Array(n);
+	for (let i = 0; i < n; i++) core[i] = dist[i] > half ? 1 : 0;
+	const toCore = distance({ ...bm, data: core }, 0);
+	const wide = new Uint8Array(n);
+	const narrow = new Uint8Array(n);
+	for (let i = 0; i < n; i++) {
+		if (!data[i]) continue;
+		if (core[i] || toCore[i] <= half) wide[i] = 1;
+		else narrow[i] = 1;
+	}
+	// small narrow pieces against a wide part are the corners the disc couldn't reach: they're fill
+	const { label, sizes } = regions(narrow, W, H);
+	const touches = new Uint8Array(sizes.length);
+	for (let i = 0; i < n; i++) {
+		if (label[i] < 0) continue;
+		const x = i % W;
+		if ((x > 0 && wide[i - 1]) || (x < W - 1 && wide[i + 1]) || (i >= W && wide[i - W]) || (i < n - W && wide[i + W])) touches[label[i]] = 1;
+	}
+	const small = 2 * half * half;
+	for (let i = 0; i < n; i++) {
+		const l = label[i];
+		if (l >= 0 && touches[l] && sizes[l] < small) {
+			narrow[i] = 0;
+			wide[i] = 1;
+		}
+	}
+	return { wide, narrow };
+}

package/src/stitch/satin.d.ts

@@ -0,0 +1,2 @@
+/** Satin threads across a mask, edge to edge, along the stroke's local direction (pixel coordinates, flat `x0, y0, x1, y1` each). */
+export function satinStitches(mask: Uint8Array, dist: Float32Array, W: number, H: number, o: { spacing: number; half: number; smooth: number }): number[];

package/src/stitch/satin.js

@@ -0,0 +1,86 @@
+/**
+ * @module @logomarks/core/stitch/satin
+ *
+ * Satin stitch: the narrow parts covered by threads laid side by side
+ * straight across them, edge to edge, each following the stroke's local
+ * direction. The threads start on the stroke's middle line (the ridge of
+ * its distance field), spaced evenly along it, and run both ways along the
+ * direction across until the edge. Where the picks along the middle line
+ * leave a gap, and where threads fan apart (the outside of a bend, a
+ * stroke's end), more threads are laid through what's left bare.
+ */
+
+import { acrossField, sample, spaced, reach } from './field.js';
+
+/** How many times the threads are topped up through what's still bare. */
+const PASSES = 2;
+
+/**
+ * Marks the pixels near a stitch as covered.
+ *
+ * @param {Uint8Array} covered The coverage, changed in place.
+ * @param {number} W The width.
+ * @param {number} H The height.
+ * @param {number[]} s The stitch: `x0, y0, x1, y1`.
+ * @param {number} r How near, in pixels.
+ */
+function cover(covered, W, H, [x0, y0, x1, y1], r) {
+	const [dx, dy] = [x1 - x0, y1 - y0];
+	const L2 = Math.max(1e-9, dx * dx + dy * dy);
+	for (let y = Math.max(0, Math.floor(Math.min(y0, y1) - r)); y <= Math.min(H - 1, Math.ceil(Math.max(y0, y1) + r)); y++) {
+		for (let x = Math.max(0, Math.floor(Math.min(x0, x1) - r)); x <= Math.min(W - 1, Math.ceil(Math.max(x0, x1) + r)); x++) {
+			const t = Math.max(0, Math.min(1, ((x - x0) * dx + (y - y0) * dy) / L2));
+			if ((x - x0 - t * dx) ** 2 + (y - y0 - t * dy) ** 2 <= r * r) covered[y * W + x] = 1;
+		}
+	}
+}
+
+/**
+ * The satin stitches over a mask.
+ *
+ * @param {Uint8Array} mask Where (1 inside: the narrow parts).
+ * @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.spacing The distance between threads, in pixels.
+ * @param {number} o.half Half the widest satin, in pixels (a thread reaches no farther from where it starts than about this).
+ * @param {number} o.smooth How far the direction is smoothed, in pixels.
+ * @returns {number[]} The stitches, flat: `x0, y0, x1, y1` each, in pixel coordinates.
+ */
+export function satinStitches(mask, dist, W, H, { spacing, half, smooth }) {
+	const field = acrossField(dist, mask, W, H, Math.max(1, Math.round(smooth)));
+	const out = [];
+	const covered = new Uint8Array(W * H);
+	const lay = (i) => {
+		const x = i % W, y = (i - x) / W;
+		const [ax, ay] = [Math.cos(field[i]), Math.sin(field[i])];
+		const max = Math.min(half * 1.6, dist[i] * 1.8) + 1.5;
+		const tp = reach(dist, W, H, x, y, ax, ay, max);
+		const tm = reach(dist, W, H, x, y, -ax, -ay, max);
+		if (tp + tm < 0.8) return;
+		const s = [x - ax * tm, y - ay * tm, x + ax * tp, y + ay * tp];
+		out.push(...s);
+		cover(covered, W, H, s, spacing * 1.1);
+	};
+	// the middle line: pixels at least as far from the edge as their neighbours across
+	const ridge = [];
+	for (let i = 0; i < W * H; i++) {
+		if (!mask[i] || dist[i] < 1) continue;
+		const x = i % W, y = (i - x) / W;
+		const [ax, ay] = [Math.cos(field[i]), Math.sin(field[i])];
+		if (dist[i] >= sample(dist, W, H, x + ax, y + ay) - 1e-3 && dist[i] >= sample(dist, W, H, x - ax, y - ay) - 1e-3) ridge.push(i);
+	}
+	for (const i of spaced(ridge, W, spacing)) lay(i);
+	// where the picks along the middle line met from two sides and left a gap, one more thread
+	const near = new Uint8Array(W * H);
+	for (let k = 0; k < out.length; k += 4) cover(near, W, H, out.slice(k, k + 4), spacing * 0.6);
+	for (const i of spaced(ridge.filter((j) => !near[j]), W, spacing * 0.8)) lay(i);
+	for (let p = 0; p < PASSES; p++) {
+		const bare = [];
+		for (let i = 0; i < W * H; i++) if (mask[i] && !covered[i]) bare.push(i);
+		if (!bare.length) break;
+		for (const i of spaced(bare, W, spacing, (j) => covered[j] === 1)) lay(i);
+	}
+	return out;
+}