Skip to content

Official Codebase of 3DCodeVerse

Python
10.1 KB
Raw Blame
/**
 * Overview orbit rig fitted to the CONTENT of a scene (pure).
 *
 * `framingBox(census, bounds)` picks what to frame: the union of the census's
 * content groups (sky dome and ground plane are never content), dropping any
 * group that sprawls past the plan bounds (scatter across the whole ground) and
 * clamping the result to the bounds — never the ground plane, never the sky.
 * `fitOrbitCameras(bbox, views, opts)` then fits each view so the box's eight
 * corners fill the frame (exact per-corner frustum fit with a margin, not a
 * bounding-sphere fit).  Scenes sit on ground, so the rig is ground-aware: eyes
 * never go below ground, low "eye level" views stand just outside the footprint
 * ~1.6 m above ground and look at the content centre, and a CONTACT view (elevation
 * under 10°, `fitContactCamera`) stands at ~1.2× the content span, 0.4 m above the
 * ground, aimed at the ground edge of the content box — the angle that shows daylight
 * under a base.  Azimuth 0 = front (+Z), CCW from above; elevation in degrees above
 * the horizon (conventions.py).
 */

const DEG = Math.PI / 180;
const FIT_MARGIN = 1.05;     // overview fit: the bbox corners stay 5 % inside the frame
const BOUNDS_SPRAWL = 1.1;   // a content group wider than 110 % of the plan bounds is scatter, not a zone
const BOUNDS_CLAMP = 1.1;    // framing box is clamped to the plan bounds grown by 10 %

/** Unit direction from azimuth/elevation (Y-up, +Z front). */
export function orbitDirection(azimuthDeg, elevationDeg) {
  const az = azimuthDeg * DEG, el = elevationDeg * DEG;
  return [Math.sin(az) * Math.cos(el), Math.sin(el), Math.cos(az) * Math.cos(el)];
}

function unionBox(boxes) {
  if (!boxes.length) return null;
  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
  for (const b of boxes) for (let i = 0; i < 3; i++) { min[i] = Math.min(min[i], b.min[i]); max[i] = Math.max(max[i], b.max[i]); }
  return { min, max, size: max.map((v, i) => v - min[i]) };
}

function span(box) {
  return Math.max(box.max[0] - box.min[0], box.max[2] - box.min[2]);
}

/**
 * The box the overview rig should frame.
 * @param {object|null} census   host census (`groups[]`, `content_bbox`, `bbox`)
 * @param {{min:number[],max:number[]}|null} bounds  plan bounds (optional)
 */
export function framingBox(census, bounds = null) {
  if (!census) return null;
  let groups = (census.groups || []).filter((g) => g.kind === 'content' && g.bbox && g.bbox.min && g.bbox.max);
  if (bounds && bounds.min && bounds.max && groups.length > 1) {
    const limit = span(bounds) * BOUNDS_SPRAWL;
    const kept = groups.filter((g) => span(g.bbox) <= limit);
    if (kept.length) groups = kept;
  }
  let box = unionBox(groups.map((g) => g.bbox)) || census.content_bbox || census.bbox || null;
  if (box && bounds && bounds.min && bounds.max) {
    const c = bounds.min.map((v, i) => (v + bounds.max[i]) / 2);
    const h = bounds.max.map((v, i) => ((v - bounds.min[i]) / 2) * BOUNDS_CLAMP);
    const min = box.min.map((v, i) => Math.max(v, c[i] - h[i]));
    const max = box.max.map((v, i) => Math.min(v, c[i] + h[i]));
    if (min.every((v, i) => v < max[i])) box = { min, max, size: max.map((v, i) => v - min[i]) };
  }
  return box;
}

function corners(bbox) {
  const out = [];
  for (const x of [bbox.min[0], bbox.max[0]]) for (const y of [bbox.min[1], bbox.max[1]]) for (const z of [bbox.min[2], bbox.max[2]]) out.push([x, y, z]);
  return out;
}

