@fusion.dev/helix-plot 0.197.1 → 0.199.0

package/dist/three/ribbon-driver.d.ts

@@ -0,0 +1,35 @@
+import type { SpatialRibbonChartDriver } from '../connect-spatial-ribbon-chart/connect-spatial-ribbon-chart.js';
+/** How the three.js ribbon driver behaves where the page does not say. */
+export interface ThreeRibbonDriverOptions {
+    /**
+     * How many pixels the drawing has for each of the page's. By default, on a
+     * screen worked with a mouse, half as many again as the screen has, at
+     * least two and at most three; on a touch screen, as many as the screen
+     * has, at most two.
+     */
+    density?: number | undefined;
+}
+/**
+ * Draws a Spatial Ribbon Chart's series as ribbons in three dimensions with
+ * three.js. Pass it to `connectSpatialRibbonChart` with the element to draw
+ * in, which the chart holds in its plot:
+ *
+ * ```js
+ * import { connectSpatialRibbonChart } from '@fusion.dev/helix-plot'
+ * import { threeRibbonDriver } from '@fusion.dev/helix-plot/three'
+ *
+ * connectSpatialRibbonChart(chart, threeRibbonDriver(chart.querySelector('div')))
+ * ```
+ *
+ * **Each series is a ribbon in its own depth**, its top following the
+ * values and its sides falling to zero, in a box long across and shallow in
+ * depth, lit from above. Each series takes a series color from the theme.
+ *
+ * **Dragging turns the box, and the wheel and a pinch bring it nearer.**
+ * Shift with an arrow on the chart turns it a step. It never turns by itself.
+ * It draws only while something moves, asks for no frames at rest, and
+ * shares the page's WebGL contexts with every three.js drawing Helix makes.
+ *
+ * The renderer is the driver's own, and `disconnect()` frees it.
+ */
+export declare const threeRibbonDriver: (container: HTMLElement, options?: ThreeRibbonDriverOptions) => SpatialRibbonChartDriver;

package/dist/three/ribbon-driver.js

