@volter/editor-blender 0.1.150 → 0.1.152

package/contributions/blender-icon-trace.mjs

@@ -1,53 +1,4 @@
-/**
- * TRACING BLENDER'S OWN ICON SOURCES — the half of `blender-icons.source.mjs`
- * that turns one of Blender's per-icon SVGs into a path on this set's 16-unit
- * grid (WORK.md §Blender in the tab is Blender, "Inspection parity", I2
- * decision 2).
- *
- * ## Why a trace and not a drawing
- *
- * The Properties rail's sixteen tabs used to be OUR marks in Blender's idiom,
- * and I1 measured what that cost: thirteen of the sixteen were a distinct NAME
- * over a neighbouring silhouette this set already drew (a globe for World, a
- * magnet for Constraints, a palette for Material), not a measurement of
- * Blender's mark. The north star is "the reference is Blender's SOURCE as well
- * as its frames" (ARCHITECTURE-CORE §Blender north star), and for an icon the
- * source is literally a vector file: `release/datafiles/icons_svg/<name>.svg`
- * in the Blender checkout at the engine's pin. Tracing it is a MEASUREMENT;
- * drawing a lookalike is a guess with a citation stapled to it.
- *
- * ## Licence
- *
- * Blender's icon sources are GPL-2.0-or-later, like the rest of the Blender
- * tree, and a trace of one is a derivative of it. `@volter/editor-blender` therefore
- * carries BOTH licences — its SPDX expression is
- * `AGPL-3.0-only AND GPL-3.0-or-later` (`packages/blender/LICENSE`): our code
- * AGPL-3.0-only, Blender's traced artwork conveyed under GPL-3.0-or-later on
- * Blender's own "or later", and AGPL §13 / GPL §13 permitting the
- * combination. So a GPL icon PATH may live inside this package, and that is
- * deliberate, stated in the package's LICENSE and recorded per glyph in
- * `blender.icons.traced.json` (source file + sha256). Nothing traced here may
- * be copied into an Apache-2.0 or MIT part of this repo — `packages/editor`'s
- * own icon set included.
- *
- * ## The geometry
- *
- * Blender authors each icon on a 16-unit grid and Inkscape writes it out
- * inside a 1600x1600 viewBox with a `matrix(100 0 0 100 tx ty)` on the path —
- * so the trace is: compose the element's transforms, scale by
- * `16 / viewBox width`, and the result is already this set's coordinate
- * system. Nothing is re-proportioned, re-stroked or re-centred; a traced
- * glyph is Blender's own outline.
- *
- * Not every icon is that simple, which is why this is a general affine
- * transform rather than a scale-and-offset: `material.svg` carries a
- * REFLECTION (`matrix(-99.99 0 0 99.99 …)`), `particles.svg` a quarter
- * ROTATION (`matrix(0 100 -100 0 …)`) with a second matrix on the path inside
- * it, and `pointcloud_data.svg` a NON-UNIFORM scale. Under any of those an
- * elliptical arc's radii and x-axis rotation change, and a reflection flips
- * its sweep — {@link transformArc} does that properly instead of assuming the
- * matrix is a scale.
- */
+/** Trace Blender’s per-icon SVG source into this set’s 16-unit grid. Compose affine transforms and scale by the authored Inkscape grid unit; transformArc handles rotation, reflection and non-uniform scale. Blender artwork is GPL-2.0-or-later and is conveyed here under GPL-3.0-or-later, combined with AGPL-3.0-only code under both licences’ section 13. The package LICENSE and blender.icons.traced.json retain source paths and hashes. Traced artwork must not enter Apache-2.0 or MIT packages. */
 
 // ------------------------------------------------------------------ matrices
 
@@ -287,47 +238,13 @@ function chunk(values, size) {
   return out;
 }
 
