Skip to content

3D engine that AI agents drive

13.6 KB
Raw Blame
import { mat4, vec3 } from 'gl-matrix';

/** Lens fields a camera may carry on top of eye, target, up, fov, near and far; each is absent unless the scene sets it. */
export const CAMERA_LENS_FIELDS = Object.freeze(['projection', 'orthoScale', 'focalLength', 'sensorWidth', 'shift', 'fStop', 'focusDistance']);

/** Image-centre shift as fractions of the frame width and height, like Blender's lens shift; positive moves the frame right and up. */
export function validateCameraShift(shift) {
  if (!Array.isArray(shift) || shift.length !== 2 || !shift.every(component => Number.isFinite(component) && Math.abs(component) <= 1)) {
    throw new RangeError('Camera shift must be [x, y], each between -1 and 1 as a fraction of the frame.');
  }
}

export function applyProjection(matrix, frame, aspect, { world = false } = {}) {
  if (!Number.isFinite(aspect) || aspect <= 0) throw new RangeError('Camera aspect must be positive and finite');
  const hasLens = frame.projection !== undefined || frame.fov !== undefined || frame.focalLength !== undefined;
  const hasClipping = frame.near !== undefined || frame.far !== undefined;
  if (!hasLens && !hasClipping) return matrix;
  const near = frame.near ?? 0.1;
  const far = frame.far ?? (world ? 600 : 100);
  if (!Number.isFinite(near) || !Number.isFinite(far) || near <= 0 || far <= near) throw new RangeError('Camera clipping planes must satisfy 0 < near < far');
  if (!hasLens) {
    // Only the clipping planes are given: keep the renderer's own lens (its field of view and off-centre shift) and replace the planes.
    const fieldOfView = 2 * Math.atan(1 / matrix[5]);
    const shift = matrix[8];
    mat4.perspective(matrix, fieldOfView, aspect, near, far);
    matrix[8] = shift;
    return matrix;
  }
  if (frame.shift !== undefined) validateCameraShift(frame.shift);
  if (frame.projection === 'orthographic') {
    const height = frame.orthographicHeight ?? frame.orthoScale ?? 4;
    if (!Number.isFinite(height) || height <= 0) throw new RangeError('Orthographic height must be positive and finite');
    const halfHeight = height / 2;
    mat4.ortho(matrix, -halfHeight * aspect, halfHeight * aspect, -halfHeight, halfHeight, near, far);
    // An orthographic window moves sideways in clip space: x' = x + translation.
    if (frame.shift) {
      matrix[12] -= 2 * frame.shift[0];
      matrix[13] -= 2 * frame.shift[1];
    }
    return matrix;
  }
  if (frame.projection && frame.projection !== 'perspective') throw new RangeError(`Unsupported camera projection: ${frame.projection}`);
  mat4.perspective(matrix, cameraFieldOfView(frame, aspect) * Math.PI / 180, aspect, near, far);
  // The z column of x and y moves the image centre by -matrix / depth in clip space, so +2 per frame fraction.
  if (frame.shift) {
    matrix[8] += 2 * frame.shift[0];
    matrix[9] += 2 * frame.shift[1];
  }
  return matrix;
}

/** Vertical field of view in degrees: `fov`, or a focal length on a sensor `sensorWidth` wide (default 36, full frame) across the image. */
export function cameraFieldOfView(frame, aspect) {
  if (frame.focalLength !== undefined) {
    const { focalLength, sensorWidth = 36 } = frame;
    if (!Number.isFinite(focalLength) || focalLength <= 0 || !Number.isFinite(sensorWidth) || sensorWidth <= 0) throw new RangeError('Focal length and sensor width must be positive and finite');
    return 2 * Math.atan(sensorWidth / aspect / focalLength / 2) * 180 / Math.PI;
  }
  const fov = frame.fov ?? 45;
  if (!Number.isFinite(fov) || fov <= 0 || fov >= 180) throw new RangeError('Camera field of view must be between 0 and 180 degrees');
  return fov;
}

export const MAX_APERTURE_BLADES = 64;

export function requirePositiveFinite(value, name) {
  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
    throw new RangeError(`Camera ${name} must be a positive finite number, got ${JSON.stringify(value)}.`);
  }
}

/** Focal length in millimetres: `focalLength` as given, or the one that gives `fov` on a sensor `sensorWidth` wide across the image. */
export function cameraFocalLength(frame, aspect) {
  if (frame.focalLength !== undefined) {
    requirePositiveFinite(frame.focalLength, 'focalLength');
    return frame.focalLength;
  }
  const sensorWidth = frame.sensorWidth ?? 36;
  requirePositiveFinite(sensorWidth, 'sensorWidth');
  const fieldOfView = cameraFieldOfView(frame, aspect);
  return sensorWidth / aspect / (2 * Math.tan(fieldOfView * Math.PI / 360));
}

