3D engine that AI agents drive
Curves: grow field animates trim as a morph track (#701)
Nguyen Xuan Anac383085f115
diff --git a/changes/701.md b/changes/701.mdnew file mode 100644index 00000000..9df8d165--- /dev/null+++ b/changes/701.md@@ -0,0 +1 @@+- A recipe curve takes `grow`, morph targets of the curve grown step by step, so a motion morph track grows a vine and seeking equals playing (#701)diff --git a/docs/agent-scene.md b/docs/agent-scene.mdindex aef6b1b9..06868c74 100644--- a/docs/agent-scene.md+++ b/docs/agent-scene.md@@ -90,7 +90,7 @@ The generators also enforce their existing numeric and modeling constraints.| `lathe` | `profile`, `segments`, `startAngle`, `sweep` | Required XY profile, `64`, `0`, `2π` || `extrude` | `contour`, `holes`, `depth`, `steps`, `bevel`, `bevelThickness`, `bevelSegments` | Required XY contour, `[]`, `1`, `1`, `0`, bevel, `3` || `tube` | `path`, `radius`, `segments`, `radialSegments`, `closed` | Required XYZ path, `0.1`, `64`, `12`, `false` |-| `curve` | `points` or `shape` or `splines`, `closed`, `kind`, `weights`, `trim`, `radius`, `taper`, `profile`, `resolution`, `radialSegments` | One of points, shape or splines, `false`, `bezier`, 1, none, `0.05`, none, round, `12`, `8` |+| `curve` | `points` or `shape` or `splines`, `closed`, `kind`, `weights`, `trim`, `grow`, `radius`, `taper`, `profile`, `resolution`, `radialSegments` | One of points, shape or splines, `false`, `bezier`, 1, none, none, `0.05`, none, round, `12`, `8` || `text` | `text`, `size`, `depth`, `font`, `align`, `curveSegments` | Required string, `1`, `0.2`, `default`, `left`, `4` || `terrain` | `size`, `resolution`, `seed`, `amplitude`, `holes` | `40` m, `64` cells, `1`, `1` m, none |diff --git a/docs/modeling.md b/docs/modeling.mdindex 28003451..a6277e8e 100644--- a/docs/modeling.md+++ b/docs/modeling.md@@ -86,7 +86,12 @@ in `splines`, never both. A spline is `{ points | shape, closed, kind, weights,as lengths when `length` is true (lengths past the end are clamped to it). `end` must be greater than `start`. A trimmedcurve is open and gets caps, also when it was closed. Trimming a range that covers an open curve changes nothing. Trim iscomputed from the same samples every time, so raising `end` frame by frame grows the curve along the same path: that is how a- vine grows. Building a mesh per frame is the caller's job.+ vine grows in code.+- `grow: { name, steps = 8, value = 1 }` on a recipe curve makes that growth a motion track. The geometry is the bare root and+ each of `steps` (2 to 16) morph targets holds the curve grown that far, resampled to the same rings, so a morph track+ `{ kind: "morph", id: <name>, property: "weight", keyframes }` with values 0 to 1 grows the vine, and seeking equals playing.+ The growth runs over the spline's own trim range (a trim in factors). `value` is the growth with no track. More steps follow+ a curved path more closely; between steps the tube blends the two neighbours.Not covered: trim ranges that wrap around the start of a closed curve, NURBS of other orders or with custom knots, a splinefill, and mesh edges to curve.diff --git a/docs/parity.md b/docs/parity.mdindex 81a3a177..28b24826 100644--- a/docs/parity.md+++ b/docs/parity.md@@ -52,7 +52,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.| Modeling > Meshes > UVs | partial | `uv_unwrap` with LSCM, axis charts and shelf packing. Patterns can not use the result yet. | | #50 || Modeling > Meshes > Mesh Analysis | partial | `lintMesh` reports topology problems. With `{ geometry: true }` (always on in `mesh_inspect`) it also warns of crossing parts, a solid cutting itself, thin walls, floating parts and near-symmetry, using the BVH within face budgets. Checks are heuristics on parts, not Blender's exact Select Non-Manifold or Intersect checks. | [tests/mesh-lint-geometry.test.js](../tests/mesh-lint-geometry.test.js), [src/mesh-lint-geometry.js](../src/mesh-lint-geometry.js) | #66 || Modeling > Meshes > Remeshing | partial | `remesh` rebuilds a closed mesh as an even quad surface on a voxel grid (surface nets over a BVH signed distance). Quad remesh and Instant Meshes style retopology are not here. | [blender golden](../tests/blender-golden.test.js) | #40 |-| Modeling > Curves | partial | The `curve` geometry sweeps a cubic Bezier chain with explicit or automatic handles, a round or custom profile, a taper along the length and flat caps. Volume, area and bounds match Blender for an open and a closed curve to 2e-5. Splines can be poly or uniform cubic NURBS (with weights), several splines share one mesh, and arc, spiral and star primitives and a trim by factor or length (open result, caps) build a curve from parameters. There is no NURBS order or knot control, no mesh to curve, no handle types, no fill for flat curves, no offset or extrude, and no separate taper or bevel object. | [curve-text](../tests/curve-text.test.js), [curve-splines](../tests/curve-splines.test.js), [Blender comparison](../tests/blender-curve-text.test.js) | #45, #701 |+| Modeling > Curves | partial | The `curve` geometry sweeps a cubic Bezier chain with explicit or automatic handles, a round or custom profile, a taper along the length and flat caps. Volume, area and bounds match Blender for an open and a closed curve to 2e-5. Splines can be poly or uniform cubic NURBS (with weights), several splines share one mesh, and arc, spiral and star primitives and a trim by factor or length (open result, caps) build a curve from parameters. A `grow` field turns the trim into a morph track, so a vine grows over a motion. There is no NURBS order or knot control, no mesh to curve, no handle types, no fill for flat curves, no offset or extrude, and no separate taper or bevel object. | [curve-text](../tests/curve-text.test.js), [curve-splines](../tests/curve-splines.test.js), [Blender comparison](../tests/blender-curve-text.test.js) | #45, #701 || Modeling > Curves (New) | missing | No hair curves. | | #63 || Modeling > Surfaces | out of scope | Issue #45 records NURBS surfaces as out of scope unless demand appears. | | || Modeling > Metaball | partial | The `sdf` geometry blends spheres and other primitives with a smooth union, which gives the metaball look as a mesh meshed by surface nets. There is no metaball object, no per-element stiffness and no threshold setting. | [modeling-sdf](../tests/modeling-sdf.test.js) | #700 |diff --git a/src/agent-motion.js b/src/agent-motion.jsindex 1b432b7f..4b4cfc25 100644--- a/src/agent-motion.js+++ b/src/agent-motion.js@@ -491,7 +491,7 @@ export function normalizeAgentMotion(input, recipe) {const nodes = new Set((recipe.nodes ?? []).map(node => node.id));const materials = new Set((recipe.materials ?? []).map(material => material.id));// An imported asset lists its morph targets; a recipe mesh offers the names of its shape keys.- const morphTargets = new Set(recipe.morphTargets ?? (recipe.geometries ?? []).flatMap(geometry => (geometry.shapeKeys ?? []).map(key => key.name)));+ const morphTargets = new Set(recipe.morphTargets ?? (recipe.geometries ?? []).flatMap(geometry => geometry.grow ? [geometry.grow.name] : (geometry.shapeKeys ?? []).map(key => key.name)));const identities = new Set();let keyframeCount = 0;const tracks = inputTracks.map((track, index) => {diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 4e0225bc..a80a6083 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -65,7 +65,7 @@ export const CURVE_TEXT_LIMITS = Object.freeze({});export const CURVE_TEXT_DETAILS = Object.freeze({curve: 'bends along path, 2-64 points [x,y,z] (Catmull-Rom); the coordinate along axis (x) is the distance from the path start, so model from 0.',- splines: 'Geometry curve takes points (kind bezier|poly|nurbs, weights for nurbs, closed), or shape {type arc|spiral|star} (arc: radius, startAngle, sweep radians, segments; spiral: rotations, startRadius, endRadius, height, pointsPerRotation, reverse; star: points, innerRadius, outerRadius, innerTwist), or splines: up to 64 of those in one mesh. trim {start, end, length}: factors 0-1 of the arc length, or lengths when length is true; a trimmed curve is open. See docs/modeling.md.',+ splines: 'Geometry curve takes points (kind bezier|poly|nurbs, weights for nurbs, closed), or shape {type arc|spiral|star} (arc: radius, startAngle, sweep radians, segments; spiral: rotations, startRadius, endRadius, height, pointsPerRotation, reverse; star: points, innerRadius, outerRadius, innerTwist), or splines: up to 64 of those in one mesh. trim {start, end, length}: factors 0-1 of the arc length, or lengths when length is true; a trimmed curve is open. grow {name, steps 2-16, value}: morph targets of the curve grown step by step; animate with a motion track { kind: "morph", id: <name>, property: "weight", keyframes 0-1 } so a vine grows. See docs/modeling.md.',sdf: 'Geometry sdf: root is a tree meshed by surface nets, resolution 4-128 cells along the longest side (default 32). Primitive {shape sphere|box|roundBox|capsule|cylinder|torus, radius, size, height, tubeRadius, position, rotation (Euler radians), scale (uniform)}. Operation {op union|subtract|intersect, smooth (blend radius), children: 2-16} (subtract removes the rest from the first) or {op offset, distance, child}. At most 64 nodes, 8 levels. See docs/modeling.md.',text: 'Extruded text, baseline y=0 along +X, facing +Z. text (\n for lines), size (1), depth (0.2), align left|center|right, curveSegments, font. See docs/modeling.md.',});diff --git a/src/agent-scene.js b/src/agent-scene.jsindex e3be67fe..da4202ae 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -459,7 +459,7 @@ const GEOMETRY_FIELDS = {extrude: ['contour', 'holes', 'depth', 'steps', 'bevel', 'bevelThickness', 'bevelSegments'],tube: ['path', 'radius', 'segments', 'radialSegments', 'closed'],sdf: ['root', 'resolution'],- curve: ['points', 'shape', 'splines', 'closed', 'kind', 'weights', 'trim', 'radius', 'taper', 'profile', 'resolution', 'radialSegments'],+ curve: ['points', 'shape', 'splines', 'closed', 'kind', 'weights', 'trim', 'grow', 'radius', 'taper', 'profile', 'resolution', 'radialSegments'],text: ['text', 'size', 'depth', 'font', 'align', 'curveSegments'],mesh: ['base', 'edits', 'stack', 'smoothAngle', 'shapeKeys'],terrain: ['size', 'resolution', 'seed', 'amplitude', 'holes'],@@ -493,7 +493,7 @@ function geometryEstimate(value, scope = PENDING_CUTTER_SCOPE) {return input.length;}for (const field of GEOMETRY_FIELDS[value.type]) {- if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align', 'from', 'to', 'shape', 'splines', 'kind', 'weights', 'trim', 'root'].includes(field)) {+ if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align', 'from', 'to', 'shape', 'splines', 'kind', 'weights', 'trim', 'grow', 'root'].includes(field)) {finite(value[field], field);}}@@ -529,7 +529,7 @@ function geometryEstimate(value, scope = PENDING_CUTTER_SCOPE) {}return (detail('segments', 64, 3, 2048) + 1) * (detail('radialSegments', 12, 3, 128) + 1);case 'curve': {- if (['shape', 'splines', 'kind', 'weights', 'trim'].some(field => value[field] !== undefined)) {+ if (['shape', 'splines', 'kind', 'weights', 'trim', 'grow'].some(field => value[field] !== undefined)) {return agentSceneModule('modeling').curveGeometryVertexCount(value);}const knots = value.points;@@ -1190,8 +1190,15 @@ function partsWithCloth(restParts, clothGeometries, previousParts) {// A shape key weighs what its morph track samples at this time, or its starting value when no track names it.function publishShapeKeyWeights(part, sampledMorphs) {- const { morphTargetNames, morphTargetValues } = part.geometry;+ const { morphTargetNames, morphTargetValues, morphGrowth } = part.geometry;if (!morphTargetNames || !part.morph) return;+ if (morphGrowth) {+ const growth = sampledMorphs?.get(morphGrowth.name)?.weight ?? morphGrowth.value;+ agentSceneModule('modeling').growthWeights(morphGrowth.steps, growth).forEach((weight, index) => {+ part.morph.weights[index] = weight;+ });+ return;+ }morphTargetNames.forEach((name, index) => {part.morph.weights[index] = sampledMorphs?.get(name)?.weight ?? morphTargetValues[index];});diff --git a/src/modeling-splines.js b/src/modeling-splines.jsindex dbf0a5da..9523e026 100644--- a/src/modeling-splines.js+++ b/src/modeling-splines.js@@ -260,3 +260,25 @@ export function trimSamples(samples, closed, { start = 0, end = 1, length: byLenplace(to);return { points, tangents };}++/** Spreads `count` samples evenly by arc length along an open curve, so curves of any length share one topology. */+export function resampleSamples(samples, count) {+ const { points, tangents } = samples;+ const distances = [0];+ for (let index = 1; index < points.length; index++) {+ const segment = subtract(points[index], points[index - 1]);+ distances.push(distances[index - 1] + Math.hypot(segment[0], segment[1], segment[2]));+ }+ const total = distances.at(-1);+ const resampled = { points: [], tangents: [] };+ let upper = 1;+ for (let index = 0; index < count; index++) {+ const distance = total * index / (count - 1);+ while (upper < points.length - 1 && distances[upper] < distance) upper++;+ const span = distances[upper] - distances[upper - 1];+ const weight = span > 0 ? Math.min(Math.max((distance - distances[upper - 1]) / span, 0), 1) : 0;+ resampled.points.push(lerp(points[upper - 1], points[upper], weight));+ resampled.tangents.push(unitOrNull(lerp(tangents[upper - 1], tangents[upper], weight)) ?? tangents[upper]);+ }+ return resampled;+}diff --git a/src/modeling.js b/src/modeling.jsindex 7f0c1629..6990dd41 100644--- a/src/modeling.js+++ b/src/modeling.js@@ -1,6 +1,6 @@import { buildLathe, buildExtrusion, buildTube } from './modeling-shapes.js';import { sweepSamples } from './modeling-bezier.js';-import { sampleCountOf, sampleSpline, shapeToSpline, trimSamples } from './modeling-splines.js';+import { resampleSamples, sampleCountOf, sampleSpline, shapeToSpline, trimSamples } from './modeling-splines.js';import { planSdf, sdfGeometry as buildSdf } from './modeling-sdf.js';const MAX_INPUT_POINTS = 4096;@@ -418,15 +418,81 @@ function splinesOfGeometry(value) {return { splines: value.splines, label: 'splines[0]' };}-/** The curve scene geometry: points, a shape or splines, with the shared sweep options. */+/** The curve scene geometry: points, a shape or splines, with the shared sweep options and an optional growth. */export function curveGeometry(value, maxVertices) {const { splines, label } = splinesOfGeometry(value);+ if (value.grow !== undefined) return growingCurve(splines, { ...value, maxVertices }, label);return curveSet(splines, { ...value, maxVertices }, label);}+const GROW_FIELDS = ['name', 'steps', 'value'];+const MAX_GROW_STEPS = 16;+const MAX_GROW_MORPH_VERTICES = 2000000;+// The smallest fraction a growing curve starts from, so its first state still has a length to sweep.+const MINIMUM_GROWTH = 0.01;++/** Validates the grow field of a curve geometry: { name, steps, value } with the defaults filled in. */+export function growFrom(input) {+ if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('grow must be an object such as { "name": "vine", "steps": 8 }.');+ for (const key of Object.keys(input)) {+ if (!GROW_FIELDS.includes(key)) throw new TypeError(`Unknown grow field: ${key}. Use ${GROW_FIELDS.join(', ')}.`);+ }+ if (typeof input.name !== 'string' || !input.name.trim() || input.name.length > 64) throw new TypeError('grow.name must be 1 to 64 characters, such as "vine". A motion track { kind: "morph", id: <name>, property: "weight" } animates it.');+ const steps = input.steps ?? 8;+ integer(steps, 2, MAX_GROW_STEPS, 'grow.steps');+ const value = finite(input.value ?? 1, 'grow.value');+ if (value < 0 || value > 1) throw new RangeError('grow.value must be from 0 to 1 (0 is a bare root, 1 the whole curve).');+ return { name: input.name, steps, value };+}++// One sweep of every spline grown to `fraction` of its trim range, resampled to the full-curve ring count so all+// states share one topology.+function growthState(plan, fraction) {+ const { resolved, radius, profilePoints, taperFactors, radialSegments, resolution } = plan;+ const parts = resolved.map(spline => {+ if (spline.trim?.length) throw new TypeError('grow works with a trim in factors (length false), not lengths. Remove trim.length.');+ const start = spline.trim?.start ?? 0;+ const end = start + ((spline.trim?.end ?? 1) - start) * fraction;+ const ringCount = Math.max(2, sampleCountOf(spline, resolution) + (spline.closed ? 1 : 0));+ const samples = resampleSamples(trimSamples(sampleSpline(spline, resolution), spline.closed, { start, end }), ringCount);+ return sweepSamples({ ...samples, closed: false, radius, taper: taperFactors, profile: profilePoints, radialSegments });+ });+ return joinSweeps(parts);+}++// A curve that grows: the bare root is the geometry and each step is a morph target holding the curve at that+// length. The motion weight 0 to 1 of grow.name blends two neighbouring steps, so seeking equals playing.+function growingCurve(splines, options, label) {+ const grow = growFrom(options.grow);+ const plan = planCurveSet(splines, options, label);+ if (plan.vertexCount * grow.steps > MAX_GROW_MORPH_VERTICES) {+ throw new RangeError(`grow needs ${plan.vertexCount * grow.steps} morph vertices; at most ${MAX_GROW_MORPH_VERTICES}. Lower grow.steps, resolution or radialSegments.`);+ }+ const maximum = options.maxVertices ?? DEFAULT_VERTEX_LIMIT;+ const base = meshFrom(growthState(plan, MINIMUM_GROWTH), maximum);+ base.morphTargets = Array.from({ length: grow.steps }, (_, index) => {+ const state = meshFrom(growthState(plan, Math.max((index + 1) / grow.steps, MINIMUM_GROWTH)), maximum);+ return {+ positions: state.positions.map((position, offset) => position - base.positions[offset]),+ normals: state.normals.map((normal, offset) => normal - base.normals[offset]),+ };+ });+ base.morphTargetNames = base.morphTargets.map((_, index) => `${grow.name}#${index + 1}`);+ base.morphTargetValues = Float32Array.from(growthWeights(grow.steps, grow.value));+ base.morphGrowth = Object.freeze(grow);+ return base;+}++/** Weights of the growth steps at a growth from 0 to 1: the two steps around it share the weight, the others are 0. */+export function growthWeights(steps, growth) {+ const position = Math.min(Math.max(growth, 0), 1) * steps;+ return Array.from({ length: steps }, (_, index) => Math.max(0, 1 - Math.abs(position - (index + 1))));+}+/** The vertex count of a curve scene geometry, validated like curveGeometry. */export function curveGeometryVertexCount(value) {const { splines, label } = splinesOfGeometry(value);+ if (value.grow !== undefined) growFrom(value.grow);return planCurveSet(splines, value, label).vertexCount;}diff --git a/tests/curve-splines.test.js b/tests/curve-splines.test.jsindex e5533c62..6980178f 100644--- a/tests/curve-splines.test.js+++ b/tests/curve-splines.test.js@@ -190,3 +190,73 @@ test('a recipe curve geometry takes a shape, splines, kind and trim, and rejectsassert.throws(() => createAgentScene(recipe({ shape: { type: 'star', points: 1 } })), /shape\.points/);assert.throws(() => createAgentScene(recipe({ shape: { type: 'star' }, trim: { end: 3 } })), /trim/);});++function vineRecipe(grow = { name: 'vine', steps: 8 }, keyframes = [{ time: 0, value: 0 }, { time: 1, value: 1 }]) {+ return {+ format: '67js.scene',+ schemaVersion: 1,+ materials: [{ id: 'leaf', color: [0.2, 0.6, 0.2] }],+ geometries: [{ id: 'vine', type: 'curve', points: [[0, 0, 0], [2, 0, 0], [4, 1, 0], [6, 1, 0]], kind: 'poly', radius: 0.02, radialSegments: 4, grow }],+ nodes: [{ id: 'vine', geometry: 'vine', material: 'leaf' }],+ motion: { duration: 1, tracks: [{ kind: 'morph', id: 'vine', property: 'weight', keyframes }] },+ };+}++function still(grow) {+ const { motion, ...recipe } = vineRecipe(grow);+ return recipe;+}++// The renderer adds weight times offset to every vertex; this does the same on the CPU.+function blendedPositions(part) {+ const blended = Float32Array.from(part.geometry.positions);+ part.geometry.morphTargets.forEach((target, index) => {+ for (let component = 0; component < blended.length; component++) blended[component] += part.morph.weights[index] * target.positions[component];+ });+ return blended;+}++test('a growing vine reaches further along its curve as the grow track plays, and seeking equals playing', () => {+ const scene = createAgentScene(vineRecipe());+ const [part] = scene.parts;+ const reach = () => bounds({ positions: blendedPositions(part) }).maximum[0];+ const played = [0, 0.25, 0.5, 0.75, 1].map(time => {+ scene.sampleMotion(time);+ return reach();+ });+ played.reduce((previous, current) => {+ assert.ok(current > previous, `the vine grew from ${previous} to ${current}`);+ return current;+ });+ assert.ok(played[0] < 0.3, `a bare root at the start (${played[0]})`);+ const whole = curve([[0, 0, 0], [2, 0, 0], [4, 1, 0], [6, 1, 0]], { kind: 'poly', radius: 0.02, radialSegments: 4 });+ assert.ok(Math.abs(bounds(whole).maximum[0] - played.at(-1)) < 0.02, `the whole curve at the end (${played.at(-1)})`);+ scene.sampleMotion(1);+ scene.sampleMotion(0.5);+ const sought = reach();+ const fresh = createAgentScene(vineRecipe());+ fresh.sampleMotion(0.5);+ assert.equal(sought, bounds({ positions: blendedPositions(fresh.parts[0]) }).maximum[0], 'seeking equals a fresh sample');+ assert.equal(sought, played[2]);+});++test('a growing vine without a track shows the curve grown to grow.value, and the targets are deterministic', () => {+ const grown = createAgentScene(still({ name: 'vine', steps: 4 }));+ const [part] = grown.parts;+ assert.deepEqual(part.geometry.morphTargetNames, ['vine#1', 'vine#2', 'vine#3', 'vine#4']);+ assert.deepEqual(Array.from(part.morph.weights), [0, 0, 0, 1]);+ const half = createAgentScene(still({ name: 'vine', steps: 4, value: 0.5 }));+ assert.deepEqual(Array.from(half.parts[0].morph.weights), [0, 1, 0, 0]);+ const again = createAgentScene(still({ name: 'vine', steps: 4 }));+ assert.deepEqual(part.geometry.morphTargets[2].positions, again.parts[0].geometry.morphTargets[2].positions);+});++test('grow rejects bad fields with what to pass', () => {+ for (const [grow, pattern] of [+ [{ steps: 4 }, /grow\.name/],+ [{ name: 'vine', steps: 1 }, /grow\.steps/],+ [{ name: 'vine', steps: 99 }, /grow\.steps/],+ [{ name: 'vine', value: 2 }, /grow\.value/],+ [{ name: 'vine', bogus: 1 }, /Unknown grow field: bogus/],+ ]) assert.throws(() => createAgentScene(still(grow)), pattern);+});