@@ -0,0 +1,128 @@
+import { BufferGeometry, Color, DirectionalLight, DoubleSide, Float32BufferAttribute, HemisphereLight, LineBasicMaterial, LineSegments, Mesh, MeshLambertMaterial, Vector3, } from 'three';
+import { createStage, edgeOf, HALF, inBox, lookThrough } from './stage.js';
+const THICKNESS = 0.45;
+const ROOM = 0.12;
+export const threeRibbonDriver = (container, options = {}) => {
+    let field;
+    let readings = new Map();
+    const ribbonMaterial = new MeshLambertMaterial({
+        polygonOffset: true,
+        polygonOffsetFactor: 1,
+        polygonOffsetUnits: 1,
+        side: DoubleSide,
+        vertexColors: true,
+    });
+    const ribbons = new Mesh(new BufferGeometry(), ribbonMaterial);
+    const edgeMaterial = new LineBasicMaterial({ vertexColors: true });
+    const edges = new LineSegments(new BufferGeometry(), edgeMaterial);
+    const stage = createStage(container, {
+        density: options.density,
+        pick: (ray) => {
+            const hit = ray.intersectObject(ribbons)[0];
+            if (!hit) {
+                return -1;
+            }
+            let found = -1;
+            let nearest = Number.POSITIVE_INFINITY;
+            for (const [index, at] of readings) {
+                const away = at.distanceTo(hit.point);
+                if (away < nearest) {
+                    nearest = away;
+                    found = index;
+                }
+            }
+            return found;
+        },
+    });
+    const sky = new HemisphereLight(0xffffff, 0xffffff, 2.2);
+    const sun = new DirectionalLight(0xffffff, 1);
+    sun.position.set(-2, 4, 1);
+    stage.scene.add(ribbons, edges, sky, sun);
+    return {
+        draw: (next, colors, font) => {
+            field = next;
+            const [ex, ey, ez] = next.axes.extent ?? [1, 1, 1];
+            const count = Math.max(next.series.length, 1);
+            const half = ((THICKNESS * 2) / count / 2) * HALF * ez;
+            const zero = inBox(next.axes.y, Math.max(next.axes.y.range[0], 0)) * ey;
+            const page = new Color(colors.page);
+            const { emphasis, through } = colors.look;
+            const positions = [];
+            const tints = [];
+            const lines = [];
+            const lineTints = [];
+            readings = new Map();
+            next.series.forEach((_, series) => {
+                const tone = new Color(colors.groups[series % colors.groups.length] ?? colors.ink);
+                const color = emphasis === 'outlined' ? tone.clone().lerp(page, 0.4) : tone;
+                const edge = emphasis === 'solid' ? edgeOf(color) : tone;
+                const z = inBox(next.axes.z, series) * ez;
+                const points = [];
+                next.categories.forEach((__, across) => {
+                    const index = across * next.series.length + series;
+                    const value = next.cells[index]?.value;
+                    if (value !== undefined) {
+                        const at = new Vector3(inBox(next.axes.x, across) * ex, inBox(next.axes.y, value) * ey, z);
+                        points.push(at);
+                        readings.set(index, at.clone().setZ(z + half));
+                    }
+                });
+                const quad = (a, b, c, d) => {
+                    for (const one of [a, b, c, a, c, d]) {
+                        positions.push(one.x, one.y, one.z);
+                        tints.push(color.r, color.g, color.b);
+                    }
+                };
+                const line = (a, b) => {
+                    lines.push(a.x, a.y, a.z, b.x, b.y, b.z);
+                    lineTints.push(edge.r, edge.g, edge.b, edge.r, edge.g, edge.b);
+                };
+                const near = (point, y = point.y) => new Vector3(point.x, y, z + half);
+                const far = (point, y = point.y) => new Vector3(point.x, y, z - half);
+                for (let at = 0; at + 1 < points.length; at++) {
+                    const [a, b] = [points[at], points[at + 1]];
+                    quad(near(a), near(b), far(b), far(a));
+                    quad(near(a, zero), near(b, zero), near(b), near(a));
+                    quad(far(a, zero), far(b, zero), far(b), far(a));
+                    line(near(a), near(b));
+                    line(far(a), far(b));
+                }
+                const [first, last] = [points[0], points.at(-1)];
+                for (const end of [first, last]) {
+                    if (end) {
+                        quad(near(end, zero), near(end), far(end), far(end, zero));
+                    }
+                }
+            });
+            ribbons.geometry.dispose();
+            const geometry = new BufferGeometry();
+            geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));
+            geometry.setAttribute('color', new Float32BufferAttribute(tints, 3));
+            geometry.computeVertexNormals();
+            ribbons.geometry = geometry;
+            edges.geometry.dispose();
+            const lined = new BufferGeometry();
+            lined.setAttribute('position', new Float32BufferAttribute(lines, 3));
+            lined.setAttribute('color', new Float32BufferAttribute(lineTints, 3));
+            edges.geometry = lined;
+            lookThrough(ribbonMaterial, (emphasis === 'subtle' ? 0.2 : 1) * through);
+            lookThrough(edgeMaterial, through);
+            stage.setAxes(next.axes, colors, font);
+            stage.frame(new Vector3(-HALF * ex - ROOM, -HALF * ey - ROOM, -HALF * ez - ROOM), new Vector3(HALF * ex + ROOM, HALF * ey, HALF * ez + ROOM));
+        },
+        focus: (index) => {
+            stage.setMarker(field ? readings.get(index) : undefined);
+        },
+        onHover: (listener) => stage.onHover(listener),
+        onPlace: (listener) => stage.onPlace(listener),
+        onPress: (listener) => stage.onPress(listener),
+        stop: () => {
+            ribbons.geometry.dispose();
+            ribbonMaterial.dispose();
+            edges.geometry.dispose();
+            edgeMaterial.dispose();
+            stage.stop();
+        },
+        turnBy: (across, up, animate) => stage.turnBy(across, up, animate),
+    };
+};

