@logomarks/core 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to `@logomarks/core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] — 2026-11-15
+
+### Added
+
+The Lookbook's mark measures, moved here from `@logomarks/lookbook/marks` (the code unchanged, documented and typed), so the cards and anything else that sizes a mark share one copy. Browser-safe, like the rest of `/analyse` and `/edit`.
+
+- **The optical size in `/analyse`:** `markBox(paths)` (the real box round a mark's outlines, the 448 fit's box when there is nothing to read), `inkShare(paths)` (how much of that box is ink, by scanline coverage 16 cells across), `opticalScale(box, ink)` (how much bigger to draw a wide, slim or light mark: 1 for a square solid, 448 × 200 about 1.22, never above 1.3) and `OPTICAL`, its limits.
+- **Cells by count in `/edit`:** `cellsAcross(n, box)` beside `pixelGrid` (a grid `n` cells across the box's longest side, any `n`, where `pixelGrid` takes an amount and stops at 14 across), and `markCells(paths, n)` (shapes → rings → coverage → filled cells and their path in one call).
+
+Proved on `@logomarks/lookbook` 0.1.0: its own functions give the same values as these on the golden cases, and its equivalence tests pass unchanged on them. The golden tests gain the five cases (`optical.*`, `cells.*`), on six live marks.
+
 ## [0.2.0] — 2026-11-15
 
 ### Added

package/README.md

@@ -27,10 +27,10 @@ checkFit(mark).problems;              // []
 - `/geometry`: shapes and real booleans, strokes, tracks, iso solids, badges and letter skeletons
 - `/svg`: one SVG path parser, filled shapes, bounds and rings
 - `/fit`: the 448 fit and its check (refitting a fitted mark gives the same file)
-- `/analyse`: specks, slivers and pin-holes, gap and stroke widths, shape tags
+- `/analyse`: specks, slivers and pin-holes, gap and stroke widths, shape tags, the optical size (a mark's box, its ink, how much bigger to draw it)
 - `/similar`: outline and letter signatures, IoU and nearest marks
 - `/raster`: scanline fill, components, distance transform
-- `/edit`: the studio's shape edits (weight, soften, gap, detail) and pixelate
+- `/edit`: the studio's shape edits (weight, soften, gap, detail) and pixelate, by amount or by a count of cells
 - `/sdf`: shapes as signed distance fields, smooth unions and exact gap cuts, traced to kit shapes
 - `/stitch`: a mark planned as machine embroidery (fill, satin and border stitches), for a renderer to draw as thread
 - `/parts`: the parts the industry symbols are built from (Node)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logomarks/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Geometry, SVG reading, fitting, analysis and similarity for logomarks on a 512 grid: the kit the Logomarks set is drawn with (shapes, real booleans, strokes, tracks, iso solids, badges, letter skeletons), one SVG path parser, the 448 fit, speck and shape-tag analysis, outline signatures, signed distance fields traced to shapes, stitch plans for embroidery, and the parts the generators draw with: iso objects, letters and type, font glyphs, pixel dither, objects and the Bold, Line and Track forms, plus the batch runner.",
   "type": "module",
   "main": "src/index.js",

package/src/analyse/index.d.ts

@@ -6,3 +6,4 @@ export { SPECKS, vectorParts, rasterParts, markParts, smallParts } from './speck
 export { SHAPE, shapeTags, tagsOf } from './tags.js';
 export { MEASURE, shapeMeasures } from './shape/measures.js';
 export { WIDTHS, groupRuns, widths } from './widths.js';
+export { OPTICAL, markBox, inkShare, opticalScale } from './optical.js';

package/src/analyse/index.js

@@ -1,8 +1,9 @@
 /**
- * Analysis of a mark: its pieces and holes (specks, slivers, pin-holes), its stroke and gap widths, and its shape tags
- * (with the measures they are decided on).
+ * Analysis of a mark: its pieces and holes (specks, slivers, pin-holes), its stroke and gap widths, its shape tags
+ * (with the measures they are decided on), and its optical size (its real box and how much of it is ink).
  */
 export { SPECKS, vectorParts, rasterParts, markParts, smallParts } from './specks.js';
 export { SHAPE, shapeTags, tagsOf } from './tags.js';
 export { MEASURE, shapeMeasures } from './shape/measures.js';
 export { WIDTHS, groupRuns, widths } from './widths.js';
+export { OPTICAL, markBox, inkShare, opticalScale } from './optical.js';

package/src/analyse/optical.d.ts

@@ -0,0 +1,20 @@
+import type { Bounds } from '../svg/outline.js';
+
+/** The optical size's limits: the most a mark grows, and how much its box and its ink count. */
+export const OPTICAL: {
+	/** The most a mark grows (× its 448 fit). */
+	readonly max: 1.3;
+	/** The box's term: (448² / its area) to this power, so a square is 1, 448 × 200 about 1.22. */
+	readonly power: 0.25;
+	/** The ink's term: up to this much more for a light mark … */
+	readonly light: 0.1;
+	/** … in full at or below this share of its box inked, none at or above `solid`. */
+	readonly thin: 0.2;
+	readonly solid: 0.45;
+};
+/** The real box round a mark's outlines (its paths, or the whole file), on the 512 canvas; the 448 fit's box when there is nothing to read. */
+export function markBox(paths: string): Bounds;
+/** How much of a mark's own box is ink, 0–1 (scanline coverage, 16 cells across its longest side); 1 when there is nothing to read. */
+export function inkShare(paths: string): number;
+/** The mark's optical size: how much bigger to draw a wide, slim or light mark, 1 to `OPTICAL.max`; `ink` 1 leaves the ink out of it. */
+export function opticalScale(box: Pick<Bounds, 'w' | 'h'>, ink?: number): number;

package/src/analyse/optical.js

@@ -0,0 +1,76 @@
+/**
+ * @module @logomarks/core/analyse/optical
+ *
+ * A mark's optical size: its real box, how much of that box is ink, and how much bigger to draw it so a wide, slim or
+ * light mark holds as much of the eye as a square, solid one at the 448 fit. Browser-safe (core's SVG reader and
+ * scanline coverage, no renderer). From the Lookbook's mark measures (`@logomarks/lookbook/marks`).
+ */
+
+import { shapes } from '../svg/shapes.js';
+import { bounds } from '../svg/outline.js';
+import { rings } from '../svg/rings.js';
+import { cellsAcross, pixelCoverage } from '../edit/pixelate.js';
+import { CANVAS, FIT } from '../fit/index.js';
+
+/** The 448 fit's box on the 512 canvas: what `markBox` gives when there is nothing to read. */
+const FITTED = { x: (CANVAS - FIT) / 2, y: (CANVAS - FIT) / 2, w: FIT, h: FIT };
+
+/** The optical size's limits: the most a mark grows, and how much its box and its ink count. */
+export const OPTICAL = {
+	/** The most a mark grows (× its 448 fit). */
+	max: 1.3,
+	/** The box's term: (448² / its area) to this power, so a square is 1, 448 × 200 about 1.22. */
+	power: 0.25,
+	/** The ink's term: up to this much more for a light mark … */
+	light: 0.1,
+	/** … in full at or below this share of its box inked, none at or above `solid`. */
+	thin: 0.2,
+	solid: 0.45,
+};
+
+/**
+ * The real box round a mark's outlines, on the 512 canvas (curves and arcs sampled, as the fit measures them); the
+ * 448 fit's box when there is nothing to read.
+ *
+ * @param {string} paths The mark's markup: its paths, or the whole file.
+ * @returns {import('../svg/outline.js').Bounds} The box.
+ */
+export function markBox(paths) {
+	const list = shapes(paths);
+	if (!list.length) return { ...FITTED };
+	const b = bounds(list);
+	return Number.isFinite(b.w) && b.w > 0 ? b : { ...FITTED };
+}
+
+/**
+ * How much of a mark's own box is ink, 0–1: the scanline coverage on a grid 16 cells across its longest side.
+ *
+ * @param {string} paths The mark's markup: its paths, or the whole file.
+ * @returns {number} The share inked; 1 when there is nothing to read.
+ */
+export function inkShare(paths) {
+	const list = shapes(paths);
+	if (!list.length) return 1;
+	const grid = cellsAcross(16, markBox(paths));
+	const cov = pixelCoverage(list.map((s) => ({ rings: rings(s.segs, 3), evenodd: s.evenodd })), grid);
+	let sum = 0;
+	for (const v of cov) sum += v;
+	return cov.length ? sum / cov.length : 1;
+}
+
+/**
+ * The mark's optical size: how much bigger to draw it so it holds as much of the eye as a square, solid mark at the
+ * 448 fit. Every mark is fitted to 448 on its longest side, so a wide, short one (448 × 200) or a slim one (266 × 448)
+ * carries far less area, and a light, line-drawn one less weight. 1 for a square solid; 448 × 200 about 1.22; never
+ * below 1, never above `OPTICAL.max`.
+ *
+ * @param {{ w: number, h: number }} box The mark's box (`markBox`).
+ * @param {number} [ink=1] The share of its box inked (`inkShare`); 1 leaves the ink out of it.
+ * @returns {number} The scale, 1 to `OPTICAL.max`.
+ */
+export function opticalScale(box, ink = 1) {
+	const { max, power, light, thin, solid } = OPTICAL;
+	const area = (FIT * FIT) / Math.max(1, box.w * box.h);
+	const weight = 1 + light * Math.min(1, Math.max(0, (solid - ink) / (solid - thin)));
+	return Math.min(max, Math.max(1, area ** power * weight));
+}

package/src/edit/cells.d.ts

@@ -0,0 +1,13 @@
+import type { PixelGrid } from './pixelate.js';
+
+/** A mark as square cells: the grid, which cells are filled (row by row), and the filled cells as one path. */
+export interface MarkCells {
+	grid: PixelGrid;
+	/** 1 per filled cell, row by row. */
+	on: Uint8Array;
+	/** The filled cells merged into rectangles, as one path's d; empty when none is filled. */
+	d: string;
+}
+
+/** The mark (its paths, or the whole file) as square cells, `n` across its longest side, by scanline coverage. */
+export function markCells(paths: string, n: number): MarkCells;

package/src/edit/cells.js

@@ -0,0 +1,26 @@
+/**
+ * @module @logomarks/core/edit/cells
+ *
+ * A mark as square cells by count: shapes → rings → scanline coverage → filled cells in one call, on a grid `n` cells
+ * across the mark's real box (`cellsAcross`). Browser-safe. From the Lookbook's mark measures (its pixel and LED looks).
+ */
+
+import { shapes } from '../svg/shapes.js';
+import { rings } from '../svg/rings.js';
+import { markBox } from '../analyse/optical.js';
+import { cellsAcross, pixelCoverage, pixelCells, pixelPath } from './pixelate.js';
+
+/**
+ * The mark as square cells, `n` across its longest side, measured by scanline coverage (half a cell covered, or a
+ * fifth where a cell would otherwise break a thin line: `pixelCells`).
+ *
+ * @param {string} paths The mark's markup: its paths, or the whole file.
+ * @param {number} n Cells across the longest side.
+ * @returns {import('./cells.js').MarkCells} The grid, the filled cells and the filled cells as one path (empty when none).
+ */
+export function markCells(paths, n) {
+	const list = shapes(paths);
+	const grid = cellsAcross(n, markBox(paths));
+	const cov = pixelCoverage(list.map((s) => ({ rings: rings(s.segs), evenodd: s.evenodd })), grid);
+	return { grid, on: pixelCells(cov, grid), d: pixelPath(cov, grid) ?? '' };
+}

package/src/edit/index.d.ts

@@ -1,6 +1,8 @@
 export type { ShapeInfo, SmallSizeInfo } from './reshape.js';
 export type { Adjust, Frame, Similarity, AdjustEnv } from './adjust.js';
 export type { PixelGrid } from './pixelate.js';
+export type { MarkCells } from './cells.js';
 export { loadShaper, shaperReady, hasCorners, reshape, pieceCount, shapeInfo, smallSizeInfo } from './reshape.js';
 export { NO_ADJUST, isAdjusted, adjustSuffix, transformPath, adjustPaths } from './adjust.js';
-export { SS, pixelGrid, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { SS, pixelGrid, cellsAcross, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { markCells } from './cells.js';

package/src/edit/index.js

@@ -1,7 +1,9 @@
 /**
  * Shape edits for a studio: weight, soften, gap and detail (Clipper, loaded on first use), turns, tilts, flips and
- * frames, and pixel-art redraws. Browser-safe: what needs a renderer (exact bounds, a canvas) is passed in.
+ * frames, and pixel-art redraws (by amount, or by a count of cells across). Browser-safe: what needs a renderer (exact
+ * bounds, a canvas) is passed in.
  */
 export { loadShaper, shaperReady, hasCorners, reshape, pieceCount, shapeInfo, smallSizeInfo } from './reshape.js';
 export { NO_ADJUST, isAdjusted, adjustSuffix, transformPath, adjustPaths } from './adjust.js';
-export { SS, pixelGrid, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { SS, pixelGrid, cellsAcross, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { markCells } from './cells.js';

package/src/edit/pixelate.d.ts

@@ -13,6 +13,8 @@ export interface PixelGrid {
 export const SS: 6;
 /** The grid for a box: 48 cells across its longest side at amount 0, 14 at amount 1, centred. */
 export function pixelGrid(amount: number, box: { x: number; y: number; width: number; height: number }): PixelGrid;
+/** The grid for a box by count: `n` cells across its longest side (any `n`), centred. */
+export function cellsAcross(n: number, box: { x: number; y: number; w: number; h: number }): PixelGrid;
 /** How much of each cell the mark's rings cover (0–1, row by row), by scanline at SS × SS samples a cell. */
 export function pixelCoverage(paths: readonly FillPath[], grid: PixelGrid): Float32Array;
 /** The filled cells (1 each, row by row): half covered, or a fifth where a cell stands alone or bridges two. */

package/src/edit/pixelate.js

@@ -36,6 +36,21 @@ export function pixelGrid(amount, box) {
 	return { cols, rows, cell, x0, y0 };
 }
 
+/**
+ * A pixel grid of `n` cells across a box's longest side, centred on it: `pixelGrid` sized by a count, any count
+ * (`pixelGrid` takes an amount and stops at 14 across).
+ *
+ * @param {number} n Cells across the longest side.
+ * @param {{ x: number, y: number, w: number, h: number }} box The mark's box (`markBox` in `/analyse`, or `bounds`).
+ * @returns {import('./index.js').PixelGrid} The grid: columns, rows, cell size and top-left corner.
+ */
+export function cellsAcross(n, box) {
+	const cell = Math.max(box.w, box.h) / n;
+	const cols = Math.max(1, Math.round(box.w / cell)), rows = Math.max(1, Math.round(box.h / cell));
+	const x0 = box.x + box.w / 2 - (cols * cell) / 2, y0 = box.y + box.h / 2 - (rows * cell) / 2;
+	return { cols, rows, cell, x0, y0 };
+}
+
 /**
  * How much of each cell the mark covers, measured from its rings by scanline at `SS` × `SS` samples a cell: what a
  * canvas would measure, without one.