Skip to content

Official Codebase of 3DCodeVerse

Python
7.0 KB
Raw Blame
/**
 * Backdrop classification — THE single owner of "is this drawable sky, ground
 * or content?" for a scene.  Used by the census (`host_census.mjs`, which
 * decides what `content_bbox` covers) and by the frame-coverage instrument
 * (`host_coverage.mjs`, which masks the same three classes per frame), so the
 * word "content" means exactly one thing everywhere.
 *
 * Rules (explicit metadata, then name + world-box shape, in order):
 *   sky      a non-depth-writing drawable with userData.sceneBackdrop === 'sky'
 *   sky      a sky-ish name spanning > 50 m or not writing depth, or anything enormous (span > 2 km,
 *            or tall AND wide: sy > 300 with span > 300)
 *   content  an InstancedMesh (scatter spans the map but is not ground)
 *   ground   a ground-ish name on a wide, flat box (span > 20, sy < 6 % of span)
 *            or any very wide, very flat box (span > 40, sy < 2 % of span)
 *            or — only when `contentSpan` is known (coverage) — a flat box far
 *            larger than the content itself (span > 2.5 × contentSpan)
 *   content  everything else
 */

/**
 * A mesh that does not WRITE DEPTH is a volumetric pass, not matter: haze shells,
 * god rays, light shafts, glow cards.  It cannot support anything, nothing can sink
 * into it, and overlapping it is what it is FOR.
 *
 * Measured on bench/out/scene_baseline (2026-09-05): every scene the generator wrote
 * uses `depthWrite: false` 34-42 times, and two of the six cells failed
 * `scene_placement` on nothing else — "BlackPine_5 is sunken 3.46 m into
 * AtmosphereHaze" (MeshBasicMaterial, opacity 0.035) and "WindowSnowView/Mesh_49 and
 * Environment/MoonlightShaft overlap 100%" (opacity 0.04, AdditiveBlending).  Both
 * scenes were correct; the gate was measuring fog.
 *
 * Opacity is deliberately NOT part of the rule: glass sits at 0.3-0.6 and keeps
 * writing depth, and a greenhouse pane really is a surface.  A solid wall the model
 * mistakenly wrote `depthWrite: false` on stops being a support — a missed defect,
 * which is the cheaper error, and one that matches how the frame actually renders.
 */
export function nonSolid(mesh) {
  const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
  const real = mats.filter(Boolean);
  return real.length > 0 && real.every((m) => m.depthWrite === false);
}

/** World-space AABB of a drawable (a fresh THREE.Box3), or null when it has none.  An
 * InstancedMesh's box spans every instance (three's own `InstancedMesh.boundingBox`), not the
 * prototype's: 40 cloud puffs over 3 km are a 3 km box, whoever asks. */
export function drawableBox(o, THREE) {
  if (!o.geometry) return null;
  if (!o.geometry.boundingBox) o.geometry.computeBoundingBox();
  if (o.isInstancedMesh && !o.boundingBox) o.computeBoundingBox();
  const gb = o.isInstancedMesh ? o.boundingBox : o.geometry.boundingBox;
  if (!gb || gb.isEmpty()) return null;
  const box = new THREE.Box3().copy(gb).applyMatrix4(o.matrixWorld);
  return box.isEmpty() ? null : box;
}

/** python's `conventions._INSTANCE_RE`: `Leg_2` / `Rock.003` / `Fence-1` → ['Leg', '2']; a name with no
 * instance suffix (`Leg2`, `Cart_800006`) → [name, '']. THE instance rule on the JS side (tests pin the two). */
const INSTANCE_RE = /^(.+?)[_.-](\d{1,3})$/;
export function splitInstance(name) {
  const m = INSTANCE_RE.exec(String(name || ''));
  return m ? [m[1], m[2]] : [String(name || ''), ''];
}

/** The words of python's `conventions.to_snake(name)`, digits-only words dropped: `LEDStairs` →
 * ['led', 'stairs'].  THE name tokeniser every JS word rule (sky, ground, water, placement) reads. */