package/dist/three/scatter-driver.js

@@ -1,15 +1,21 @@
-import { BufferGeometry, CanvasTexture, Color, Float32BufferAttribute, Points, PointsMaterial, Vector3, } from 'three';
-import { createStage, inBox } from './stage.js';
+import { BufferGeometry, CanvasTexture, Color, Float32BufferAttribute, LineBasicMaterial, LineSegments, Points, PointsMaterial, Vector3, } from 'three';
+import { createStage, HALF, inBox, lookThrough } from './stage.js';
 const REACH = 0.03;
-const dot = () => {
+const dot = () => ringed(1);
+const ringed = (inside) => {
     const canvas = document.createElement('canvas');
     canvas.width = canvas.height = 64;
     const context = canvas.getContext('2d');
     if (context) {
         context.beginPath();
         context.arc(32, 32, 28, 0, Math.PI * 2);
-        context.fillStyle = '#fff';
+        context.fillStyle = `rgba(255, 255, 255, ${inside})`;
         context.fill();
+        if (inside < 1) {
+            context.lineWidth = 7;
+            context.strokeStyle = '#fff';
+            context.stroke();
+        }
     }
     return new CanvasTexture(canvas);
 };
@@ -23,6 +29,7 @@ export const threeScatterDriver = (container, options = {}) => {
         return new Vector3(inBox(field.axes.x, point.x), inBox(field.axes.y, point.y), inBox(field.axes.z, point.z));
     };
     const pointTexture = dot();
+    const rings = new Map();
     const pointMaterial = new PointsMaterial({
         alphaTest: 0.5,
         map: pointTexture,
@@ -31,6 +38,12 @@ export const threeScatterDriver = (container, options = {}) => {
         vertexColors: true,
     });
     const points = new Points(new BufferGeometry(), pointMaterial);
+    const dropMaterial = new LineBasicMaterial({
+        opacity: 0.45,
+        transparent: true,
+        vertexColors: true,
+    });
+    const drops = new LineSegments(new BufferGeometry(), dropMaterial);
     const stage = createStage(container, {
         density: options.density,
         pick: (ray) => {
@@ -47,7 +60,7 @@ export const threeScatterDriver = (container, options = {}) => {
             return found;
         },
     });
-    stage.scene.add(points);
+    stage.scene.add(drops, points);
     return {
         draw: (next, colors, font) => {
             field = next;
@@ -65,6 +78,28 @@ export const threeScatterDriver = (container, options = {}) => {
             geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));
             geometry.setAttribute('color', new Float32BufferAttribute(tints, 3));
             points.geometry = geometry;
+            drops.geometry.dispose();
+            const lines = new BufferGeometry();
+            const feet = [];
+            for (let at = 0; at < positions.length; at += 3) {
+                feet.push(positions[at], positions[at + 1], positions[at + 2], positions[at], -HALF, positions[at + 2]);
+            }
+            lines.setAttribute('position', new Float32BufferAttribute(feet, 3));
+            lines.setAttribute('color', new Float32BufferAttribute(tints.flatMap((_, at) => at % 3 === 0 ? [...tints.slice(at, at + 3), ...tints.slice(at, at + 3)] : []), 3));
+            drops.geometry = lines;
+            drops.visible = colors.look.drops;
+            const { emphasis, through } = colors.look;
+            const inside = emphasis === 'outlined' ? 0.6 : emphasis === 'subtle' ? 0.2 : 1;
+            if (inside < 1 && !rings.has(inside)) {
+                rings.set(inside, ringed(inside));
+            }
+            pointMaterial.map = rings.get(inside) ?? pointTexture;
+            pointMaterial.alphaTest = inside < 1 ? 0.05 : 0.5;
+            lookThrough(pointMaterial, through);
+            if (inside < 1) {
+                pointMaterial.transparent = true;
+                pointMaterial.depthWrite = false;
+            }
             stage.setAxes(next.axes, colors, font);
         },
         focus: (index) => {
@@ -77,6 +112,11 @@ export const threeScatterDriver = (container, options = {}) => {
             points.geometry.dispose();
             pointMaterial.dispose();
             pointTexture.dispose();
+            drops.geometry.dispose();
+            dropMaterial.dispose();
+            for (const texture of rings.values()) {
+                texture.dispose();
+            }
             stage.stop();
         },
         turnBy: (across, up, animate) => stage.turnBy(across, up, animate),

package/dist/three/stage.d.ts

@@ -1,13 +1,26 @@
-import { Raycaster, Scene, Vector3 } from 'three';
+import { Color, type Material, Raycaster, Scene, Vector3 } from 'three';
 import type { Axis, PlotColors } from '../connect-plot/connect-plot.js';
 /** The box's half edge, in three.js's units: what is plotted stands between -1 and 1 on each axis. */
 export declare const HALF = 1;
+/**
+ * Lets `amount` of a mark's material through, as `material` and a `subtle`
+ * emphasis ask: opaque at 1, and see-through below it, where a mark writes
+ * no depth so the marks behind it still draw.
+ */
+export declare const lookThrough: (material: Material, amount: number) => void;
+/**
+ * An edge a little lighter than a dark face and a little darker than a light
+ * one, as the charts' own drawings draw them, so every block keeps its form
+ * on every step of a ramp.
+ */
+export declare const edgeOf: (face: Color) => Color;
 /** A number on an axis, written short enough for a tick. */
 export declare const tickText: (value: number) => string;
 /** Where a number stands in the box, from -1 at its axis' low end to 1 at its high end. */
 export declare const inBox: (axis: Axis, value: number) => number;
-/** The plot's three axes: across, up, and in depth. */
+/** The plot's three axes: across, up, and in depth, and how long the box is along each, where not a cube. */
 export interface Axes {
+    extent?: readonly [number, number, number] | undefined;
     x: Axis;
     y: Axis;
     z: Axis;

package/dist/three/stage.js

@@ -1,10 +1,22 @@
 import { boxLabels, pageBudget, } from '@fusion.dev/helix-core';
-import { BufferGeometry, CanvasTexture, Float32BufferAttribute, LineBasicMaterial, LineSegments, PerspectiveCamera, Raycaster, Scene, Spherical, Sprite, SpriteMaterial, Vector2, Vector3, WebGLRenderer, } from 'three';
+import { BufferGeometry, CanvasTexture, Color, Float32BufferAttribute, LineBasicMaterial, LineSegments, PerspectiveCamera, Raycaster, Scene, Spherical, Sprite, SpriteMaterial, Vector2, Vector3, WebGLRenderer, } from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 const STEP = Math.PI / 12;
 const DURATION = 250;
 const DRAG = 4;
 export const HALF = 1;
+export const lookThrough = (material, amount) => {
+    const clear = amount < 1;
+    material.opacity = amount;
+    material.transparent = clear;
+    material.depthWrite = !clear;
+    material.needsUpdate = true;
+};
+export const edgeOf = (face) => {
+    const hsl = { h: 0, l: 0, s: 0 };
+    face.getHSL(hsl);
+    return face.clone().lerp(new Color(hsl.l < 0.5 ? 0xffffff : 0x000000), hsl.l < 0.5 ? 0.22 : 0.18);
+};
 const ease = (at) => (at < 0.5 ? 2 * at * at : 1 - (-2 * at + 2) ** 2 / 2);
 export const tickText = (value) => String(Number(value.toPrecision(6)));
 export const inBox = (axis, value) => {
@@ -26,8 +38,9 @@ const ring = () => {
 };
 const gridLines = (axes) => {
     const lines = [];
+    const [ex, ey, ez] = axes.extent ?? [1, 1, 1];
     const line = (from, to) => {
-        lines.push(...from, ...to);
+        lines.push(from[0] * ex, from[1] * ey, from[2] * ez, to[0] * ex, to[1] * ey, to[2] * ez);
     };
     const h = HALF;
     for (const a of [-h, h]) {
@@ -37,11 +50,11 @@ const gridLines = (axes) => {
             line([a, b, -h], [a, b, h]);
         }
     }
-    for (const x of axes.x.ticks.map((tick) => inBox(axes.x, tick))) {
+    for (const x of (axes.x.rules ?? axes.x.ticks).map((tick) => inBox(axes.x, tick))) {
         line([x, -h, -h], [x, -h, h]);
         line([x, -h, -h], [x, h, -h]);
     }
-    for (const z of axes.z.ticks.map((tick) => inBox(axes.z, tick))) {
+    for (const z of (axes.z.rules ?? axes.z.ticks).map((tick) => inBox(axes.z, tick))) {
         line([-h, -h, z], [h, -h, z]);
         line([-h, -h, z], [-h, h, z]);
     }
@@ -134,7 +147,7 @@ export const createStage = (container, options) => {
         }
     };
     const drawLabels = () => {
-        if (!axes || !colors) {
+        if (!axes || !colors?.look.box) {
             labels.replaceChildren();
             return;
         }
@@ -153,14 +166,18 @@ export const createStage = (container, options) => {
         };
         const place = new Vector3();
         const seen = ([x, y, z]) => {
-            place.set(x * HALF, y * HALF, z * HALF);
+            const [ex, ey, ez] = axes?.extent ?? [1, 1, 1];
+            place.set(x * HALF * ex, y * HALF * ey, z * HALF * ez);
             const depth = -place.distanceTo(camera.position);
             const on = place.project(camera);
             return { depth, x: ((on.x + 1) / 2) * width, y: ((1 - on.y) / 2) * height };
         };
         const text = (axis) => ({
             name: axis.name,
-            ticks: axis.ticks.map((tick) => ({ at: inBox(axis, tick) / HALF, text: tickText(tick) })),
+            ticks: axis.ticks.map((tick, index) => ({
+                at: inBox(axis, tick) / HALF,
+                text: axis.labels?.[index] ?? tickText(tick),
+            })),
         });
         for (const one of boxLabels(seen, { x: text(axes.x), y: text(axes.y), z: text(axes.z) }, { gap: 6, name: 13, tick: 11, wide: 0.58 })) {
             label(one.x, one.y, one.text, one.name);
@@ -199,6 +216,21 @@ export const createStage = (container, options) => {
             dirty = true;
             if (through >= 1) {
                 turn = undefined;
+                turned();
+            }
+        }
+        if (settle) {
+            const through = Math.min((now - settle.start) / DURATION, 1);
+            const eased = ease(through);
+            const toward = camera.position.clone().sub(controls.target).normalize();
+            const [near, far] = settle.distance;
+            controls.target.lerpVectors(settle.from, settle.to, eased);
+            camera.position.copy(controls.target).add(toward.multiplyScalar(near + (far - near) * eased));
+            camera.lookAt(controls.target);
+            dirty = true;
+            if (through >= 1) {
+                settle = undefined;
+                controls.update();
             }
         }
         if (!dirty) {
@@ -209,7 +241,7 @@ export const createStage = (container, options) => {
         drawLabels();
         tellPlace();
         tellTracked();
-        if (turn && !pending) {
+        if ((turn || settle) && !pending) {
             pending = requestAnimationFrame(tick);
         }
     };
@@ -224,12 +256,8 @@ export const createStage = (container, options) => {
         : undefined;
     seen?.observe(container);
     let framed;
-    const fit = () => {
-        if (!framed) {
-            return;
-        }
-        const { high, low } = framed;
-        const toward = camera.position.clone().sub(controls.target).normalize();
+    const fitFrom = (toward, box) => {
+        const { high, low } = box;
         const right = new Vector3(0, 1, 0).cross(toward).normalize();
         const up = toward.clone().cross(right).normalize();
         const tanUp = Math.tan((camera.fov * Math.PI) / 360);
@@ -270,14 +298,61 @@ export const createStage = (container, options) => {
                 .add(up.clone().multiplyScalar(((bottom + top) / 2) * tanUp * distance));
             distance = distanceFrom(center);
         }
-        distance *= 1.06;
-        controls.target.copy(center);
-        camera.position.copy(center).add(toward.multiplyScalar(distance));
+        return { center, distance: distance * 1.06 };
+    };
+    const reach = (distance) => {
         controls.minDistance = distance * 0.35;
         controls.maxDistance = distance * 3;
+    };
+    const fit = () => {
+        if (!framed) {
+            return;
+        }
+        const toward = camera.position.clone().sub(controls.target).normalize();
+        const { center, distance } = fitFrom(toward, framed);
+        settle = undefined;
+        controls.target.copy(center);
+        camera.position.copy(center).add(toward.multiplyScalar(distance));
+        reach(distance);
         camera.lookAt(controls.target);
         controls.update();
     };
+    let settle;
+    let began = 0;
+    const turning = () => {
+        settle = undefined;
+        if (framed) {
+            const toward = camera.position.clone().sub(controls.target).normalize();
+            began = fitFrom(toward, framed).distance;
+        }
+    };
+    const turned = () => {
+        if (!framed || began <= 0) {
+            return;
+        }
+        const toward = camera.position.clone().sub(controls.target).normalize();
+        const { center, distance } = fitFrom(toward, framed);
+        reach(distance);
+        const zoomed = camera.position.distanceTo(controls.target) / began;
+        const to = { center, distance: distance * zoomed };
+        if (still()) {
+            controls.target.copy(to.center);
+            camera.position.copy(to.center).add(toward.multiplyScalar(to.distance));
+            camera.lookAt(controls.target);
+            controls.update();
+            invalidate();
+            return;
+        }
+        settle = {
+            distance: [camera.position.distanceTo(controls.target), to.distance],
+            from: controls.target.clone(),
+            start: performance.now(),
+            to: to.center,
+        };
+        invalidate();
+    };
+    controls.addEventListener('start', turning);
+    controls.addEventListener('end', turned);
     const resize = () => {
         const width = Math.max(container.clientWidth, 1);
         const height = Math.max(container.clientHeight, 1);
@@ -388,6 +463,7 @@ export const createStage = (container, options) => {
             const lines = new BufferGeometry();
             lines.setAttribute('position', new Float32BufferAttribute(gridLines(next), 3));
             grid.geometry = lines;
+            grid.visible = nextColors.look.box;
             gridMaterial.color.setStyle(nextColors.quiet);
             marker.material.color.setStyle(nextColors.ink);
             invalidate();
@@ -412,6 +488,8 @@ export const createStage = (container, options) => {
             canvas.removeEventListener('pointerup', onUp);
             canvas.removeEventListener('pointermove', onMove);
             canvas.removeEventListener('pointerleave', onLeave);
+            controls.removeEventListener('start', turning);
+            controls.removeEventListener('end', turned);
             controls.dispose();
             grid.geometry.dispose();
             gridMaterial.dispose();
@@ -429,6 +507,7 @@ export const createStage = (container, options) => {
             };
         },
         turnBy: (across, up, animate) => {
+            turning();
             const from = new Spherical().setFromVector3(camera.position.clone().sub(controls.target));
             const to = from.clone();
             to.theta += across * STEP;
@@ -436,6 +515,7 @@ export const createStage = (container, options) => {
             if (!animate || still()) {
                 camera.position.setFromSpherical(to).add(controls.target);
                 camera.lookAt(controls.target);
+                turned();
                 invalidate();
                 return;
             }

package/dist/three/surface-driver.js

@@ -1,5 +1,5 @@
 import { BufferGeometry, Color, DirectionalLight, DoubleSide, Float32BufferAttribute, HemisphereLight, LineBasicMaterial, LineSegments, Mesh, MeshLambertMaterial, Vector3, } from 'three';
-import { createStage, HALF, inBox } from './stage.js';
+import { createStage, edgeOf, HALF, inBox, lookThrough } from './stage.js';
 const REACH = 0.03;
 export const threeSurfaceDriver = (container, options = {}) => {
     let field;
@@ -18,8 +18,14 @@ export const threeSurfaceDriver = (container, options = {}) => {
         vertexColors: true,
     });
     const surface = new Mesh(new BufferGeometry(), surfaceMaterial);
-    const ruleMaterial = new LineBasicMaterial({ opacity: 0.3, transparent: true });
+    const ruleMaterial = new LineBasicMaterial({
+        opacity: 0.3,
+        transparent: true,
+        vertexColors: true,
+    });
     const rules = new LineSegments(new BufferGeometry(), ruleMaterial);
+    const contourMaterial = new LineBasicMaterial({ vertexColors: true });
+    const contours = new LineSegments(new BufferGeometry(), contourMaterial);
     const stage = createStage(container, {
         density: options.density,
         pick: (ray) => {
@@ -68,7 +74,7 @@ export const threeSurfaceDriver = (container, options = {}) => {
     const sky = new HemisphereLight(0xffffff, 0xffffff, 2.2);
     const sun = new DirectionalLight(0xffffff, 1);
     sun.position.set(-2, 4, 1);
-    stage.scene.add(surface, rules, sky, sun);
+    stage.scene.add(contours, surface, rules, sky, sun);
     return {
         draw: (next, colors, font) => {
             field = next;
@@ -77,7 +83,11 @@ export const threeSurfaceDriver = (container, options = {}) => {
             const tints = [];
             const low = new Color(colors.ramp.low);
             const high = new Color(colors.ramp.high);
+            const page = new Color(colors.page);
+            const ink = new Color(colors.ink);
+            const { emphasis, through } = colors.look;
             const tint = new Color();
+            const ramp = [];
             const values = next.cells.flatMap((cell) => (cell.value === undefined ? [] : [cell.value]));
             const [least, most] = [Math.min(...values), Math.max(...values)];
             next.cells.forEach((cell, index) => {
@@ -85,14 +95,23 @@ export const threeSurfaceDriver = (container, options = {}) => {
                 positions.push(at.x, at.y, at.z);
                 const level = cell.value === undefined || most === least ? 0.5 : (cell.value - least) / (most - least);
                 tint.lerpColors(low, high, level);
+                ramp.push(tint.r, tint.g, tint.b);
+                if (emphasis === 'outlined') {
+                    tint.lerp(page, 0.4);
+                }
                 tints.push(tint.r, tint.g, tint.b);
             });
             const has = (index) => next.cells[index]?.value !== undefined;
             const faces = [];
             const lines = [];
+            const lineTints = [];
+            const wire = emphasis !== 'solid';
             const line = (from, to) => {
                 if (has(from) && has(to)) {
                     lines.push(...positions.slice(from * 3, from * 3 + 3), ...positions.slice(to * 3, to * 3 + 3));
+                    for (const at of [from, to]) {
+                        lineTints.push(...(wire ? ramp.slice(at * 3, at * 3 + 3) : [ink.r, ink.g, ink.b]));
+                    }
                 }
             };
             for (let across = 0; across < next.acrosses.length; across++) {
@@ -127,8 +146,49 @@ export const threeSurfaceDriver = (container, options = {}) => {
             rules.geometry.dispose();
             const ruled = new BufferGeometry();
             ruled.setAttribute('position', new Float32BufferAttribute(lines, 3));
+            ruled.setAttribute('color', new Float32BufferAttribute(lineTints, 3));
             rules.geometry = ruled;
-            ruleMaterial.color.setStyle(colors.ink);
+            const floor = [];
+            const floorTints = [];
+            const [bottom, top] = [next.lowest ?? least, next.highest ?? most];
+            for (const contour of next.contours ?? []) {
+                tint.lerpColors(low, high, top === bottom ? 0.5 : (contour.level - bottom) / (top - bottom));
+                tint.copy(edgeOf(tint));
+                for (let at = 0; at + 2 < faces.length; at += 3) {
+                    const corners = faces.slice(at, at + 3);
+                    const crossings = [];
+                    for (const [from, to] of [
+                        [corners[0], corners[1]],
+                        [corners[1], corners[2]],
+                        [corners[2], corners[0]],
+                    ]) {
+                        const [one, other] = [next.cells[from ?? 0]?.value, next.cells[to ?? 0]?.value];
+                        if (one === undefined ||
+                            other === undefined ||
+                            one >= contour.level === other >= contour.level) {
+                            continue;
+                        }
+                        const along = (contour.level - one) / (other - one);
+                        for (let axis = 0; axis < 3; axis++) {
+                            const start = positions[(from ?? 0) * 3 + axis] ?? 0;
+                            crossings.push(start + ((positions[(to ?? 0) * 3 + axis] ?? 0) - start) * along);
+                        }
+                    }
+                    if (crossings.length === 6) {
+                        floor.push(...crossings);
+                        floorTints.push(tint.r, tint.g, tint.b, tint.r, tint.g, tint.b);
+                    }
+                }
+            }
+            contours.geometry.dispose();
+            const lined = new BufferGeometry();
+            lined.setAttribute('position', new Float32BufferAttribute(floor, 3));
+            lined.setAttribute('color', new Float32BufferAttribute(floorTints, 3));
+            contours.geometry = lined;
+            contours.visible = colors.look.contours;
+            lookThrough(surfaceMaterial, (emphasis === 'subtle' ? 0.2 : 1) * through);
+            lookThrough(ruleMaterial, (wire ? 1 : 0.3) * through);
+            ruleMaterial.transparent = true;
             stage.setAxes(next.axes, colors, font);
         },
         focus: (index) => {
@@ -142,6 +202,8 @@ export const threeSurfaceDriver = (container, options = {}) => {
             surfaceMaterial.dispose();
             rules.geometry.dispose();
             ruleMaterial.dispose();
+            contours.geometry.dispose();
+            contourMaterial.dispose();
             stage.stop();
         },
         turnBy: (across, up, animate) => stage.turnBy(across, up, animate),

package/dist/three/treemap-driver.d.ts

@@ -0,0 +1,36 @@
+import type { SpatialTreemapDriver } from '../connect-spatial-treemap/connect-spatial-treemap.js';
+/** How the three.js treemap driver behaves where the page does not say. */
+export interface ThreeTreemapDriverOptions {
+    /**
+     * How many pixels the drawing has for each of the page's. By default, on a
+     * screen worked with a mouse, half as many again as the screen has, at
+     * least two and at most three; on a touch screen, as many as the screen
+     * has, at most two.
+     */
+    density?: number | undefined;
+}
+/**
+ * Draws a Spatial Treemap's blocks in three dimensions with three.js. Pass it
+ * to `connectSpatialTreemap` with the element to draw in, which the chart
+ * holds in its plot:
+ *
+ * ```js
+ * import { connectSpatialTreemap } from '@fusion.dev/helix-plot'
+ * import { threeTreemapDriver } from '@fusion.dev/helix-plot/three'
+ *
+ * connectSpatialTreemap(chart, threeTreemapDriver(chart.querySelector('div')))
+ * ```
+ *
+ * **Each block stands on its part of the floor, from zero to its height**,
+ * or as one slab where the table gives no heights, in a box with the
+ * height's grid on two of its walls, lit from above. Each group takes a
+ * series color from the theme.
+ *
+ * **Dragging turns the box, and the wheel and a pinch bring it nearer.**
+ * Shift with an arrow on the chart turns it a step. It never turns by itself.
+ * It draws only while something moves, asks for no frames at rest, and
+ * shares the page's WebGL contexts with every three.js drawing Helix makes.
+ *
+ * The renderer is the driver's own, and `disconnect()` frees it.
+ */
+export declare const threeTreemapDriver: (container: HTMLElement, options?: ThreeTreemapDriverOptions) => SpatialTreemapDriver;