/**
 * Smallest distance along `dir` (unit, from `center`) at which every corner sits
 * inside a camera looking back at `center` with the given half-angle tangents.
 *
 * THE distance fit for both rigs: the scene orbit (this module) and the object
 * rig (`browser/camera_fit.js`, which passes the screen-up vector it gives the
 * THREE camera).  Exact per-corner solution — the projected half-extent of a
 * corner is `(offAxis * margin) / (tan · (dist - depthOffset))`, so requiring
 * ≤ 1 on both axes for all eight corners is one max, no iteration.
 * @param {number[]|null} upHint  screen-up used for the roll (default: +Y, or
 *   -Z for an exactly vertical view — what THREE's lookAt does)
 */
export function fitDistance(bbox, center, dir, tanH, tanV, margin, upHint = null) {
  // same roll as THREE's lookAt (world up = +Y unless the view is exactly vertical)
  const up0 = upHint || (Math.abs(dir[1]) > 0.9999 ? [0, 0, -1] : [0, 1, 0]);
  const f = dir.map((v) => -v);   // forward; right = forward × up0; up = right × forward
  const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
  const norm = (v) => { const l = Math.hypot(...v) || 1; return v.map((x) => x / l); };
  const right = norm(cross(f, up0));
  const up = norm(cross(right, f));
  let dist = 0;
  for (const c of corners(bbox)) {
    const rel = c.map((v, i) => v - center[i]);
    const depthOffset = rel[0] * dir[0] + rel[1] * dir[1] + rel[2] * dir[2];   // + toward the eye
    const x = Math.abs(rel[0] * right[0] + rel[1] * right[1] + rel[2] * right[2]);
    const y = Math.abs(rel[0] * up[0] + rel[1] * up[1] + rel[2] * up[2]);
    dist = Math.max(dist, depthOffset + (x * margin) / tanH, depthOffset + (y * margin) / tanV);
  }
  return dist;
}

function boxGeom(bbox, groundY) {
  const size = bbox.max.map((v, i) => v - bbox.min[i]);
  const center = bbox.min.map((v, i) => v + size[i] / 2);
  const floor = groundY === null || groundY === undefined ? bbox.min[1] : groundY;
  return { size, center, floor };
}

function round3(spec) {
  spec.position = spec.position.map((x) => +x.toFixed(3));
  spec.lookAt = spec.lookAt.map((x) => +x.toFixed(3));
  return spec;
}

/**
 * Eye-level camera standing just outside the bbox footprint on the given
 * azimuth side, ~1.6 m above ground, looking into the content.  THE owner of
 * the zone-camera fit (assemble.py consumes it through probe_scene.mjs).
 * @returns {{position:number[], lookAt:number[], fov:number}}
 */
export function fitZoneCamera(bbox, { azimuth = 45, floor = null, fov = 50 } = {}) {
  const g = boxGeom(bbox, floor);
  const [dx, , dz] = orbitDirection(azimuth, 0);
  // distance from the centre to the bbox's xz boundary along (dx, dz)
  const hx = g.size[0] / 2, hz = g.size[2] / 2;
  const tx = Math.abs(dx) > 1e-6 ? hx / Math.abs(dx) : Infinity;
  const tz = Math.abs(dz) > 1e-6 ? hz / Math.abs(dz) : Infinity;
  const back = Math.min(tx, tz) + Math.max(2, 0.12 * Math.max(g.size[0], g.size[2]));
  const eyeH = Math.max(g.floor + 0.5, g.floor + 1.6 + Math.min(4, 0.1 * g.size[1]));
  return round3({
    position: [g.center[0] + dx * back, eyeH, g.center[2] + dz * back],
    lookAt: [g.center[0], Math.min(g.center[1], g.floor + 0.35 * g.size[1] + 0.5), g.center[2]],
    fov,
  });
}

const CONTACT_SPAN_FACTOR = 1.2;   // eye distance from the content centre, in content spans
const CONTACT_EYE_M = 0.4;         // eye height above the ground: a base's daylight is a few cm tall

