Skip to content

Playbook and Three.js code kit for detailed dioramas: classic pixel art, stroked toon or pixel + stroke; two intake gates for look and model sourcing; free orbit, palette snap and ink; animated toy-scale cast; per-entity frame QA.

3.2 KB
Raw Blame
import * as THREE from 'three';

/**
 * Reset hero three-quarter camera. Distance is solved against fit points
 * (slab corners plus tall props) for a stable margin at each aspect ratio.
 * REQUIRED: attach createDioramaOrbit from orbit.js after fitting in every preset.
 * This module only solves the deterministic hero pose; it never auto-spins.
 */
export const CAMERA = {
  fov: 20.5,
  azimuth: (45.0 * Math.PI) / 180,
  elevation: (33.0 * Math.PI) / 180,
  target: new THREE.Vector3(0, -0.15, 0),
  fillX: 0.84,
  fillY: 0.86,
  // Post-fit camera multiplier. Keep 1.0 for the fitted size; 0.70 makes the
  // diorama 30% smaller linearly and leaves more paper margin. This is a camera
  // move only: slab, world clip, shadows and canvas stay at full scale.
  subjectScale: 1.0,
};

/** Override this list for a different slab / landmark height. */
export const FIT_POINTS = [
  new THREE.Vector3(-10.5, 0.0, -7.0),
  new THREE.Vector3(10.5, 0.0, -7.0),
  new THREE.Vector3(10.5, 0.0, 7.0),
  new THREE.Vector3(-10.5, 0.0, 7.0),
  new THREE.Vector3(-10.5, -0.42, -7.0),
  new THREE.Vector3(10.5, -0.42, -7.0),
  new THREE.Vector3(10.5, -0.42, 7.0),
  new THREE.Vector3(-10.5, -0.42, 7.0),
  new THREE.Vector3(0.0, 3.6, 0.0),
];

export function cameraDirection(out = new THREE.Vector3()) {
  const ce = Math.cos(CAMERA.elevation);
  return out.set(
    ce * Math.cos(CAMERA.azimuth),
    Math.sin(CAMERA.elevation),
    ce * Math.sin(CAMERA.azimuth)
  );
}

function fits(dir, right, up, aspect, distance, points) {
  const tanHalf = Math.tan((CAMERA.fov * Math.PI) / 360);
  const p = new THREE.Vector3();
  for (const fit of points) {
    p.subVectors(fit, CAMERA.target);
    const depth = distance - p.dot(dir);
    if (depth < 0.4) return false;
    const x = p.dot(right) / (depth * tanHalf * aspect);
    const y = p.dot(up) / (depth * tanHalf);
    if (Math.abs(x) > CAMERA.fillX) return false;
    if (Math.abs(y) > CAMERA.fillY) return false;
  }
  return true;
}

export function solveDistance(aspect, points = FIT_POINTS) {
  const a = Math.max(0.3, aspect);
  const dir = cameraDirection();
  const right = new THREE.Vector3().crossVectors(new THREE.Vector3(0, 1, 0), dir).normalize();
  const up = new THREE.Vector3().crossVectors(dir, right).normalize();

  let lo = 5;
  let hi = 300;
  for (let i = 0; i < 48; i++) {
    const mid = (lo + hi) * 0.5;
    if (fits(dir, right, up, a, mid, points)) hi = mid;
    else lo = mid;
  }
  return hi;
}

export function createCamera(aspect = 1.16, points = FIT_POINTS) {
  const camera = new THREE.PerspectiveCamera(CAMERA.fov, aspect, 0.5, 400);
  updateCamera(camera, aspect, points);
  return camera;
}

export function updateCamera(camera, aspect, points = FIT_POINTS) {
  const a = Math.max(0.3, aspect);
  const fit = solveDistance(a, points);
  const scale = CAMERA.subjectScale ?? 1;
  const d = fit / Math.max(0.1, scale);
  const dir = cameraDirection();
  camera.position.copy(CAMERA.target).addScaledVector(dir, d);
  camera.lookAt(CAMERA.target);
  camera.aspect = a;
  camera.near = Math.max(0.3, d * 0.01);
  camera.far = d * 4 + 80;
  camera.updateProjectionMatrix();
  camera.userData.fitDistance = fit;
  camera.userData.subjectScale = scale;
  camera.userData.distance = d;
}