Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
import * as THREE from 'three';
const UP = new THREE.Vector3(0, 1, 0);
/** Default three-quarter view from slightly above the asset. */
const ELEVATION = 0.315; // radians, about 18 degrees
export const AZIMUTH = 0.733; // radians, about 42 degrees
export const orbitDirection = (azimuth: number) =>
new THREE.Vector3(
Math.cos(azimuth) * Math.cos(ELEVATION),
Math.sin(ELEVATION),
Math.sin(azimuth) * Math.cos(ELEVATION),
);
/**
* The ground grid's size, from the asset's radius.
*
* A plane just big enough for the fade, carried along under the camera, rather
* than drei's `infiniteGrid`. That option multiplies the plane by 1 + fadeDistance,
* and the fade grows with the asset, so the plane grows with the square of the
* radius: about 310 km out from a cathedral 83 m in radius, and tens of thousands
* of kilometres from the Golden Gate Bridge. The shader's 32-bit coordinates can't
* hold a line still at that scale, so the grid broke into stair-steps and stripes
* that jumped as the camera moved. `followCamera` keeps the lines fixed in the
* world while the plane stays small.
*/
export function groundGrid(radius: number) {
const fadeDistance = radius * 9;
return {
args: [radius * 20, radius * 20] as [number, number],
cellSize: radius / 5,
sectionSize: radius,
fadeDistance,
followCamera: true,
};
}
/** A saved camera a page can offer beside the orbit controls, in the model's own metres. */
export interface SavedView {
label: string;
position: [number, number, number];
target: [number, number, number];
}
/** Moves the camera and the orbit target to a saved view; the orbit controls take it from there. */
export function showView(camera: THREE.Camera, target: THREE.Vector3, view: SavedView) {
camera.position.fromArray(view.position);
target.fromArray(view.target);
}
/** Past this many vertices, the surface sample below is coarse enough to step over a slim part altogether. */
const MESH_TOPS_ABOVE_VERTICES = 1_000_000;
export const wantsMeshTops = (vertices: number) => vertices > MESH_TOPS_ABOVE_VERTICES;
/**
* The top of each mesh, added to the sample when framing a very large model. At one
* vertex in hundreds the sample can miss a spire entirely, and it then sticks out of
* the frame. Smaller models are framed from their vertices alone, as before.
*/
export function meshTops(meshes: readonly THREE.Object3D[]) {
return meshes.map((mesh) => {
const box = new THREE.Box3().setFromObject(mesh);
return new THREE.Vector3((box.min.x + box.max.x) / 2, box.max.y, (box.min.z + box.max.z) / 2);
});
}
const AZIMUTH_SAMPLES = 16;
/**
* Every sampled point resolved into camera axes, once per azimuth on the
* turntable.
*
* The whole turntable and not just the opening angle, because the view rotates:
* framing for the angle it happens to start at walks the tail of a fifty-metre
* airship off the edge four seconds later. Flat typed arrays because the search
* below sweeps these tens of times and allocating a vector per point per pass
* turns ten milliseconds into a second.
*/
function project(points: readonly THREE.Vector3[], origin: THREE.Vector3) {
const n = points.length;
const depth = new Float64Array(AZIMUTH_SAMPLES * n);
const across = new Float64Array(AZIMUTH_SAMPLES * n);
const above = new Float64Array(AZIMUTH_SAMPLES * n);
const p = new THREE.Vector3();
for (let a = 0; a < AZIMUTH_SAMPLES; a++) {
const forward = orbitDirection((a / AZIMUTH_SAMPLES) * Math.PI * 2);
const right = new THREE.Vector3().crossVectors(UP, forward).normalize();
const up = new THREE.Vector3().crossVectors(forward, right);
for (let i = 0; i < n; i++) {
p.copy(points[i]!).sub(origin);
const at = a * n + i;
depth[at] = p.dot(forward);
across[at] = p.dot(right);
above[at] = p.dot(up);
}
}
return { n, depth, across, above };
}
type Projection = ReturnType<typeof project>;
/**
* How far back the camera has to sit for everything to stay in frame, with the
* orbit target raised by `lift` from where the projection was taken.
*
* A point is on screen when |across| <= (distance - depth) * tanH, and likewise
* vertically, so each point names a distance and the largest one wins. Raising
* the target moves each point down by `lift` in world space, which is a shift of
* `lift * cos(elevation)` in the camera's vertical axis and `lift *
* sin(elevation)` in depth; nothing moves horizontally, because the horizontal
* axis of an orbiting camera is always level.
*/
function distanceFor(proj: Projection, lift: number, tanH: number, tanV: number) {
const dz = lift * Math.sin(ELEVATION);
const dy = lift * Math.cos(ELEVATION);
let needed = 0;
for (let i = 0; i < proj.depth.length; i++) {
const depth = proj.depth[i]! - dz;
const h = depth + Math.abs(proj.across[i]!) / tanH;
const v = depth + Math.abs(proj.above[i]! - dy) / tanV;
if (h > needed) needed = h;
if (v > needed) needed = v;
}
return needed;
}
/**
* Where to point the camera and how far back to put it.
*
* Aiming at the centre of the bounding box is the obvious choice and it wastes a
* lot of screen. The camera looks down from eighteen degrees, so the near-bottom
* of a wide asset projects much further below the centre than its far-top
* projects above: the cathedral came out sitting low in a frame padded to fit the
* corner of its own base slab, at about forty per cent of the width it could
* have had. Raising the aim point re-centres the silhouette and the padding goes
* away with it.
*
* The distance needed is convex in that height, so a ternary search finds the
* best one in a few dozen evaluations of arithmetic over flat arrays.
*/
export function frameAsset(
points: readonly THREE.Vector3[],
center: THREE.Vector3,
extent: number,
fov: number,
aspect: number,
) {
const tanV = Math.tan((fov * Math.PI) / 360);
const tanH = tanV * aspect;
const proj = project(points, center);
let low = -extent;
let high = extent;
for (let i = 0; i < 22; i++) {
const a = low + (high - low) / 3;
const b = high - (high - low) / 3;
// Center from the vertical fit first. Including the horizontal constraint here
// pushes the aim toward the top edge in portrait viewports: it shaves a little
// distance while leaving the entire asset low in the frame.
if (distanceFor(proj, a, Infinity, tanV) < distanceFor(proj, b, Infinity, tanV)) high = b;
else low = a;
}
const lift = (low + high) / 2;
return {
target: new THREE.Vector3(center.x, center.y + lift, center.z),
distance: distanceFor(proj, lift, tanH, tanV),
};
}