/**
 * The kernel's aperture rotation in radians for a Blender-style rotation in degrees (Blender's aperture_rotation reaches Cycles'
 * bladesrotation as radians, unchanged, in intern/cycles/blender/camera.cpp).
 * Cook's cam_sample_regular_polygon places the corners as Cycles' regular_polygon_sample does (at rotation + pi/n + 2 pi k / n,
 * codepawl/cook#13), so the kernel takes Cycles' rotation unchanged: degrees to radians, for any number of blades.
 */
function kernelApertureRotation(rotationDegrees) {
  return rotationDegrees * Math.PI / 180;
}

/**
 * The thin lens a camera with an `fStop` describes, for the native path tracer (Cycles' camera model): the aperture radius in
 * scene units (focalLength / (2 * fStop), millimetres to metres), the focus distance along the view axis (`focusDistance`, by
 * default the distance from eye to target), and the optional polygonal blades (`apertureBlades`, 0 or 3 to 64) turned by
 * `apertureRotation` degrees. Returns null for a camera without `fStop`: a pinhole.
 */
export function resolveThinLens(frame, { aspect, eye, target }) {
  if (frame.fStop === undefined) return null;
  requirePositiveFinite(frame.fStop, 'fStop');
  const focusDistance = frame.focusDistance ?? Math.hypot(target[0] - eye[0], target[1] - eye[1], target[2] - eye[2]);
  requirePositiveFinite(focusDistance, 'focusDistance');
  const blades = frame.apertureBlades ?? 0;
  if (!Number.isInteger(blades) || blades < 0 || blades === 1 || blades === 2 || blades > MAX_APERTURE_BLADES) {
    throw new RangeError(`Camera apertureBlades must be 0 (a round aperture) or a whole number from 3 to ${MAX_APERTURE_BLADES}, got ${JSON.stringify(frame.apertureBlades)}.`);
  }
  const rotationDegrees = frame.apertureRotation ?? 0;
  if (typeof rotationDegrees !== 'number' || !Number.isFinite(rotationDegrees)) {
    throw new RangeError(`Camera apertureRotation must be a finite number of degrees, got ${JSON.stringify(frame.apertureRotation)}.`);
  }
  return {
    apertureRadius: cameraFocalLength(frame, aspect) / 1000 / (2 * frame.fStop),
    focalDistance: focusDistance,
    apertureBlades: blades,
    apertureRotation: kernelApertureRotation(rotationDegrees),
  };
}

const viewDirections = { front: [0, 0, 1], right: [1, 0, 0], top: [0, 1, 0], perspective: [0.58, 0.34, 0.74] };

export function cameraView(name = 'front', { target = [0, 1.5, 0], height = 3.8, distance = 8 } = {}) {
  const direction = viewDirections[name];
  if (!direction) throw new RangeError(`Unsupported camera view: ${name}`);
  if (!Number.isFinite(height) || height <= 0) throw new RangeError('Orthographic height must be positive and finite');
  if (target.length !== 3 || !target.every(Number.isFinite) || !Number.isFinite(distance) || distance <= 0) throw new RangeError('Camera target and positive distance must be finite');
  const unitDirection = vec3.normalize(vec3.create(), direction);
  const eye = Array.from(vec3.scaleAndAdd(vec3.create(), target, unitDirection, distance));
  return { eye, target: [...target], up: name === 'top' ? [0, 0, -1] : [0, 1, 0], projection: name === 'perspective' ? 'perspective' : 'orthographic', orthographicHeight: height, fov: 45 };
}

/** Throws unless the eye, target and up of `view` are finite, the eye differs from the target and up is not parallel to the view; `subject` starts each message. */
export function requireNonDegenerateView(view, subject = 'Fit') {
  const up = view?.up ?? [0, 1, 0];
  const isFiniteVector = vector => vector?.length === 3 && Array.from(vector).every(value => typeof value === 'number' && Number.isFinite(value));
  if (!isFiniteVector(view?.eye) || !isFiniteVector(view?.target) || !isFiniteVector(up)) {
    throw new RangeError(`${subject} camera eye, target and up must be three finite numbers each.`);
  }
  const forward = [0, 1, 2].map(axis => view.target[axis] - view.eye[axis]);
  const forwardLength = Math.hypot(...forward);
  const upLength = Math.hypot(...up);
  if (forwardLength === 0 || upLength === 0) {
    throw new RangeError(`${subject} eye and target must differ and up must be nonzero.`);
  }
  const alignment = forward.reduce((sum, component, axis) => sum + component * up[axis], 0) / (forwardLength * upLength);
  if (Math.abs(alignment) >= 1 - 1e-10) {
    throw new RangeError(`${subject} up must not be parallel to the view direction; pass another up, such as [0, 0, -1] for a top view.`);
  }
}

