@preference-sl/pref-viewer 2.17.1 → 2.17.2-beta.1

package/README.md

@@ -6,7 +6,7 @@
 
 - Native custom elements: `<pref-viewer>`, `<pref-viewer-2d>`, `<pref-viewer-3d>`, `<pref-viewer-dialog>`, and `<pref-viewer-menu-3d>`.
 - Babylon.js-based 3D visualization for glTF and GLB assets.
-- Default-enabled, draggable 3D ViewCube with 26 selectable orientations: click a face, edge or corner for a smooth, model-fitted view, or drag the cube to orbit the model. It follows the camera in real time and works with perspective and orthographic cameras.
+- Default-enabled, draggable 3D ViewCube with 26 selectable orientations: click a face, edge or corner for a smooth, model-fitted view, or drag the cube to orbit the model. It follows the camera in real time, including its projection: the cube is orthographic for an orthographic viewer camera and perspective, with the same vertical FOV, for a perspective one.
 - Model-only, geometry-dependent orbital zoom protection with near-plane sampling, independent of ViewCube visibility.
 - Viewer dialogs above the render menu and ViewCube, with background pointer-input protection.
 - Proportional mouse-wheel zoom for unlocked orbital cameras: increments decrease as the camera approaches its target, using Babylon's native input without an additional viewer zoom increment. Wheel sensitivity is currently an internal setting, not a public attribute or option.
