Skip to content

feat(cad): add PatternInstancer linear/grid/circular/alongCurve arrays - #99

Merged
jbingham merged 1 commit into
feat/cad-loft-geometryfrom
feat/cad-pattern-instancer
Nov 13, 2026
Merged

jbingham merged 1 commit into
feat/cad-loft-geometryfrom
feat/cad-pattern-instancer

Conversation

@jbingham

Copy link
Copy Markdown
Collaborator

Summary

Implements Stage 3 of the CAD & Pattern enhancement plan in three-live-cad: declarative THREE.PatternInstancer (alias THREE.Pattern) arrays built on InstancedMesh, so LLM-authored scenes no longer need hand-written trigonometry and Matrix4 loops. Stacked on #98.

API

Each call returns an InstancedMesh, so it exports as EXT_mesh_gpu_instancing in GLB and PointInstancer in USDZ, with at most 10,000 instances.

  • PatternInstancer.linear(geo, mat, { count, step | span, direction, centered, startOffset, instanceRotation, rotationStep, scaleRange, colors })
  • PatternInstancer.grid(geo, mat, { counts: [nx, ny, nz] | countX/Y/Z, spacing, centered, centerY, origin, checkerboard, colors })
    • Oversized grids shrink their largest axis until they fit the instance cap.
  • PatternInstancer.circular(geo, mat, { count, radius, axis: 'y' | 'z' | 'x', center, startAngle, angleSpan | endAngle, endpoint, alignRadial, axialStep, instanceRotation, scaleRange, colors })
    • Each instance is the seed rigidly rotated about the axis.
    • A full turn never duplicates the seam; partial arcs include both endpoints.
  • PatternInstancer.alongCurve(geo, mat, { count, path | curve, closed, alignTangent, up, instanceRotation, scaleRange, colors })
    • Instances follow twist-free Bishop frames: local +Z is the tangent and +Y the up vector.
    • Closed loops never duplicate the seam.
  • new THREE.PatternInstancer(geo, mat, { mode: 'linear' | 'grid' | 'circular' | 'curve', ... }) or new THREE.Pattern(...)
    • If mode is omitted, it is inferred from the options. An unknown mode logs a warning.
  • PatternInstancer.toGeometry(inst)
    • Bakes the instances into one indexed BufferGeometry: inverse-transpose normals, mirrored instances re-wound, and instance colors as vertex colors.
    • Capped at 100k vertices / 300k indices, with a warning when it truncates.
  • THREE.CSG.subtract/union/intersect now accept an InstancedMesh operand, e.g. drilling a bolt-hole pattern in one call. userData.csg targets accept one too.

Audit fixes (self-review + independent audit)

  • Merged indices are capped as well as vertices, and instance counts are clamped to instanceMatrix capacity.
  • The matrix is reset per instance, out-of-range indices are skipped, and normals are recomputed when the source has none.
  • With checkerboard, the palette is indexed per kept cell, so 2 colors actually alternate.
  • Circular mode is inferred from startAngle / endAngle / axialStep / alignRadial too.
  • Numeric-string step / span values are accepted, a negative radius uses its absolute value, and material arrays use their first material.

Docs and prompts

Added to the README tables, AGENTS.md (new "Pattern Arrays" helper), the LLM guide, the authoring skill, llms.txt, and the AI edit prompt (with its Rust mirror in compiler/src/ai_edit.rs).

Bundle budgets

three-live-cad.min.js is now 18.8 KB gz, so its budget moves to < 20 KB gz. three-live-full moves to < 233 KB gz (232.6 KB) and xr-live-full to < 342 KB gz (341.6 KB).

Testing

  • node scripts/build.js --test: all suites pass (three-author 133/133). New coverage includes:
    • linear, grid, circular (y/z/x rigid-rotation check), and along-curve (tangent alignment, closed seam)
    • constructor and mode inference, hostile inputs, and toGeometry mirroring and watertightness
    • CSG.subtract with an InstancedMesh cutter, GLB/USDZ export, checkerboard palettes, and the bake index cap
  • cargo test --manifest-path compiler/Cargo.toml -- --test-threads=4: passes (100 + 86).

@jbingham
jbingham merged commit 23818e5 into feat/cad-loft-geometry Nov 13, 2026
1 check passed
jbingham added a commit that referenced this pull request Nov 15, 2026
…isibility, and PatternInstancer (#101)

* feat(cad): add PatternInstancer linear/grid/circular/alongCurve arrays and InstancedMesh CSG operands (#99)

Co-authored-by: Jonathan Bingham <binghamj@google.com>

* fix(web,ios): support opaque-origin static HTML hosting and hide internal XCFramework symbols

* fix(ios): pass -platform_version to ld -r in build_ios_xcframework.sh for Xcode ld-prime

---------

Co-authored-by: Jonathan Bingham <binghamj@google.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants