MotrixSimWeb/src/preview/UniversalPreviewer.ts
2026-06-25 16:16:01 +08:00

3332 lines
117 KiB
TypeScript

import * as THREE from "three";
import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
import { OBJLoader } from "three/examples/jsm/loaders/OBJLoader.js";
import { STLLoader } from "three/examples/jsm/loaders/STLLoader.js";
import { ConvexGeometry } from "three/examples/jsm/geometries/ConvexGeometry.js";
import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
import type {
BodyState,
MeshGeometry,
PreviewFrame,
PreviewGeometry,
PreviewMaterial,
PreviewObject,
Quat,
RendererStats,
SceneManifest,
Vec3,
} from "../types";
import { CoordinateConverter } from "../utils/coordinates";
const LARGE_SCENE_ROOT_BATCH_SIZE = 24;
const LARGE_SCENE_LOADING_RENDER_INTERVAL_MS = 1000 / 20;
const LARGE_SCENE_MESH_SOURCE_LOAD_LIMIT = 24;
type InteractionMode = "idle" | "inspect" | "hover" | "dragging";
type DomPointerEvent = PointerEvent | MouseEvent;
interface PointerSnapshot {
clientX: number;
clientY: number;
button: number;
pointerId?: number;
}
type PointerLikeEvent = DomPointerEvent | PointerSnapshot;
interface PreviewerOptions {
hoverLabel?: HTMLElement;
}
interface RendererStatsOptions {
samplePixels?: boolean;
}
interface BoundObject {
manifest: PreviewObject;
root: THREE.Object3D;
}
interface InstancedSubmesh {
mesh: THREE.InstancedMesh;
sourceMatrix: THREE.Matrix4;
}
interface InstancedVisualBatch {
key: string;
root: THREE.Group;
capacity: number;
used: number;
submeshes: InstancedSubmesh[];
}
interface InstancedVisualBinding {
batch: InstancedVisualBatch;
index: number;
root: THREE.Object3D;
localMatrix: THREE.Matrix4;
}
interface InstancedVisual {
localMatrix: THREE.Matrix4;
sourceBounds: THREE.Box3;
}
interface PickBoundsTarget {
id: string;
localBounds: THREE.Box3;
worldBounds: THREE.Box3;
}
interface ObjVertexRef {
position: number;
uv?: number;
normal?: number;
}
interface ObjParseState {
sourcePositions: number[];
sourceNormals: number[];
sourceUvs: number[];
positions: number[];
normals: number[];
uvs: number[];
positionCount: number;
sourceNormalCount: number;
sourceUvCount: number;
normalCount: number;
missingNormalCount: number;
uvCount: number;
missingUvCount: number;
faceVertexCount: number;
lineCount: number;
}
interface SceneBuildRoots {
visible: THREE.Object3D[];
instanced: THREE.Object3D[];
}
export interface DragTargetPose {
id: string;
source: [number, number, number];
body?: string;
quat?: Quat;
}
export interface DragPose {
id: string;
source: [number, number, number];
sourceDelta: [number, number, number];
body?: string;
quat?: Quat;
groupId?: string;
targets?: DragTargetPose[];
kind: "prop" | "robot";
start: boolean;
end: boolean;
}
export interface DragOptions {
editableObjectIds: Iterable<string>;
enabled?: boolean;
robotPrefix?: string;
robotId?: string;
onDrag?: (event: DragPose) => void;
}
interface DragState {
kind: "prop" | "robot";
targetId: string;
target: THREE.Object3D;
pointerId?: number;
plane: THREE.Plane;
worldStart: THREE.Vector3;
sourceStart: [number, number, number];
sourceStartById: Map<string, [number, number, number]>;
sourceOffsetStartById: Map<string, [number, number, number]>;
worldStartById: Map<string, THREE.Vector3>;
targetIds: string[];
robotPoseStart: [number, number, number];
}
interface CachedBodyState {
pos?: [number, number, number];
quat?: [number, number, number, number];
}
function isEditingInputTarget(target: EventTarget | null): boolean {
if (!(target instanceof HTMLElement)) {
return false;
}
return target.isContentEditable || ["INPUT", "SELECT", "TEXTAREA"].includes(target.tagName);
}
export class UniversalPreviewer {
readonly renderer: THREE.WebGLRenderer;
readonly scene = new THREE.Scene();
readonly camera = new THREE.PerspectiveCamera(46, 1, 0.05, 500);
readonly controls: OrbitControls;
private readonly root = new THREE.Group();
private readonly environmentTarget: THREE.WebGLRenderTarget;
private readonly materials = new Map<string, THREE.Material>();
private readonly primitiveGeometryCache = new Map<string, THREE.BufferGeometry>();
private readonly gltfLoader = new GLTFLoader();
private readonly objLoader = new OBJLoader();
private readonly stlLoader = new STLLoader();
private readonly meshCache = new Map<string, Promise<THREE.Object3D>>();
private readonly meshSourceBounds = new Map<string, THREE.Box3>();
private readonly cachedMeshSources = new Set<THREE.Object3D>();
private readonly retainedMeshGeometries = new Set<THREE.BufferGeometry>();
private readonly retainedMeshMaterials = new Set<THREE.Material>();
private readonly meshSourceLoadQueue: Array<() => void> = [];
private readonly instancedMeshBatchCapacities = new Map<string, number>();
private readonly instancedMeshBatches = new Map<string, Promise<InstancedVisualBatch>>();
private readonly instancedVisualBindings = new Map<string, InstancedVisualBinding>();
private readonly bodyBindings = new Map<string, BoundObject[]>();
private readonly objectsById = new Map<string, BoundObject>();
private readonly pickBoundsById = new Map<string, PickBoundsTarget>();
private readonly sceneObjectBounds = new THREE.Box3();
private readonly objectBodyIds = new Map<string, string[]>();
private readonly editableGroups = new Map<string, string[]>();
private readonly pickTargets: PickBoundsTarget[] = [];
private readonly editablePickTargets: PickBoundsTarget[] = [];
private readonly spinningObjects: THREE.Object3D[] = [];
private readonly hoverOutlineBounds = new THREE.Box3();
private readonly hoverOutline = new THREE.Box3Helper(this.hoverOutlineBounds, "#38bdf8");
private readonly virtualInstancedRoot = new THREE.Object3D();
private readonly scratchBounds = new THREE.Box3();
private readonly scratchPickWorldBounds = new THREE.Box3();
private readonly scratchPickLocalBounds = new THREE.Box3();
private readonly scratchFitBounds = new THREE.Box3();
private readonly scratchSize = new THREE.Vector3();
private readonly scratchPickPoint = new THREE.Vector3();
private readonly scratchBoundsCorner = new THREE.Vector3();
private readonly scratchPreviousFocusPosition = new THREE.Vector3();
private readonly scratchPreviousFocusQuaternion = new THREE.Quaternion();
private readonly scratchCameraCenter = new THREE.Vector3();
private readonly scratchCameraSize = new THREE.Vector3();
private readonly scratchCameraDirection = new THREE.Vector3();
private readonly scratchPointerWorld = new THREE.Vector3();
private readonly scratchPointerPlaneNormal = new THREE.Vector3();
private readonly scratchPointerPlane = new THREE.Plane();
private readonly scratchDragDelta = new THREE.Vector3();
private readonly scratchBodyPosition = new THREE.Vector3();
private readonly scratchBodyOffset = new THREE.Vector3();
private readonly scratchBodyQuaternion = new THREE.Quaternion();
private readonly scratchScreenPoint = new THREE.Vector3();
private readonly scratchSourcePosition: Vec3 = [0, 0, 0];
private readonly scratchMatrix = new THREE.Matrix4();
private readonly scratchLocalWorldMatrix = new THREE.Matrix4();
private readonly scratchInverseMatrix = new THREE.Matrix4();
private readonly scratchPoseObject = new THREE.Object3D();
private readonly editableObjectIds = new Set<string>();
private readonly clock = new THREE.Clock();
private readonly raycaster = new THREE.Raycaster();
private readonly pointer = new THREE.Vector2();
private dragState: DragState | undefined;
private pendingDragPointer: PointerSnapshot | undefined;
private dragUpdateFrameHandle = 0;
private dragUpdateTimeoutHandle = 0;
private lastDragAppliedAt = 0;
private currentMode: InteractionMode = "idle";
private readonly focusMarker = new THREE.Mesh(
new THREE.RingGeometry(0.7, 1, 48),
new THREE.MeshBasicMaterial({
color: "#38bdf8",
depthTest: false,
opacity: 0.92,
side: THREE.DoubleSide,
transparent: true,
}),
);
private readonly focusMarkerTarget = new THREE.Vector3();
private focusMarkerRadius = 0.2;
private converter = new CoordinateConverter({ up: "Z" });
private manifest?: SceneManifest;
private animationHandle = 0;
private focusMarkerHideHandle = 0;
private frameCount = 0;
private renderSkipCount = 0;
private lastRenderDurationMs = 0;
private readbackRenderCount = 0;
private renderWindowStartedAt = 0;
private renderWindowFrameCount = 0;
private measuredRenderFps = 0;
private sceneLoadTotalMs = 0;
private sceneLoadConfigureMs = 0;
private sceneLoadMaterialsMs = 0;
private sceneLoadHelpersMs = 0;
private sceneLoadObjectsMs = 0;
private sceneLoadEditableRefreshMs = 0;
private sceneLoadCameraFitMs = 0;
private instancedMeshPrewarmCount = 0;
private instancedMeshPrewarmMs = 0;
private instancedMeshFinalizeMs = 0;
private frozenStaticObjectCount = 0;
private preFrozenMeshCloneCount = 0;
private spinningScanSkippedCount = 0;
private instancedMeshObjectCount = 0;
private instancedMeshBatchCount = 0;
private instancedMeshDrawCount = 0;
private instancedMeshMatrixUpdateCount = 0;
private instancedMeshFrustumCulledCount = 0;
private instancedMeshStaticMatrixCount = 0;
private instancedLocalObjectElisionCount = 0;
private virtualInstancedRootCount = 0;
private manualMatrixRootCount = 0;
private manualMatrixUpdateCount = 0;
private releasedGeometryCount = 0;
private releasedMaterialCount = 0;
private releasedTextureCount = 0;
private loadedMeshCount = 0;
private fallbackCount = 0;
private meshSourceLoadLimit = Number.POSITIVE_INFINITY;
private activeMeshSourceLoadCount = 0;
private peakMeshSourceLoadCount = 0;
private queuedMeshSourceLoadCount = 0;
private meshCacheHitCount = 0;
private meshCacheMissCount = 0;
private fastObjParseCount = 0;
private fastObjLineScanCount = 0;
private fastObjStreamChunkCount = 0;
private fastObjStreamByteCount = 0;
private objLoaderFallbackCount = 0;
private sceneObjectBoundsCount = 0;
private fastPickProxyBoundsCount = 0;
private pickBoundsScratchTransformCount = 0;
private hoverProxyBoundsHitCount = 0;
private hoverCachedBoundsHitCount = 0;
private hoverRootBoundsFallbackCount = 0;
private cameraFitTraversalCount = 0;
private dragMoveEventCount = 0;
private dragCoalescedMoveCount = 0;
private dragAppliedMoveCount = 0;
private sceneLoadInProgress = false;
private sceneLoadSuppressedRenderCount = 0;
private sceneBuildYieldCount = 0;
private statePayloadBodyCount = 0;
private mergedBodyStateCount = 0;
private bodyBoundObjectCount = 0;
private groupedObjectCount = 0;
private reducedStateFrameCount = 0;
private incrementalBodyMergeCount = 0;
private batchedSceneRootCount = 0;
private sceneRootBatchCount = 0;
private lastPixelSampleAt = 0;
private lastPixelSamples = 0;
private renderSuspendedUntil = 0;
private renderDirty = true;
private lastRenderAt = 0;
private targetRenderIntervalMs = 0;
private hoverPickIntervalMs = 0;
private lastHoverPickAt = 0;
private largeSceneMode = false;
private loadToken = 0;
private lastFrame?: PreviewFrame;
private robotOffsetPose: [number, number, number] = [0, 0, 0];
private readonly robotBodyNames = new Set<string>();
private readonly robotObjectIds = new Set<string>();
private readonly bodySourceOffsets = new Map<string, [number, number, number]>();
private readonly bodyVisualOffsets = new Map<string, [number, number, number]>();
private readonly bodyStateCache = new Map<string, CachedBodyState>();
private appliedBodyStateCount = 0;
private skippedBodyStateCount = 0;
private unchangedFrameCount = 0;
private hoveredObjectId: string | undefined;
private dragOptions: DragOptions = {
editableObjectIds: [],
enabled: false,
};
private readonly statusElement: HTMLElement;
private readonly hoverLabel: HTMLElement | undefined;
constructor(private readonly container: HTMLElement, statusElement: HTMLElement, options: PreviewerOptions = {}) {
this.statusElement = statusElement;
this.hoverLabel = options.hoverLabel;
this.renderer = new THREE.WebGLRenderer({
antialias: true,
alpha: false,
powerPreference: "high-performance",
preserveDrawingBuffer: false,
});
this.renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
this.renderer.outputColorSpace = THREE.SRGBColorSpace;
this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
this.renderer.toneMappingExposure = 1.05;
this.renderer.shadowMap.enabled = true;
this.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
this.renderer.domElement.className = "preview-canvas";
this.container.appendChild(this.renderer.domElement);
this.scene.background = new THREE.Color("#0f172a");
const environmentGenerator = new THREE.PMREMGenerator(this.renderer);
this.environmentTarget = environmentGenerator.fromScene(new RoomEnvironment(), 0.04);
this.scene.environment = this.environmentTarget.texture;
environmentGenerator.dispose();
this.scene.add(this.root);
this.virtualInstancedRoot.name = "virtual_instanced_root";
this.virtualInstancedRoot.matrixAutoUpdate = false;
this.virtualInstancedRoot.updateMatrixWorld(true);
this.focusMarker.visible = false;
this.focusMarker.renderOrder = 50;
this.scene.add(this.focusMarker);
this.hoverOutline.visible = false;
this.hoverOutline.renderOrder = 52;
(this.hoverOutline.material as THREE.LineBasicMaterial).depthTest = false;
this.scene.add(this.hoverOutline);
this.controls = new OrbitControls(this.camera, this.renderer.domElement);
this.controls.enableDamping = true;
this.controls.dampingFactor = 0.08;
this.controls.mouseButtons = {
LEFT: THREE.MOUSE.ROTATE,
MIDDLE: THREE.MOUSE.DOLLY,
RIGHT: THREE.MOUSE.PAN,
};
this.controls.touches = {
ONE: THREE.TOUCH.ROTATE,
TWO: THREE.TOUCH.DOLLY_PAN,
};
this.controls.screenSpacePanning = true;
this.controls.target.set(0, 1, 0);
this.camera.position.set(5.5, 4.6, 7.2);
this.setupCameraInput();
this.resize();
window.addEventListener("resize", () => this.resize());
this.renderWindowStartedAt = performance.now();
this.animate();
}
async loadManifest(manifest: SceneManifest): Promise<void> {
const loadStartedAt = performance.now();
const token = this.loadToken + 1;
this.loadToken = token;
this.manifest = manifest;
this.converter = new CoordinateConverter(manifest.coordinateSystem);
this.resetSceneLoadTimings();
const configureStartedAt = performance.now();
this.configurePerformanceForManifest(manifest);
this.sceneLoadConfigureMs = performance.now() - configureStartedAt;
this.sceneLoadInProgress = true;
this.clearScene();
try {
const materialsStartedAt = performance.now();
this.buildMaterials(manifest.materials ?? []);
this.sceneLoadMaterialsMs = performance.now() - materialsStartedAt;
const helpersStartedAt = performance.now();
this.prepareInstancedMeshBatchCapacities(manifest.objects);
this.addDefaultHelpers();
this.addLights(manifest);
this.applyCamera(manifest);
this.sceneLoadHelpersMs = performance.now() - helpersStartedAt;
const objectsStartedAt = performance.now();
await this.addObjects(manifest.objects, token);
this.sceneLoadObjectsMs = performance.now() - objectsStartedAt;
if (token !== this.loadToken) {
return;
}
const editableStartedAt = performance.now();
this.refreshEditableObjectIds();
this.sceneLoadEditableRefreshMs = performance.now() - editableStartedAt;
const cameraFitStartedAt = performance.now();
this.fitCameraToObjects();
this.sceneLoadCameraFitMs = performance.now() - cameraFitStartedAt;
this.sceneLoadTotalMs = performance.now() - loadStartedAt;
this.updateStatus(`manifest loaded: ${manifest.objects.length} objects`);
} finally {
if (token === this.loadToken) {
this.sceneLoadInProgress = false;
this.markRenderDirty();
}
}
}
applyFrame(frame: PreviewFrame): void {
const previousFrame = this.lastFrame;
const bodies = frame.bodies;
let statePayloadBodyCount = 0;
let mergedBodies = previousFrame?.bodies;
let mergedBodyStateCount = this.mergedBodyStateCount;
if (bodies) {
if (!mergedBodies) {
mergedBodies = {};
mergedBodyStateCount = 0;
}
for (const bodyName in bodies) {
const bodyState = bodies[bodyName];
if (!bodyState) {
continue;
}
statePayloadBodyCount += 1;
if (!Object.prototype.hasOwnProperty.call(mergedBodies, bodyName)) {
mergedBodyStateCount += 1;
}
mergedBodies[bodyName] = bodyState;
}
this.incrementalBodyMergeCount += 1;
}
const metadataChanged = (frame.step !== undefined && frame.step !== previousFrame?.step)
|| (frame.paused !== undefined && frame.paused !== previousFrame?.paused)
|| (frame.running !== undefined && frame.running !== previousFrame?.running);
this.lastFrame = {
...(previousFrame ?? {}),
...frame,
bodies: mergedBodies,
joints: frame.joints ?? previousFrame?.joints,
actuators: frame.actuators ?? previousFrame?.actuators,
};
let changed = false;
let appliedBodyStateCount = 0;
let skippedBodyStateCount = 0;
if (bodies) {
for (const bodyName in bodies) {
const bodyState = bodies[bodyName];
if (!bodyState) {
continue;
}
const bound = this.bodyBindings.get(bodyName);
if (!bound) {
continue;
}
if (this.shouldSkipFixedBodyState(bodyName, bound)) {
this.cacheBodyState(bodyName, bodyState);
skippedBodyStateCount += bound.length;
continue;
}
if (this.isCachedBodyStateUnchanged(bodyName, bodyState)) {
skippedBodyStateCount += bound.length;
continue;
}
this.cacheBodyState(bodyName, bodyState);
for (const item of bound) {
const itemChanged = this.applyBodyState(item.root, bodyName, bodyState);
if (itemChanged) {
this.updatePickTargetBounds(item.manifest.id);
this.updateInstancedVisualMatrix(item.manifest.id);
}
changed = itemChanged || changed;
appliedBodyStateCount += 1;
}
}
}
if (bodies) {
this.appliedBodyStateCount = appliedBodyStateCount;
this.skippedBodyStateCount = skippedBodyStateCount;
this.statePayloadBodyCount = statePayloadBodyCount;
this.mergedBodyStateCount = mergedBodyStateCount;
if (statePayloadBodyCount > 0 && statePayloadBodyCount < mergedBodyStateCount) {
this.reducedStateFrameCount += 1;
}
}
if (changed || metadataChanged) {
this.markRenderDirty();
} else {
this.unchangedFrameCount += 1;
}
}
private shouldSkipFixedBodyState(bodyName: string, bound: BoundObject[]): boolean {
return !this.robotBodyNames.has(bodyName)
&& !this.bodyVisualOffsets.has(bodyName)
&& bound.length > 0
&& bound.every((item) => item.manifest.physics === "fixed");
}
setDragOptions(options: DragOptions): void {
this.dragOptions = {
editableObjectIds: options.editableObjectIds,
enabled: options.enabled ?? this.dragOptions.enabled,
robotPrefix: options.robotPrefix,
robotId: options.robotId,
onDrag: options.onDrag,
};
this.refreshEditableObjectIds();
}
setDragEnabled(enabled: boolean): void {
this.dragOptions = {
...this.dragOptions,
enabled,
};
if (!enabled && this.currentMode !== "dragging") {
this.setInteractionMode("idle");
}
}
clearBodyVisualOffset(bodyName?: string): void {
if (!bodyName) {
this.bodyVisualOffsets.clear();
this.bodyStateCache.clear();
return;
}
this.bodyVisualOffsets.delete(bodyName);
this.bodyStateCache.delete(bodyName);
}
setRobotPose(pose: [number, number, number]): void {
this.robotOffsetPose[0] = pose[0];
this.robotOffsetPose[1] = pose[1];
this.robotOffsetPose[2] = pose[2];
for (const bodyName of this.robotBodyNames) {
this.bodyStateCache.delete(bodyName);
}
this.applyRobotPoseOffset();
this.markRenderDirty();
}
private refreshEditableObjectIds(): void {
this.editableObjectIds.clear();
for (const item of this.dragOptions.editableObjectIds) {
this.editableObjectIds.add(item);
}
this.robotObjectIds.clear();
if (this.dragOptions.robotPrefix) {
for (const id of this.objectsById.keys()) {
if (this.isRobotManifestObject(id)) {
this.robotObjectIds.add(id);
}
}
}
this.robotBodyNames.clear();
if (this.dragOptions.robotPrefix) {
for (const object of this.objectsById.values()) {
if (object.manifest.body && this.isRobotManifestObject(object.manifest.id)) {
this.robotBodyNames.add(object.manifest.body);
}
}
}
this.refreshEditablePickTargets();
}
getStats(options: RendererStatsOptions = {}): RendererStats {
return {
manifestName: this.manifest?.name ?? "none",
objectCount: this.manifest?.objects.length ?? 0,
bodyBoundObjectCount: this.bodyBoundObjectCount,
largeSceneMode: this.largeSceneMode,
targetRenderFps: this.targetRenderIntervalMs > 0 ? Math.round(1000 / this.targetRenderIntervalMs) : 60,
actualRenderFps: this.measuredRenderFps,
renderPixelRatio: this.renderer.getPixelRatio(),
preserveDrawingBufferEnabled: this.renderer.getContext().getContextAttributes()?.preserveDrawingBuffer === true,
shadowsEnabled: this.renderer.shadowMap.enabled,
renderSkipCount: this.renderSkipCount,
lastRenderDurationMs: this.lastRenderDurationMs,
readbackRenderCount: this.readbackRenderCount,
hoverPickIntervalMs: this.hoverPickIntervalMs,
sceneLoadTotalMs: this.sceneLoadTotalMs,
sceneLoadConfigureMs: this.sceneLoadConfigureMs,
sceneLoadMaterialsMs: this.sceneLoadMaterialsMs,
sceneLoadHelpersMs: this.sceneLoadHelpersMs,
sceneLoadObjectsMs: this.sceneLoadObjectsMs,
sceneLoadEditableRefreshMs: this.sceneLoadEditableRefreshMs,
sceneLoadCameraFitMs: this.sceneLoadCameraFitMs,
instancedMeshPrewarmCount: this.instancedMeshPrewarmCount,
instancedMeshPrewarmMs: this.instancedMeshPrewarmMs,
instancedMeshFinalizeMs: this.instancedMeshFinalizeMs,
frozenStaticObjectCount: this.frozenStaticObjectCount,
preFrozenMeshCloneCount: this.preFrozenMeshCloneCount,
spinningScanSkippedCount: this.spinningScanSkippedCount,
instancedMeshObjectCount: this.instancedMeshObjectCount,
instancedMeshBatchCount: this.instancedMeshBatchCount,
instancedMeshDrawCount: this.instancedMeshDrawCount,
instancedMeshMatrixUpdateCount: this.instancedMeshMatrixUpdateCount,
instancedMeshFrustumCulledCount: this.instancedMeshFrustumCulledCount,
instancedMeshStaticMatrixCount: this.instancedMeshStaticMatrixCount,
instancedLocalObjectElisionCount: this.instancedLocalObjectElisionCount,
virtualInstancedRootCount: this.virtualInstancedRootCount,
manualMatrixRootCount: this.manualMatrixRootCount,
manualMatrixUpdateCount: this.manualMatrixUpdateCount,
primitiveGeometryCount: this.primitiveGeometryCache.size,
pickProxyCount: this.pickBoundsById.size,
hoverPickTargetCount: this.pickTargets.length,
appliedBodyStateCount: this.appliedBodyStateCount,
skippedBodyStateCount: this.skippedBodyStateCount,
unchangedFrameCount: this.unchangedFrameCount,
dragMoveEventCount: this.dragMoveEventCount,
dragCoalescedMoveCount: this.dragCoalescedMoveCount,
dragAppliedMoveCount: this.dragAppliedMoveCount,
releasedGeometryCount: this.releasedGeometryCount,
releasedMaterialCount: this.releasedMaterialCount,
releasedTextureCount: this.releasedTextureCount,
loadedMeshCount: this.loadedMeshCount,
fallbackCount: this.fallbackCount,
meshSourceLoadLimit: Number.isFinite(this.meshSourceLoadLimit) ? this.meshSourceLoadLimit : 0,
activeMeshSourceLoadCount: this.activeMeshSourceLoadCount,
peakMeshSourceLoadCount: this.peakMeshSourceLoadCount,
queuedMeshSourceLoadCount: this.queuedMeshSourceLoadCount,
meshCacheSourceCount: this.meshCache.size,
meshCacheHitCount: this.meshCacheHitCount,
meshCacheMissCount: this.meshCacheMissCount,
fastObjParseCount: this.fastObjParseCount,
fastObjLineScanCount: this.fastObjLineScanCount,
fastObjStreamChunkCount: this.fastObjStreamChunkCount,
fastObjStreamByteCount: this.fastObjStreamByteCount,
objLoaderFallbackCount: this.objLoaderFallbackCount,
retainedMeshGeometryCount: this.retainedMeshGeometries.size,
retainedMeshMaterialCount: this.retainedMeshMaterials.size,
sceneObjectBoundsCount: this.sceneObjectBoundsCount,
fastPickProxyBoundsCount: this.fastPickProxyBoundsCount,
pickBoundsScratchTransformCount: this.pickBoundsScratchTransformCount,
meshSourceBoundsCount: this.meshSourceBounds.size,
hoverProxyBoundsHitCount: this.hoverProxyBoundsHitCount,
hoverCachedBoundsHitCount: this.hoverCachedBoundsHitCount,
hoverRootBoundsFallbackCount: this.hoverRootBoundsFallbackCount,
cameraFitTraversalCount: this.cameraFitTraversalCount,
sceneLoadSuppressedRenderCount: this.sceneLoadSuppressedRenderCount,
sceneBuildYieldCount: this.sceneBuildYieldCount,
statePayloadBodyCount: this.statePayloadBodyCount,
mergedBodyStateCount: this.mergedBodyStateCount,
reducedStateFrameCount: this.reducedStateFrameCount,
incrementalBodyMergeCount: this.incrementalBodyMergeCount,
batchedSceneRootCount: this.batchedSceneRootCount,
sceneRootBatchCount: this.sceneRootBatchCount,
editableGroupCount: this.editableGroups.size,
groupedObjectCount: this.groupedObjectCount,
frameCount: this.frameCount,
lastStep: this.lastFrame?.step,
lastBodyCount: this.lastFrame?.bodies ? this.mergedBodyStateCount : 0,
paused: this.lastFrame?.paused,
running: this.lastFrame?.running,
nonBackgroundPixelSamples: options.samplePixels ? this.cachedCanvasPixelSamples() : this.lastPixelSamples,
};
}
objectScreenPoint(idOrBody: string): { x: number; y: number; visible: boolean } | undefined {
const objectId = this.resolveObjectIdOrBody(idOrBody);
const target = objectId ? this.pickBoundsById.get(objectId) : undefined;
const bound = objectId ? this.objectsById.get(objectId) : undefined;
if (!target || !bound || target.worldBounds.isEmpty()) {
return undefined;
}
target.worldBounds.getCenter(this.scratchScreenPoint);
this.scratchScreenPoint.project(this.camera);
const rect = this.renderer.domElement.getBoundingClientRect();
return {
x: rect.left + ((this.scratchScreenPoint.x + 1) / 2) * rect.width,
y: rect.top + ((1 - this.scratchScreenPoint.y) / 2) * rect.height,
visible: this.scratchScreenPoint.z >= -1 && this.scratchScreenPoint.z <= 1,
};
}
refitCamera(): void {
this.fitCameraToObjects();
}
capturePng(): string {
this.renderForReadback();
return this.renderer.domElement.toDataURL("image/png");
}
sampleCanvasPixels(): number {
this.renderForReadback();
const gl = this.renderer.getContext();
const canvas = this.renderer.domElement;
const width = canvas.width;
const height = canvas.height;
if (width === 0 || height === 0) {
return 0;
}
const points: [number, number][] = [];
for (let y = 0.2; y <= 0.85; y += 0.13) {
for (let x = 0.18; x <= 0.85; x += 0.13) {
points.push([x, y]);
}
}
const background = new THREE.Color(this.scene.background as THREE.Color);
const bg = [
Math.round(background.r * 255),
Math.round(background.g * 255),
Math.round(background.b * 255),
];
let nonBackground = 0;
const pixel = new Uint8Array(4);
for (const [px, py] of points) {
gl.readPixels(Math.floor(width * px), Math.floor(height * py), 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
const delta = Math.abs(pixel[0] - bg[0]) + Math.abs(pixel[1] - bg[1]) + Math.abs(pixel[2] - bg[2]);
if (delta > 24) {
nonBackground += 1;
}
}
return nonBackground;
}
private cachedCanvasPixelSamples(): number {
if (this.lastPixelSamples > 0) {
return this.lastPixelSamples;
}
const now = performance.now();
if (this.lastPixelSampleAt > 0 && now - this.lastPixelSampleAt < 2000) {
return this.lastPixelSamples;
}
this.lastPixelSamples = this.sampleCanvasPixels();
this.lastPixelSampleAt = now;
return this.lastPixelSamples;
}
dispose(): void {
cancelAnimationFrame(this.animationHandle);
this.cancelPendingDragUpdate();
this.disposeSceneGraphResources(this.root);
this.root.clear();
this.environmentTarget.dispose();
this.disposeMaterials();
this.disposeCachedMeshSources();
for (const geometry of this.primitiveGeometryCache.values()) {
geometry.dispose();
}
this.primitiveGeometryCache.clear();
this.renderer.dispose();
this.controls.dispose();
}
private markRenderDirty(): void {
this.renderDirty = true;
}
private configurePerformanceForManifest(manifest: SceneManifest): void {
this.largeSceneMode = manifest.objects.length > 300;
this.targetRenderIntervalMs = this.largeSceneMode ? 1000 / 45 : 0;
this.hoverPickIntervalMs = this.largeSceneMode ? 32 : 0;
this.meshSourceLoadLimit = this.largeSceneMode ? LARGE_SCENE_MESH_SOURCE_LOAD_LIMIT : Number.POSITIVE_INFINITY;
const pixelRatioCap = this.largeSceneMode ? 1 : 2;
this.renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, pixelRatioCap));
this.renderer.shadowMap.enabled = !this.largeSceneMode;
this.resize();
this.markRenderDirty();
}
private resetSceneLoadTimings(): void {
this.sceneLoadTotalMs = 0;
this.sceneLoadConfigureMs = 0;
this.sceneLoadMaterialsMs = 0;
this.sceneLoadHelpersMs = 0;
this.sceneLoadObjectsMs = 0;
this.sceneLoadEditableRefreshMs = 0;
this.sceneLoadCameraFitMs = 0;
this.instancedMeshPrewarmCount = 0;
this.instancedMeshPrewarmMs = 0;
this.instancedMeshFinalizeMs = 0;
this.peakMeshSourceLoadCount = this.activeMeshSourceLoadCount;
this.queuedMeshSourceLoadCount = 0;
}
suspendRendering(durationMs: number): void {
this.renderSuspendedUntil = Math.max(this.renderSuspendedUntil, performance.now() + durationMs);
}
resumeRendering(): void {
this.renderSuspendedUntil = 0;
this.markRenderDirty();
}
private animate = (): void => {
this.animationHandle = requestAnimationFrame(this.animate);
const now = performance.now();
if (this.sceneLoadInProgress && !this.renderDirty) {
this.sceneLoadSuppressedRenderCount += 1;
return;
}
if (now < this.renderSuspendedUntil) {
return;
}
const controlsChanged = this.controls.update();
const focusChanged = this.updateFocusMarker();
const spinChanged = this.updateSpinningObjects(this.clock.getElapsedTime());
const renderIntervalMs = this.sceneLoadInProgress
? Math.max(this.targetRenderIntervalMs, LARGE_SCENE_LOADING_RENDER_INTERVAL_MS)
: this.targetRenderIntervalMs;
const enoughTimeElapsed = renderIntervalMs <= 0 || now - this.lastRenderAt >= renderIntervalMs;
if (!enoughTimeElapsed || (!this.renderDirty && !controlsChanged && !focusChanged && !spinChanged)) {
this.renderSkipCount += 1;
return;
}
this.frameCount += 1;
this.lastRenderAt = now;
this.renderDirty = false;
const renderStartedAt = performance.now();
this.renderer.render(this.scene, this.camera);
this.lastRenderDurationMs = performance.now() - renderStartedAt;
this.updateRenderFps(performance.now());
};
private renderForReadback(): void {
const renderStartedAt = performance.now();
this.renderer.render(this.scene, this.camera);
const now = performance.now();
this.lastRenderDurationMs = now - renderStartedAt;
this.lastRenderAt = now;
this.renderDirty = false;
this.readbackRenderCount += 1;
}
private updateSpinningObjects(elapsed: number): boolean {
if (this.spinningObjects.length === 0) {
return false;
}
for (const object of this.spinningObjects) {
object.rotation.y = elapsed * 0.6;
}
return true;
}
private updateRenderFps(now: number): void {
this.renderWindowFrameCount += 1;
const elapsedMs = now - this.renderWindowStartedAt;
if (elapsedMs < 1000) {
return;
}
this.measuredRenderFps = (this.renderWindowFrameCount * 1000) / elapsedMs;
this.renderWindowFrameCount = 0;
this.renderWindowStartedAt = now;
}
private setupCameraInput(): void {
const canvas = this.renderer.domElement;
canvas.addEventListener("contextmenu", (event) => event.preventDefault());
const isPrimaryButton = (event: DomPointerEvent): boolean => event.button === 0;
const startDragByEvent = (event: DomPointerEvent): void => {
if (!isPrimaryButton(event) || isEditingInputTarget(event.target)) {
return;
}
if (this.startDrag(event)) {
event.preventDefault();
event.stopImmediatePropagation();
}
};
const updateDragByEvent = (event: DomPointerEvent): void => {
if (!this.dragState) {
this.updateDragHoverTarget(event);
return;
}
this.queueDragTargetUpdate(event);
event.preventDefault();
};
const endDragByEvent = (event: DomPointerEvent): void => {
const activePointerId = this.getPointerId(event);
if (!this.dragState) {
return;
}
if (this.dragState.pointerId === undefined || activePointerId === undefined || this.dragState.pointerId === activePointerId) {
this.finishDrag(event);
event.preventDefault();
event.stopImmediatePropagation();
}
};
const isCanvasEventFromTarget = (target: EventTarget | null): boolean => this.isCanvasEvent(target);
if (typeof window.PointerEvent === "undefined") {
window.addEventListener(
"mousedown",
(event) => {
if (this.currentMode === "dragging") {
return;
}
if (!isCanvasEventFromTarget(event.target)) {
return;
}
startDragByEvent(event);
},
{ capture: true, passive: false },
);
canvas.addEventListener("mousedown", startDragByEvent, {
capture: true,
passive: false,
});
canvas.addEventListener("mousemove", updateDragByEvent, {
capture: true,
passive: false,
});
canvas.addEventListener("mouseup", endDragByEvent, {
capture: true,
passive: false,
});
canvas.addEventListener("mouseout", () => {
if (!this.dragState) {
this.setInteractionMode("idle");
this.focusMarker.visible = false;
this.hideHoverOutline();
this.updateHoverLabel(undefined);
this.hoveredObjectId = undefined;
}
}, { capture: true });
window.addEventListener("mouseup", (event) => {
if (!this.dragState || this.currentMode !== "dragging") {
return;
}
endDragByEvent(event);
this.hideFocusMarkerSoon();
});
return;
}
window.addEventListener(
"pointerdown",
(event) => {
if (this.currentMode === "dragging") {
return;
}
if (!this.isCanvasEvent(event.target)) {
return;
}
startDragByEvent(event);
},
{ capture: true, passive: false },
);
canvas.addEventListener("pointerdown", startDragByEvent, {
capture: true,
passive: false,
});
canvas.addEventListener(
"pointermove",
updateDragByEvent,
{ capture: true, passive: false },
);
canvas.addEventListener(
"pointerup",
endDragByEvent,
{ capture: true, passive: false },
);
canvas.addEventListener(
"pointerleave",
() => {
if (!this.dragState) {
this.setInteractionMode("idle");
this.focusMarker.visible = false;
this.hideHoverOutline();
this.updateHoverLabel(undefined);
this.hoveredObjectId = undefined;
}
},
{ capture: true },
);
canvas.addEventListener(
"pointercancel",
(event) => {
const pointerId = this.getPointerId(event);
if (this.dragState?.pointerId === undefined || this.dragState?.pointerId === pointerId) {
this.cancelDrag();
this.setInteractionMode("idle");
}
},
{ capture: true },
);
window.addEventListener("pointerup", (event) => {
if (!this.dragState || this.currentMode !== "dragging") {
return;
}
const activePointerId = this.getPointerId(event);
if (this.dragState.pointerId === undefined || this.dragState.pointerId === activePointerId) {
endDragByEvent(event);
this.hideFocusMarkerSoon();
}
});
window.addEventListener("blur", () => {
this.cancelDrag();
this.setInteractionMode("idle");
this.hideFocusMarkerSoon();
});
}
private getPointerId(event: PointerLikeEvent): number | undefined {
return typeof (event as PointerEvent).pointerId === "number" ? (event as PointerEvent).pointerId : undefined;
}
private isCanvasEvent(target: EventTarget | null): boolean {
if (!(target instanceof Node)) {
return false;
}
return this.renderer.domElement === target || this.renderer.domElement.contains(target);
}
private setInteractionMode(mode: InteractionMode): void {
this.currentMode = mode;
const canvas = this.renderer.domElement;
canvas.classList.toggle("inspect-hover", mode === "inspect");
canvas.classList.toggle("draggable-hover", mode === "hover");
canvas.classList.toggle("dragging", mode === "dragging");
if (mode === "dragging") {
canvas.style.cursor = "grabbing";
return;
}
if (mode === "hover") {
canvas.style.cursor = "grab";
return;
}
if (mode === "inspect") {
canvas.style.cursor = "";
return;
}
if (mode === "idle") {
canvas.style.cursor = "";
return;
}
}
private showHoverOutlineAtBounds(bounds: THREE.Box3, colorHex: string): void {
this.hoverOutlineBounds.copy(bounds);
(this.hoverOutline.material as THREE.LineBasicMaterial).color.set(colorHex);
this.hoverOutline.visible = true;
this.markRenderDirty();
}
private hideHoverOutline(): void {
if (!this.hoverOutline.visible) {
return;
}
this.hoverOutline.visible = false;
this.markRenderDirty();
}
private updateHoverLabel(
id: string | undefined,
bound?: BoundObject,
editable = false,
disabledReason?: string,
): void {
if (!this.hoverLabel) {
return;
}
if (!id || !bound) {
this.hoverLabel.textContent = "";
this.hoverLabel.removeAttribute("title");
return;
}
const name = bound.manifest.name && bound.manifest.name !== id ? `${id} · ${bound.manifest.name}` : id;
this.hoverLabel.textContent = `${disabledReason ?? (editable ? "可拖拽" : "非可拖拽")}: ${name}`;
this.hoverLabel.title = name;
}
private showFocusAtBounds(bounds: THREE.Box3, target: THREE.Object3D, colorHex: string, radiusScale = 1): void {
if (bounds.isEmpty()) {
target.getWorldPosition(this.focusMarkerTarget);
this.focusMarkerRadius = 0.12 * radiusScale;
} else {
bounds.getCenter(this.focusMarkerTarget);
bounds.getSize(this.scratchSize);
this.focusMarkerRadius = Math.max(
0.08,
Math.max(this.scratchSize.x, this.scratchSize.y, this.scratchSize.z) * 0.5 * radiusScale,
);
}
this.focusMarker.visible = true;
(this.focusMarker.material as THREE.MeshBasicMaterial).color.set(colorHex);
window.clearTimeout(this.focusMarkerHideHandle);
this.markRenderDirty();
}
private showFocusAndOutlineForObject(id: string, root: THREE.Object3D, colorHex: string, radiusScale = 1): void {
const bounds = this.cachedInteractionBounds(id, root);
this.showFocusAtBounds(bounds, root, colorHex, radiusScale);
this.showHoverOutlineAtBounds(bounds, colorHex);
}
private cachedInteractionBounds(id: string, root: THREE.Object3D): THREE.Box3 {
const target = this.pickBoundsById.get(id);
if (target && !target.worldBounds.isEmpty()) {
this.hoverCachedBoundsHitCount += 1;
return this.scratchBounds.copy(target.worldBounds);
}
this.hoverRootBoundsFallbackCount += 1;
return this.scratchBounds.setFromObject(root);
}
private setHoverFromPick(
pick: { id: string; bound: BoundObject; editable: boolean; disabledReason?: string } | undefined,
): void {
if (!pick) {
if (this.currentMode !== "dragging") {
this.setInteractionMode("idle");
this.focusMarker.visible = false;
this.hideHoverOutline();
this.updateHoverLabel(undefined);
}
this.hoveredObjectId = undefined;
return;
}
if (this.hoveredObjectId !== pick.id) {
this.hoveredObjectId = pick.id;
if (this.pickBoundsById.has(pick.id)) {
this.hoverProxyBoundsHitCount += 1;
}
const color = pick.editable ? "#38bdf8" : "#f59e0b";
this.showFocusAndOutlineForObject(pick.id, pick.bound.root, color, 1.05);
this.setInteractionMode(pick.editable ? "hover" : "inspect");
}
this.updateHoverLabel(pick.id, pick.bound, pick.editable, pick.disabledReason);
}
private updateDragHoverTarget(event: PointerLikeEvent): void {
if (this.currentMode === "dragging") {
return;
}
const now = performance.now();
if (this.hoverPickIntervalMs > 0 && now - this.lastHoverPickAt < this.hoverPickIntervalMs) {
return;
}
this.lastHoverPickAt = now;
const pick = this.pickAnyObject(event);
this.setHoverFromPick(pick);
}
private showFocusMarker(): void {
window.clearTimeout(this.focusMarkerHideHandle);
if (this.currentMode !== "idle") {
return;
}
this.focusMarker.visible = true;
}
private hideFocusMarkerSoon(): void {
window.clearTimeout(this.focusMarkerHideHandle);
this.focusMarkerHideHandle = window.setTimeout(() => {
this.focusMarker.visible = false;
this.setInteractionMode("idle");
this.markRenderDirty();
}, 650);
}
private updateFocusMarker(): boolean {
if (!this.focusMarker.visible) {
return false;
}
this.scratchPreviousFocusPosition.copy(this.focusMarker.position);
this.scratchPreviousFocusQuaternion.copy(this.focusMarker.quaternion);
const previousScale = this.focusMarker.scale.x;
this.focusMarker.position.copy(this.focusMarkerTarget);
this.focusMarker.quaternion.copy(this.camera.quaternion);
const distance = this.camera.position.distanceTo(this.focusMarker.position);
const scale = Math.max(0.06, distance * 0.12 * this.focusMarkerRadius);
this.focusMarker.scale.setScalar(scale);
return this.scratchPreviousFocusPosition.distanceToSquared(this.focusMarker.position) > 1e-10
|| Math.abs(this.scratchPreviousFocusQuaternion.dot(this.focusMarker.quaternion)) < 0.999999
|| Math.abs(previousScale - scale) > 1e-6;
}
private resize(): void {
const width = Math.max(320, this.container.clientWidth);
const height = Math.max(320, this.container.clientHeight);
this.camera.aspect = width / height;
this.camera.updateProjectionMatrix();
this.renderer.setSize(width, height, false);
this.markRenderDirty();
}
private clearScene(): void {
this.disposeSceneGraphResources(this.root);
this.root.clear();
this.disposeMaterials();
this.bodyBindings.clear();
this.objectsById.clear();
this.pickBoundsById.clear();
this.objectBodyIds.clear();
this.editableGroups.clear();
this.pickTargets.length = 0;
this.editablePickTargets.length = 0;
this.spinningObjects.length = 0;
this.bodySourceOffsets.clear();
this.bodyVisualOffsets.clear();
this.bodyStateCache.clear();
this.instancedMeshBatches.clear();
this.instancedMeshBatchCapacities.clear();
this.instancedVisualBindings.clear();
this.robotObjectIds.clear();
this.robotBodyNames.clear();
this.cancelDrag();
this.hoveredObjectId = undefined;
this.hideHoverOutline();
this.updateHoverLabel(undefined);
this.loadedMeshCount = 0;
this.fallbackCount = 0;
this.lastFrame = undefined;
this.frameCount = 0;
this.appliedBodyStateCount = 0;
this.skippedBodyStateCount = 0;
this.unchangedFrameCount = 0;
this.renderSkipCount = 0;
this.lastRenderDurationMs = 0;
this.readbackRenderCount = 0;
this.measuredRenderFps = 0;
this.frozenStaticObjectCount = 0;
this.preFrozenMeshCloneCount = 0;
this.spinningScanSkippedCount = 0;
this.instancedMeshObjectCount = 0;
this.instancedMeshBatchCount = 0;
this.instancedMeshDrawCount = 0;
this.instancedMeshMatrixUpdateCount = 0;
this.instancedMeshFrustumCulledCount = 0;
this.instancedMeshStaticMatrixCount = 0;
this.instancedLocalObjectElisionCount = 0;
this.virtualInstancedRootCount = 0;
this.manualMatrixRootCount = 0;
this.manualMatrixUpdateCount = 0;
this.fastObjParseCount = 0;
this.fastObjLineScanCount = 0;
this.fastObjStreamChunkCount = 0;
this.fastObjStreamByteCount = 0;
this.objLoaderFallbackCount = 0;
this.sceneObjectBounds.makeEmpty();
this.sceneObjectBoundsCount = 0;
this.fastPickProxyBoundsCount = 0;
this.pickBoundsScratchTransformCount = 0;
this.hoverProxyBoundsHitCount = 0;
this.hoverCachedBoundsHitCount = 0;
this.hoverRootBoundsFallbackCount = 0;
this.cameraFitTraversalCount = 0;
this.sceneLoadSuppressedRenderCount = 0;
this.sceneBuildYieldCount = 0;
this.statePayloadBodyCount = 0;
this.mergedBodyStateCount = 0;
this.bodyBoundObjectCount = 0;
this.groupedObjectCount = 0;
this.reducedStateFrameCount = 0;
this.incrementalBodyMergeCount = 0;
this.batchedSceneRootCount = 0;
this.sceneRootBatchCount = 0;
this.renderWindowFrameCount = 0;
this.renderWindowStartedAt = performance.now();
this.lastPixelSampleAt = 0;
this.lastPixelSamples = 0;
this.markRenderDirty();
}
private disposeSceneGraphResources(root: THREE.Object3D, options: { disposeRetainedMeshResources?: boolean } = {}): void {
const cachedPrimitiveGeometries = new Set(this.primitiveGeometryCache.values());
const ownedMaterials = new Set(this.materials.values());
const disposedGeometries = new Set<THREE.BufferGeometry>();
const disposedMaterials = new Set<THREE.Material>();
const disposedTextures = new Set<THREE.Texture>();
root.traverse((child) => {
if (child.userData.pickProxy === true) {
return;
}
const renderable = child as THREE.Object3D & {
geometry?: THREE.BufferGeometry;
material?: THREE.Material | THREE.Material[];
};
const geometry = renderable.geometry;
const geometryIsRetained = geometry instanceof THREE.BufferGeometry && this.retainedMeshGeometries.has(geometry);
if (
geometry instanceof THREE.BufferGeometry
&& !cachedPrimitiveGeometries.has(geometry)
&& (!geometryIsRetained || options.disposeRetainedMeshResources)
&& !disposedGeometries.has(geometry)
) {
geometry.dispose();
disposedGeometries.add(geometry);
this.releasedGeometryCount += 1;
}
if (!renderable.material) {
return;
}
for (const material of this.materialList(renderable.material)) {
const materialIsRetained = this.retainedMeshMaterials.has(material);
if (
!ownedMaterials.has(material)
&& (!materialIsRetained || options.disposeRetainedMeshResources)
&& !disposedMaterials.has(material)
) {
this.disposeMaterial(material, disposedTextures);
disposedMaterials.add(material);
}
}
});
}
private disposeMaterials(): void {
const disposedTextures = new Set<THREE.Texture>();
for (const material of this.materials.values()) {
if (!this.retainedMeshMaterials.has(material)) {
this.disposeMaterial(material, disposedTextures);
}
}
this.materials.clear();
}
private disposeCachedMeshSources(): void {
for (const source of this.cachedMeshSources) {
this.disposeSceneGraphResources(source, { disposeRetainedMeshResources: true });
}
this.meshCache.clear();
this.meshSourceBounds.clear();
this.cachedMeshSources.clear();
this.retainedMeshGeometries.clear();
this.retainedMeshMaterials.clear();
this.instancedMeshBatches.clear();
this.instancedMeshBatchCapacities.clear();
this.instancedVisualBindings.clear();
}
private disposeMaterial(material: THREE.Material, disposedTextures: Set<THREE.Texture>): void {
for (const texture of this.materialTextures(material)) {
if (!disposedTextures.has(texture)) {
texture.dispose();
disposedTextures.add(texture);
this.releasedTextureCount += 1;
}
}
material.dispose();
this.releasedMaterialCount += 1;
}
private materialList(material: THREE.Material | THREE.Material[]): THREE.Material[] {
return Array.isArray(material) ? material : [material];
}
private materialTextures(material: THREE.Material): THREE.Texture[] {
const textureKeys = [
"alphaMap",
"aoMap",
"bumpMap",
"clearcoatMap",
"clearcoatNormalMap",
"clearcoatRoughnessMap",
"displacementMap",
"emissiveMap",
"envMap",
"iridescenceMap",
"iridescenceThicknessMap",
"lightMap",
"map",
"metalnessMap",
"normalMap",
"roughnessMap",
"sheenColorMap",
"sheenRoughnessMap",
"specularColorMap",
"specularIntensityMap",
"specularMap",
"thicknessMap",
"transmissionMap",
] as const;
const textures: THREE.Texture[] = [];
const fields = material as unknown as Record<string, unknown>;
for (const key of textureKeys) {
const value = fields[key];
if (value instanceof THREE.Texture) {
textures.push(value);
}
}
return textures;
}
private isRobotManifestObject(id: string): boolean {
if (!this.dragOptions.robotPrefix) {
return false;
}
const prefix = this.dragOptions.robotPrefix;
return id === prefix || id.startsWith(`${prefix}_`);
}
private resolveObjectIdOrBody(idOrBody: string): string | undefined {
if (this.objectsById.has(idOrBody)) {
return idOrBody;
}
for (const [id, bound] of this.objectsById) {
if (bound.manifest.body === idOrBody) {
return id;
}
}
return undefined;
}
private dragTargetIdsFor(id: string): string[] {
const bound = this.objectsById.get(id);
const groupId = bound?.manifest.editableGroup;
if (!groupId || bound.manifest.editableGroupRole === "member") {
return [id];
}
const grouped = this.editableGroups.get(groupId) ?? [];
const editableGrouped = grouped.filter((candidateId) => this.editableObjectIds.has(candidateId));
return editableGrouped.length > 0 ? [...new Set(editableGrouped)] : [id];
}
private dragTargetsFor(ids: string[]): DragTargetPose[] {
const targets: DragTargetPose[] = [];
for (const id of ids) {
const bound = this.objectsById.get(id);
if (!bound) {
continue;
}
targets.push({
id,
body: bound.manifest.body,
source: this.toSourceTuple(bound.root.position),
quat: this.currentSourceQuat(bound.manifest.body),
});
}
return targets;
}
private startDrag(event: PointerLikeEvent): boolean {
if (!this.dragOptions.enabled) {
return false;
}
this.cancelPendingDragUpdate();
const found = this.pickEditableObject(event);
if (!found) {
return false;
}
const pointerWorld = this.pointerWorld(event);
if (!pointerWorld) {
return false;
}
const { id, bound } = found;
const isRobot = this.robotObjectIds.has(id);
const targetIds = isRobot ? Array.from(this.robotObjectIds) : this.dragTargetIdsFor(id);
const worldStartById = new Map<string, THREE.Vector3>();
const sourceStartById = new Map<string, [number, number, number]>();
const sourceOffsetStartById = new Map<string, [number, number, number]>();
for (const targetId of targetIds) {
const targetBound = this.objectsById.get(targetId);
if (!targetBound) {
continue;
}
worldStartById.set(targetId, targetBound.root.position.clone());
sourceStartById.set(targetId, this.toSourceTuple(targetBound.root.position));
if (targetBound.manifest.body) {
sourceOffsetStartById.set(targetId, this.bodyVisualOffsets.get(targetBound.manifest.body) ?? [0, 0, 0]);
}
}
if (sourceStartById.size === 0) {
return false;
}
this.camera.getWorldDirection(this.scratchPointerPlaneNormal);
const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(this.scratchPointerPlaneNormal, pointerWorld);
this.dragState = {
kind: isRobot ? "robot" : "prop",
targetId: id,
target: bound.root,
pointerId: this.getPointerId(event),
plane,
worldStart: pointerWorld.clone(),
sourceStart: sourceStartById.get(id) ?? [0, 0, 0],
sourceStartById,
sourceOffsetStartById,
worldStartById,
targetIds,
robotPoseStart: [...this.robotOffsetPose],
};
this.lastDragAppliedAt = 0;
this.controls.enabled = false;
this.canvasSetPointerCapture(event);
const sourceDelta: [number, number, number] = [0, 0, 0];
this.emitDragEvent({
id,
body: bound.manifest.body,
source: sourceStartById.get(id) ?? [0, 0, 0],
quat: this.currentSourceQuat(bound.manifest.body),
groupId: bound.manifest.editableGroup,
targets: this.dragTargetsFor(targetIds),
sourceDelta,
kind: isRobot ? "robot" : "prop",
start: true,
end: false,
});
this.showFocusAndOutlineForObject(id, bound.root, "#f97316", 1.2);
this.setInteractionMode("dragging");
return true;
}
private snapshotPointerEvent(event: PointerLikeEvent): PointerSnapshot {
return {
clientX: event.clientX,
clientY: event.clientY,
button: event.button,
pointerId: this.getPointerId(event),
};
}
private queueDragTargetUpdate(event: PointerLikeEvent): void {
this.dragMoveEventCount += 1;
this.pendingDragPointer = this.snapshotPointerEvent(event);
if (this.dragUpdateFrameHandle || this.dragUpdateTimeoutHandle) {
this.dragCoalescedMoveCount += 1;
return;
}
const dragUpdateIntervalMs = this.largeSceneMode ? 1000 / 30 : 0;
const delayMs = Math.max(0, dragUpdateIntervalMs - (performance.now() - this.lastDragAppliedAt));
if (delayMs > 0) {
this.dragCoalescedMoveCount += 1;
this.dragUpdateTimeoutHandle = window.setTimeout(() => {
this.dragUpdateTimeoutHandle = 0;
this.scheduleDragAnimationFrame();
}, delayMs);
return;
}
this.scheduleDragAnimationFrame();
}
private scheduleDragAnimationFrame(): void {
this.dragUpdateFrameHandle = requestAnimationFrame(() => {
this.dragUpdateFrameHandle = 0;
this.applyPendingDragUpdate();
});
}
private applyPendingDragUpdate(): void {
const snapshot = this.pendingDragPointer;
this.pendingDragPointer = undefined;
if (!snapshot || !this.dragState) {
return;
}
this.dragAppliedMoveCount += 1;
this.lastDragAppliedAt = performance.now();
this.updateDragTarget(snapshot);
}
private cancelPendingDragUpdate(): void {
if (this.dragUpdateFrameHandle) {
cancelAnimationFrame(this.dragUpdateFrameHandle);
this.dragUpdateFrameHandle = 0;
}
if (this.dragUpdateTimeoutHandle) {
window.clearTimeout(this.dragUpdateTimeoutHandle);
this.dragUpdateTimeoutHandle = 0;
}
this.pendingDragPointer = undefined;
}
private flushPendingDragUpdate(): void {
if (this.dragUpdateFrameHandle) {
cancelAnimationFrame(this.dragUpdateFrameHandle);
this.dragUpdateFrameHandle = 0;
}
if (this.dragUpdateTimeoutHandle) {
window.clearTimeout(this.dragUpdateTimeoutHandle);
this.dragUpdateTimeoutHandle = 0;
}
this.applyPendingDragUpdate();
}
private updateDragTarget(event: PointerLikeEvent): void {
if (!this.dragState) {
return;
}
const current = this.pointerWorld(event);
if (!current) {
return;
}
const delta = this.scratchDragDelta.copy(current).sub(this.dragState.worldStart);
const deltaSource = this.toSourceVector(delta);
for (const targetId of this.dragState.targetIds) {
const start = this.dragState.worldStartById.get(targetId);
const bound = this.objectsById.get(targetId);
if (!start || !bound) {
continue;
}
bound.root.position.copy(start).add(delta);
this.updateManualObjectMatrix(bound.root);
this.updatePickTargetBounds(targetId);
this.updateInstancedVisualMatrix(targetId);
}
this.updateDraggedBodyOffsets(deltaSource);
this.refreshDragHighlight();
this.markRenderDirty();
const primarySource = this.toSourceTuple(this.objectsById.get(this.dragState.targetId)?.root.position ?? this.dragState.worldStart);
const sourceDelta: [number, number, number] = [
primarySource[0] - this.dragState.sourceStart[0],
primarySource[1] - this.dragState.sourceStart[1],
primarySource[2] - this.dragState.sourceStart[2],
];
this.emitDragEvent({
id: this.dragState.targetId,
body: this.objectsById.get(this.dragState.targetId)?.manifest.body,
source: this.dragState.kind === "robot"
? [
this.dragState.robotPoseStart[0] + deltaSource[0],
this.dragState.robotPoseStart[1] + deltaSource[1],
this.dragState.robotPoseStart[2] + deltaSource[2],
]
: primarySource,
quat: this.currentSourceQuat(this.objectsById.get(this.dragState.targetId)?.manifest.body),
groupId: this.objectsById.get(this.dragState.targetId)?.manifest.editableGroup,
targets: this.dragTargetsFor(this.dragState.targetIds),
sourceDelta,
kind: this.dragState.kind,
start: false,
end: false,
});
}
private finishDrag(event?: PointerLikeEvent): void {
if (!this.dragState) {
return;
}
this.flushPendingDragUpdate();
const finalWorld = event ? this.pointerWorld(event) : undefined;
if (finalWorld) {
const delta = this.scratchDragDelta.copy(finalWorld).sub(this.dragState.worldStart);
const deltaSource = this.toSourceVector(delta);
for (const targetId of this.dragState.targetIds) {
const start = this.dragState.worldStartById.get(targetId);
const bound = this.objectsById.get(targetId);
if (!start || !bound) {
continue;
}
bound.root.position.copy(start).add(delta);
this.updateManualObjectMatrix(bound.root);
this.updatePickTargetBounds(targetId);
this.updateInstancedVisualMatrix(targetId);
}
this.updateDraggedBodyOffsets(deltaSource);
this.refreshDragHighlight();
this.markRenderDirty();
const source: [number, number, number] = this.dragState.kind === "robot"
? [
this.dragState.robotPoseStart[0] + deltaSource[0],
this.dragState.robotPoseStart[1] + deltaSource[1],
this.dragState.robotPoseStart[2] + deltaSource[2],
]
: this.toSourceTuple(
this.objectsById.get(this.dragState.targetId)?.root.position ?? this.dragState.worldStart,
);
const sourceStart = this.dragState.sourceStartById.get(this.dragState.targetId) ?? [0, 0, 0];
const sourceDelta: [number, number, number] = [
source[0] - sourceStart[0],
source[1] - sourceStart[1],
source[2] - sourceStart[2],
];
this.emitDragEvent({
id: this.dragState.targetId,
body: this.objectsById.get(this.dragState.targetId)?.manifest.body,
source,
quat: this.currentSourceQuat(this.objectsById.get(this.dragState.targetId)?.manifest.body),
groupId: this.objectsById.get(this.dragState.targetId)?.manifest.editableGroup,
targets: this.dragTargetsFor(this.dragState.targetIds),
sourceDelta,
kind: this.dragState.kind,
start: false,
end: true,
});
} else {
this.emitDragEvent({
id: this.dragState.targetId,
body: this.objectsById.get(this.dragState.targetId)?.manifest.body,
source: this.dragState.sourceStart,
quat: this.currentSourceQuat(this.objectsById.get(this.dragState.targetId)?.manifest.body),
groupId: this.objectsById.get(this.dragState.targetId)?.manifest.editableGroup,
targets: this.dragTargetsFor(this.dragState.targetIds),
sourceDelta: [0, 0, 0],
kind: this.dragState.kind,
start: false,
end: true,
});
}
this.controls.enabled = true;
this.canvasReleasePointerCapture(this.dragState.pointerId);
const endState = this.dragState;
this.dragState = undefined;
this.setInteractionMode("idle");
if (event) {
this.updateDragHoverTarget(event);
this.setInteractionMode(this.hoveredObjectId === endState.targetId ? "hover" : "idle");
} else {
this.focusMarker.visible = false;
this.hideHoverOutline();
this.updateHoverLabel(undefined);
this.hoveredObjectId = undefined;
}
this.renderer.domElement.style.cursor = "";
this.markRenderDirty();
}
private cancelDrag(): void {
this.cancelPendingDragUpdate();
if (this.dragState) {
for (const targetId of this.dragState.targetIds) {
const bound = this.objectsById.get(targetId);
const body = bound?.manifest.body;
if (!body) {
continue;
}
const startOffset = this.dragState.sourceOffsetStartById.get(targetId);
if (startOffset) {
this.bodyVisualOffsets.set(body, [...startOffset]);
} else {
this.bodyVisualOffsets.delete(body);
}
this.bodyStateCache.delete(body);
}
this.canvasReleasePointerCapture(this.dragState.pointerId);
this.dragState = undefined;
this.markRenderDirty();
}
this.controls.enabled = true;
this.setInteractionMode("idle");
this.renderer.domElement.style.cursor = "";
}
private refreshDragHighlight(): void {
if (!this.dragState) {
return;
}
const bound = this.objectsById.get(this.dragState.targetId);
if (!bound) {
return;
}
this.showFocusAndOutlineForObject(this.dragState.targetId, bound.root, "#f97316", 1.2);
}
private pickEditableObject(event: PointerLikeEvent): { id: string; bound: BoundObject } | undefined {
if (this.editableObjectIds.size === 0 && this.robotObjectIds.size === 0) {
return undefined;
}
const target = this.pickBoundsTarget(event, this.editablePickTargets);
if (!target) {
return undefined;
}
const bound = this.objectsById.get(target.id);
return bound ? { id: target.id, bound } : undefined;
}
private pickAnyObject(
event: PointerLikeEvent,
): { id: string; bound: BoundObject; editable: boolean; disabledReason?: string } | undefined {
if (this.objectsById.size === 0) {
return undefined;
}
const target = this.pickBoundsTarget(event, this.pickTargets);
if (!target) {
return undefined;
}
const bound = this.objectsById.get(target.id);
if (!bound) {
return undefined;
}
const isEditable = this.editableObjectIds.has(target.id) || this.robotObjectIds.has(target.id);
const disabledReason = isEditable && this.dragOptions.enabled === false
? "需暂停后拖拽"
: bound.manifest.physics === "fixed"
? "固定物理体"
: bound.manifest.physics === "stateOnly"
? "状态同步体"
: !isEditable && !bound.manifest.body
? "静态对象"
: undefined;
return {
id: target.id,
bound,
editable: isEditable && this.dragOptions.enabled !== false,
disabledReason,
};
}
private pickBoundsTarget(event: PointerLikeEvent, targets: PickBoundsTarget[]): PickBoundsTarget | undefined {
if (targets.length === 0) {
return undefined;
}
this.updatePointerFromEvent(event);
this.raycaster.setFromCamera(this.pointer, this.camera);
const origin = this.raycaster.ray.origin;
let closest: PickBoundsTarget | undefined;
let closestDistanceSq = Number.POSITIVE_INFINITY;
for (const target of targets) {
if (target.worldBounds.isEmpty()) {
continue;
}
const point = this.raycaster.ray.intersectBox(target.worldBounds, this.scratchPickPoint);
if (!point) {
continue;
}
const distanceSq = origin.distanceToSquared(point);
if (distanceSq < closestDistanceSq) {
closestDistanceSq = distanceSq;
closest = target;
}
}
return closest;
}
private currentSourceQuat(bodyName?: string): Quat | undefined {
if (!bodyName) {
return undefined;
}
const quat = this.lastFrame?.bodies?.[bodyName]?.quat;
return quat ? [quat[0], quat[1], quat[2], quat[3]] : undefined;
}
private updateDraggedBodyOffsets(deltaSource: [number, number, number]): void {
if (!this.dragState || this.dragState.kind !== "prop") {
return;
}
for (const targetId of this.dragState.targetIds) {
const bound = this.objectsById.get(targetId);
const body = bound?.manifest.body;
if (!body) {
continue;
}
const startOffset = this.dragState.sourceOffsetStartById.get(targetId) ?? [0, 0, 0];
this.bodyVisualOffsets.set(body, [
startOffset[0] + deltaSource[0],
startOffset[1] + deltaSource[1],
startOffset[2] + deltaSource[2],
]);
this.bodyStateCache.delete(body);
}
}
private pointerWorld(event: PointerLikeEvent): THREE.Vector3 | undefined {
this.updatePointerFromEvent(event);
this.raycaster.setFromCamera(this.pointer, this.camera);
if (!this.dragState) {
this.camera.getWorldDirection(this.scratchPointerPlaneNormal);
this.scratchPointerPlane.setFromNormalAndCoplanarPoint(this.scratchPointerPlaneNormal, this.controls.target);
return this.raycaster.ray.intersectPlane(this.scratchPointerPlane, this.scratchPointerWorld) ?? undefined;
}
return this.raycaster.ray.intersectPlane(this.dragState.plane, this.scratchPointerWorld) ?? undefined;
}
private toSourceTuple(value: THREE.Vector3): [number, number, number] {
const converted = this.converter.worldToSourcePosition([value.x, value.y, value.z]);
return [converted[0], converted[1], converted[2]];
}
private toSourceVector(value: THREE.Vector3): [number, number, number] {
const converted = this.converter.worldToSourcePosition([value.x, value.y, value.z]);
return [converted[0], converted[1], converted[2]];
}
private canvasSetPointerCapture(event: PointerLikeEvent): void {
const canvas = this.renderer.domElement;
if (typeof canvas.setPointerCapture !== "function") {
return;
}
try {
const pointerId = this.getPointerId(event);
if (pointerId === undefined) {
return;
}
canvas.setPointerCapture(pointerId);
} catch {
// Some browsers may reject repeated capture calls, ignore for graceful UX.
}
}
private canvasReleasePointerCapture(pointerId?: number): void {
const target = this.renderer.domElement;
if (pointerId === undefined || typeof target.releasePointerCapture !== "function") {
return;
}
try {
if (target.hasPointerCapture(pointerId)) {
target.releasePointerCapture(pointerId);
}
} catch {
// Ignore pointer capture lifecycle exceptions.
}
}
private updatePointerFromEvent(event: PointerLikeEvent): void {
const rect = this.renderer.domElement.getBoundingClientRect();
this.pointer.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
this.pointer.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
}
private emitDragEvent(event: DragPose): void {
if (!this.dragOptions.onDrag) {
return;
}
this.dragOptions.onDrag(event);
}
private buildMaterials(materials: PreviewMaterial[]): void {
const defaults: PreviewMaterial[] = [
{ id: "default", color: "#93c5fd", roughness: 0.65 },
{ id: "fallback", color: "#fb7185", wireframe: true },
];
for (const material of [...defaults, ...materials]) {
const texture = this.createMaterialTexture(material);
const [roughness, metalness] = this.previewSurface(material);
const parameters: THREE.MeshStandardMaterialParameters = {
color: material.color ?? "#93c5fd",
opacity: material.opacity ?? 1,
transparent: material.opacity !== undefined && material.opacity < 1,
roughness,
metalness,
side: THREE.DoubleSide,
wireframe: material.wireframe ?? false,
};
if (texture) {
parameters.map = texture;
}
const threeMaterial = new THREE.MeshStandardMaterial(parameters);
this.materials.set(material.id, threeMaterial);
}
}
private previewSurface(material: PreviewMaterial): [roughness: number, metalness: number] {
let roughness = material.roughness ?? 0.68;
let metalness = material.metalness ?? 0;
if (metalness >= 0.85 && roughness >= 0.85) {
// MJCF store assets use painted white metal as rough metallic PBR.
// Without the original HDR environment that previews too dark, so keep it readable.
metalness = 0.16;
roughness = 0.58;
}
return [roughness, metalness];
}
private createMaterialTexture(material: PreviewMaterial): THREE.Texture | undefined {
let texture: THREE.Texture | undefined;
let immediateImage = false;
if (material.textureUrl) {
texture = new THREE.TextureLoader().load(material.textureUrl);
texture.colorSpace = THREE.SRGBColorSpace;
} else if (material.textureKind === "checker") {
texture = this.createCheckerTexture(material.textureColors ?? ["#64748b", "#e5e7eb"]);
immediateImage = true;
}
if (!texture) {
return undefined;
}
const [repeatX, repeatY] = material.textureRepeat ?? [1, 1];
texture.wrapS = THREE.RepeatWrapping;
texture.wrapT = THREE.RepeatWrapping;
texture.repeat.set(repeatX, repeatY);
if (immediateImage) {
texture.needsUpdate = true;
}
return texture;
}
private createCheckerTexture(colors: [string, string]): THREE.Texture {
const size = 128;
const squares = 8;
const canvas = document.createElement("canvas");
canvas.width = size;
canvas.height = size;
const context = canvas.getContext("2d");
if (context) {
const cell = size / squares;
for (let y = 0; y < squares; y += 1) {
for (let x = 0; x < squares; x += 1) {
context.fillStyle = colors[(x + y) % 2];
context.fillRect(x * cell, y * cell, cell, cell);
}
}
}
const texture = new THREE.CanvasTexture(canvas);
texture.colorSpace = THREE.SRGBColorSpace;
return texture;
}
private getMaterial(id?: string): THREE.Material {
return this.materials.get(id ?? "default") ?? this.materials.get("default")!;
}
private addDefaultHelpers(): void {
const grid = new THREE.GridHelper(12, 24, "#64748b", "#243244");
grid.position.y = 0;
grid.userData.helper = true;
this.root.add(grid);
}
private addLights(manifest: SceneManifest): void {
const lights = manifest.lights ?? [
{ type: "hemisphere" as const, intensity: 0.75, color: "#e0f2fe" },
{ type: "directional" as const, intensity: 2.0, color: "#ffffff", position: [4, -5, 7] as [number, number, number] },
];
for (const lightSpec of lights) {
if (lightSpec.type === "ambient") {
this.root.add(new THREE.AmbientLight(lightSpec.color ?? "#ffffff", lightSpec.intensity ?? 0.4));
} else if (lightSpec.type === "hemisphere") {
this.root.add(new THREE.HemisphereLight(lightSpec.color ?? "#ffffff", "#111827", lightSpec.intensity ?? 0.6));
} else {
const light = new THREE.DirectionalLight(lightSpec.color ?? "#ffffff", lightSpec.intensity ?? 2);
light.position.copy(this.converter.position(lightSpec.position, [3, -4, 7]));
light.castShadow = !this.largeSceneMode;
light.shadow.mapSize.set(2048, 2048);
this.root.add(light);
}
}
}
private applyCamera(manifest: SceneManifest): void {
const camera = manifest.camera;
if (!camera) {
return;
}
this.camera.fov = camera.fov ?? 46;
this.camera.near = camera.near ?? 0.05;
this.camera.far = camera.far ?? 500;
this.camera.position.copy(this.converter.position(camera.position, [5.5, -7.2, 4.6]));
this.controls.target.copy(this.converter.position(camera.target, [0, 0, 1.2]));
this.camera.updateProjectionMatrix();
this.controls.update();
}
private fitCameraToObjects(): void {
const bounds = this.sceneObjectBoundsCount > 0
? this.scratchFitBounds.copy(this.sceneObjectBounds)
: this.scratchFitBounds.makeEmpty();
let found = false;
if (this.sceneObjectBoundsCount > 0) {
found = !bounds.isEmpty();
} else {
for (const child of this.root.children) {
if (!child.userData.manifestId) {
continue;
}
const childBounds = this.scratchBounds.setFromObject(child);
this.cameraFitTraversalCount += 1;
if (childBounds.isEmpty()) {
continue;
}
bounds.union(childBounds);
found = true;
}
}
if (!found || bounds.isEmpty()) {
return;
}
const center = bounds.getCenter(this.scratchCameraCenter);
const size = bounds.getSize(this.scratchCameraSize);
const maxSize = Math.max(size.x, size.y, size.z, 0.8);
const distance = Math.max(1.6, (maxSize / (2 * Math.tan(THREE.MathUtils.degToRad(this.camera.fov) / 2))) * 1.55);
const direction = this.scratchCameraDirection.copy(this.camera.position).sub(this.controls.target);
if (direction.lengthSq() < 1e-6) {
direction.set(1.2, 0.9, 1.2);
}
direction.normalize();
this.controls.target.copy(center);
this.camera.position.copy(center).addScaledVector(direction, distance);
this.camera.near = Math.max(0.01, distance / 100);
this.camera.far = Math.max(50, distance * 100);
this.camera.updateProjectionMatrix();
this.controls.update();
}
private prepareInstancedMeshBatchCapacities(objects: PreviewObject[]): void {
this.instancedMeshBatchCapacities.clear();
for (const object of objects) {
if (!this.isInstancedMeshCandidate(object)) {
continue;
}
const key = this.meshCacheKey(object.geometry, object.material);
this.instancedMeshBatchCapacities.set(key, (this.instancedMeshBatchCapacities.get(key) ?? 0) + 1);
}
for (const [key, count] of [...this.instancedMeshBatchCapacities]) {
if (count < 2) {
this.instancedMeshBatchCapacities.delete(key);
}
}
}
private isInstancedMeshCandidate(object: PreviewObject): object is PreviewObject & { geometry: MeshGeometry } {
return this.largeSceneMode
&& object.visible !== false
&& object.geometry.kind === "mesh"
&& object.physics === "fixed"
&& Boolean(object.body);
}
private async createInstancedVisual(
object: PreviewObject,
root: THREE.Object3D,
token: number,
sceneRoots: SceneBuildRoots,
): Promise<InstancedVisual | undefined> {
if (!this.isInstancedMeshCandidate(object)) {
return undefined;
}
const key = this.meshCacheKey(object.geometry, object.material);
if (!this.instancedMeshBatchCapacities.has(key)) {
return undefined;
}
try {
const batch = await this.getInstancedMeshBatch(object.geometry, object.material, key, sceneRoots);
if (token !== this.loadToken) {
return undefined;
}
const sourceBounds = this.meshSourceBounds.get(key);
if (!sourceBounds || sourceBounds.isEmpty() || batch.submeshes.length === 0 || batch.used >= batch.capacity) {
return undefined;
}
const localMatrix = this.createPoseMatrix(object.pose);
const index = batch.used;
batch.used += 1;
this.instancedVisualBindings.set(object.id, {
batch,
index,
root,
localMatrix,
});
this.instancedMeshObjectCount += 1;
this.instancedLocalObjectElisionCount += 1;
this.loadedMeshCount += 1;
root.userData.hasSpinningObjects = false;
return { localMatrix, sourceBounds };
} catch {
return undefined;
}
}
private createPoseMatrix(pose: PreviewObject["pose"]): THREE.Matrix4 {
this.scratchPoseObject.position.set(0, 0, 0);
this.scratchPoseObject.quaternion.identity();
this.scratchPoseObject.scale.set(1, 1, 1);
this.converter.applyPose(this.scratchPoseObject, pose);
this.scratchPoseObject.updateMatrix();
return this.scratchPoseObject.matrix.clone();
}
private async getInstancedMeshBatch(
geometry: MeshGeometry,
materialId: string | undefined,
key: string,
sceneRoots: SceneBuildRoots,
): Promise<InstancedVisualBatch> {
const pending = this.instancedMeshBatches.get(key);
if (pending) {
return pending;
}
const capacity = this.instancedMeshBatchCapacities.get(key) ?? 0;
const created = this.getMeshSource(geometry, materialId)
.then(({ source }) => this.createInstancedMeshBatch(key, source, capacity));
this.instancedMeshBatches.set(key, created);
const batch = await created;
sceneRoots.instanced.push(batch.root);
return batch;
}
private createInstancedMeshBatch(key: string, source: THREE.Object3D, capacity: number): InstancedVisualBatch {
const root = new THREE.Group();
root.name = `instanced_${key.replace(/[^a-z0-9_-]+/gi, "_").slice(0, 72)}`;
root.matrixAutoUpdate = false;
source.updateWorldMatrix(true, true);
const submeshes: InstancedSubmesh[] = [];
source.traverse((child) => {
const sourceMesh = child as THREE.Mesh;
if (!sourceMesh.isMesh || !sourceMesh.geometry || !sourceMesh.material) {
return;
}
const instanced = new THREE.InstancedMesh(sourceMesh.geometry, sourceMesh.material, capacity);
instanced.name = `${root.name}_${submeshes.length}`;
instanced.castShadow = false;
instanced.receiveShadow = false;
instanced.frustumCulled = false;
instanced.matrixAutoUpdate = false;
instanced.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
root.add(instanced);
submeshes.push({
mesh: instanced,
sourceMatrix: sourceMesh.matrixWorld.clone(),
});
});
this.instancedMeshBatchCount += 1;
this.instancedMeshDrawCount += submeshes.length;
return {
key,
root,
capacity,
used: 0,
submeshes,
};
}
private updateInstancedVisualMatrix(id: string): void {
const binding = this.instancedVisualBindings.get(id);
if (!binding) {
return;
}
binding.root.updateWorldMatrix(true, false);
this.scratchLocalWorldMatrix.multiplyMatrices(binding.root.matrixWorld, binding.localMatrix);
this.writeInstancedVisualMatrix(binding.batch, binding.index, this.scratchLocalWorldMatrix);
}
private writeInstancedVisualMatrix(batch: InstancedVisualBatch, index: number, matrix: THREE.Matrix4): void {
for (const submesh of batch.submeshes) {
this.scratchMatrix.multiplyMatrices(matrix, submesh.sourceMatrix);
submesh.mesh.setMatrixAt(index, this.scratchMatrix);
submesh.mesh.instanceMatrix.needsUpdate = true;
}
this.instancedMeshMatrixUpdateCount += 1;
}
private async finalizeInstancedMeshBatches(): Promise<void> {
this.instancedMeshFrustumCulledCount = 0;
this.instancedMeshStaticMatrixCount = 0;
const batches = await Promise.all(this.instancedMeshBatches.values());
for (const batch of batches) {
for (const submesh of batch.submeshes) {
submesh.mesh.instanceMatrix.setUsage(THREE.StaticDrawUsage);
submesh.mesh.instanceMatrix.needsUpdate = true;
submesh.mesh.computeBoundingBox();
submesh.mesh.computeBoundingSphere();
submesh.mesh.frustumCulled = true;
this.instancedMeshStaticMatrixCount += 1;
this.instancedMeshFrustumCulledCount += 1;
}
}
}
private async addObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise<void> {
if (await this.addVirtualInstancedObject(object, token, sceneRoots)) {
return;
}
const root = new THREE.Group();
root.name = object.name ?? object.id;
root.visible = object.visible !== false;
root.userData.manifestId = object.id;
const instancedVisual = await this.createInstancedVisual(object, root, token, sceneRoots);
if (token !== this.loadToken) {
return;
}
const visual = instancedVisual ? undefined : await this.createVisual(object.geometry, object.material, token);
if (token !== this.loadToken || (!instancedVisual && !visual)) {
return;
}
if (visual) {
visual.castShadow = !this.largeSceneMode && (object.castShadow ?? true);
visual.receiveShadow = !this.largeSceneMode && (object.receiveShadow ?? true);
visual.name = `${object.id}_visual`;
}
if (visual && object.body) {
const local = new THREE.Group();
local.name = `${object.id}_local_pose`;
this.converter.applyPose(local, object.pose);
local.add(visual);
root.add(local);
} else if (visual) {
this.converter.applyPose(root, object.pose);
root.add(visual);
}
this.freezeStaticVisualSubtree(root, visual);
const pickTarget = instancedVisual
? this.createPickTargetFromSourceBounds(root, instancedVisual.sourceBounds, instancedVisual.localMatrix, object.id)
: this.createPickTarget(root, object.id, visual);
if (pickTarget) {
if (instancedVisual) {
this.fastPickProxyBoundsCount += 1;
}
this.sceneObjectBounds.union(pickTarget.worldBounds);
this.sceneObjectBoundsCount += 1;
this.pickBoundsById.set(object.id, pickTarget);
if (this.shouldIncludeHoverPickTarget(object, Boolean(instancedVisual))) {
this.pickTargets.push(pickTarget);
}
}
this.freezeObjectRootMatrix(root);
if (!instancedVisual) {
sceneRoots.visible.push(root);
}
if (instancedVisual) {
this.spinningScanSkippedCount += 1;
} else {
this.registerSpinningObjects(root, visual);
}
if (instancedVisual) {
this.updateInstancedVisualMatrix(object.id);
}
this.objectsById.set(object.id, { manifest: object, root });
this.registerObjectMetadata(object, root);
}
private async addVirtualInstancedObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise<boolean> {
if (!this.isInstancedMeshCandidate(object)) {
return false;
}
const key = this.meshCacheKey(object.geometry, object.material);
if (!this.instancedMeshBatchCapacities.has(key)) {
return false;
}
let batch: InstancedVisualBatch;
try {
batch = await this.getInstancedMeshBatch(object.geometry, object.material, key, sceneRoots);
} catch {
return false;
}
if (token !== this.loadToken) {
return true;
}
const sourceBounds = this.meshSourceBounds.get(key);
if (!sourceBounds || sourceBounds.isEmpty() || batch.submeshes.length === 0 || batch.used >= batch.capacity) {
return false;
}
const localMatrix = this.createPoseMatrix(object.pose);
const index = batch.used;
batch.used += 1;
this.instancedVisualBindings.set(object.id, {
batch,
index,
root: this.virtualInstancedRoot,
localMatrix,
});
this.writeInstancedVisualMatrix(batch, index, localMatrix);
this.instancedMeshObjectCount += 1;
this.instancedLocalObjectElisionCount += 1;
this.virtualInstancedRootCount += 1;
this.loadedMeshCount += 1;
this.spinningScanSkippedCount += 1;
const pickTarget = this.createPickTargetFromWorldMatrix(sourceBounds, localMatrix, object.id);
if (pickTarget) {
this.fastPickProxyBoundsCount += 1;
this.sceneObjectBounds.union(pickTarget.worldBounds);
this.sceneObjectBoundsCount += 1;
this.pickBoundsById.set(object.id, pickTarget);
if (this.shouldIncludeHoverPickTarget(object, true)) {
this.pickTargets.push(pickTarget);
}
}
this.objectsById.set(object.id, { manifest: object, root: this.virtualInstancedRoot });
this.registerObjectMetadata(object, this.virtualInstancedRoot);
return true;
}
private registerObjectMetadata(object: PreviewObject, root: THREE.Object3D): void {
if (object.editableGroup) {
const group = this.editableGroups.get(object.editableGroup) ?? [];
if (!group.includes(object.id)) {
group.push(object.id);
this.groupedObjectCount += 1;
}
this.editableGroups.set(object.editableGroup, group);
}
if (object.body) {
const ids = this.objectBodyIds.get(object.id) ?? [];
if (!ids.includes(object.body)) {
ids.push(object.body);
}
this.objectBodyIds.set(object.id, ids);
const sourcePose = object.pose?.position ?? [0, 0, 0];
if (!this.bodySourceOffsets.has(object.body)) {
this.bodySourceOffsets.set(object.body, [...sourcePose] as [number, number, number]);
}
const items = this.bodyBindings.get(object.body) ?? [];
items.push({ manifest: object, root });
this.bodyBindings.set(object.body, items);
this.bodyBoundObjectCount += 1;
return;
}
this.objectBodyIds.set(object.id, []);
}
private prewarmInstancedMeshBatches(objects: PreviewObject[], token: number, sceneRoots: SceneBuildRoots): void {
if (!this.largeSceneMode || this.instancedMeshBatchCapacities.size === 0) {
return;
}
const startedAt = performance.now();
const seen = new Set<string>();
for (const object of objects) {
if (token !== this.loadToken) {
break;
}
if (!this.isInstancedMeshCandidate(object)) {
continue;
}
const key = this.meshCacheKey(object.geometry, object.material);
if (seen.has(key) || !this.instancedMeshBatchCapacities.has(key) || !this.meshCache.has(key)) {
continue;
}
seen.add(key);
this.instancedMeshPrewarmCount += 1;
void this.getInstancedMeshBatch(object.geometry, object.material, key, sceneRoots).catch(() => undefined);
}
this.instancedMeshPrewarmMs = performance.now() - startedAt;
}
private async addObjects(objects: PreviewObject[], token: number): Promise<void> {
let nextIndex = 0;
let builtSinceYield = 0;
const sceneRoots: SceneBuildRoots = {
visible: [],
instanced: [],
};
this.prewarmInstancedMeshBatches(objects, token, sceneRoots);
const workerCount = Math.min(24, Math.max(1, objects.length));
const workers = Array.from({ length: workerCount }, async () => {
while (token === this.loadToken) {
const index = nextIndex;
nextIndex += 1;
const object = objects[index];
if (!object) {
return;
}
await this.addObject(object, token, sceneRoots);
builtSinceYield += 1;
this.flushSceneRootBatch(sceneRoots.visible);
if (this.largeSceneMode && builtSinceYield >= 24) {
builtSinceYield = 0;
await this.yieldDuringSceneBuild(token);
}
}
});
await Promise.all(workers);
if (token !== this.loadToken) {
return;
}
this.flushSceneRootBatch(sceneRoots.visible, true);
const finalizeStartedAt = performance.now();
await this.finalizeInstancedMeshBatches();
this.instancedMeshFinalizeMs = performance.now() - finalizeStartedAt;
if (token !== this.loadToken) {
return;
}
this.flushSceneRootBatch(sceneRoots.instanced, true);
this.refreshEditablePickTargets();
}
private flushSceneRootBatch(sceneRoots: THREE.Object3D[], force = false): void {
if (sceneRoots.length === 0) {
return;
}
if (!force && sceneRoots.length < LARGE_SCENE_ROOT_BATCH_SIZE) {
return;
}
const batch = sceneRoots.splice(0, sceneRoots.length);
this.root.add(...batch);
this.batchedSceneRootCount += batch.length;
this.sceneRootBatchCount += 1;
this.markRenderDirty();
}
private async yieldDuringSceneBuild(token: number): Promise<void> {
this.sceneBuildYieldCount += 1;
await new Promise<void>((resolve) => window.setTimeout(resolve, 0));
if (token !== this.loadToken) {
return;
}
}
private refreshEditablePickTargets(): void {
this.editablePickTargets.length = 0;
const targets = new Map<string, PickBoundsTarget>();
for (const id of this.editableObjectIds) {
const target = this.pickBoundsById.get(id);
if (target) {
targets.set(id, target);
}
}
for (const id of this.robotObjectIds) {
const target = this.pickBoundsById.get(id);
if (target) {
targets.set(id, target);
}
}
this.editablePickTargets.push(...targets.values());
}
private shouldIncludeHoverPickTarget(object: PreviewObject, isInstancedVisual: boolean): boolean {
if (object.visible === false) {
return false;
}
if (!this.largeSceneMode || !isInstancedVisual || object.physics !== "fixed") {
return true;
}
const searchableName = `${object.body ?? ""} ${object.name ?? ""} ${object.id} ${
object.geometry.kind === "mesh" ? object.geometry.url : ""
}`.toLowerCase();
return searchableName.includes("shelf");
}
private registerSpinningObjects(root: THREE.Object3D, visual?: THREE.Object3D): void {
if (visual?.userData.hasSpinningObjects === false) {
this.spinningScanSkippedCount += 1;
return;
}
root.traverse((child) => {
if (child.userData.spin === true) {
this.spinningObjects.push(child);
}
});
}
private freezeStaticVisualSubtree(root: THREE.Object3D, visual?: THREE.Object3D): void {
const preFrozenCount = visual?.userData.preFrozenStaticObjectCount;
if (visual && typeof preFrozenCount === "number") {
this.frozenStaticObjectCount += preFrozenCount;
this.preFrozenMeshCloneCount += 1;
let current = visual.parent;
while (current && current !== root) {
this.freezeStaticObject(current);
current = current.parent;
}
return;
}
root.traverse((child) => {
if (
child === root
|| !this.canFreezeStaticObject(child)
) {
return;
}
this.freezeStaticObject(child);
});
}
private canFreezeStaticObject(object: THREE.Object3D): boolean {
return object.userData.spin !== true
&& !(object as THREE.SkinnedMesh).isSkinnedMesh
&& object.type !== "Bone";
}
private freezeStaticObject(object: THREE.Object3D): void {
object.updateMatrix();
object.matrixAutoUpdate = false;
object.matrixWorldNeedsUpdate = true;
this.frozenStaticObjectCount += 1;
}
private freezeObjectRootMatrix(root: THREE.Object3D): void {
root.updateMatrix();
root.matrixAutoUpdate = false;
root.matrixWorldNeedsUpdate = true;
this.manualMatrixRootCount += 1;
}
private updateManualObjectMatrix(root: THREE.Object3D): void {
if (!root.matrixAutoUpdate) {
root.updateMatrix();
root.matrixWorldNeedsUpdate = true;
this.manualMatrixUpdateCount += 1;
}
}
private createPickTarget(
root: THREE.Object3D,
manifestId: string,
visual?: THREE.Object3D,
): PickBoundsTarget | undefined {
const cached = visual ? this.createPickTargetFromCachedBounds(root, visual, manifestId) : undefined;
if (cached) {
this.fastPickProxyBoundsCount += 1;
return cached;
}
root.updateWorldMatrix(true, true);
const worldBounds = this.scratchPickWorldBounds.setFromObject(root);
if (worldBounds.isEmpty()) {
return undefined;
}
const inverseRootMatrix = this.scratchInverseMatrix.copy(root.matrixWorld).invert();
const localBounds = this.transformBoundsInto(worldBounds, inverseRootMatrix, this.scratchPickLocalBounds);
if (localBounds.isEmpty()) {
return undefined;
}
return this.createPickTargetFromBounds(localBounds, worldBounds, manifestId);
}
private createPickTargetFromCachedBounds(
root: THREE.Object3D,
visual: THREE.Object3D,
manifestId: string,
): PickBoundsTarget | undefined {
const sourceBounds = visual.userData.sourceLocalBounds as THREE.Box3 | undefined;
if (!sourceBounds || sourceBounds.isEmpty()) {
return undefined;
}
return this.createPickTargetFromSourceBounds(root, sourceBounds, visual.matrixWorld, manifestId);
}
private createPickTargetFromSourceBounds(
root: THREE.Object3D,
sourceBounds: THREE.Box3,
sourceMatrix: THREE.Matrix4,
manifestId: string,
): PickBoundsTarget | undefined {
root.updateWorldMatrix(true, true);
const worldBounds = this.transformBoundsInto(sourceBounds, sourceMatrix, this.scratchPickWorldBounds);
if (worldBounds.isEmpty()) {
return undefined;
}
const inverseRootMatrix = this.scratchInverseMatrix.copy(root.matrixWorld).invert();
const localBounds = this.transformBoundsInto(worldBounds, inverseRootMatrix, this.scratchPickLocalBounds);
if (localBounds.isEmpty()) {
return undefined;
}
return this.createPickTargetFromBounds(localBounds, worldBounds, manifestId);
}
private createPickTargetFromWorldMatrix(
sourceBounds: THREE.Box3,
worldMatrix: THREE.Matrix4,
manifestId: string,
): PickBoundsTarget | undefined {
const worldBounds = this.transformBoundsInto(sourceBounds, worldMatrix, this.scratchPickWorldBounds);
if (worldBounds.isEmpty()) {
return undefined;
}
return this.createPickTargetFromBounds(worldBounds, worldBounds, manifestId);
}
private createPickTargetFromBounds(
localBounds: THREE.Box3,
worldBounds: THREE.Box3,
manifestId: string,
): PickBoundsTarget {
return {
id: manifestId,
localBounds: localBounds.clone(),
worldBounds: worldBounds.clone(),
};
}
private updatePickTargetBounds(id: string): void {
const target = this.pickBoundsById.get(id);
const bound = this.objectsById.get(id);
if (!target || !bound) {
return;
}
bound.root.updateWorldMatrix(true, false);
target.worldBounds.copy(target.localBounds).applyMatrix4(bound.root.matrixWorld);
}
private transformBoundsInto(bounds: THREE.Box3, matrix: THREE.Matrix4, target: THREE.Box3): THREE.Box3 {
target.makeEmpty();
const min = bounds.min;
const max = bounds.max;
this.expandTransformedBoundsCorner(target, matrix, min.x, min.y, min.z);
this.expandTransformedBoundsCorner(target, matrix, min.x, min.y, max.z);
this.expandTransformedBoundsCorner(target, matrix, min.x, max.y, min.z);
this.expandTransformedBoundsCorner(target, matrix, min.x, max.y, max.z);
this.expandTransformedBoundsCorner(target, matrix, max.x, min.y, min.z);
this.expandTransformedBoundsCorner(target, matrix, max.x, min.y, max.z);
this.expandTransformedBoundsCorner(target, matrix, max.x, max.y, min.z);
this.expandTransformedBoundsCorner(target, matrix, max.x, max.y, max.z);
this.pickBoundsScratchTransformCount += 1;
return target;
}
private expandTransformedBoundsCorner(
target: THREE.Box3,
matrix: THREE.Matrix4,
x: number,
y: number,
z: number,
): void {
target.expandByPoint(this.scratchBoundsCorner.set(x, y, z).applyMatrix4(matrix));
}
private async createVisual(geometry: PreviewGeometry, materialId: string | undefined, token: number): Promise<THREE.Object3D> {
if (geometry.kind === "mesh") {
return this.loadMesh(geometry, materialId, token);
}
if (geometry.kind === "convexMesh") {
return this.createInlineMesh(geometry.vertices, geometry.faces, materialId, token);
}
const material = this.getMaterial(materialId);
switch (geometry.primitive) {
case "sphere":
return new THREE.Mesh(this.getPrimitiveGeometry(geometry), material);
case "capsule":
return new THREE.Mesh(this.getPrimitiveGeometry(geometry), material);
case "cylinder":
return new THREE.Mesh(this.getPrimitiveGeometry(geometry), material);
case "plane": {
const mesh = new THREE.Mesh(this.getPrimitiveGeometry(geometry), material);
mesh.rotation.x = -Math.PI / 2;
return mesh;
}
case "axes": {
const [x] = geometry.size ?? [1, 1, 1];
return new THREE.AxesHelper(x);
}
case "box":
default: {
return new THREE.Mesh(this.getPrimitiveGeometry(geometry), material);
}
}
}
private getPrimitiveGeometry(geometry: Extract<PreviewGeometry, { kind: "primitive" }>): THREE.BufferGeometry {
const key = this.primitiveGeometryKey(geometry);
const cached = this.primitiveGeometryCache.get(key);
if (cached) {
return cached;
}
let created: THREE.BufferGeometry;
switch (geometry.primitive) {
case "sphere":
created = new THREE.SphereGeometry(geometry.radius ?? 0.25, geometry.segments ?? 32, geometry.segments ?? 24);
break;
case "capsule":
created = new THREE.CapsuleGeometry(geometry.radius ?? 0.1, geometry.length ?? 0.8, 8, geometry.segments ?? 24);
break;
case "cylinder":
created = new THREE.CylinderGeometry(geometry.radius ?? 0.1, geometry.radius ?? 0.1, geometry.length ?? 0.8, geometry.segments ?? 32);
break;
case "plane": {
const [x, , z] = this.converter.primitiveSize(geometry.size, [4, 0, 4]);
created = new THREE.PlaneGeometry(x, z);
break;
}
case "box":
default: {
const [x, y, z] = this.converter.primitiveSize(geometry.size, [0.3, 0.3, 0.3]);
created = new THREE.BoxGeometry(x, y, z);
break;
}
}
this.primitiveGeometryCache.set(key, created);
return created;
}
private primitiveGeometryKey(geometry: Extract<PreviewGeometry, { kind: "primitive" }>): string {
const size = geometry.size ? this.converter.primitiveSize(geometry.size, [0.3, 0.3, 0.3]) : undefined;
return [
geometry.primitive,
size?.join(",") ?? "",
geometry.radius ?? "",
geometry.length ?? "",
geometry.segments ?? "",
].join("|");
}
private createInlineMesh(vertices: number[], faces: number[] | undefined, materialId: string | undefined, token: number): THREE.Object3D {
const material = this.getMaterial(materialId);
const points: THREE.Vector3[] = [];
for (let index = 0; index + 2 < vertices.length; index += 3) {
points.push(new THREE.Vector3(vertices[index], vertices[index + 1], vertices[index + 2]));
}
let geometry: THREE.BufferGeometry;
if (faces && faces.length >= 3) {
geometry = new THREE.BufferGeometry();
geometry.setAttribute("position", new THREE.Float32BufferAttribute(vertices, 3));
geometry.setIndex(faces);
geometry.computeVertexNormals();
} else if (points.length >= 4) {
geometry = new ConvexGeometry(points);
} else {
geometry = new THREE.BufferGeometry();
geometry.setAttribute("position", new THREE.Float32BufferAttribute(vertices, 3));
geometry.computeVertexNormals();
}
const mesh = new THREE.Mesh(geometry, material);
this.converter.applySourceBasis(mesh);
if (token === this.loadToken) {
this.loadedMeshCount += 1;
}
return mesh;
}
private async loadMesh(geometry: MeshGeometry, materialId: string | undefined, token: number): Promise<THREE.Object3D> {
try {
const { source, cacheKey } = await this.getMeshSource(geometry, materialId);
const loaded = source.clone(true);
const sourceBounds = this.meshSourceBounds.get(cacheKey);
if (sourceBounds) {
loaded.userData.sourceLocalBounds = sourceBounds;
}
if (token === this.loadToken) {
this.loadedMeshCount += 1;
}
return loaded;
} catch (error) {
if (token === this.loadToken) {
this.fallbackCount += 1;
}
const fallback = new THREE.Mesh(
new THREE.BoxGeometry(0.6, 0.6, 0.6),
this.getMaterial("fallback"),
);
fallback.name = `mesh_fallback:${geometry.url}`;
fallback.userData.error = (error as Error).message;
return fallback;
}
}
private async getMeshSource(
geometry: MeshGeometry,
materialId: string | undefined,
): Promise<{ source: THREE.Object3D; cacheKey: string }> {
const format = geometry.format ?? inferMeshFormat(geometry.url);
const cacheKey = this.meshCacheKey(geometry, materialId, format);
let pending = this.meshCache.get(cacheKey);
if (!pending) {
this.meshCacheMissCount += 1;
const material = this.getMaterial(geometry.materialOverride ?? materialId);
pending = this.withMeshSourceLoadSlot(() => this.loadMeshSource(geometry, format, material))
.then((source) => {
this.prepareLoadedMesh(source);
const bounds = new THREE.Box3().setFromObject(source);
if (!bounds.isEmpty()) {
this.meshSourceBounds.set(cacheKey, bounds.clone());
}
this.cachedMeshSources.add(source);
this.retainMeshSourceResources(source);
return source;
})
.catch((error) => {
this.meshCache.delete(cacheKey);
throw error;
});
this.meshCache.set(cacheKey, pending);
} else {
this.meshCacheHitCount += 1;
}
return { source: await pending, cacheKey };
}
private async withMeshSourceLoadSlot<T>(operation: () => Promise<T>): Promise<T> {
if (this.activeMeshSourceLoadCount >= this.meshSourceLoadLimit) {
this.queuedMeshSourceLoadCount += 1;
await new Promise<void>((resolve) => {
this.meshSourceLoadQueue.push(resolve);
});
}
this.activeMeshSourceLoadCount += 1;
this.peakMeshSourceLoadCount = Math.max(this.peakMeshSourceLoadCount, this.activeMeshSourceLoadCount);
try {
return await operation();
} finally {
this.activeMeshSourceLoadCount = Math.max(0, this.activeMeshSourceLoadCount - 1);
const next = this.meshSourceLoadQueue.shift();
if (next) {
queueMicrotask(next);
}
}
}
private meshCacheKey(
geometry: MeshGeometry,
materialId: string | undefined,
format: MeshGeometry["format"] | undefined = geometry.format ?? inferMeshFormat(geometry.url),
): string {
return `${format ?? "unknown"}:${geometry.url}:${geometry.materialOverride ?? materialId ?? "default"}`;
}
private async loadMeshSource(
geometry: MeshGeometry,
format: MeshGeometry["format"] | undefined,
material: THREE.Material,
): Promise<THREE.Object3D> {
let loaded: THREE.Object3D;
if (format === "gltf" || format === "glb") {
const gltf = await this.gltfLoader.loadAsync(geometry.url);
loaded = gltf.scene;
} else if (format === "stl") {
const stl = await this.stlLoader.loadAsync(geometry.url);
loaded = new THREE.Mesh(stl, material);
} else if (format === "obj") {
loaded = await this.loadObjSource(geometry.url, material);
} else {
throw new Error(`unsupported mesh format: ${format ?? "unknown"}`);
}
loaded.traverse((child) => {
if ((child as THREE.Mesh).isMesh) {
const mesh = child as THREE.Mesh;
if (format === "obj" || format === "stl" || !mesh.material || Array.isArray(mesh.material)) {
mesh.material = material;
}
}
});
this.converter.applySourceBasis(loaded);
return loaded;
}
private async loadObjSource(url: string, material: THREE.Material): Promise<THREE.Object3D> {
if (!this.shouldUseFastObjParser(url)) {
return this.objLoader.loadAsync(url);
}
try {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`OBJ fetch failed ${response.status}`);
}
const parsed = await this.parseObjMeshResponse(response, material);
parsed.name = `fast_obj:${url}`;
this.fastObjParseCount += 1;
return parsed;
} catch {
this.objLoaderFallbackCount += 1;
return this.objLoader.loadAsync(url);
}
}
private shouldUseFastObjParser(url: string): boolean {
if (url.startsWith("blob:") || url.startsWith("data:")) {
return false;
}
try {
return new URL(url, window.location.href).pathname.includes("/assets/");
} catch {
return url.includes("/assets/");
}
}
private async parseObjMeshResponse(response: Response, material: THREE.Material): Promise<THREE.Object3D> {
if (!response.body) {
return this.parseObjMeshText(await response.text(), material);
}
const state = this.createObjParseState();
const reader = response.body.getReader();
const decoder = new TextDecoder();
let pending = "";
let streamChunkCount = 0;
let streamByteCount = 0;
try {
while (true) {
const { value, done } = await reader.read();
if (done) {
break;
}
streamChunkCount += 1;
streamByteCount += value.byteLength;
const text = pending + decoder.decode(value, { stream: true });
let lineStart = 0;
while (lineStart < text.length) {
const lineEnd = text.indexOf("\n", lineStart);
if (lineEnd === -1) {
break;
}
this.processObjLine(text.slice(lineStart, lineEnd), state);
lineStart = lineEnd + 1;
}
pending = text.slice(lineStart);
}
const remainder = pending + decoder.decode();
if (remainder.length > 0) {
this.processObjLine(remainder, state);
}
this.fastObjStreamChunkCount += streamChunkCount;
this.fastObjStreamByteCount += streamByteCount;
return this.finishObjParse(state, material);
} finally {
reader.releaseLock();
}
}
private parseObjMeshText(text: string, material: THREE.Material): THREE.Object3D {
const state = this.createObjParseState();
let lineStart = 0;
while (lineStart <= text.length) {
let lineEnd = text.indexOf("\n", lineStart);
if (lineEnd === -1) {
lineEnd = text.length;
}
this.processObjLine(text.slice(lineStart, lineEnd), state);
lineStart = lineEnd + 1;
}
return this.finishObjParse(state, material);
}
private createObjParseState(): ObjParseState {
return {
sourcePositions: [],
sourceNormals: [],
sourceUvs: [],
positions: [],
normals: [],
uvs: [],
positionCount: 0,
sourceNormalCount: 0,
sourceUvCount: 0,
normalCount: 0,
missingNormalCount: 0,
uvCount: 0,
missingUvCount: 0,
faceVertexCount: 0,
lineCount: 0,
};
}
private processObjLine(rawLine: string, state: ObjParseState): void {
const line = (rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine).trim();
state.lineCount += 1;
if (line.length === 0 || line.startsWith("#")) {
return;
}
const firstSpace = line.search(/\s/);
const keyword = firstSpace === -1 ? line : line.slice(0, firstSpace);
const body = firstSpace === -1 ? "" : line.slice(firstSpace + 1).trim();
if (keyword === "v") {
this.pushObjNumbers(body, 3, state.sourcePositions);
state.positionCount += 1;
} else if (keyword === "vn") {
this.pushObjNumbers(body, 3, state.sourceNormals);
state.sourceNormalCount += 1;
} else if (keyword === "vt") {
this.pushObjNumbers(body, 2, state.sourceUvs);
state.sourceUvCount += 1;
} else if (keyword === "f") {
const rawRefs = body.split(/\s+/).filter(Boolean);
if (rawRefs.length < 3) {
return;
}
const firstRef = this.parseObjVertexRef(rawRefs[0]!, state.positionCount, state.sourceUvCount, state.sourceNormalCount);
let previousRef = this.parseObjVertexRef(rawRefs[1]!, state.positionCount, state.sourceUvCount, state.sourceNormalCount);
for (let index = 2; index < rawRefs.length; index += 1) {
const nextRef = this.parseObjVertexRef(rawRefs[index]!, state.positionCount, state.sourceUvCount, state.sourceNormalCount);
this.appendObjRef(firstRef, state);
this.appendObjRef(previousRef, state);
this.appendObjRef(nextRef, state);
previousRef = nextRef;
}
}
}
private appendObjRef(ref: ObjVertexRef, state: ObjParseState): void {
this.pushObjVertex(
ref,
state.sourcePositions,
state.sourceUvs,
state.sourceNormals,
state.positions,
state.uvs,
state.normals,
);
if (ref.normal === undefined) {
state.missingNormalCount += 1;
} else {
state.normalCount += 1;
}
if (ref.uv === undefined) {
state.missingUvCount += 1;
} else {
state.uvCount += 1;
}
state.faceVertexCount += 1;
}
private finishObjParse(state: ObjParseState, material: THREE.Material): THREE.Object3D {
this.fastObjLineScanCount += state.lineCount;
if (state.faceVertexCount === 0 || state.positions.length === 0) {
throw new Error("OBJ has no faces");
}
const geometry = new THREE.BufferGeometry();
geometry.setAttribute("position", new THREE.Float32BufferAttribute(state.positions, 3));
if (state.uvCount > 0 && state.missingUvCount === 0) {
geometry.setAttribute("uv", new THREE.Float32BufferAttribute(state.uvs, 2));
}
if (state.normalCount > 0 && state.missingNormalCount === 0) {
geometry.setAttribute("normal", new THREE.Float32BufferAttribute(state.normals, 3));
} else {
geometry.computeVertexNormals();
}
geometry.computeBoundingBox();
geometry.computeBoundingSphere();
return new THREE.Mesh(geometry, material);
}
private pushObjNumbers(body: string, count: number, target: number[]): void {
const parts = body.split(/\s+/);
if (parts.length < count) {
throw new Error("OBJ numeric row is too short");
}
for (let index = 0; index < count; index += 1) {
const value = Number(parts[index]);
if (!Number.isFinite(value)) {
throw new Error("OBJ numeric row contains invalid number");
}
target.push(value);
}
}
private parseObjVertexRef(raw: string, positionCount: number, uvCount: number, normalCount: number): ObjVertexRef {
const [positionRaw, uvRaw, normalRaw] = raw.split("/");
return {
position: this.resolveObjIndex(positionRaw, positionCount),
uv: uvRaw ? this.resolveObjIndex(uvRaw, uvCount) : undefined,
normal: normalRaw ? this.resolveObjIndex(normalRaw, normalCount) : undefined,
};
}
private resolveObjIndex(raw: string | undefined, length: number): number {
const value = Number.parseInt(raw ?? "", 10);
if (!Number.isFinite(value) || value === 0) {
throw new Error("OBJ face contains invalid index");
}
const index = value > 0 ? value - 1 : length + value;
if (index < 0 || index >= length) {
throw new Error("OBJ face index is out of range");
}
return index;
}
private pushObjVertex(
ref: ObjVertexRef,
sourcePositions: number[],
sourceUvs: number[],
sourceNormals: number[],
positions: number[],
uvs: number[],
normals: number[],
): void {
const positionOffset = ref.position * 3;
if (positionOffset + 2 >= sourcePositions.length) {
throw new Error("OBJ vertex position is missing");
}
positions.push(sourcePositions[positionOffset]!, sourcePositions[positionOffset + 1]!, sourcePositions[positionOffset + 2]!);
if (ref.uv !== undefined) {
const uvOffset = ref.uv * 2;
if (uvOffset + 1 >= sourceUvs.length) {
throw new Error("OBJ uv is missing");
}
uvs.push(sourceUvs[uvOffset]!, sourceUvs[uvOffset + 1]!);
}
if (ref.normal !== undefined) {
const normalOffset = ref.normal * 3;
if (normalOffset + 2 >= sourceNormals.length) {
throw new Error("OBJ normal is missing");
}
normals.push(sourceNormals[normalOffset]!, sourceNormals[normalOffset + 1]!, sourceNormals[normalOffset + 2]!);
}
}
private retainMeshSourceResources(source: THREE.Object3D): void {
source.traverse((child) => {
if ((child as THREE.Mesh).isMesh) {
const mesh = child as THREE.Mesh;
if (mesh.geometry) {
this.retainedMeshGeometries.add(mesh.geometry);
}
if (mesh.material) {
for (const material of this.materialList(mesh.material)) {
this.retainedMeshMaterials.add(material);
}
}
}
});
}
private prepareLoadedMesh(loaded: THREE.Object3D): void {
let preFrozenStaticObjectCount = 0;
let spinningObjectCount = 0;
loaded.traverse((child) => {
if (child.userData.spin === true) {
spinningObjectCount += 1;
}
if ((child as THREE.Mesh).isMesh) {
const mesh = child as THREE.Mesh;
mesh.castShadow = !this.largeSceneMode;
mesh.receiveShadow = !this.largeSceneMode;
}
if (!this.canFreezeStaticObject(child)) {
return;
}
child.updateMatrix();
child.matrixAutoUpdate = false;
child.matrixWorldNeedsUpdate = true;
preFrozenStaticObjectCount += 1;
});
loaded.userData.preFrozenStaticObjectCount = preFrozenStaticObjectCount;
loaded.userData.hasSpinningObjects = spinningObjectCount > 0;
}
private applyBodyState(target: THREE.Object3D, bodyName: string, bodyState: BodyState): boolean {
let changed = false;
const isRobotBody = this.robotBodyNames.has(bodyName);
if (bodyState.pos) {
const nextPosition = this.converter.positionInto(bodyState.pos, this.scratchBodyPosition);
if (isRobotBody) {
nextPosition.add(this.converter.positionInto(this.robotOffsetPose, this.scratchBodyOffset));
} else {
const visualOffset = this.bodyVisualOffsets.get(bodyName);
if (visualOffset) {
nextPosition.add(this.converter.positionInto(visualOffset, this.scratchBodyOffset));
}
}
if (target.position.distanceToSquared(nextPosition) > 1e-12) {
target.position.copy(nextPosition);
changed = true;
}
} else if (isRobotBody) {
const baseSource = this.bodySourceOffsets.get(bodyName);
if (baseSource) {
this.scratchSourcePosition[0] = baseSource[0] + this.robotOffsetPose[0];
this.scratchSourcePosition[1] = baseSource[1] + this.robotOffsetPose[1];
this.scratchSourcePosition[2] = baseSource[2] + this.robotOffsetPose[2];
const nextPosition = this.converter.positionInto(this.scratchSourcePosition, this.scratchBodyPosition);
if (target.position.distanceToSquared(nextPosition) > 1e-12) {
target.position.copy(nextPosition);
changed = true;
}
}
}
if (bodyState.quat) {
const nextQuaternion = this.converter.quaternionInto(bodyState.quat, this.scratchBodyQuaternion);
if (Math.abs(target.quaternion.dot(nextQuaternion)) < 0.999999999) {
target.quaternion.copy(nextQuaternion);
changed = true;
}
}
if (changed) {
this.updateManualObjectMatrix(target);
}
return changed;
}
private isCachedBodyStateUnchanged(bodyName: string, bodyState: BodyState): boolean {
const cached = this.bodyStateCache.get(bodyName);
if (!cached) {
return false;
}
return this.vec3Equals(cached.pos, bodyState.pos) && this.quatEquals(cached.quat, bodyState.quat);
}
private cacheBodyState(bodyName: string, bodyState: BodyState): void {
this.bodyStateCache.set(bodyName, {
pos: bodyState.pos ? [bodyState.pos[0], bodyState.pos[1], bodyState.pos[2]] : undefined,
quat: bodyState.quat ? [bodyState.quat[0], bodyState.quat[1], bodyState.quat[2], bodyState.quat[3]] : undefined,
});
}
private vec3Equals(left: [number, number, number] | undefined, right: [number, number, number] | undefined): boolean {
if (!left || !right) {
return left === right;
}
return left[0] === right[0] && left[1] === right[1] && left[2] === right[2];
}
private quatEquals(
left: [number, number, number, number] | undefined,
right: [number, number, number, number] | undefined,
): boolean {
if (!left || !right) {
return left === right;
}
return left[0] === right[0] && left[1] === right[1] && left[2] === right[2] && left[3] === right[3];
}
private applyRobotPoseOffset(): void {
if (this.robotObjectIds.size === 0) {
return;
}
const offsetSource = this.robotOffsetPose;
for (const objectId of this.robotObjectIds) {
const bound = this.objectsById.get(objectId);
if (!bound || !bound.manifest.body) {
continue;
}
const baseSource = this.bodySourceOffsets.get(bound.manifest.body);
if (!baseSource) {
continue;
}
this.scratchSourcePosition[0] = baseSource[0] + offsetSource[0];
this.scratchSourcePosition[1] = baseSource[1] + offsetSource[1];
this.scratchSourcePosition[2] = baseSource[2] + offsetSource[2];
bound.root.position.copy(this.converter.positionInto(this.scratchSourcePosition, this.scratchBodyPosition));
this.updateManualObjectMatrix(bound.root);
}
}
private updateStatus(message: string): void {
this.statusElement.textContent = message;
}
}
function inferMeshFormat(url: string): MeshGeometry["format"] | undefined {
const lower = url.toLowerCase().split("?")[0];
if (lower.endsWith(".gltf")) return "gltf";
if (lower.endsWith(".glb")) return "glb";
if (lower.endsWith(".obj")) return "obj";
if (lower.endsWith(".stl")) return "stl";
return undefined;
}