export function nameWords(name) {
  return String(name || '').replace(/[^0-9A-Za-z]+/g, ' ')
    .replace(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g, ' ')
    .toLowerCase().split(' ').filter((w) => w && !/^\d+$/.test(w));
}

/** `nameWords` as one string, for the word regexes: 'HDRISky' → 'hdri sky'. */
export function nameText(name) { return nameWords(name).join(' '); }

/** classifyBackdrop's shape rules (metres, fractions of the horizontal span).  The scene-composition
 * skill quotes them; its `_claims` pin each one, so a change here fails that test. */
export const SKY_NAMED_SPAN_M = 50;       // a sky-named mesh wider than this is sky
export const GROUND_NAMED_SPAN_M = 20;    // a ground-named mesh wider than this ...
export const GROUND_NAMED_FLAT = 0.06;    // ... and flatter than this fraction of its span is ground
export const GROUND_SPAN_M = 40;          // ANY mesh wider than this ...
export const GROUND_FLAT = 0.02;          // ... and flatter than this fraction of its span is ground

export const SKY_NAME_RE = /\b(sky|skydome|skybox|stars|clouds?|sun|moon|atmosphere)\b/i;
export const GROUND_NAME_RE = /\b(ground|terrain|floor|water|ocean|sea|lake|river|plane|sand|grass|land)\b/i;

/**
 * 'sky' | 'ground' | 'content' for one drawable with world box `box`.
 * @param {object} obj           mesh/points/line/sprite (name, parent, userData, material, isInstancedMesh)
 * @param {{min:{x,y,z}, max:{x,y,z}}} box   world-space AABB
 * @param {number} contentSpan   horizontal span of the known content bbox (0 = unknown)
 */
export function classifyBackdrop(obj, box, contentSpan = 0) {
  // Procedural sky volumes may be compact or carry a caller's custom name.
  // Only non-solid drawables can opt in; metadata cannot hide opaque content.
  if (obj.userData?.sceneBackdrop === 'sky' && nonSolid(obj)) return 'sky';
  // Generated scene names normally use PascalCase / snake_case. Word boundaries
  // alone missed PlanetSkyBackdrop and SkyAtmosphereBand0, framing the sky as a
  // building. Keep the same vocabulary and shape rules for every naming style.
  const name = nameText(obj.name || (obj.parent && obj.parent.name) || '');
  const sx = box.max.x - box.min.x, sy = box.max.y - box.min.y, sz = box.max.z - box.min.z;
  const span = Math.max(sx, sz);
  // sunRig's MoonDisc can be only five metres wide in a compact worldShell, but
  // its non-depth-writing light image still must not move the scene's centre.
  if (SKY_NAME_RE.test(name) && (span > SKY_NAMED_SPAN_M || nonSolid(obj))) return 'sky';
  if (span > 2000 || (sy > 300 && span > 300)) return 'sky';
  // a small thing kilometres from the origin is a backdrop whatever it is called: the sun/moon
  // disc `sunRig` parks at 0.9 × the sky radius ('SunDisc' — no word boundary for the regex)
  // blew the content bbox to 2.5 km and put the overview rig 5 km up (measured 2026-09-07)
  const far = Math.max(Math.abs(box.min.x), Math.abs(box.max.x), Math.abs(box.min.y), Math.abs(box.max.y),
                       Math.abs(box.min.z), Math.abs(box.max.z));
  if (far > 1500 && span < 0.1 * far) return 'sky';
  if (obj.isInstancedMesh) return 'content';   // scattered instances span the map but are not ground
  if (span > GROUND_NAMED_SPAN_M && sy < GROUND_NAMED_FLAT * span && GROUND_NAME_RE.test(name)) return 'ground';
  if (span > GROUND_SPAN_M && sy < GROUND_FLAT * span) return 'ground';
  if (contentSpan > 0 && span > 2.5 * contentSpan && sy < 0.1 * span) return 'ground';
  return 'content';
}