@konitif/viewer-3d 0.285.6 → 0.285.8

package/dist/renderer/Viewer3DRenderer.js

@@ -1,3 +1,6 @@
+import { ViewerCardinalGridLayer } from './CardinalGridLayer.js';
+import { ViewerSceneEnvironmentLayer } from './SceneEnvironmentLayer.js';
+import { measureViewerOperation } from './PerformanceObservation.js';
 import { createViewerPhysicsFrameQuaternion, resolveViewerSceneYaw, projectViewerImpulseByFrame, projectViewerPointByFrame } from './physics/ViewerPhysicsFrame.js';
 import { resolveViewerJointMapping, selectDirectViewerJointMappings } from './physics/ViewerJointResolution.js';
 import { createPhysicsJointTargetValue, createVisualJointValueFromPhysics, createVisualJointValueFromSource } from './physics/ViewerPhysicsJointMapping.js';
@@ -257,6 +260,9 @@ export class Viewer3D {
     gridHelper = null;
     visualGroundLayer = null;
     keyLight = null;
+    cardinalGrid = null;
+    sceneDayCycle = null;
+    sceneFog = null;
     trajectoryGroup = null;
     contactPointGroup = null;
     physicsDebugGroup = null;
@@ -700,6 +706,12 @@ export class Viewer3D {
         }
         this.scheduleLoop();
     }