@@ -256,7 +256,7 @@ The inner view is the principal model view. English ViewCube face labels read `I
 | Top / Superior | +Y | Looks down toward the model. |
 | Bottom / Inferior | -Y | Looks up toward the model. |
 
-The cube is drawn on its own small canvas, with a separate Babylon.js engine and virtual scene, in a PrefSketch-style look: six square labelled faces, thin bars on the twelve edges and small spheres on the eight corners; there are no chamfers. Every part of an edge or corner selects the same orientation. The cube is always drawn with an orthographic camera, whatever the projection or FOV of the viewer camera, and it follows only the direction of the camera, independent of model zoom. It lives in its own scene, so it adds nothing to the model scene, to model picking or to exports.
+The cube is drawn on its own small canvas, with a separate Babylon.js engine and virtual scene, in a PrefSketch-style look: six square labelled faces, thin bars on the twelve edges and small spheres on the eight corners; there are no chamfers. Every part of an edge or corner selects the same orientation. The cube follows the projection and FOV of the viewer camera: it is drawn with an orthographic camera when the viewer camera is orthographic, and with a perspective camera using the same vertical FOV when it is perspective (the cube keeps the same on-screen size either way, and an FOV change redraws it). Apart from that it follows only the direction of the camera, independent of model zoom. It lives in its own scene, so it adds nothing to the model scene, to model picking or to exports.
 
 Hover paints the region under the pointer with `styles.colorPrimary` (`--pref-viewer-color-primary`). Any CSS colour syntax is accepted: hex, `rgb()`, `hsl()` or a named colour. The angularly nearest of the 26 views is shown as the current region, painted with the primary colour mixed 25% into the face fill; hover takes precedence until the pointer leaves. A primary-colour change is picked up within 250 ms, or immediately after a resize, a culture change or re-enabling the cube. The rest of the palette (face fill, borders, label text, edge bars and corner spheres) is a fixed light palette and is not configurable. There are no region tooltips.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.17.1",
+    "version": "2.17.2-beta.1",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-view-cube-controller.js

@@ -851,14 +851,15 @@ export default class BabylonJSViewCubeController {
      * @param {ArrayLike<number>} matrix - Camera view matrix elements.
      * @param {number} mode - Camera projection mode.
      * @param {boolean} rightHanded - Whether the scene is right-handed.
+     * @param {number} fov - Camera vertical field of view in radians.
      * @returns {boolean} Whether anything differs from the previous call.
      */
-    #updateGeometryKey(matrix, mode, rightHanded) {
+    #updateGeometryKey(matrix, mode, rightHanded, fov) {
         const key = this.#geometryKey;
-        if (key && key.mode === mode && key.rightHanded === rightHanded && key.matrix.every((value, i) => value === matrix[i])) {
+        if (key && key.mode === mode && key.rightHanded === rightHanded && key.fov === fov && key.matrix.every((value, i) => value === matrix[i])) {
             return false;
         }
-        this.#geometryKey = { matrix: Array.from(matrix), mode, rightHanded };
+        this.#geometryKey = { matrix: Array.from(matrix), mode, rightHanded, fov };
         return true;
     }
 
@@ -1114,7 +1115,7 @@ export default class BabylonJSViewCubeController {
                 this.#dirty = true;
             }
             const rightHanded = camera.getScene().useRightHandedSystem;
-            if (this.#updateGeometryKey(camera.getViewMatrix().m, camera.mode, rightHanded)) {
+            if (this.#updateGeometryKey(camera.getViewMatrix().m, camera.mode, rightHanded, camera.fov)) {
                 const pose = this.#readPose(camera);
                 const rotation = this.#rotationMatrix(pose.rotation);
                 const towardObserver = Vector3.TransformNormal(new Vector3(0, 0, rightHanded ? 1 : -1), rotation).normalize();
@@ -1124,7 +1125,7 @@ export default class BabylonJSViewCubeController {
                 const angles = anglesFromDirection(horizontal, this.#alpha);
                 if (angles) {
                     this.#alpha = angles.alpha;
-                    renderer.setPose(angles);
+                    renderer.setPose({ ...angles, mode: camera.mode, fov: camera.fov });
                 }
                 const nearest = this.#regions.reduce((best, r) => (Vector3.Dot(r.direction, towardObserver) > Vector3.Dot(best.direction, towardObserver) ? r : best));
                 renderer.setCurrent(nearest.id);

package/src/babylonjs-view-cube-renderer.js

@@ -20,6 +20,11 @@ const BORDER_INSET = 4;
 const BORDER_WIDTH = 4;
 const ORTHO_EXTENT = 1.15;
 const CAMERA_RADIUS = 5;
+const DEFAULT_FOV = 0.8;
+// Perspective depth range around the cube, which is at most ~0.87 from its centre (corner), so +-2 leaves margin.
+const PERSPECTIVE_DEPTH_MARGIN = 2;
+// Distance from the cube centre to a corner sphere centre (half the cube diagonal).
+const CORNER_DISTANCE = Math.sqrt(3) / 2;
 const TEXTURE_SIZE = 128;
 // Hits farther than this behind the nearest one are other sides of the cube, not overlapping parts.
 const PICK_DEPTH_TOLERANCE = 0.15;
@@ -82,8 +87,8 @@ const FACE_LABEL_KEYS = Object.freeze({ "1,0,0": "left", "-1,0,0": "right", "0,1
 /**
  * Renders the 3D view cube on its own Babylon.js engine and scene, bound to a small canvas.
  *
- * The scene is left-handed and Y-up like the viewer scene and its orthographic ArcRotateCamera uses the host
- * camera's alpha/beta unchanged, so no axis mirroring is needed. Every pickable mesh carries
+ * The scene is left-handed and Y-up like the viewer scene and its ArcRotateCamera (orthographic or perspective, following
+ * the host camera) uses the host camera's alpha/beta unchanged, so no axis mirroring is needed. Every pickable mesh carries
  * `metadata.regionId` equal to a VIEW_CUBE_DIRECTIONS id. The class owns no render loop and no
  * interaction logic: the host calls render() and decides what pick() results mean. It touches neither
  * `window` nor `document` itself, so it can be imported in any environment.
@@ -93,6 +98,8 @@ export default class BabylonJSViewCubeRenderer {
     #engine;
     #scene;
     #camera;
+    #mode = Camera.ORTHOGRAPHIC_CAMERA;
+    #fov = DEFAULT_FOV;
     #colors;
     #labels;
     #devicePixelRatio;
@@ -159,23 +166,34 @@ export default class BabylonJSViewCubeRenderer {
     }
 
     /**
-     * Orients the cube like the host camera.
-     * @param {{alpha: number, beta: number}} pose - Host camera angles in radians; beta is clamped away from the poles.
+     * Orients the cube like the host camera and follows its projection. An orthographic host gives an orthographic
+     * cube (radius 5, extents +-1.15). A perspective host gives a perspective cube with the host's vertical fov at
+     * radius 0.5 + 1.15 / tan(fov / 2), so the near face and its corner knobs keep the on-screen size of the
+     * orthographic layout (the rest of the cube foreshortens behind it).
+     * @param {{alpha: number, beta: number, mode?: number, fov?: number}} pose - Host camera angles in radians (beta is clamped away from the poles), projection mode (Camera.ORTHOGRAPHIC_CAMERA or Camera.PERSPECTIVE_CAMERA; absent keeps the last one) and vertical field of view in radians (absent or not a finite positive number keeps the last one, 0.8 initially).
      * @returns {void}
      */
-    setPose({ alpha, beta }) {
+    setPose({ alpha, beta, mode, fov }) {
         if (this.#disposed) {
             return;
         }
-        this.#camera.alpha = alpha;
-        this.#camera.beta = clampBeta(beta);
-        this.#camera.getViewMatrix(true);
+        const camera = this.#camera;
+        if (mode === Camera.ORTHOGRAPHIC_CAMERA || mode === Camera.PERSPECTIVE_CAMERA) {
+            this.#mode = mode;
+        }
+        if (typeof fov === "number" && Number.isFinite(fov) && fov > 0) {
+            this.#fov = fov;
+        }
+        this.#applyProjection(camera);
+        camera.alpha = alpha;
+        camera.beta = clampBeta(beta);
+        camera.getViewMatrix(true);
     }
 
     /**
      * Finds the region under a point. Coordinates are CSS pixels from the canvas top-left; they are scaled by
      * the canvas client size (falling back to the render size when the client size is unknown) and cast as an
-     * orthographic ray, so the result does not depend on hardware scaling. Corners win over edges and edges over
+     * ray (parallel for an orthographic cube, from the camera for a perspective one), so the result does not depend on hardware scaling. Corners win over edges and edges over
      * faces when they overlap on screen. A front-facing edge or corner whose projected centre is within the pick tolerance
      * of the pointer wins over the face under it (corners before edges, then the nearest centre). The tolerance is
      * min(8 CSS px, 1/12 of the cube side), so small cubes keep their face centres pickable. It also rescues a ray that
@@ -200,13 +218,16 @@ export default class BabylonJSViewCubeRenderer {
         const forward = camera.target.subtract(camera.position).normalize();
         const right = Vector3.Cross(camera.upVector, forward).normalize();
         const up = Vector3.Cross(forward, right);
-        const halfWidth = (camera.orthoRight - camera.orthoLeft) / 2;
-        const halfHeight = (camera.orthoTop - camera.orthoBottom) / 2;
-        const origin = camera.position
-            .add(right.scale((x / width * 2 - 1) * halfWidth))
-            .add(up.scale((1 - y / height * 2) * halfHeight));
+        const perspective = camera.mode === Camera.PERSPECTIVE_CAMERA;
+        // Half extents of the view plane through the cube centre: fixed for orthographic, radius * tan(fov / 2) for perspective.
+        const halfHeight = perspective ? camera.radius * Math.tan(camera.fov / 2) : (camera.orthoTop - camera.orthoBottom) / 2;
+        const halfWidth = perspective ? halfHeight * (width / height) : (camera.orthoRight - camera.orthoLeft) / 2;
+        const offset = right.scale((x / width * 2 - 1) * halfWidth).add(up.scale((1 - y / height * 2) * halfHeight));
+        const ray = perspective
+            ? new Ray(camera.position, forward.scale(camera.radius).add(offset).normalize(), 100)
+            : new Ray(camera.position.add(offset), forward, 100);
         const hits = this.#scene
-            .multiPickWithRay(new Ray(origin, forward, 100), (mesh) => Boolean(mesh.metadata?.regionId))
+            .multiPickWithRay(ray, (mesh) => Boolean(mesh.metadata?.regionId))
             .filter((hit) => hit.hit)
             .sort((a, b) => a.distance - b.distance);
         const near = this.#pickByTolerance(x, y, width, height, forward, computePickTolerance(Math.min(width, height)));
@@ -373,6 +394,25 @@ export default class BabylonJSViewCubeRenderer {
         return best?.id ?? null;
     }
 
+    // Orthographic: fixed radius and extents. Perspective: the host fov and the radius that frames the same half extent
+    // at the near face plane (CUBE_HALF in front of the centre), where the corner knobs and the face in view are drawn.
+    #applyProjection(camera) {
+        if (this.#mode === Camera.PERSPECTIVE_CAMERA) {
+            camera.mode = Camera.PERSPECTIVE_CAMERA;
+            camera.fovMode = Camera.FOVMODE_VERTICAL_FIXED;
+            camera.fov = this.#fov;
+            camera.radius = CUBE_HALF + ORTHO_EXTENT / Math.tan(this.#fov / 2);
+            // A wide fov brings the camera closer than the margin: keep the near plane positive and before the nearest corner.
+            camera.minZ = Math.max(camera.radius - PERSPECTIVE_DEPTH_MARGIN, Math.min(0.1, (camera.radius - CORNER_DISTANCE) / 2));
+            camera.maxZ = camera.radius + PERSPECTIVE_DEPTH_MARGIN;
+            return;
+        }
+        camera.mode = Camera.ORTHOGRAPHIC_CAMERA;
+        camera.radius = CAMERA_RADIUS;
+        camera.minZ = 0.1;
+        camera.maxZ = CAMERA_RADIUS * 4;
+    }
+
     #createCamera() {
         const camera = new ArcRotateCamera("view-cube-camera", Math.PI / 2, Math.PI / 2, CAMERA_RADIUS, Vector3.Zero(), this.#scene);
         camera.inputs.clear();
@@ -413,9 +453,10 @@ export default class BabylonJSViewCubeRenderer {
         const [x, y, z] = region.axes;
         const mesh = MeshBuilder.CreatePlane(`view-cube-face-${region.id}`, { size: CUBE_HALF * 2 }, this.#scene);
         mesh.position.set(x * CUBE_HALF, y * CUBE_HALF, z * CUBE_HALF);
-        // A plane shows its texture upright from -Z, so aim local +Z into the cube; text stays unmirrored from outside.
+        // Babylon's plane is visible, with its texture upright and unmirrored, from the side its normal points to; aim local
+        // +Z outward so back-face culling keeps the near faces (checked on screen: aimed inward, the far faces showed through).
         const up = y ? new Vector3(0, 0, -y) : Vector3.Up();
-        mesh.rotationQuaternion = Quaternion.FromLookDirectionLH(new Vector3(-x, -y, -z), up);
+        mesh.rotationQuaternion = Quaternion.FromLookDirectionLH(new Vector3(x, y, z), up);
         region.texture = new DynamicTexture(`view-cube-label-${region.id}`, this.#createLabelCanvas(), this.#scene, true);
         region.material.diffuseTexture = region.texture;
         region.material.emissiveColor = new Color3(EMISSIVE_SCALE, EMISSIVE_SCALE, EMISSIVE_SCALE);