/**
 * Ground-level CONTACT camera on the given azimuth side (scene's `overview_low_front`,
 * 2026-10-14): the eye stands `CONTACT_SPAN_FACTOR` content spans from the centre, 0.4 m
 * above the ground, and looks at the point where the view line leaves the content box's
 * footprint AT ground height — so the near edge of the content sits mid-frame with the
 * ground under it, where a hovering base or a part through a neighbour is visible.  The
 * overview fits look down at 32°+ and see a base's shadow, not its gap; the judge's
 * contact crops are cut from this tile (judges/prompt_builder.plan_detail_crops).
 * @returns {{position:number[], lookAt:number[], fov:number}}
 */
export function fitContactCamera(bbox, { azimuth = 20, floor = null, fov = 50 } = {}) {
  const g = boxGeom(bbox, floor);
  const [dx, , dz] = orbitDirection(azimuth, 0);
  const hx = g.size[0] / 2, hz = g.size[2] / 2;
  const tx = Math.abs(dx) > 1e-6 ? hx / Math.abs(dx) : Infinity;
  const tz = Math.abs(dz) > 1e-6 ? hz / Math.abs(dz) : Infinity;
  const edge = Math.min(tx, tz);                       // centre → footprint boundary along the view line
  const dist = Math.max(edge + 2, CONTACT_SPAN_FACTOR * Math.max(span(bbox), 1));
  return round3({
    position: [g.center[0] + dx * dist, g.floor + CONTACT_EYE_M, g.center[2] + dz * dist],
    lookAt: [g.center[0] + dx * edge, g.floor, g.center[2] + dz * edge],
    fov,
  });
}

/**
 * Overview camera on the given azimuth side, fitted so the bbox's eight
 * corners fill the frame (exact per-corner frustum fit, ground-aware — never
 * a bounding-sphere fit).  THE owner of the overview fit.
 * @returns {{position:number[], lookAt:number[], fov:number}}
 */
export function fitOverviewCamera(bbox, { azimuth = 45, elevation = 30, fov = 50, aspect = 16 / 9, groundY = null } = {}) {
  const g = boxGeom(bbox, groundY);
  const el = Math.max(3, Math.min(89, elevation));
  const d = orbitDirection(azimuth, el);
  const tanV = Math.tan((fov * DEG) / 2);
  const tanH = tanV * aspect;
  const minDist = Math.max(1.5, 0.35 * Math.hypot(g.size[0], g.size[1], g.size[2]));
  const dist = Math.max(minDist, fitDistance(bbox, g.center, d, tanH, tanV, FIT_MARGIN));
  const eye = g.center.map((c, i) => c + d[i] * dist);
  if (eye[1] < g.floor + 0.5) eye[1] = g.floor + 0.5;
  return round3({ position: eye, lookAt: g.center.slice(), fov });
}

/**
 * Build camera specs for `views` around `bbox` ({min:[..], max:[..]}):
 * fitOverviewCamera above 20°, fitZoneCamera at eye level (10°–20°), fitContactCamera
 * under 10°.  Only the overviews drop the fog and lift ceilings (`noFog`): the eye and
 * contact views are pictures of the place as lit.
 * @returns {Array<{name, position, lookAt, fov, kind:'orbit'}>}
 */
export function fitOrbitCameras(bbox, views, { fov = 50, aspect = 16 / 9, groundY = null } = {}) {
  if (!bbox || !bbox.min || !bbox.max) return [];
  const out = [];
  for (const v of views) {
    const el = Math.max(3, Math.min(89, v.elevation));
    const fit = el < 10
      ? fitContactCamera(bbox, { azimuth: v.azimuth, floor: groundY, fov })
      : el <= 20
        ? fitZoneCamera(bbox, { azimuth: v.azimuth, floor: groundY, fov })
        : fitOverviewCamera(bbox, { azimuth: v.azimuth, elevation: el, fov, aspect, groundY });
    out.push({ name: v.name, ...fit, kind: 'orbit', noFog: el > 20 });
  }
  return out;
}