+    /** Signal a projection-only change made to caller-owned scene contributions.
+     * Uses the viewer's existing coalesced frame loop; does not advance simulation or transport.
+     */
+    requestPresentationFrame() {
+        this.requestRender();
+    }
     setStatsVisible(showStats) {
         if (this.options.showStats === showStats) {
             return;
@@ -729,6 +741,31 @@ export class Viewer3D {
             this.globalRafProbeFrame = 0;
         }
     }
+    /** Set a static local solar time; the caller owns persistence and playback. */
+    setSceneTimeHours(timeHours) {
+        this.sceneDayCycle ??= new ViewerSceneEnvironmentLayer(this.scene, this.renderer, this.keyLight, () => this.requestRender(), this.options.transparent);
+        this.sceneDayCycle.setFog(this.sceneFog);
+        this.sceneDayCycle.setTime(timeHours);
+    }
+    /** A null density delegates to the environment. Manual density survives day/night and theme changes. */
+    setSceneFog(settings) {
+        this.sceneFog = settings ? { enabled: settings.enabled, density: typeof settings.density === 'number' && Number.isFinite(settings.density) ? Math.max(0, Math.min(.5, settings.density)) : null } : null;
+        if (this.sceneDayCycle)
+            this.sceneDayCycle.setFog(this.sceneFog);
+        else
+            this.updateVisualGroundEnvironment();
+        this.requestRender();
+    }
+    setCardinalGridVisible(visible) {
+        if (visible)
+            this.cardinalGrid ??= new ViewerCardinalGridLayer(this.scene, () => this.controls.target, this.renderer.domElement.parentElement ?? undefined);
+        else {
+            this.cardinalGrid?.dispose();
+            this.cardinalGrid = null;
+        }
+        this.requestRender();
+    }
+    clearSceneTimeHours() { this.sceneDayCycle?.dispose(); this.sceneDayCycle = null; this.applyTheme(); }
     setGridVisible(showGrid) {
         if (this.options.showGrid === showGrid) {
             return;
@@ -1453,6 +1490,11 @@ export class Viewer3D {
     getPerformanceSummary() {
         return this.performanceMonitor.getSummary();
     }
+    performanceObserver = null;
+    /** Borrowed, optional sink. Does not allocate a loop, timer or browser observer. */
+    setPerformanceObserver(observer) {
+        this.performanceObserver = observer;
+    }
     setTemporalProjectionMode(mode) {
         if (this.temporalProjection.getMode() === mode) {
             return;
@@ -3144,6 +3186,11 @@ export class Viewer3D {
         this.requestRender();
     }
     destroy(options = {}) {
+        this.cardinalGrid?.dispose();
+        this.cardinalGrid = null;
+        this.sceneDayCycle?.dispose();
+        this.sceneDayCycle = null;
+        this.performanceObserver = null;
         if (this.destroyed) {
             return;
         }
@@ -3309,14 +3356,14 @@ export class Viewer3D {
         }
         this.updateVisualGroundShadowCasters();
         this.updateVisualGroundFocusTiltPasses();
-        const fogEnabled = this.options.showVisualGround && (config?.components.fogFade ?? true);
+        const fogEnabled = this.sceneFog?.enabled ?? (this.options.showVisualGround && (config?.components.fogFade ?? true));
         if (!fogEnabled || this.options.transparent) {
             this.scene.fog = null;
             return;
         }
         const themeBackgroundColor = this.resolveThemeColor('--color-background-canvas', '#111722');
         const fogColor = this.resolveVisualGroundSkyColor(themeBackgroundColor);
-        const fogDensity = config?.fogDensity ?? DEFAULT_VIEWER_VISUAL_GROUND_CONFIG.fogDensity;
+        const fogDensity = this.sceneFog?.density ?? config?.fogDensity ?? DEFAULT_VIEWER_VISUAL_GROUND_CONFIG.fogDensity;
         if (this.scene.fog instanceof FogExp2) {
             // Preserve the same fog authority while Viewer settings react. Replacing
             // the object on every layer update invalidated material state and could
@@ -3438,6 +3485,7 @@ export class Viewer3D {
         if (this.scene.fog instanceof FogExp2) {
             this.scene.fog.color.copy(backgroundColor);
         }
+        this.sceneDayCycle?.apply();
         if (!this.gridHelper) {
             this.requestRender();
             return;
@@ -3668,7 +3716,10 @@ export class Viewer3D {
         this.perspectiveCamera.near = planes.near;
         this.perspectiveCamera.far = planes.far;
         this.perspectiveCamera.updateProjectionMatrix();
-        this.orthographicCamera.near = planes.near;
+        // Orthographic projection has no perspective eye plane. Include geometry
+        // on both sides of the camera plane, especially the foreground floor
+        // at grazing angles; otherwise it is sliced by a positive near plane.
+        this.orthographicCamera.near = -planes.far;
         this.orthographicCamera.far = planes.far;
         this.orthographicCamera.updateProjectionMatrix();
     }
@@ -3936,6 +3987,9 @@ export class Viewer3D {
         if (!this.animationLoop.beginFrame()) {
             return;
         }
+        measureViewerOperation(this.performanceObserver, 'viewer.loop.cpu', () => this.runFrame());
+    };
+    runFrame() {
         const loopStartedAt = performance.now();
         const rafNow = loopStartedAt;
         this.temporalScheduler.frame(rafNow / 1000);
@@ -4012,7 +4066,7 @@ export class Viewer3D {
             const controlsStartedAt = performance.now();
             const shouldUpdateControls = this.controls.enabled && (this.controlsActive || this.controlsSettlingFrames > 0);
             if (shouldUpdateControls) {
-                this.controls.update();
+                measureViewerOperation(this.performanceObserver, 'viewer.controls.cpu', () => this.controls.update());
             }
             if (shouldUpdateControls) {
                 this.markFrameSignal('controls');
@@ -4097,8 +4151,12 @@ export class Viewer3D {
         if (shouldContinueLoop && this.animationLoop.isIdle()) {
             this.scheduleLoop();
         }
-    };
+    }
     render() {
+        measureViewerOperation(this.performanceObserver, 'viewer.draw.cpu', () => this.renderScene());
+    }
+    renderScene() {
+        this.cardinalGrid?.update(this.camera);
         this.projectComparisonSimulation();
         if (this.observedRobotGhostMirrorsSimulatedRobot) {
             this.syncObservedRobotGhostFromSimulatedRobot();
@@ -4814,6 +4872,11 @@ export class Viewer3D {
                     : undefined
         };
     }
+    /** Invalidate the on-demand projection after caller-owned scene changes. */
+    notifySceneChanged() {
+        if (!this.destroyed)
+            this.requestRender();
+    }
     requestRender() {
         this.animationLoop.requestRender();
     }
@@ -11063,8 +11126,8 @@ export class Viewer3D {
         this.updateViewerDebugLayers({ poseHandles: true });
     }
     setCameraPose(position, target = this.options.cameraTarget, up) {
-        if (this.options.cameraControlMode === 'orbit') {
-            const worldUpPose = resolveWorldUpCameraPose(new Vector3(position.x, position.y, position.z), new Vector3(target.x, target.y, target.z), up ? new Vector3(up.x, up.y, up.z) : this.camera.up);
+        if (this.options.cameraControlMode === 'orbit' && !up) {
+            const worldUpPose = resolveWorldUpCameraPose(new Vector3(position.x, position.y, position.z), new Vector3(target.x, target.y, target.z), this.camera.up);
             this.cameraController.setCameraPose(this.serializeCameraVector(worldUpPose.position), target, this.serializeCameraVector(worldUpPose.up));
             return;
         }
@@ -11108,13 +11171,13 @@ export class Viewer3D {
             z: Number(vector.z.toFixed(4))
         };
     }
-    transitionCameraPose(position, target = this.options.cameraTarget, durationMs = 420, up) {
-        if (this.options.cameraControlMode === 'orbit') {
+    transitionCameraPose(position, target = this.options.cameraTarget, durationMs = 420, up, transition = {}) {
+        if (this.options.cameraControlMode === 'orbit' && !transition.orbit) {
             const worldUpPose = resolveWorldUpCameraPose(new Vector3(position.x, position.y, position.z), new Vector3(target.x, target.y, target.z), up ? new Vector3(up.x, up.y, up.z) : this.camera.up);
-            this.cameraController.transitionCameraPose(this.serializeCameraVector(worldUpPose.position), target, durationMs, this.serializeCameraVector(worldUpPose.up));
+            this.cameraController.transitionCameraPose(this.serializeCameraVector(worldUpPose.position), target, durationMs, this.serializeCameraVector(worldUpPose.up), transition);
             return;
         }
-        this.cameraController.transitionCameraPose(position, target, durationMs, up);
+        this.cameraController.transitionCameraPose(position, target, durationMs, up, transition);
     }
     resetCameraView(durationMs = 520) {
         this.transitionCameraPose(VIEWER3D_DEFAULT_CAMERA_POSITION, VIEWER3D_DEFAULT_CAMERA_TARGET, durationMs, {