diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml index ae0a7280..f7ed197b 100755 --- a/.github/workflows/desktop.yml +++ b/.github/workflows/desktop.yml @@ -132,6 +132,10 @@ jobs: # models end in a message, not in an empty canvas (#290) - name: Test the 3D viewer's mesh check run: node scripts/viewer-mesh.test.mjs + # which mouse drag rotates and which pans in each scheme of the + # viewer's Mouse setting (#459) + - name: Test the 3D viewer's mouse schemes + run: node scripts/viewer-input.test.mjs # the shared rules (labels, numbers, sizes, ages, state glyphs, # markdown-lite) against shared/test-vectors – the same vectors # src/ui_vectors.rs pins the server's Rust side to diff --git a/CHANGELOG.md b/CHANGELOG.md index 7375659a..bd937b30 100755 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,17 @@ see the notices in the README. ## [Unreleased] +### Added + +- **Panning in the 3D viewer** (#459), in the browser and the desktop app: + every drag only rotated before. Right or middle drag, Shift or Ctrl + drag, + a drag with both buttons, two fingers on a touch screen and Shift + arrow + keys move the model sideways; *Reset view* centres it again. The new + **mouse setting** below the view chooses which button rotates and which + pans (left, right or middle drag rotates; Shift + middle pans or rotates), + kept per browser and app. Right and middle drags no longer open the + context menu or start autoscroll on the canvas. + ## [0.2.13] - 2026-11-22 ### Fixed diff --git a/desktop/ui/js/workspace.js b/desktop/ui/js/workspace.js index 294e1df9..b6b89248 100755 --- a/desktop/ui/js/workspace.js +++ b/desktop/ui/js/workspace.js @@ -68,7 +68,7 @@ export function revViewer(tab, el) { }, f.filename + " v" + f.version); }))), h("div", null, [h("div.viewer-stage", null, [canvas, overlay]), h("div.viewer-bar", null, [status, h("div.row", null, [upBtn, resetBtn, stlBtn])]), - h("p.hint", { text: "Drag to rotate, wheel to zoom, arrow keys to turn, double-click to reset." })]) + h("p.hint", { text: "Drag to rotate, right-drag or Shift + drag to pan (other buttons: the mouse setting below the view), wheel to zoom, arrow keys to turn, double-click to reset." })]) ])); // the server converts the file into a mesh (pure Rust) – the app only draws it var versionId = tab.viewerVersion; diff --git a/docs/src/guide/desktop.md b/docs/src/guide/desktop.md index 43f788a9..e5e93319 100755 --- a/docs/src/guide/desktop.md +++ b/docs/src/guide/desktop.md @@ -330,7 +330,8 @@ account under a random computer name and can look at everything but change nothing. The app uses the same skins and 3D viewer as the web interface; the models are converted by the server, and *Loading* or the reason a model cannot be shown appears on the canvas of -the *3D viewer* tab (see [Files](files.md)); point clouds (PTS, XYZ, LAS, E57) have no +the *3D viewer* tab (see [Files](files.md), also for rotating, panning and +the mouse setting below the view); point clouds (PTS, XYZ, LAS, E57) have no *Export STL*, and a thinned cloud says so below the view. *Settings → Appearance*: *TeamCraft* (the default) follows the light or dark appearance of the operating system and switches with it, *TeamCraft Light* diff --git a/docs/src/guide/files.md b/docs/src/guide/files.md index d21aa9a9..fb3cebd5 100755 --- a/docs/src/guide/files.md +++ b/docs/src/guide/files.md @@ -59,7 +59,20 @@ group below the list, e.g. *2 files in other CAD formats (SolidWorks, Inventor)* Meshes, point clouds and STEP models open in a WebGL viewer in the browser and in the desktop app. Drag to rotate, wheel or pinch to zoom, arrow keys to -turn, double-click to reset; *Z up / Y up* switches the convention. Below the +turn, double-click to reset; *Z up / Y up* switches the convention. +**Panning** (moving the model sideways): right or middle drag, Shift or Ctrl + +drag, both buttons held, two fingers on a touch screen, or Shift + arrow +keys; *Reset view* centres the model again. Which button rotates and which +pans is the **mouse setting** below the view, kept per browser and app: + +| Setting | Rotate | Pan | +|--------------------------------------------|--------------------|-----------------------------------------| +| *Left drag rotates · right or middle pans* (default) | left drag | right or middle drag | +| *Right drag rotates · middle pans* | right or left drag | middle drag | +| *Middle drag rotates · Shift + middle pans* | middle or left drag | Shift + middle drag, right drag | +| *Middle drag pans · Shift + middle rotates* | Shift + middle or left drag | middle or right drag | + +Shift or Ctrl + left drag and a drag with both buttons always pan. Below the model, *Section X / Y / Z* cuts it open along a plane: the slider moves the plane through the model (its position is shown in model units), *flip* keeps the other side – for a look inside housings and assemblies. *Measure* picks diff --git a/scripts/viewer-input.test.mjs b/scripts/viewer-input.test.mjs new file mode 100644 index 00000000..2495ec5e --- /dev/null +++ b/scripts/viewer-input.test.mjs @@ -0,0 +1,61 @@ +// SPDX-License-Identifier: MPL-2.0 +// Unit tests of TeamCraftViewer.dragAction (shared/js/viewer.js): which mouse +// drag rotates and which pans in each scheme of the viewer's *Mouse* setting +// (#459). Plain Node.js, no packages; run by the CI job `ui`: +// +// node scripts/viewer-input.test.mjs +// +// viewer.js is a classic script that sets window.TeamCraftViewer; it runs +// here in a sandbox without a page (no #viewer-canvas, so it mounts nothing). +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import vm from "node:vm"; +import { fileURLToPath } from "node:url"; + +const file = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../shared/js/viewer.js"); +const sandbox = { window: {}, document: { getElementById: () => null } }; +vm.runInNewContext(fs.readFileSync(file, "utf8"), sandbox, { filename: file }); +const { dragAction, MOUSE_SCHEMES } = sandbox.window.TeamCraftViewer; + +const LEFT = 1, RIGHT = 2, MIDDLE = 4; +const schemes = MOUSE_SCHEMES.map((s) => s.id); + +// four schemes with their own ids and labels; the default is the first +assert.deepEqual(schemes, ["left-rotate", "right-rotate", "middle-rotate", "middle-pan"]); +assert.ok(MOUSE_SCHEMES.every((s) => s.label.length > 0)); + +// in every scheme: no button = nothing, a plain left drag rotates, Shift or +// Ctrl + left drag and the left and right button together pan – the +// combinations of the issue +for (const s of schemes) { + assert.equal(dragAction(s, 0, false, false), null, s); + assert.equal(dragAction(s, LEFT, false, false), "rotate", s); + assert.equal(dragAction(s, LEFT, true, false), "pan", `${s}: Shift + left`); + assert.equal(dragAction(s, LEFT, false, true), "pan", `${s}: Ctrl + left`); + assert.equal(dragAction(s, LEFT | RIGHT, false, false), "pan", `${s}: left + right`); +} + +// left drag rotates (default): right and middle pan +assert.equal(dragAction("left-rotate", RIGHT, false, false), "pan"); +assert.equal(dragAction("left-rotate", MIDDLE, false, false), "pan"); + +// right drag rotates: middle pans +assert.equal(dragAction("right-rotate", RIGHT, false, false), "rotate"); +assert.equal(dragAction("right-rotate", MIDDLE, false, false), "pan"); + +// middle drag rotates, Shift + middle pans; right pans +assert.equal(dragAction("middle-rotate", MIDDLE, false, false), "rotate"); +assert.equal(dragAction("middle-rotate", MIDDLE, true, false), "pan"); +assert.equal(dragAction("middle-rotate", RIGHT, false, false), "pan"); + +// middle drag pans, Shift + middle rotates; right pans +assert.equal(dragAction("middle-pan", MIDDLE, false, false), "pan"); +assert.equal(dragAction("middle-pan", MIDDLE, true, false), "rotate"); +assert.equal(dragAction("middle-pan", RIGHT, false, false), "pan"); + +// an unknown or missing scheme behaves like the default +assert.equal(dragAction("nonsense", RIGHT, false, false), "pan"); +assert.equal(dragAction(undefined, LEFT, false, false), "rotate"); + +console.log("viewer input: all checks passed"); diff --git a/shared/js/viewer.js b/shared/js/viewer.js index a804e2f6..1f427104 100755 --- a/shared/js/viewer.js +++ b/shared/js/viewer.js @@ -10,10 +10,12 @@ // Web pages mount the viewer through data attributes on #viewer-canvas; the // desktop app calls TeamCraftViewer.mount(canvas, options) with its own loader. // -// Mouse: drag = rotate, wheel = zoom, double-click = reset. Touch: one finger -// rotates, pinch zooms. Keyboard (canvas focused): arrows rotate, +/- zoom, -// 0 resets. Below the canvas a section plane (X, Y or Z, position, side) -// cuts the model open. +// Mouse: drag = rotate, right or middle drag (or Shift/Ctrl + drag) = pan – +// which button does what is the *Mouse* setting below the canvas (#459) –, +// wheel = zoom, double-click = reset. Touch: one finger rotates, two fingers +// pan and pinch zooms. Keyboard (canvas focused): arrows rotate, Shift + +// arrows pan, +/- zoom, 0 resets. Below the canvas a section plane (X, Y or +// Z, position, side) cuts the model open. (function () { "use strict"; @@ -48,6 +50,56 @@ return null; } + /** + * The mouse schemes of the viewer (#459): which drag rotates and which pans. + * In every scheme a plain left drag rotates, and Shift or Ctrl + left drag + * and a drag with the left and right button held pan – the combinations + * people try first. The choice is kept per browser (localStorage). + */ + var MOUSE_SCHEMES = [ + { id: "left-rotate", label: "Left drag rotates · right or middle pans" }, + { id: "right-rotate", label: "Right drag rotates · middle pans" }, + { id: "middle-rotate", label: "Middle drag rotates · Shift + middle pans" }, + { id: "middle-pan", label: "Middle drag pans · Shift + middle rotates" } + ]; + var MOUSE_KEY = "teamcraft-viewer-mouse"; + + /** + * What a drag does in `scheme`: "rotate", "pan" or null (no button held). + * `buttons` is PointerEvent.buttons (1 left, 2 right, 4 middle); an unknown + * scheme is the first one. + */ + function dragAction(scheme, buttons, shift, ctrl) { + var left = (buttons & 1) !== 0, right = (buttons & 2) !== 0, middle = (buttons & 4) !== 0; + if (!left && !right && !middle) return null; + if (left && right) return "pan"; + var leftDrag = shift || ctrl ? "pan" : "rotate"; + switch (scheme) { + case "right-rotate": + if (right) return "rotate"; + if (middle) return "pan"; + return leftDrag; + case "middle-rotate": + if (middle) return shift ? "pan" : "rotate"; + if (right) return "pan"; + return leftDrag; + case "middle-pan": + if (middle) return shift ? "rotate" : "pan"; + if (right) return "pan"; + return leftDrag; + default: + if (middle || right) return "pan"; + return leftDrag; + } + } + + /** The stored mouse scheme, or the first one. */ + function storedMouseScheme() { + var id = null; + try { id = window.localStorage.getItem(MOUSE_KEY); } catch (e) { /* blocked */ } + return MOUSE_SCHEMES.some(function (s) { return s.id === id; }) ? id : MOUSE_SCHEMES[0].id; + } + /** * Shows a model on `canvas`. * @@ -434,6 +486,7 @@ // zUp: CAD convention (NX, CATIA, FreeCAD, 3D printing); toggle for Y-up exports. var view = { yaw: -0.6, pitch: 0.45, dist: 1, center: [0, 0, 0], radius: 1, zUp: true }; var home = null; + var mouseScheme = storedMouseScheme(); // Model and canvas colours from the skin tokens (skins.css); read again // when the system switches between light and dark (the System skin). var baseColor, clearColor; @@ -589,6 +642,24 @@ el.appendChild(decimals); el.appendChild(result); + // Mouse: which drag rotates and which pans (#459), kept per browser. + var mouse = document.createElement("select"); + mouse.className = "small"; + mouse.setAttribute("aria-label", "Mouse buttons"); + mouse.title = "Which mouse drag rotates and which pans. Shift or Ctrl + left drag always pans."; + MOUSE_SCHEMES.forEach(function (s) { + var opt = document.createElement("option"); + opt.value = s.id; + opt.textContent = s.label; + mouse.appendChild(opt); + }); + mouse.value = mouseScheme; + mouse.addEventListener("change", function () { + mouseScheme = mouse.value; + try { window.localStorage.setItem(MOUSE_KEY, mouseScheme); } catch (e) { /* blocked */ } + }); + el.appendChild(mouse); + // Notes pinned to the model (design review), when the page offers them. if (notesApi) { var noteBtn = document.createElement("button"); @@ -664,7 +735,7 @@ view.center = [(b[0] + b[3]) / 2, (b[1] + b[4]) / 2, (b[2] + b[5]) / 2]; view.radius = Math.max(Math.hypot(size[0], size[1], size[2]) / 2, 1e-6); view.dist = view.radius * 2.8; - home = { yaw: view.yaw, pitch: view.pitch, dist: view.dist }; + home = { yaw: view.yaw, pitch: view.pitch, dist: view.dist, center: view.center.slice() }; function fmt(v) { return (Math.round(v * 100) / 100).toLocaleString(); } var what = mesh.indices ? (mesh.indices.length / 3).toLocaleString() + " triangles · " + mesh.parts.toLocaleString() + (mesh.parts === 1 ? " body" : " bodies") @@ -762,9 +833,28 @@ redraw(); } + // Moves the point the view turns around along the screen by (dx, dy) CSS + // pixels, so the model follows the pointer at the depth of that point. + // Rows 0 and 1 of the view rotation are the screen's right and up in + // model space (see `back` in pick); the point stays within a few model + // radii of the model's centre, so the model cannot be lost. + function pan(dx, dy) { + if (!home) return; + var rot = multiply(rotationX(view.pitch), rotationY(view.yaw)); + if (view.zUp) rot = multiply(rot, rotationX(-Math.PI / 2)); + var perPixel = 2 * view.dist * Math.tan(Math.PI / 8) / Math.max(canvas.clientHeight, 1); + var limit = view.radius * 4; + for (var i = 0; i < 3; i++) { + var c = view.center[i] - (rot[i * 4] * dx - rot[i * 4 + 1] * dy) * perPixel; + view.center[i] = Math.max(home.center[i] - limit, Math.min(home.center[i] + limit, c)); + } + redraw(); + } + function reset() { if (!home) return; view.yaw = home.yaw; view.pitch = home.pitch; view.dist = home.dist; + view.center = home.center.slice(); redraw(); } @@ -778,8 +868,12 @@ pointers[e.pointerId] = { x: e.clientX, y: e.clientY }; downAt = { x: e.clientX, y: e.clientY }; }); - // a click (not a drag) in measure mode picks a point + // right and middle drags pan or rotate: no context menu, no autoscroll + canvas.addEventListener("contextmenu", function (e) { e.preventDefault(); }); + canvas.addEventListener("mousedown", function (e) { if (e.button === 1) e.preventDefault(); }); + // a left click (not a drag) in measure mode picks a point canvas.addEventListener("pointerup", function (e) { + if (e.button !== 0) return; if (!(measure.on || noting) || !downAt || Math.hypot(e.clientX - downAt.x, e.clientY - downAt.y) > 4) return; var rect = canvas.getBoundingClientRect(); var hit = pick(e.clientX - rect.left, e.clientY - rect.top); @@ -805,8 +899,15 @@ var d = Math.hypot(e.clientX - other.x, e.clientY - other.y); if (pinch) zoom(pinch / Math.max(d, 1)); pinch = d; + // two fingers moving together pan: the midpoint moves half as far + pan((e.clientX - prev.x) / 2, (e.clientY - prev.y) / 2); } else { - rotate((e.clientX - prev.x) * 0.01, (e.clientY - prev.y) * 0.01); + var dx = e.clientX - prev.x, dy = e.clientY - prev.y; + // touch and pen: one contact rotates, like a left drag + var buttons = e.pointerType === "mouse" ? e.buttons : 1; + var action = dragAction(mouseScheme, buttons, e.shiftKey, e.ctrlKey); + if (action === "pan") pan(dx, dy); + else if (action === "rotate") rotate(dx * 0.01, dy * 0.01); } pointers[e.pointerId] = { x: e.clientX, y: e.clientY }; }); @@ -821,12 +922,12 @@ canvas.addEventListener("dblclick", reset); canvas.addEventListener("keydown", function (e) { if (e.ctrlKey || e.metaKey || e.altKey) return; // page shortcuts (zoom, …) - var step = 0.12; + var step = 0.12, shift = 40; // radians to turn, CSS pixels to pan switch (e.key) { - case "ArrowLeft": rotate(-step, 0); break; - case "ArrowRight": rotate(step, 0); break; - case "ArrowUp": rotate(0, -step); break; - case "ArrowDown": rotate(0, step); break; + case "ArrowLeft": if (e.shiftKey) pan(-shift, 0); else rotate(-step, 0); break; + case "ArrowRight": if (e.shiftKey) pan(shift, 0); else rotate(step, 0); break; + case "ArrowUp": if (e.shiftKey) pan(0, -shift); else rotate(0, -step); break; + case "ArrowDown": if (e.shiftKey) pan(0, shift); else rotate(0, step); break; case "+": case "=": zoom(0.85); break; case "-": case "_": zoom(1 / 0.85); break; case "0": reset(); break; @@ -943,7 +1044,7 @@ }; } - window.TeamCraftViewer = { mount: mount, checkMesh: checkMesh }; + window.TeamCraftViewer = { mount: mount, checkMesh: checkMesh, dragAction: dragAction, MOUSE_SCHEMES: MOUSE_SCHEMES }; // Web pages: . var canvas = document.getElementById("viewer-canvas"); diff --git a/templates/files/preview.html b/templates/files/preview.html index 8594e8af..a09733d7 100755 --- a/templates/files/preview.html +++ b/templates/files/preview.html @@ -47,7 +47,7 @@

{{ file.filename }}

Loading …

-

Drag to rotate, wheel or pinch to zoom, arrow keys to turn, double-click to reset. +

Drag to rotate, right-drag or Shift + drag to pan (other buttons: Mouse below the view), wheel or pinch to zoom, two fingers to pan, arrow keys to turn, double-click to reset. {% if is_brep %}STEP files are tessellated on the server (pure Rust B-rep kernel) the first time they are shown; large assemblies take a moment.{% endif %} {% if is_points %}Large point clouds are thinned out evenly for the preview.{% endif %} {% if is_result %}Simulation results show the outer surface of the mesh, coloured by a result field: vectors as magnitude, stress tensors as von Mises, cell data averaged to the nodes. Grey means no value.{% endif %}