@fusion.dev/helix-graph 0.124.0 → 0.126.0

package/README.md

@@ -239,6 +239,23 @@ const stencil = { ...(await shapeFromModel('/models/brain.glb')), place: 'surfac
 connectGraph(frame, threeDriver(box), { stencil })
 ```
 
+**`regions` sends each group to a named part of the shape**, such as a lobe
+of a brain or a state on a map:
+
+```js
+const stencil = {
+  ...(await shapeFromModel('/models/brain.glb')),
+  place: 'surface',
+  regions: { Vision: 'occipital', Hearing: 'temporal', Balance: 'cerebellum' },
+}
+```
+
+A model's parts are its meshes, named as it names them, where it has two or
+more; an SVG's are its shapes with an `id`, or in a group with one; and a
+field a page makes says its own with `regionOf(x, y, z)`. Each part fills
+evenly with the groups sent to it, and a group sent nowhere, or to a part the
+shape does not have, shares the parts no group claims.
+
 **A model is read a column of cells at a time**, so one of a hundred thousand
 triangles becomes a field in a moment. Any closed mesh works; a mesh with
 holes is read as closed where it can be. A model served from another origin

package/dist/connect-graph/shape-field.d.ts

@@ -24,6 +24,11 @@ export interface ShapeField {
         corners: Float32Array;
         triangles: Uint32Array;
     } | undefined;
+    /**
+     * Which named part of the shape a point is in, where the shape has named
+     * parts: the part nearest it, or undefined where it has none.
+     */
+    regionOf?(x: number, y: number, z?: number): string | undefined;
     /** How wide the box is. */
     readonly width: number;
 }

package/dist/connect-graph/stencil.d.ts

@@ -23,6 +23,14 @@ export type GraphStencil = (ShapeField | {
     place?: 'fill' | 'surface' | undefined;
     /** How thick the surface's shell is, as a share of the shape's size. 0.04 by default. */
     shell?: number | undefined;
+    /**
+     * Which named part of the shape each group's notes go to, by group, such
+     * as `{ Vision: 'occipital' }`, where the shape has named parts: a model's
+     * named meshes, or an SVG's elements with an `id`. A group not named here,
+     * or naming a part the shape does not have, shares the parts no group
+     * claims.
+     */
+    regions?: Readonly<Record<string, string>> | undefined;
 };
 /** The field a stencil is, or is made into. */
 export declare const fieldOf: (stencil: GraphStencil) => ShapeField;

package/dist/connect-graph/stencil.js

@@ -78,6 +78,62 @@ export const placesIn = (field, count, { place = 'fill', shell = SHELL } = {}) =
     }
     return [];
 };
+const placesByRegion = (field, wanted, options) => {
+    const regionOf = field.regionOf;
+    const count = [...wanted.values()].reduce((sum, many) => sum + many, 0);
+    if (!regionOf) {
+        return undefined;
+    }
+    for (let times = 3; times <= 24; times *= 2) {
+        const pool = placesIn(field, count * times, options);
+        if (pool.length === 0) {
+            return undefined;
+        }
+        const byRegion = new Map();
+        const inRegion = pool.map((place) => regionOf(place.x, place.y, place.z));
+        pool.forEach((place, at) => {
+            const region = inRegion[at];
+            const list = byRegion.get(region);
+            if (list) {
+                list.push(place);
+            }
+            else {
+                byRegion.set(region, [place]);
+            }
+        });
+        const claimed = new Set([...wanted.keys()].filter((region) => region !== undefined));
+        const places = [];
+        const regions = [];
+        let short = false;
+        for (const [region, many] of wanted) {
+            if (region === undefined) {
+                continue;
+            }
+            const own = byRegion.get(region) ?? [];
+            if (own.length < many) {
+                short = true;
+                break;
+            }
+            for (const place of own.slice(0, many)) {
+                places.push(place);
+                regions.push(region);
+            }
+        }
+        const rest = wanted.get(undefined) ?? 0;
+        const taken = new Set(places);
+        const free = pool.filter((_, at) => !claimed.has(inRegion[at]));
+        const spare = free.length >= rest ? free : pool.filter((place) => !taken.has(place));
+        if (short || spare.length < rest) {
+            continue;
+        }
+        for (const place of spare.slice(0, rest)) {
+            places.push(place);
+            regions.push(undefined);
+        }
+        return { places, regions };
+    }
+    return undefined;
+};
 const nested = (items, keys) => {
     const [key, ...rest] = keys;
     if (!key) {
@@ -101,10 +157,26 @@ export const fitInStencil = (positions, stencil, { clustersOf, } = {}) => {
         return { positions: new Map() };
     }
     const field = fieldOf(stencil);
-    const places = placesIn(field, notes.length, {
-        place: stencil.place ?? 'fill',
-        shell: stencil.shell ?? SHELL,
-    });
+    const options = { place: stencil.place ?? 'fill', shell: stencil.shell ?? SHELL };
+    const groupOf = (id) => clustersOf?.(id)[0];
+    const noteRegion = new Map(notes.map((note) => {
+        const group = groupOf(note.id);
+        return [note.id, group === undefined ? undefined : stencil.regions?.[group]];
+    }));
+    const wanted = new Map();
+    for (const region of noteRegion.values()) {
+        wanted.set(region, (wanted.get(region) ?? 0) + 1);
+    }
+    const regional = stencil.regions && [...wanted.keys()].some((region) => region !== undefined)
+        ? placesByRegion(field, wanted, options)
+        : undefined;
+    if (!regional) {
+        for (const id of noteRegion.keys()) {
+            noteRegion.set(id, undefined);
+        }
+    }
+    const places = regional?.places ?? placesIn(field, notes.length, options);
+    const placeRegion = regional?.regions ?? places.map(() => undefined);
     if (places.length < notes.length) {
         return { positions: new Map(positions) };
     }
@@ -237,13 +309,17 @@ export const fitInStencil = (positions, stencil, { clustersOf, } = {}) => {
             halve(ours.slice(0, half), near, level);
             halve(ours.slice(half), rest, level);
         };
-        halve([...notes], targets.map((_, at) => at));
+        for (const region of wanted.keys()) {
+            halve(notes.filter((note) => noteRegion.get(note.id) === region), targets.flatMap((_, at) => (placeRegion[at] === region ? [at] : [])));
+        }
         return { frame: { field, middle, scale, shell: thickness }, positions: fitted };
     }
-    const ours = nested(notes, [(note) => note.at.x, (note) => note.at.y]);
-    const theirs = nested(spots, [(spot) => spot.across, (spot) => spot.down]);
-    ours.forEach((note, at) => {
-        fitted.set(note.id, theirs[at].at);
-    });
+    for (const region of wanted.keys()) {
+        const ours = nested(notes.filter((note) => noteRegion.get(note.id) === region), [(note) => note.at.x, (note) => note.at.y]);
+        const theirs = nested(spots.filter((_, at) => placeRegion[at] === region), [(spot) => spot.across, (spot) => spot.down]);
+        ours.forEach((note, at) => {
+            fitted.set(note.id, theirs[at].at);
+        });
+    }
     return { frame: { field, middle, scale, shell: thickness }, positions: fitted };
 };

package/dist/shapes/flat.d.ts

@@ -2,7 +2,8 @@ import { type ShapeField } from '../connect-graph/shape-field.js';
 /**
  * A flat field from an SVG: an `<svg>` element, or its markup. Its box is
  * its `viewBox`, and its shape every path, rectangle, circle, ellipse and
- * polygon in it, together, their holes cut by the even-odd rule.
+ * polygon in it, together, their holes cut by the even-odd rule. Each shape
+ * with an `id`, or in a group with one, is a named part.
  *
  * Transforms on the shapes are not read: draw the outline in the `viewBox`'s
  * own units, as an exported icon or logo is.

package/dist/shapes/flat.js

@@ -35,10 +35,59 @@ export const shapeFromSvg = (svg, resolution = FLAT) => {
         height: height || Number(element.getAttribute('height') ?? 0),
         width: width || Number(element.getAttribute('width') ?? 0),
     };
-    const path = [...element.querySelectorAll('path, rect, circle, ellipse, polygon')]
-        .map(pathOf)
-        .join(' ');
-    return fieldFromPath(path, box.width || 1, box.height || 1, resolution);
+    const shapes = [...element.querySelectorAll('path, rect, circle, ellipse, polygon')];
+    const path = shapes.map(pathOf).join(' ');
+    const field = fieldFromPath(path, box.width || 1, box.height || 1, resolution);
+    const named = shapes.flatMap((shape) => {
+        const name = shape.closest('[id]')?.getAttribute('id');
+        return name && shape.closest('[id]') !== element ? [{ name, path: pathOf(shape) }] : [];
+    });
+    return named.length > 0 ? { ...field, regionOf: partsOf(named, field, resolution) } : field;
+};
+const partsOf = (named, box, resolution) => {
+    const cell = Math.max(box.width, box.height, 1) / resolution;
+    const nx = Math.max(1, Math.ceil(box.width / cell));
+    const ny = Math.max(1, Math.ceil(box.height / cell));
+    const canvas = document.createElement('canvas');
+    canvas.width = nx;
+    canvas.height = ny;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    const labels = new Uint16Array(nx * ny);
+    if (context) {
+        context.scale(1 / cell, 1 / cell);
+        named.forEach(({ path }, at) => {
+            const label = at + 1;
+            context.fillStyle = `rgb(${label & 255}, ${(label >> 8) & 255}, 0)`;
+            context.fill(new Path2D(path), 'evenodd');
+        });
+        const pixels = context.getImageData(0, 0, nx, ny).data;
+        for (let at = 0; at < labels.length; at++) {
+            if ((pixels[at * 4 + 3] ?? 0) === 255 && (pixels[at * 4 + 2] ?? 0) === 0) {
+                const label = (pixels[at * 4] ?? 0) + ((pixels[at * 4 + 1] ?? 0) << 8);
+                labels[at] = label <= named.length ? label : 0;
+            }
+        }
+    }
+    return (x, y) => {
+        const column = Math.floor(x / cell);
+        const row = Math.floor(y / cell);
+        for (let ring = 0; ring <= 3; ring++) {
+            for (let dy = -ring; dy <= ring; dy++) {
+                for (let dx = -ring; dx <= ring; dx++) {
+                    const c = column + dx;
+                    const r = row + dy;
+                    if (c < 0 || r < 0 || c >= nx || r >= ny) {
+                        continue;
+                    }
+                    const label = labels[r * nx + c] ?? 0;
+                    if (label > 0) {
+                        return named[label - 1]?.name;
+                    }
+                }
+            }
+        }
+        return undefined;
+    };
 };
 export const shapeFromImage = (image, { resolution = FLAT, threshold = 0.5 } = {}) => {
     const size = (value) => typeof value === 'number' ? value : value.baseVal.value;

package/dist/shapes/model.d.ts

@@ -3,7 +3,10 @@ import { type TriangleOptions } from './triangles.js';
 /**
  * A solid field from a glTF model, the web's standard format for one: a
  * URL to a `.glb` or `.gltf` file, or the file's bytes. Every mesh in it is
- * read, placed as the model places it.
+ * read, placed as the model places it, and where it has two meshes or more,
+ * each is a part of the field, named as the model names it, which a
+ * stencil's `regions` sends groups to. A mesh the model leaves unnamed is
+ * named as three.js names it, `mesh_0` and on.
  *
  * **three.js reads the file**, imported when this is first called, so a page
  * that draws no model never downloads a loader. It is an optional peer of

package/dist/shapes/model.js

@@ -10,6 +10,8 @@ export const shapeFromModel = async (source, options = {}) => {
         : await loader.parseAsync(source, '');
     model.scene.updateMatrixWorld(true);
     const corners = [];
+    const names = [];
+    const ofTriangle = [];
     const point = new Vector3();
     model.scene.traverse((object) => {
         if (!(object instanceof Mesh)) {
@@ -20,12 +22,24 @@ export const shapeFromModel = async (source, options = {}) => {
         if (!place) {
             return;
         }
+        const name = object.name || geometry.name || '';
+        let part = names.indexOf(name);
+        if (name && part < 0) {
+            part = names.push(name) - 1;
+        }
         const index = geometry.getIndex();
         const count = index ? index.count : place.count;
         for (let at = 0; at < count; at++) {
             point.fromBufferAttribute(place, index ? index.getX(at) : at).applyMatrix4(object.matrixWorld);
             corners.push(point.x, point.y, point.z);
         }
+        for (let triangle = 0; triangle < Math.floor(count / 3); triangle++) {
+            ofTriangle.push(part);
+        }
+    });
+    const named = names.length > 1 && !ofTriangle.includes(-1);
+    return shapeFromTriangles(corners, null, {
+        ...options,
+        ...(named ? { regions: { names, ofTriangle } } : {}),
     });
-    return shapeFromTriangles(corners, null, options);
 };

package/dist/shapes/triangles.d.ts

@@ -1,6 +1,15 @@
 import { type ShapeField } from '../connect-graph/shape-field.js';
 /** How a solid is read from triangles. */
 export interface TriangleOptions {
+    /**
+     * The named parts the triangles make: each part's name, and which part
+     * each triangle is in, by its place in `names`. Gives the field
+     * `regionOf`, the part a point is in: the part of the triangle nearest it.
+     */
+    regions?: {
+        names: readonly string[];
+        ofTriangle: ArrayLike<number>;
+    } | undefined;
     /** How many cells the field has along the solid's longest side. 96 by default. */
     resolution?: number | undefined;
 }
@@ -17,4 +26,4 @@ export interface TriangleOptions {
  * minutes. A surface with gaps is read as closed where it can be, and a gap
  * shows as a column filled or emptied through.
  */
-export declare const shapeFromTriangles: (positions: ArrayLike<number>, index?: ArrayLike<number> | null | undefined, { resolution }?: TriangleOptions) => ShapeField;
+export declare const shapeFromTriangles: (positions: ArrayLike<number>, index?: ArrayLike<number> | null | undefined, { regions, resolution }?: TriangleOptions) => ShapeField;

package/dist/shapes/triangles.js

@@ -1,6 +1,54 @@
 import { fieldFromCells, SOLID } from '../connect-graph/shape-field.js';
 const NUDGE = 1e-6 * Math.PI;
-export const shapeFromTriangles = (positions, index, { resolution = SOLID } = {}) => {
+const NEAREST = 40;
+const nearestPart = (middles, parts, names, box) => {
+    const size = Math.max(box.width, box.height, box.depth) / NEAREST;
+    const cells = new Map();
+    const key = (cx, cy, cz) => `${cx},${cy},${cz}`;
+    const count = middles.length / 3;
+    for (let at = 0; at < count; at++) {
+        const k = key(Math.floor(middles[at * 3] / size), Math.floor(middles[at * 3 + 1] / size), Math.floor(middles[at * 3 + 2] / size));
+        const list = cells.get(k);
+        if (list) {
+            list.push(at);
+        }
+        else {
+            cells.set(k, [at]);
+        }
+    }
+    return (x, y, z = box.depth / 2) => {
+        const cx = Math.floor(x / size);
+        const cy = Math.floor(y / size);
+        const cz = Math.floor(z / size);
+        let best = -1;
+        let nearest = Number.POSITIVE_INFINITY;
+        for (let ring = 0; ring <= NEAREST; ring++) {
+            for (let dx = -ring; dx <= ring; dx++) {
+                for (let dy = -ring; dy <= ring; dy++) {
+                    for (let dz = -ring; dz <= ring; dz++) {
+                        if (Math.max(Math.abs(dx), Math.abs(dy), Math.abs(dz)) !== ring) {
+                            continue;
+                        }
+                        for (const at of cells.get(key(cx + dx, cy + dy, cz + dz)) ?? []) {
+                            const far = (middles[at * 3] - x) ** 2 +
+                                (middles[at * 3 + 1] - y) ** 2 +
+                                (middles[at * 3 + 2] - z) ** 2;
+                            if (far < nearest) {
+                                nearest = far;
+                                best = at;
+                            }
+                        }
+                    }
+                }
+            }
+            if (best >= 0 && Math.sqrt(nearest) <= ring * size) {
+                break;
+            }
+        }
+        return best < 0 ? undefined : names[parts[best]];
+    };
+};
+export const shapeFromTriangles = (positions, index, { regions, resolution = SOLID } = {}) => {
     const corners = Math.floor(positions.length / 3);
     const low = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
     const high = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
@@ -84,9 +132,23 @@ export const shapeFromTriangles = (positions, index, { resolution = SOLID } = {}
         height: ny * cell,
         width: nx * cell,
     });
+    let regionOf;
+    if (regions && regions.names.length > 0) {
+        const middles = new Float32Array(triangles * 3);
+        for (let triangle = 0; triangle < triangles; triangle++) {
+            for (let which = 0; which < 3; which++) {
+                const at = corner(triangle, which);
+                middles[triangle * 3] = middles[triangle * 3] + (at[0] * cell) / 3;
+                middles[triangle * 3 + 1] = middles[triangle * 3 + 1] + (at[1] * cell) / 3;
+                middles[triangle * 3 + 2] = middles[triangle * 3 + 2] + (at[2] * cell) / 3;
+            }
+        }
+        regionOf = nearestPart(middles, regions.ofTriangle, regions.names, field);
+    }
     return {
         ...field,
         distance: field.distance,
         mesh: { corners: meshCorners, triangles: meshTriangles },
+        ...(regionOf ? { regionOf } : {}),
     };
 };

package/dist/three/three-driver.js

@@ -255,6 +255,42 @@ const framed = (geometry) => {
     geometry.setAttribute('frame', new BufferAttribute(frame, 4));
     return geometry;
 };
+const SMOOTH = { surface: 3, ways: 6 };
+const neighborsOf = (index, count) => {
+    const sets = Array.from({ length: count }, () => new Set());
+    for (let at = 0; at < index.count; at += 3) {
+        const a = index.getX(at);
+        const b = index.getX(at + 1);
+        const c = index.getX(at + 2);
+        sets[a]?.add(b).add(c);
+        sets[b]?.add(a).add(c);
+        sets[c]?.add(a).add(b);
+    }
+    return sets.map((set) => Int32Array.from(set));
+};
+const averaged = (values, neighbors, share) => {
+    const out = new Float32Array(values.length);
+    neighbors.forEach((around, at) => {
+        let x = 0;
+        let y = 0;
+        let z = 0;
+        for (const other of around) {
+            x += values[other * 3];
+            y += values[other * 3 + 1];
+            z += values[other * 3 + 2];
+        }
+        const many = around.length || 1;
+        for (const [axis, sum] of [
+            [0, x],
+            [1, y],
+            [2, z],
+        ]) {
+            const value = values[at * 3 + axis];
+            out[at * 3 + axis] = around.length ? value + share * (sum / many - value) : value;
+        }
+    });
+    return out;
+};
 const channels = (color) => {
     const [red = 128, green = 128, blue = 128] = color.match(/[\d.]+/g)?.map(Number) ?? [];
     return [red / 255, green / 255, blue / 255];
@@ -403,17 +439,31 @@ export const threeDriver = (container, options = {}) => {
             geometry.setIndex(new BufferAttribute(field.mesh.triangles, 1));
             geometry = mergeVertices(geometry);
             const place = geometry.getAttribute('position');
+            const count = place.count;
+            const neighbors = neighborsOf(geometry.getIndex(), count);
             const step = Math.max(field.width, field.height, field.depth) / 64;
-            for (let at = 0; at < place.count; at++) {
+            let way = new Float32Array(count * 3);
+            for (let at = 0; at < count; at++) {
                 const x = place.getX(at);
                 const y = place.getY(at);
                 const z = place.getZ(at);
-                const gx = field.distance(x + step, y, z) - field.distance(x - step, y, z);
-                const gy = field.distance(x, y + step, z) - field.distance(x, y - step, z);
-                const gz = field.distance(x, y, z + step) - field.distance(x, y, z - step);
-                const length = Math.hypot(gx, gy, gz) || 1;
-                place.setXYZ(at, x - (gx / length) * inset, y - (gy / length) * inset, z - (gz / length) * inset);
+                way[at * 3] = field.distance(x + step, y, z) - field.distance(x - step, y, z);
+                way[at * 3 + 1] = field.distance(x, y + step, z) - field.distance(x, y - step, z);
+                way[at * 3 + 2] = field.distance(x, y, z + step) - field.distance(x, y, z - step);
+            }
+            for (let pass = 0; pass < SMOOTH.ways; pass++) {
+                way = averaged(way, neighbors, 0.5);
+            }
+            for (let at = 0; at < count; at++) {
+                const length = Math.hypot(way[at * 3], way[at * 3 + 1], way[at * 3 + 2]) ||
+                    1;
+                place.setXYZ(at, place.getX(at) - (way[at * 3] / length) * inset, place.getY(at) - (way[at * 3 + 1] / length) * inset, place.getZ(at) - (way[at * 3 + 2] / length) * inset);
+            }
+            let corners = place.array;
+            for (let pass = 0; pass < SMOOTH.surface; pass++) {
+                corners = averaged(averaged(corners, neighbors, 0.5), neighbors, -0.53);
             }
+            place.array.set(corners);
         }
         else {
             const { corners, triangles } = surfaceOf(field, { at: -inset });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-graph",
   "description": "Connects the Helix Graph frame to a graph renderer: Sigma.js, cosmos.gl, three.js, or a driver of your own.",
-  "version": "0.124.0",
+  "version": "0.126.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -47,12 +47,12 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.124.0"
+    "@fusion.dev/helix-core": "0.126.0"
   },
   "devDependencies": {
     "@cosmos.gl/graph": "^3.4.2",
-    "@fusion.dev/helix-headless": "0.124.0",
-    "@fusion.dev/helix-testing": "0.124.0",
+    "@fusion.dev/helix-headless": "0.126.0",
+    "@fusion.dev/helix-testing": "0.126.0",
     "@types/bun": "^1.3.0",
     "@types/three": "^0.186.0",
     "d3-force-3d": "^3.0.6",