Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ API between minor releases.
- Keep close geometry visible and pickable in kilometre-scale models. Orthographic wheel zoom changes the
magnification around the cursor while keeping the camera at the same depth.
- Speed up picking in large instanced models by skipping the trailing instances outside the pick tile.
- Keep the toolbar and model warning usable in narrow windows. Localize element counts and label unavailable menu actions.
- Close the context menu on viewer shortcuts and let Esc stop a viewpoint tour without clearing the current work.
- Preserve an active section box when reopening its controls, stabilize edge-on plane rotation, and fix view cube interaction.

## [0.3.1] - 2026-11-13

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Built clean-room under the [IOExtend](https://github.com/IOExtend) organization.
| Home / End, Enter in the model tree | Jump to the first or last row, or select and zoom to the focused element |
| H / I / Shift+H | Hide selected / isolate selected / show all |
| F | Zoom to the selection, or fit the whole model when nothing is selected |
| Esc | Close the open menu or popup, or clear the measurement; otherwise clear the selection |
| Esc | Stop the viewpoint tour, close the open menu or popup, clear the measurement, or clear the selection, one action per press |

The model's up axis is +Z.

Expand Down
3 changes: 2 additions & 1 deletion docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,4 +128,5 @@ The model's up axis is +Z. The interface is in Russian when the browser language
- Shift+left drag selects with a box: left to right selects objects fully inside, right to left selects objects it touches.
- A right click without moving opens the context menu.
- H hides the selection, I isolates it, Shift+H shows everything, F zooms to the selection (or fits the model), Esc
closes menus or clears the selection.
stops the viewpoint tour, closes the open menu or popup, clears the measurement, or clears the selection. Each
Esc press handles one action.
378 changes: 189 additions & 189 deletions src/IOViewer/Viewer/dist/viewer.js

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions src/IOViewer/Viewer/src/i18n.js
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ const dictionaries = {
'menu.copyId': 'Копировать Id',
'menu.fitAll': 'Вписать всё',
'menu.resetSections': 'Сбросить сечения',
'menu.unavailable': 'Недоступно для этой модели',
searchPlaceholder: 'Поиск по имени, типу, Id…',
noCategory: 'Без категории',
noMatches: 'Ничего не найдено',
Expand Down Expand Up @@ -175,6 +176,7 @@ const dictionaries = {
'menu.copyId': 'Copy Id',
'menu.fitAll': 'Fit all',
'menu.resetSections': 'Reset sections',
'menu.unavailable': 'Unavailable for this model',
searchPlaceholder: 'Search by name, type, Id…',
noCategory: 'No category',
noMatches: 'No matches',
Expand Down Expand Up @@ -246,6 +248,7 @@ const dictionaries = {
};

export const lang = (globalThis.navigator?.language ?? '').toLowerCase().startsWith('ru') ? 'ru' : 'en';
export const formatCount = new Intl.NumberFormat(lang).format;

// `language` is for tests; the UI always uses `lang`.
export function t(key, language = lang) {
Expand Down
20 changes: 14 additions & 6 deletions src/IOViewer/Viewer/src/nav/controls.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import * as THREE from 'three';
import { isClick, orbit, zoomTowards, wheelZoomFactor, boxSelectMode, interpolateView } from './math.js';
import { isClick, orbit, zoomTowards, wheelZoomFactor, boxSelectMode, interpolateView, poleCrossing } from './math.js';

const ORBIT_SPEED = 0.005; // radians per pixel
const DEFAULT_DIRECTION = new THREE.Vector3(1, -1, 0.8).normalize();
Expand Down Expand Up @@ -180,18 +180,21 @@ export class NavigationControls extends EventTarget {
}

// Swings the camera round the target (see interpolateView).
animateTo({ position, target, zoom = 1 }, ms = 400) {
animateTo({ position, target, zoom = 1, overPole = false }, ms = 400) {
this._stopAnimation();
const from = { position: this.camera.position.clone(), target: this.target.clone() };
const to = { position: position ?? from.position, target: target ?? from.target };
const fromZoom = this.camera.zoom;
const interpolate = overPole
? poleCrossing(from, to, new THREE.Vector3(0, 1, 0).applyQuaternion(this.camera.quaternion), this.camera.up)
: (k) => interpolateView(from, to, k);
const start = performance.now();
const step = (now) => {
const k = Math.min((now - start) / ms, 1);
const eased = k * k * (3 - 2 * k);
const r = interpolateView(from, to, eased);
const r = interpolate(eased);
if (this.camera.isOrthographicCamera) this.camera.zoom = THREE.MathUtils.lerp(fromZoom, zoom, eased);
this._set(r.position, r.target);
this._set(r.position, r.target, r.up);
this._animation = k < 1 ? requestAnimationFrame(step) : 0;
};
this._animation = requestAnimationFrame(step);
Expand All @@ -207,10 +210,15 @@ export class NavigationControls extends EventTarget {
this._animation = 0;
}

_set(position, target) {
_set(position, target, screenUp) {
this.camera.position.copy(position);
this.target.copy(target);
this.camera.lookAt(target);
if (screenUp) {
const up = this.camera.up.clone();
this.camera.up.copy(screenUp);
this.camera.lookAt(target);
this.camera.up.copy(up);
} else this.camera.lookAt(target);
this.resize();
}

Expand Down
25 changes: 25 additions & 0 deletions src/IOViewer/Viewer/src/nav/math.js
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,31 @@ export function interpolateView(a, b, k) {
return { position, target };
}

// For a cube arrow over the far edge of a pole view, take the direct arc and spread the change in roll
// across the transition. World-up lookAt at the pole itself would flip the image in a single frame.
export function poleCrossing(from, to, startUp, worldUp) {
const start = from.position.clone().sub(from.target);
const end = to.position.clone().sub(to.target);
const startDistance = start.length();
const endDistance = end.length();
start.normalize();
end.normalize();
const turn = new THREE.Quaternion().setFromUnitVectors(start, end);
const carriedUp = startUp.clone().applyQuaternion(turn);
const endUp = new THREE.Vector3().setFromMatrixColumn(new THREE.Matrix4().lookAt(to.position, to.target, worldUp), 1);
const sine = end.dot(new THREE.Vector3().crossVectors(carriedUp, endUp));
const roll = Math.atan2(Math.abs(sine) < 1e-9 ? 0 : sine, carriedUp.dot(endUp));
const rotation = new THREE.Quaternion();
return (k) => {
rotation.identity().slerp(turn, k);
const direction = start.clone().applyQuaternion(rotation);
const target = from.target.clone().lerp(to.target, k);
const position = direction.clone().multiplyScalar(THREE.MathUtils.lerp(startDistance, endDistance, k)).add(target);
const up = startUp.clone().applyQuaternion(rotation).applyAxisAngle(direction, roll * k);
return { position, target, up };
};
}

function polar(position, target) {
const o = position.clone().sub(target);
const distance = o.length();
Expand Down
38 changes: 29 additions & 9 deletions src/IOViewer/Viewer/src/nav/viewCube.js
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ export function poleView(pole, offset) {
// - left/right turn the view 90 degrees about +Z; from a side face that is the face on that side of the screen.
// - up/down from a side face go to the top/bottom, keeping that face as the heading.
// - From the top, the heading side is at the bottom of the screen: down goes to it, up goes over the far edge to
// the opposite side face (the camera keeps +Z up, so it swings round rather than rolling upside down). From the
// the opposite side face. From the
// bottom it is the other way round.
export function arrowView(offset, arrow) {
const face = alignedFace(offset);
Expand Down Expand Up @@ -153,9 +153,19 @@ export class ViewCube {
this.scene.add(this.faces, edges, this.highlight);
this._raycaster = new THREE.Raycaster();
this.hovered = null;
this._pointer = null;

this.canvas.addEventListener('pointermove', (e) => this._hover(this.regionAtClient(e.clientX, e.clientY)));
this.canvas.addEventListener('pointerleave', () => this._hover(null));
this.element.addEventListener('contextmenu', (e) => e.preventDefault());
const hoverAtPointer = (e) => {
this._pointer = [e.clientX, e.clientY];
if (this._hover(this.regionAtClient(...this._pointer))) this._render();
};
this.canvas.addEventListener('pointerenter', hoverAtPointer);
this.canvas.addEventListener('pointermove', hoverAtPointer);
this.canvas.addEventListener('pointerleave', () => {
this._pointer = null;
if (this._hover(null)) this._render();
});
this.canvas.addEventListener('click', (e) => {
const region = this.regionAtClient(e.clientX, e.clientY);
if (!region) return;
Expand All @@ -166,11 +176,15 @@ export class ViewCube {
this.arrows = ['up', 'down', 'left', 'right'].map((arrow) => {
const button = iconButton('ioviewer-viewcube-arrow', icons.chevron, t(`cube.${arrow}`));
button.dataset.arrow = arrow;
button.addEventListener('click', () => this._arrow(arrow));
button.addEventListener('click', (e) => {
if (e.detail) button.blur();
this._arrow(arrow);
});
return button;
});
const home = iconButton('ioviewer-viewcube-home', icons.home, t('cube.home'));
home.addEventListener('click', () => {
home.addEventListener('click', (e) => {
if (e.detail) home.blur();
controls.resetCameraStyle();
controls.animateTo({ position: this.home.position.clone(), target: this.home.target.clone() });
});
Expand Down Expand Up @@ -217,11 +231,13 @@ export class ViewCube {
update() {
if (!this.renderer) return;
const main = this.controls.camera;
const turned = !this.camera.quaternion.equals(main.quaternion);
this.camera.quaternion.copy(main.quaternion);
this.camera.position.set(0, 0, 5).applyQuaternion(main.quaternion);
this.camera.updateMatrixWorld();
const aligned = alignedFace(main.position.clone().sub(this.controls.target)) !== null;
for (const button of this.arrows) button.hidden = !aligned;
if (turned && this._pointer) this._hover(this.regionAtClient(...this._pointer));
this._render();
}

Expand All @@ -235,7 +251,7 @@ export class ViewCube {
}

_hover(region) {
if (region === this.hovered) return;
if (region === this.hovered) return false;
this.hovered = region;
this.highlight.visible = !!region;
if (region) {
Expand All @@ -246,24 +262,28 @@ export class ViewCube {
this.highlight.scale.set(x[1] - x[0], y[1] - y[0], z[1] - z[0]);
this.highlight.position.set((x[0] + x[1]) / 2, (y[0] + y[1]) / 2, (z[0] + z[1]) / 2);
}
this._render();
return true;
}

_arrow(arrow) {
const main = this.controls.camera;
const offset = main.position.clone().sub(this.controls.target);
const direction = arrowView(offset, arrow);
if (direction) this._look(direction);
if (!direction) return;
const face = alignedFace(offset);
const overPole = (face === 'top' && arrow === 'up') || (face === 'bottom' && arrow === 'down');
this._look(direction, overPole);
}

// Looks at the target from `direction`, at the current distance.
_look(direction) {
_look(direction, overPole = false) {
const { controls } = this;
const distance = controls.camera.position.distanceTo(controls.target);
controls.animateTo({
position: direction.clone().multiplyScalar(distance).add(controls.target),
target: controls.target.clone(),
zoom: controls.camera.zoom,
overPole,
});
}
}
44 changes: 31 additions & 13 deletions src/IOViewer/Viewer/src/tools/sectionGizmo.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ import { closestOnLine, planeRect } from './sectionMath.js';

const GIZMO_PX = 80; // plane gizmo: arrow length on screen
const HANDLE_PX = 8; // box handle radius on screen
const RING_RADIUS = 0.8;
const RING_EDGE_SIN = Math.sin(THREE.MathUtils.degToRad(12));
const COLOR = { x: '#ef4444', y: '#22c55e', z: '#3b82f6', centre: '#e2e8f0', hover: '#facc15', frame: '#93c5fd', fill: '#60a5fa' };
const AXIS_KEYS = ['x', 'y', 'z'];
// An arrow or face handle whose axis is within 12 degrees of the line of sight is hidden: it would sit on top of the
Expand Down Expand Up @@ -108,7 +110,7 @@ export class SectionGizmo extends EventTarget {
arrow.name = 'arrow';
this.arrow = arrow;
const ring = (name, axis, turn) => {
const r = handle('rotate', COLOR[axis], [turn(new THREE.TorusGeometry(0.8, 0.018, 8, 64))], turn(new THREE.TorusGeometry(0.8, 0.09, 8, 48)));
const r = handle('rotate', COLOR[axis], [turn(new THREE.TorusGeometry(RING_RADIUS, 0.018, 8, 64))], turn(new THREE.TorusGeometry(RING_RADIUS, 0.09, 8, 48)));
r.name = name;
r.userData.axis = axis;
return r;
Expand Down Expand Up @@ -193,7 +195,7 @@ export class SectionGizmo extends EventTarget {
return this._raycaster.ray.clone();
}

// The shown handle under the pointer, or null.
// The intersection with the shown handle under the pointer, or null.
_hit(e) {
if (!this.camera) return null;
this.update(this.camera);
Expand All @@ -205,14 +207,15 @@ export class SectionGizmo extends EventTarget {
const proxies = [];
this.group.traverse((o) => o.userData.handle && shown(o) && proxies.push(o));
this._ray(e);
const hit = this._raycaster.intersectObjects(proxies, false)[0];
return hit ? hit.object.userData.handle : null;
return this._raycaster.intersectObjects(proxies, false)[0] ?? null;
}

_down(e) {
if (e.target !== this.dom || e.button !== 0) return;
const h = this._hit(e);
const start = h && this._start(h, this._ray(e));
const hit = this._hit(e);
if (!hit) return;
const h = hit.object.userData.handle;
const start = this._start(h, this._raycaster.ray, hit.point, e);
if (!start) return; // nothing to drag: the press goes on to the navigation
e.stopPropagation();
e.preventDefault();
Expand All @@ -222,7 +225,7 @@ export class SectionGizmo extends EventTarget {
}

// What a drag of handle h needs from its start, or null when the ray gives no usable start.
_start(h, ray) {
_start(h, ray, point, e) {
const s = this.sections;
const { kind } = h.userData;
if (kind === 'move' || kind === 'rotate') {
Expand All @@ -235,9 +238,19 @@ export class SectionGizmo extends EventTarget {
return s0 === null ? null : { index, origin, normal, offset: s.planes[index].offset, s0 };
}
const axis = new THREE.Vector3().setComponent(AXIS_KEYS.indexOf(h.userData.axis), 1).applyQuaternion(quaternion);
const rotation = { index, origin, quaternion, axis };
if (Math.abs(axis.dot(ray.direction)) < RING_EDGE_SIN) {
// An edge-on ring projects to a line. The picked side supplies the direction along it.
const line = axis.clone().cross(ray.direction).normalize();
const tangent = axis.clone().cross(point.clone().sub(origin));
if (line.dot(tangent) < 0) line.negate();
line.applyQuaternion(this.camera.quaternion.clone().invert());
const screen = new THREE.Vector2(line.x, -line.y).normalize().divideScalar(RING_RADIUS * GIZMO_PX);
return { ...rotation, screen, x: e.clientX, y: e.clientY };
}
const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(axis, origin);
const from = ray.intersectPlane(plane, new THREE.Vector3())?.sub(origin);
return from ? { index, origin, quaternion, axis, plane, from } : null;
return from ? { ...rotation, plane, from } : null;
}
const box = s.box.clone();
if (kind === 'face') {
Expand All @@ -258,16 +271,21 @@ export class SectionGizmo extends EventTarget {
if (!d) return this._hover(e);
if (e.pointerId !== d.id) return;
if (e.buttons === 0) return this._end();
const ray = this._ray(e);
const s = this.sections;
const { kind } = d.handle.userData;
const ray = d.screen ? null : this._ray(e);
if (kind === 'move') {
const along = closestOnLine(ray, d.origin, d.normal);
if (along !== null) s.updatePlane(d.index, { offset: d.offset + along - d.s0 });
} else if (kind === 'rotate') {
const to = ray.intersectPlane(d.plane, new THREE.Vector3())?.sub(d.origin);
if (!to) return;
const angle = Math.atan2(d.axis.dot(new THREE.Vector3().crossVectors(d.from, to)), d.from.dot(to));
let angle;
if (d.screen) {
angle = d.screen.x * (e.clientX - d.x) + d.screen.y * (e.clientY - d.y);
} else {
const to = ray.intersectPlane(d.plane, new THREE.Vector3())?.sub(d.origin);
if (!to) return;
angle = Math.atan2(d.axis.dot(new THREE.Vector3().crossVectors(d.from, to)), d.from.dot(to));
}
const quaternion = new THREE.Quaternion().setFromAxisAngle(d.axis, angle).multiply(d.quaternion);
// Turn about the gizmo point: the plane keeps passing through it.
const normal = Z.clone().applyQuaternion(quaternion);
Expand Down Expand Up @@ -300,7 +318,7 @@ export class SectionGizmo extends EventTarget {

_hover(e) {
if (e.buttons !== 0) return;
this._highlight(this._hit(e));
this._highlight(this._hit(e)?.object.userData.handle ?? null);
}

_highlight(h) {
Expand Down
20 changes: 12 additions & 8 deletions src/IOViewer/Viewer/src/ui/app.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { createShell } from './shell.js';
import { createToolbar, toolbarGroups } from './toolbar.js';
import { mountTree } from './tree.js';
import { createContextMenu } from './contextMenu.js';
import { installHotkeys } from './hotkeys.js';
import { hotkeyAction } from './hotkeys.js';
import { mountStatusBar, mountTruncationBanner, showToast } from './statusBar.js';
import { mountProperties } from './properties.js';

Expand Down Expand Up @@ -130,14 +130,18 @@ export function mountUI({ root, data, scene, controls, picker, selection, measur
});

const escapeHandlers = [];
installHotkeys(window, {
...actions,
contextMenu: () => openKeyboardMenu(document.activeElement ?? document.body),
// Esc closes an open menu and keeps the selection; otherwise a feature may use it; otherwise it clears the selection.
escape: () => {
if (contextMenu.isOpen) return contextMenu.close();
window.addEventListener('keydown', (e) => {
if (e.defaultPrevented) return;
const action = hotkeyAction(e);
if (!action) return;
e.preventDefault();
if (action === 'contextMenu') return openKeyboardMenu(document.activeElement ?? document.body);
if (action === 'escape' && !contextMenu.isOpen) {
if (!escapeHandlers.some((handle) => handle())) selection.clear();
},
return;
}
contextMenu.close();
if (action !== 'escape') actions[action]();
});
mountStatusBar(document.getElementById('ioviewer-status'), selection, scene.elementCount);
mountTruncationBanner(root, meta.truncated);
Expand Down
1 change: 1 addition & 0 deletions src/IOViewer/Viewer/src/ui/contextMenu.js
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ export function createContextMenu(root) {
button.dataset.item = id;
button.setAttribute('role', 'menuitem');
button.setAttribute('aria-disabled', String(!item.enabled));
if (!item.enabled) button.title = t('menu.unavailable');
button.append(el('span', '', t(`menu.${id}`)), el('kbd', '', shortcuts[id] ?? ''));
button.addEventListener('click', () => {
if (!item.enabled) return;
Expand Down
Loading
Loading