export function fitOrthographicHeight(bounds, view, aspect, padding = 1.15) {
  if (!Number.isFinite(aspect) || aspect <= 0 || !Number.isFinite(padding) || padding < 1) throw new RangeError('Fit aspect must be positive and padding at least one');
  if (bounds.minimum.length !== 3 || bounds.maximum.length !== 3 || !bounds.minimum.every(Number.isFinite) || !bounds.maximum.every((value, axis) => Number.isFinite(value) && value >= bounds.minimum[axis])) throw new RangeError('Fit bounds must be finite and ordered');
  requireNonDegenerateView(view);
  const basis = mat4.lookAt(mat4.create(), view.eye, view.target, view.up ?? [0, 1, 0]);
  const minimum = [Infinity, Infinity];
  const maximum = [-Infinity, -Infinity];
  for (let corner = 0; corner < 8; corner++) {
    const point = [0, 1, 2].map(axis => corner & (1 << axis) ? bounds.maximum[axis] : bounds.minimum[axis]);
    const projected = vec3.transformMat4(vec3.create(), point, basis);
    for (let axis = 0; axis < 2; axis++) {
      minimum[axis] = Math.min(minimum[axis], projected[axis]);
      maximum[axis] = Math.max(maximum[axis], projected[axis]);
    }
  }
  return Math.max(maximum[1] - minimum[1], (maximum[0] - minimum[0]) / aspect) * padding;
}

// Return the eye-to-target distance needed to contain a box without changing the lens.
export function fitPerspectiveDistance(bounds, view, aspect, padding = 1.15) {
  if (!Number.isFinite(aspect) || aspect <= 0 || !Number.isFinite(padding) || padding < 1) {
    throw new RangeError('Fit aspect must be positive and padding at least one');
  }
  const finiteVector = vector => vector?.length === 3 && Array.from(vector).every(value => typeof value === 'number' && Number.isFinite(value));
  if (!finiteVector(bounds?.minimum) || !finiteVector(bounds?.maximum) || !bounds.maximum.every((value, axis) => value >= bounds.minimum[axis])) {
    throw new RangeError('Fit bounds must be finite and ordered');
  }
  const up = view?.up ?? [0, 1, 0];
  if (!finiteVector(view?.eye) || !finiteVector(view?.target) || !finiteVector(up)) {
    throw new RangeError('Fit camera vectors must be finite');
  }
  if (view.projection && view.projection !== 'perspective') {
    throw new RangeError('Perspective fit requires a perspective camera');
  }
  const fov = view.fov ?? 45;
  const near = view.near ?? 0.1;
  const far = view.far ?? 100;
  if (!Number.isFinite(fov) || fov <= 0 || fov >= 180 || !Number.isFinite(near) || !Number.isFinite(far) || near <= 0 || far <= near) {
    throw new RangeError('Fit lens must have 0 < fov < 180 and 0 < near < far');
  }
  const forward = vec3.subtract([], view.target, view.eye);
  const forwardLength = Math.hypot(...forward);
  if (!Number.isFinite(forwardLength) || forwardLength === 0) {
    throw new RangeError('Fit eye and target must differ');
  }
  for (let axis = 0; axis < 3; axis++) forward[axis] /= forwardLength;
  const upLength = Math.hypot(...up);
  if (!Number.isFinite(upLength) || upLength === 0) {
    throw new RangeError('Fit up must have a finite nonzero length');
  }
  const normalizedUp = Array.from(up, component => component / upLength);
  const right = vec3.cross([], forward, normalizedUp);
  const rightLength = Math.hypot(...right);
  if (!Number.isFinite(rightLength) || rightLength === 0) {
    throw new RangeError('Fit up must not be parallel to the view direction');
  }
  for (let axis = 0; axis < 3; axis++) right[axis] /= rightLength;
  const vertical = vec3.cross([], right, forward);
  const verticalTangent = Math.tan(fov * Math.PI / 360);
  const horizontalTangent = verticalTangent * aspect;
  if (!Number.isFinite(horizontalTangent) || horizontalTangent <= 0) {
    throw new RangeError('Fit aspect and lens exceed the supported numeric range');
  }
  let distance = near;
  let maximumDepth = -Infinity;
  for (let corner = 0; corner < 8; corner++) {
    const offset = [0, 1, 2].map(axis => (corner & (1 << axis) ? bounds.maximum[axis] : bounds.minimum[axis]) - view.target[axis]);
    const horizontal = vec3.dot(offset, right);
    const height = vec3.dot(offset, vertical);
    const depth = vec3.dot(offset, forward);
    distance = Math.max(distance, Math.abs(horizontal) * padding / horizontalTangent - depth, Math.abs(height) * padding / verticalTangent - depth, near - depth);
    maximumDepth = Math.max(maximumDepth, depth);
  }
  if (!Number.isFinite(distance) || distance <= 0 || distance + maximumDepth > far) {
    throw new RangeError('Fit bounds cannot fit within the camera clipping planes');
  }
  const fittedEye = view.target.map((component, axis) => Math.fround(component - forward[axis] * distance));
  const roundedTarget = view.target.map(component => Math.fround(component));
  if (!fittedEye.every(Number.isFinite) || !roundedTarget.every(Number.isFinite)
    || fittedEye.every((component, axis) => component === roundedTarget[axis])) {
    throw new RangeError('Fit camera collapses or overflows after Float32 rounding; use coordinates closer to the origin');
  }
  return distance;
}