-/**
- * THE AUTHORED UNIT, WHICH IS NOT THE ARTBOARD. Blender's icons are drawn on
- * an Inkscape canvas whose grid the file itself declares —
- * `<inkscape:grid spacingx="100" spacingy="100">` — and one square of that
- * grid is one unit of the 16-unit icon grid. So the scale from a file's user
- * units to this set's is `1 / spacing`, and the viewBox does not enter it.
- *
- * MEASURED at the engine's pin (v5.2.0, 790 files in
- * `release/datafiles/icons_svg/`): 755 declare `spacingx="100"`, two
- * (`key_shift*.svg`) declare 50, and 33 declare no grid at all — those 33 are
- * machine-written with a `matrix(100 …)` on the group and take the default
- * below. The viewBox is NOT square with the grid: only **536 of the 790 are
- * 1600 wide**, and the rest run from 48 to 5236. A mark authored on a
- * 14-unit-wide canvas is fourteen units wide, not sixteen, so scaling it by
- * `16 / 1400` inflated it by a seventh and pushed its ink off the bottom of
- * the cell — `light_data.svg` traced to a box 18.29 tall. That was the defect
- * this constant replaces (WORK.md §Blender in the tab is Blender, I5,
- * orchestrator ruling 2 of 2026-09-19: "the icon trace scales by the authored
- * unit, not the artboard").
- */
+/** Scale from the authored Inkscape grid spacing, not the viewBox width; source files without a grid use the default authored unit below. */
 const DEFAULT_GRID_SPACING = 100;
 
 /**
- * AND THE ARTBOARD IS A CROP, so the mark is CENTRED in the cell rather than
- * pinned to the artboard's corner.
- *
- * This is the other half of the same measurement, and the data states it
- * plainly: rescaled by the authored unit, **every one of the 197 traced marks
- * has its ink box starting at exactly (1, 1)** and ending exactly one unit
- * short of the artboard — `mod_particle_instance.svg` 1600×1600 → [1, 1, 15,
- * 15], `light_data.svg` 1400×1700 → [1, 1, 13, 16], `dot.svg` 600×600 →
- * [1, 1, 5, 5]. That is Inkscape's "resize page to drawing" with a one-grid
- * margin, run per file. So the page carries the mark's SIZE and nothing about
- * where it sits in a 16-unit cell, and reading its top-left corner as the
- * cell's corner is what put the 4-unit dot and the 10-unit checkbox in the
- * top-left eighth of their cells.
- *
- * Centring the PAGE (not the ink) keeps the authored margins symmetric, and
- * it is exactly zero for a 1600×1600 artboard — which is why this leaves the
- * 158 glyphs authored on that page byte-identical and moves only the 39 that
- * are not.
+ * Scale the artboard by its authored grid spacing, then centre it in the
+ * 16-unit cell. Centring the artboard preserves its symmetric margins when
+ * its extent differs from the cell's size.
  */
 const centreOffset = (extent, spacing) => (16 - extent / spacing) / 2;
 
@@ -344,16 +261,9 @@ const withOwn = (matrix, tag) =>
  * so the caller can state how much of the box the mark fills rather than
  * assume it.
  *
- * THE GROUPS ARE WALKED AS A TREE, not sampled. This trace used to take the
- * FIRST `<g>` carrying a transform and apply it to every path in the file, on
- * the stated belief that "nesting never goes deeper than that in this data
- * set". Measured at the pin: **21 of the 790 files nest two or more
- * transformed groups**, and `mod_particle_instance.svg` — a `matrix(0 -1 -1 0
- * 558.008 761.005)` quarter turn INSIDE a `matrix(100 0 0 -100 …)` flip —
- * traced to a box at [273, −60], seventeen grid units clear of the canvas. A
- * single-sample read cannot see an inner transform at all, so this keeps a
- * STACK: a `<g>` pushes the matrix in force times its own, `</g>` pops, and a
- * `<path>` draws under whatever is on top.
+ * Group transforms compose through a stack: `<g>` pushes the current matrix
+ * times its own transform, `</g>` pops, and each `<path>` composes its own
+ * transform with the matrix on top.
  */
 export function traceBlenderIcon(svg) {
   const viewBox = /viewBox="([^"]+)"/.exec(svg);