refactoring

CHANGELOG.md

@@ -17,6 +17,10 @@ Note that since we don't clearly distinguish between a public and private interf
 - Fix bugs in ModelServer surroundingLigands endpoint, resulting in omitWater not honored
 - Fix `Volume` and `Isosurface` getBoundingSphere ignoring instances
 - Fix SSAO half/quarter resolution textures for multi-scale
+- Camera improvements 
+  - Add the option to approximate "least obstructed direction" when focusing camera, accessibe via `PluginContext.managers.camera.focusLoci` with `optimizeDirection` option
+  - Add `CameraFocusOptions.zoomOut` option that zooms out to to make the entire scene visible before focusing on the target
+  - Add easing support in camera transtion
 
 ## [v5.9.0] - 2026-05-03
 - Fix edge case when `PluginSpec.animations` is empty

src/apps/viewer/app.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2018-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -51,7 +51,7 @@ export { consoleStats, isDebugMode, isProductionMode, isTimingMode, setDebugMode
 import { decodeColor } from '../../mol-util/color/utils';
 import '../../mol-util/polyfill';
 import { ViewerAutoPreset } from './presets';
-import { CameraFocusOptions } from '../../mol-plugin-state/manager/camera';
+import { CameraFocusLociOptions } from '../../mol-plugin-state/manager/camera';
 import { PluginSpec } from '../../mol-plugin/spec';
 import { NoPrimaryFocusLociBindings } from '../../mol-plugin/behavior/dynamic/camera';
 
@@ -535,26 +535,33 @@ export class Viewer {
      * If neither `expression` nor `elements` are provided, all selections/highlights
      * will be cleared based on the specified `action`.
      */
-    structureInteractivity({ expression, elements, action, applyGranularity = false, filterStructure, focusOptions }: {
+    structureInteractivity({ expression, elements, action: action_, applyGranularity = false, filterStructure, focusOptions }: {
         expression?: (queryBuilder: typeof MolScriptBuilder) => Expression,
         elements?: StructureElement.Schema,
-        action: 'highlight' | 'select' | 'focus',
+        action: 'highlight' | 'select' | 'focus' | ('highlight' | 'select' | 'focus')[],
         applyGranularity?: boolean,
         filterStructure?: (structure: Structure) => boolean,
-        focusOptions?: Partial<CameraFocusOptions>
+        focusOptions?: Partial<CameraFocusLociOptions>
     }) {
         const plugin = this.plugin;
+        const actions = Array.isArray(action_) ? action_ : [action_];
 
         if (!expression && !elements) {
-            if (action === 'select') {
+            if (actions.includes('select')) {
                 plugin.managers.interactivity.lociSelects.deselectAll();
-            } else if (action === 'highlight') {
+            }
+            if (actions.includes('highlight')) {
                 plugin.managers.interactivity.lociHighlights.clearHighlights();
             }
             return;
         }
 
+        if (actions.includes('select')) {
+            plugin.managers.interactivity.lociSelects.deselectAll();
+        }
+
         const structures = this.plugin.state.data.selectQ(Q => Q.rootsOfType(PluginStateObject.Molecule.Structure));
+        let focused = false;
         for (const s of structures) {
             if (!s.obj?.data) continue;
 
@@ -564,13 +571,16 @@ export class Viewer {
                 ? StructureElement.Loci.fromExpression(s.obj.data, expression)
                 : StructureElement.Loci.fromSchema(s.obj.data, elements!);
 
-            if (action === 'select') {
-                plugin.managers.interactivity.lociSelects.select({ loci }, applyGranularity);
-            } else if (action === 'highlight') {
-                plugin.managers.interactivity.lociHighlights.highlight({ loci }, applyGranularity);
-            } else if (action === 'focus' && !StructureElement.Loci.isEmpty(loci)) {
-                plugin.managers.camera.focusLoci(loci, focusOptions);
-                return;
+            for (const action of actions) {
+                if (action === 'select') {
+                    plugin.managers.interactivity.lociSelects.select({ loci }, applyGranularity);
+                } else if (action === 'highlight') {
+                    plugin.managers.interactivity.lociHighlights.highlight({ loci }, applyGranularity);
+                } else if (action === 'focus' && !StructureElement.Loci.isEmpty(loci) && !focused) {
+                    plugin.managers.camera.focusLoci(loci, focusOptions);
+                    focused = true;
+                    if (actions.length === 1) return; // if only focusing, focus the first matching structure and return immediately
+                }
             }
         }
     }

src/extensions/mvs/helpers/animation.ts

@@ -6,7 +6,7 @@
  */
 
 import { SortedArray } from '../../../mol-data/int';
-import * as EasingFns from '../../../mol-math/easing';
+import { EasingFunctions } from '../../../mol-math/easing';
 import { clamp, lerp } from '../../../mol-math/interpolate';
 import { EPSILON, Mat3, Mat4, Quat, Vec3 } from '../../../mol-math/linear-algebra';
 import { RuntimeContext } from '../../../mol-task';
@@ -65,27 +65,7 @@ export async function generateStateTransition(ctx: RuntimeContext, snapshot: Sna
     return { tree, frametimeMs: dt, frames };
 }
 
-const EasingFnMap: Record<MVSAnimationEasing, (t: number) => number> = {
-    'linear': t => t,
-    'bounce-in': EasingFns.bounceIn,
-    'bounce-out': EasingFns.bounceOut,
-    'bounce-in-out': EasingFns.bounceInOut,
-    'circle-in': EasingFns.circleIn,
-    'circle-out': EasingFns.circleOut,
-    'circle-in-out': EasingFns.circleInOut,
-    'cubic-in': EasingFns.cubicIn,
-    'cubic-out': EasingFns.cubicOut,
-    'cubic-in-out': EasingFns.cubicInOut,
-    'exp-in': EasingFns.expIn,
-    'exp-out': EasingFns.expOut,
-    'exp-in-out': EasingFns.expInOut,
-    'quad-in': EasingFns.quadIn,
-    'quad-out': EasingFns.quadOut,
-    'quad-in-out': EasingFns.quadInOut,
-    'sin-in': EasingFns.sinIn,
-    'sin-out': EasingFns.sinOut,
-    'sin-in-out': EasingFns.sinInOut,
-};
+const EasingFnMap: Record<MVSAnimationEasing, (t: number) => number> = EasingFunctions;
 
 interface InterpolationCacheEntry {
     paletteFn?: (value: number) => Color,

src/mol-canvas3d/camera.ts

@@ -1,12 +1,12 @@
 /**
- * Copyright (c) 2018-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
 
 import { Viewport, cameraProject, cameraUnproject } from './camera/util';
-import { CameraTransitionManager } from './camera/transition';
+import { CameraTransitionManager, CameraTransitionOptions } from './camera/transition';
 import { BehaviorSubject, Subject } from 'rxjs';
 import { Scene } from '../mol-gl/scene';
 import { assertUnreachable } from '../mol-util/type-helpers';
@@ -138,8 +138,12 @@ export class Camera implements ICamera {
         return changed;
     }
 
-    setState(snapshot: Partial<Camera.Snapshot>, durationMs?: number) {
-        this.transition.apply(snapshot, durationMs);
+    setState(
+        snapshot: Partial<Camera.Snapshot>,
+        durationMs?: number,
+        options?: CameraTransitionOptions
+    ) {
+        this.transition.apply(snapshot, durationMs, undefined, options);
         this.stateChanged.next(snapshot);
     }
 

src/mol-canvas3d/camera/transition.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2018-2024 Mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2026 Mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  */
@@ -8,9 +8,17 @@ import { Camera } from '../camera';
 import { lerp } from '../../mol-math/interpolate';
 import { Quat } from '../../mol-math/linear-algebra/3d/quat';
 import { Vec3 } from '../../mol-math/linear-algebra/3d/vec3';
+import { EasingFunction, getEasingFn } from '../../mol-math/easing';
 
 export { CameraTransitionManager };
 
+export interface CameraTransitionOptions {
+    /** If present, approximates the transion between, [current] -> [keyframes] -> -> [target] */
+    keyframes?: CameraTransitionManager.TransitionKeyframes,
+    /** Global easing, if easing is specified for keyframes, the "end" frame value is used  */
+    easing?: EasingFunction
+}
+
 class CameraTransitionManager {
     private t = 0;
 
@@ -20,12 +28,18 @@ class CameraTransitionManager {
     private durationMs = 0;
     private _source: Camera.Snapshot = Camera.createDefaultSnapshot();
     private _target: Camera.Snapshot = Camera.createDefaultSnapshot();
+    private _options: CameraTransitionOptions | undefined = void 0;
     private _current = Camera.createDefaultSnapshot();
 
     get source(): Readonly<Camera.Snapshot> { return this._source; }
     get target(): Readonly<Camera.Snapshot> { return this._target; }
 
-    apply(to: Partial<Camera.Snapshot>, durationMs: number = 0, transition?: CameraTransitionManager.TransitionFunc) {
+    apply(
+        to: Partial<Camera.Snapshot>,
+        durationMs: number = 0,
+        transition?: CameraTransitionManager.TransitionFunc,
+        options?: CameraTransitionOptions,
+    ) {
         if (!this.inTransition || durationMs > 0) {
             Camera.copySnapshot(this._source, this.camera.state);
         }
@@ -50,6 +64,7 @@ class CameraTransitionManager {
 
         this.inTransition = true;
         this.func = transition || CameraTransitionManager.defaultTransition;
+        this._options = options;
 
         if (!this.inTransition || durationMs > 0) {
             this.start = this.t;
@@ -76,7 +91,7 @@ class CameraTransitionManager {
             return;
         }
 
-        this.func(this._current, normalized, this._source, this._target);
+        this.func(this._current, normalized, this._source, this._target, this._options);
         Camera.copySnapshot(this.camera.state, this._current);
     }
 
@@ -86,7 +101,8 @@ class CameraTransitionManager {
 }
 
 namespace CameraTransitionManager {
-    export type TransitionFunc = (out: Camera.Snapshot, t: number, source: Camera.Snapshot, target: Camera.Snapshot) => void
+    export type TransitionKeyframes = { t: number, snapshot: Partial<Camera.Snapshot>, easing?: EasingFunction }[]
+    export type TransitionFunc = (out: Camera.Snapshot, t: number, source: Camera.Snapshot, target: Camera.Snapshot, options?: { keyframes?: TransitionKeyframes }) => void
 
     const _rotUp = Quat.identity();
     const _rotDist = Quat.identity();
@@ -94,7 +110,58 @@ namespace CameraTransitionManager {
     const _sourcePosition = Vec3();
     const _targetPosition = Vec3();
 
-    export function defaultTransition(out: Camera.Snapshot, t: number, source: Camera.Snapshot, target: Camera.Snapshot): void {
+    let _tempSource: Camera.Snapshot | undefined = void 0;
+    let _tempTarget: Camera.Snapshot | undefined = void 0;
+
+    export function defaultTransition(
+        out: Camera.Snapshot,
+        t_: number,
+        source_: Camera.Snapshot,
+        target_: Camera.Snapshot,
+        options?: CameraTransitionOptions
+    ): void {
+        let sourcePartial: Partial<Camera.Snapshot> = source_;
+        let targetPartial: Partial<Camera.Snapshot> = target_;
+
+        let tStart = 0;
+        let tEnd = 1;
+        let easingKind = options?.easing;
+
+        const keyframes = options?.keyframes;
+        if (keyframes && keyframes.length > 0) {
+            for (let i = 0; i < keyframes.length; i++) {
+                const keyframe = keyframes[i];
+                if (t_ >= keyframe.t) {
+                    sourcePartial = keyframe.snapshot;
+                    tStart = keyframe.t;
+                    break;
+                }
+            }
+            for (let i = 0; i < keyframes.length; i++) {
+                const keyframe = keyframes[i];
+                if (keyframe.t >= t_) {
+                    targetPartial = keyframe.snapshot;
+                    tEnd = keyframe.t;
+                    easingKind = keyframe.easing ?? easingKind;
+                    break;
+                }
+            }
+        }
+
+        const easing = getEasingFn(easingKind);
+        const t = easing((t_ - tStart) / (tEnd - tStart));
+
+        if (!_tempSource) _tempSource = Camera.createDefaultSnapshot();
+        if (!_tempTarget) _tempTarget = Camera.createDefaultSnapshot();
+
+        Camera.copySnapshot(_tempSource, source_);
+        Camera.copySnapshot(_tempSource, sourcePartial);
+        Camera.copySnapshot(_tempTarget, target_);
+        Camera.copySnapshot(_tempTarget, targetPartial);
+
+        const source = _tempSource;
+        const target = _tempTarget;
+
         Camera.copySnapshot(out, target);
 
         // Rotate up

src/mol-canvas3d/canvas3d.ts

@@ -53,6 +53,8 @@ import { RayHelper } from './helper/ray-helper';
 import { produce } from '../mol-util/produce';
 import { ShaderManager } from './helper/shader-manager';
 import { toFixed } from '../mol-util/number';
+import type { CameraTransitionManager } from './camera/transition';
+import { EasingFunction } from '../mol-math/easing';
 
 export const CameraFogParams = {
     intensity: PD.Numeric(15, { min: 1, max: 100, step: 1 }),
@@ -321,6 +323,13 @@ namespace Canvas3DContext {
 
 export { Canvas3D };
 
+export interface Canvas3DCameraResetOptions {
+    durationMs?: number,
+    snapshot?: Camera.SnapshotProvider,
+    keyframes?: CameraTransitionManager.TransitionKeyframes,
+    easing?: EasingFunction,
+}
+
 interface Canvas3D {
     readonly webgl: WebGLContext,
 
@@ -371,7 +380,7 @@ interface Canvas3D {
     /** performs handleResize on the next animation frame */
     requestResize(): void
     /** Focuses camera on scene's bounding sphere, centered and zoomed. */
-    requestCameraReset(options?: { durationMs?: number, snapshot?: Camera.SnapshotProvider }): void
+    requestCameraReset(options?: Canvas3DCameraResetOptions): void
     readonly camera: Camera
     readonly boundingSphere: Readonly<Sphere3D>
     readonly boundingSphereVisible: Readonly<Sphere3D>
@@ -498,8 +507,12 @@ namespace Canvas3D {
         });
 
         let cameraResetRequested = false;
-        let nextCameraResetDuration: number | undefined = void 0;
-        let nextCameraResetSnapshot: Camera.SnapshotProvider | undefined = void 0;
+        const nextCameraResetOptions: Canvas3DCameraResetOptions = {
+            durationMs: undefined,
+            snapshot: undefined,
+            keyframes: undefined,
+            easing: undefined,
+        };
         let resizeRequested = false;
 
         //
@@ -878,15 +891,18 @@ namespace Canvas3D {
             }
 
             if (radius > 0) {
-                const duration = nextCameraResetDuration === undefined ? p.cameraResetDurationMs : nextCameraResetDuration;
+                const duration = nextCameraResetOptions.durationMs === undefined ? p.cameraResetDurationMs : nextCameraResetOptions.durationMs;
                 const focus = camera.getFocus(center, radius);
-                const next = typeof nextCameraResetSnapshot === 'function' ? nextCameraResetSnapshot(scene, camera) : nextCameraResetSnapshot;
+                const next = typeof nextCameraResetOptions.snapshot === 'function' ? nextCameraResetOptions.snapshot(scene, camera) : nextCameraResetOptions.snapshot;
                 const snapshot = next ? { ...focus, ...next } : focus;
-                camera.setState({ ...snapshot, radiusMax: getSceneRadius() }, duration);
+                camera.setState({ ...snapshot, radiusMax: getSceneRadius() }, duration, { keyframes: nextCameraResetOptions.keyframes, easing: nextCameraResetOptions.easing });
             }
 
-            nextCameraResetDuration = void 0;
-            nextCameraResetSnapshot = void 0;
+            nextCameraResetOptions.durationMs = void 0;
+            nextCameraResetOptions.snapshot = void 0;
+            nextCameraResetOptions.keyframes = void 0;
+            nextCameraResetOptions.easing = void 0;
+
             cameraResetRequested = false;
         }
 
@@ -896,7 +912,7 @@ namespace Canvas3D {
         function shouldResetCamera() {
             if (camera.state.radiusMax === 0) return true;
 
-            if (camera.transition.inTransition || nextCameraResetSnapshot) return false;
+            if (camera.transition.inTransition || nextCameraResetOptions.snapshot) return false;
 
             let cameraSphereOverlapsNone = true, isEmpty = true;
             Sphere3D.set(cameraSphere, camera.state.target, camera.state.radius);
@@ -938,7 +954,7 @@ namespace Canvas3D {
             if (!p.camera.manualReset && (reprCount.value === 0 || shouldResetCamera())) {
                 cameraResetRequested = true;
             }
-            if (oldBoundingSphereVisible.radius === 0) nextCameraResetDuration = 0;
+            if (oldBoundingSphereVisible.radius === 0) nextCameraResetOptions.durationMs = 0;
 
             if (!p.camera.manualReset) camera.setState({ radiusMax: getSceneRadius() }, 0);
             reprCount.next(reprRenderObjects.size);
@@ -1222,7 +1238,7 @@ namespace Canvas3D {
             syncVisibility: () => {
                 if (camera.state.radiusMax === 0) {
                     cameraResetRequested = true;
-                    nextCameraResetDuration = 0;
+                    nextCameraResetOptions.durationMs = 0;
                 }
 
                 if (scene.syncVisibility()) {
@@ -1251,8 +1267,7 @@ namespace Canvas3D {
                 resizeRequested = true;
             },
             requestCameraReset: options => {
-                nextCameraResetDuration = options?.durationMs;
-                nextCameraResetSnapshot = options?.snapshot;
+                Object.assign(nextCameraResetOptions, options);
                 cameraResetRequested = true;
             },
             camera,

src/mol-math/easing.ts

@@ -1,7 +1,8 @@
 /**
- * Copyright (c) 2018 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-26 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ * @author David Sehnal <david.sehnal@gmail.com>
  *
  * adapted from https://github.com/d3/d3-ease
  */
@@ -103,3 +104,33 @@ export function sinInOut(t: number) {
 }
 
 //
+
+export const EasingFunctions = {
+    'linear': (t: number) => t,
+    'bounce-in': bounceIn,
+    'bounce-out': bounceOut,
+    'bounce-in-out': bounceInOut,
+    'circle-in': circleIn,
+    'circle-out': circleOut,
+    'circle-in-out': circleInOut,
+    'cubic-in': cubicIn,
+    'cubic-out': cubicOut,
+    'cubic-in-out': cubicInOut,
+    'exp-in': expIn,
+    'exp-out': expOut,
+    'exp-in-out': expInOut,
+    'quad-in': quadIn,
+    'quad-out': quadOut,
+    'quad-in-out': quadInOut,
+    'sin-in': sinIn,
+    'sin-out': sinOut,
+    'sin-in-out': sinInOut,
+};
+
+export type EasingKind = keyof typeof EasingFunctions;
+export type EasingFunction = EasingKind | ((t: number) => number);
+
+export function getEasingFn(easing: EasingFunction | undefined): (t: number) => number {
+    if (!easing) return EasingFunctions.linear;
+    return typeof easing === 'function' ? easing : EasingFunctions[easing] ?? EasingFunctions.linear;
+}

src/mol-math/linear-algebra/3d/mat3.ts

@@ -150,6 +150,10 @@ namespace Mat3 {
         return areEqual(m, _id, typeof eps === 'undefined' ? EPSILON : eps);
     }
 
+    export function is(a: any): a is Mat3 {
+        return Array.isArray(a) && a.length === 9;
+    }
+
     export function hasNaN(m: Mat3) {
         for (let i = 0; i < 9; i++) if (Number.isNaN(m[i])) return true;
         return false;

src/mol-math/linear-algebra/3d/mat4.ts

@@ -110,6 +110,10 @@ namespace Mat4 {
         return areEqual(m, _id, typeof eps === 'undefined' ? EPSILON : eps);
     }
 
+    export function is(a: any): a is Mat4 {
+        return Array.isArray(a) && a.length === 16;
+    }
+
     export function hasNaN(m: Mat4) {
         for (let i = 0; i < 16; i++) if (Number.isNaN(m[i])) return true;
         return false;

src/mol-math/linear-algebra/3d/optimize-direction.ts

@@ -0,0 +1,184 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { Vec3 } from './vec3';
+import { EVD } from '../matrix/evd';
+import { Matrix } from '../matrix/matrix';
+
+export interface LeastObstructedDirectionOptions {
+    /** Optional centroid/origin. If omitted, centroid is computed from the provided points. */
+    origin?: Vec3,
+
+    /** Optional Gaussian falloff distance. If omitted, all points have weight 1. */
+    sigma?: number,
+
+    /** Ignore points closer than this to the origin. */
+    minDistance?: number,
+}
+
+function eachPosition(points: ReadonlyArray<Vec3> | { x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number> }, callback: (x: number, y: number, z: number) => void) {
+    if (Array.isArray(points)) {
+        for (const p of points) {
+            callback(p[0], p[1], p[2]);
+        }
+    } else {
+        const { x, y, z } = points as { x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number> };
+        const n = Math.min(x.length, y.length, z.length);
+        for (let i = 0; i < n; i++) {
+            callback(x[i], y[i], z[i]);
+        }
+    }
+}
+
+/**
+ * Estimate a visually open camera direction around a selection.
+ *
+ * Geometric intuition:
+ *
+ * The selection centroid is treated as the origin. Each nearby obstruction
+ * point is converted into a unit direction on the sphere around the selection:
+ *
+ *     v_i = normalize(p_i - origin)
+ *
+ * We then build the directional second-moment matrix:
+ *
+ *     M = sum_i w_i v_i v_i^T
+ *
+ * For any candidate view direction `u`, the quadratic form
+ *
+ *     u^T M u
+ *
+ * expands to:
+ *
+ *     sum_i w_i (u · v_i)^2
+ *
+ * Since `u · v_i = cos(theta_i)`, this value is large when `u` is aligned
+ * with many obstruction directions and small when `u` is mostly perpendicular
+ * to them. Therefore, the eigenvector of `M` with the smallest eigenvalue is
+ * the axis that is least aligned, in a least-squares sense, with the nearby
+ * obstruction directions.
+ *
+ * This gives an unoriented axis: `u` and `-u` have the same score because the
+ * dot products are squared. To choose the camera-facing side, we compute the
+ * weighted mean obstruction direction:
+ *
+ *     m = sum_i w_i v_i
+ *
+ * and return the sign of the axis that points away from this mean direction.
+ *
+ * In short:
+ *
+ * - project nearby points onto a sphere around the selection;
+ * - find the sparsest angular axis using the smallest eigenvector of their
+ *   second-moment matrix;
+ * - choose the side of that axis opposite the average obstruction direction.
+ *
+ * This is a fast, deterministic heuristic. It minimizes average squared
+ * angular alignment with nearby points; it is not the exact largest-empty-cone
+ * or maximum-clearance solution.
+ *
+ * The returned vector is a unit direction from the selection centroid toward
+ * the camera.
+ */
+export function leastObstructedDirection(
+    points: ReadonlyArray<Vec3> | { x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number> },
+    options: LeastObstructedDirectionOptions = {}
+): Vec3 | undefined {
+    const origin = options.origin;
+    const minDistance = options.minDistance ?? 1e-6;
+    const minDistanceSq = minDistance * minDistance;
+
+    const sigma = options.sigma;
+    const useWeights = sigma !== void 0 && sigma > 0;
+    const twoSigmaSq = useWeights ? 2 * sigma * sigma : 1;
+
+    // Directional second moment:
+    // M = sum_i w_i v_i v_i^T
+    const evd = EVD.createCache(3);
+    const M = evd.matrix;
+    Matrix.makeZero(M);
+
+    // Weighted mean direction, used only to choose sign.
+    const mean = Vec3.zero();
+
+    let count = 0;
+    let weightSum = 0;
+
+    eachPosition(points, (x_, y_, z_) => {
+        let x = x_, y = y_, z = z_;
+        if (origin) {
+            x -= origin[0];
+            y -= origin[1];
+            z -= origin[2];
+        }
+
+        const dSq = x * x + y * y + z * z;
+        if (dSq <= minDistanceSq) return;
+
+        const d = Math.sqrt(dSq);
+        const invD = 1 / d;
+
+        // Unit obstruction direction v.
+        x *= invD;
+        y *= invD;
+        z *= invD;
+
+        const w = useWeights ? Math.exp(-dSq / twoSigmaSq) : 1;
+
+        // Accumulate symmetric matrix.
+        //
+        // M = [
+        //   xx xy xz
+        //   xy yy yz
+        //   xz yz zz
+        // ]
+        Matrix.add(M, 0, 0, w * x * x);
+        Matrix.add(M, 0, 1, w * x * y);
+        Matrix.add(M, 0, 2, w * x * z);
+
+        Matrix.add(M, 1, 0, w * y * x);
+        Matrix.add(M, 1, 1, w * y * y);
+        Matrix.add(M, 1, 2, w * y * z);
+
+        Matrix.add(M, 2, 0, w * z * x);
+        Matrix.add(M, 2, 1, w * z * y);
+        Matrix.add(M, 2, 2, w * z * z);
+
+        mean[0] += w * x;
+        mean[1] += w * y;
+        mean[2] += w * z;
+
+        count++;
+        weightSum += w;
+    });
+
+    if (count === 0 || weightSum <= 0) {
+        return undefined;
+    }
+
+    EVD.compute(evd);
+
+    // EVD sorts eigenvalues ascending, so column 0 is the smallest eigenvector.
+    const dir = Vec3.create(
+        Matrix.get(M, 0, 0),
+        Matrix.get(M, 1, 0),
+        Matrix.get(M, 2, 0)
+    );
+
+    if (Vec3.magnitude(dir) < 1e-6) {
+        return undefined;
+    }
+
+    Vec3.normalize(dir, dir);
+
+    // Pick the less-obstructed side of the axis:
+    // choose the sign opposite the weighted mean obstruction direction.
+    if (Vec3.dot(dir, mean) > 0) {
+        Vec3.scale(dir, dir, -1);
+    }
+
+    return dir;
+}

src/mol-math/linear-algebra/3d/quat.ts

@@ -71,6 +71,10 @@ namespace Quat {
         return out;
     }
 
+    export function is(a: any): a is Quat {
+        return Array.isArray(a) && a.length === 4;
+    }
+
     export function setAxisAngle(out: Quat, axis: Vec3, rad: number) {
         rad = rad * 0.5;
         const s = Math.sin(rad);

src/mol-math/linear-algebra/3d/vec2.ts

@@ -58,6 +58,10 @@ namespace Vec2 {
         return Number.isNaN(a[0]) || Number.isNaN(a[1]);
     }
 
+    export function is(a: any): a is Vec2 {
+        return Array.isArray(a) && a.length === 2;
+    }
+
     export function toArray<T extends NumberArray>(a: Vec2, out: T, offset: number) {
         out[offset + 0] = a[0];
         out[offset + 1] = a[1];

src/mol-math/linear-algebra/3d/vec3.ts

@@ -48,6 +48,10 @@ export namespace Vec3 {
         return out;
     }
 
+    export function is(a: any): a is Vec3 {
+        return Array.isArray(a) && a.length === 3;
+    }
+
     export function isFinite(a: Vec3): boolean {
         return _isFinite(a[0]) && _isFinite(a[1]) && _isFinite(a[2]);
     }

src/mol-math/linear-algebra/3d/vec4.ts

@@ -71,6 +71,10 @@ namespace Vec4 {
         return Number.isNaN(a[0]) || Number.isNaN(a[1]) || Number.isNaN(a[2]) || Number.isNaN(a[3]);
     }
 
+    export function is(a: any): a is Vec4 {
+        return Array.isArray(a) && a.length === 4;
+    }
+
     export function toArray<T extends NumberArray>(a: Vec4, out: T, offset: number) {
         out[offset + 0] = a[0];
         out[offset + 1] = a[1];

src/mol-math/linear-algebra/_spec/optimize-direction.spec.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { Vec3 } from '../3d/vec3';
+import { leastObstructedDirection } from '../3d/optimize-direction';
+
+describe('OptimizeDirection', () => {
+    it('works more or less as expected', () => {
+        const points: Vec3[] = [
+            Vec3.create(1, 0, 0),
+            Vec3.create(-1, 0, 0),
+            Vec3.create(0, 1, 0),
+            Vec3.create(0, -1, 0),
+            Vec3.create(0, 0, 1),
+        ];
+        const dir = leastObstructedDirection(points);
+
+        console.log('dir', dir);
+        expect(dir).toBeDefined();
+        expect(dir[0]).toBeCloseTo(0, 6);
+        expect(dir[1]).toBeCloseTo(0, 6);
+        expect(dir[2]).toBeCloseTo(-1, 6);
+    });
+});

src/mol-model/structure/structure/element/loci.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2017-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2017-2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -572,6 +572,42 @@ export namespace Loci {
         return Loci(loci.structure, elements);
     }
 
+    export function extendToRadius(loci: Loci, radius: number): Loci {
+        const elementsByUnit = new Map<number, Set<UnitIndex>>();
+
+        const lookup = loci.structure.lookup3d;
+        const pos = Vec3();
+        forEachLocation(loci, loc => {
+            loc.unit.conformation.position(loc.element, pos);
+            const result = lookup.find(pos[0], pos[1], pos[2], radius);
+            for (let i = 0, il = result.count; i < il; ++i) {
+                const unit = result.units[i];
+                const unitIdx = result.indices[i];
+                let set: Set<UnitIndex> = elementsByUnit.get(unit.id) as Set<UnitIndex>;
+                if (!set) {
+                    set = new Set();
+                    elementsByUnit.set(unit.id, set);
+                }
+                set.add(unitIdx);
+            }
+        });
+
+
+        const elements: Element[] = [];
+        for (const [unitId, indexSet] of elementsByUnit.entries()) {
+            const unit = loci.structure.unitMap.get(unitId)!;
+            const indices = Array.from(indexSet) as UnitIndex[];
+            indices.sort((a, b) => a - b);
+            elements.push({ unit, indices: makeIndexSet(indices) });
+        }
+
+        return {
+            kind: 'element-loci',
+            structure: loci.structure,
+            elements,
+        };
+    }
+
     //
 
     const boundaryHelper = new BoundaryHelper('98');

src/mol-plugin-state/manager/camera.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2019-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2019-2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -12,10 +12,11 @@ import { GraphicsRenderObject } from '../../mol-gl/render-object';
 import { Sphere3D } from '../../mol-math/geometry';
 import { BoundaryHelper } from '../../mol-math/geometry/boundary-helper';
 import { Mat3 } from '../../mol-math/linear-algebra';
+import { leastObstructedDirection } from '../../mol-math/linear-algebra/3d/optimize-direction';
 import { Vec3 } from '../../mol-math/linear-algebra/3d/vec3';
 import { PrincipalAxes } from '../../mol-math/linear-algebra/matrix/principal-axes';
 import { Loci } from '../../mol-model/loci';
-import { Structure, StructureElement } from '../../mol-model/structure';
+import { Structure, StructureElement, StructureProperties } from '../../mol-model/structure';
 import { PluginContext } from '../../mol-plugin/context';
 import { PluginState } from '../../mol-plugin/state';
 import { PluginStateObject } from '../objects';
@@ -23,15 +24,25 @@ import { pcaFocus } from './focus-camera/focus-first-residue';
 import { getFocusSnapshot } from './focus-camera/focus-object';
 import { changeCameraRotation, structureLayingTransform } from './focus-camera/orient-axes';
 
-// TODO: make this customizable somewhere?
-const DefaultCameraFocusOptions = {
+export const DefaultCameraFocusOptions = {
     minRadius: 1,
     extraRadius: 4,
     durationMs: 250,
+    // When set, zooms out to the current scene bounding sphere before focusing on the target.
+    zoomOut: false,
+    zoomOutOptions: {
+        durationFactor: 3.5,
+    }
 };
 
-export type CameraFocusOptions = typeof DefaultCameraFocusOptions
+export const DefaultCameraFocusLociOptions = {
+    ...DefaultCameraFocusOptions,
+    optimizeDirection: false,
+    optimizeDirectionUp: 'current' as 'current' | 'default' | Vec3,
+};
 
+export type CameraFocusOptions = typeof DefaultCameraFocusOptions;
+export type CameraFocusLociOptions = typeof DefaultCameraFocusLociOptions;
 export class CameraManager {
     private boundaryHelper = new BoundaryHelper('98');
 
@@ -57,10 +68,7 @@ export class CameraManager {
         this.focusSpheres(spheres, s => s, options);
     }
 
-    focusLoci(loci: Loci | Loci[], options?: Partial<CameraFocusOptions>) {
-        // TODO: allow computation of principal axes here?
-        // perhaps have an optimized function, that does exact axes small Loci and approximate/sampled from big ones?
-
+    private getFocusSphere(loci: Loci | Loci[]) {
         let sphere: Sphere3D | undefined;
 
         if (Array.isArray(loci) && loci.length > 1) {
@@ -88,9 +96,84 @@ export class CameraManager {
             sphere = Loci.getBoundingSphere(this.transformedLoci(loci));
         }
 
-        if (sphere) {
-            this.focusSphere(sphere, options);
+        return sphere;
+    }
+
+    private focusLociOptimized(loci: Loci | Loci[], options?: Partial<CameraFocusLociOptions>) {
+        const { canvas3d } = this.plugin;
+        if (!canvas3d) return;
+
+        const sphere = this.getFocusSphere(loci);
+        if (!sphere) return;
+
+        const lociArray = Array.isArray(loci) ? loci : [loci];
+        const positions: { x: number[], y: number[], z: number[] } = { x: [], y: [], z: [] };
+        const t = Vec3();
+
+        const { extraRadius, minRadius } = { ...DefaultCameraFocusOptions, ...options };
+        const radius = Math.max(sphere.radius + extraRadius, minRadius);
+
+        if (radius <= 1e-3) {
+            return this.getFocusSphereSnapshot(sphere, options);
         }
+
+        const entityType = StructureProperties.entity.type;
+
+        for (const l of lociArray) {
+            if (!StructureElement.Loci.is(l)) continue;
+            const extended = StructureElement.Loci.extendToRadius(l, radius);
+            StructureElement.Loci.forEachLocation(extended, loc => {
+                if (entityType(loc) === 'water') return;
+
+                loc.unit.conformation.position(loc.element, t);
+                positions.x.push(t[0]);
+                positions.y.push(t[1]);
+                positions.z.push(t[2]);
+            });
+        }
+
+        if (positions.x.length === 0) {
+            return this.getFocusSphereSnapshot(sphere, options);
+        }
+
+        const direction = leastObstructedDirection(positions, {
+            origin: sphere.center,
+            minDistance: 1e-3,
+            sigma: sphere.radius,
+        });
+        if (!direction) {
+            return this.getFocusSphereSnapshot(sphere, options);
+        }
+
+        Vec3.negate(direction, direction);
+        const upVector = options?.optimizeDirectionUp === 'default'
+            ? Vec3.unitY
+            : Vec3.is(options?.optimizeDirectionUp) ? options.optimizeDirectionUp : undefined;
+        if (upVector) {
+            return canvas3d.camera.getInvariantFocus(sphere.center, radius, upVector as Vec3, direction);
+        }
+        return canvas3d.camera.getFocus(sphere.center, radius, undefined, direction);
+    }
+
+    private focusLociBase(loci: Loci | Loci[], options?: Partial<CameraFocusOptions>) {
+        const sphere = this.getFocusSphere(loci);
+        if (sphere) {
+            return this.getFocusSphereSnapshot(sphere, options);
+        }
+    }
+
+    focusLoci(loci: Loci | Loci[], options?: Partial<CameraFocusLociOptions>) {
+        if (!this.plugin.canvas3d) return;
+
+        const options_ = { ...DefaultCameraFocusLociOptions, ...options };
+        let snapshot: Partial<Camera.Snapshot> | undefined;
+        if (options_.optimizeDirection) {
+            snapshot = this.focusLociOptimized(loci, options_);
+        } else {
+            snapshot = this.focusLociBase(loci, options_);
+        }
+
+        this.focusSnapshot(snapshot, options_);
     }
 
     focusSpheres<T>(xs: ReadonlyArray<T>, sphere: (t: T) => Sphere3D | undefined, options?: Partial<CameraFocusOptions> & { principalAxes?: PrincipalAxes, positionToFlip?: Vec3 }) {
@@ -115,21 +198,59 @@ export class CameraManager {
         this.focusSphere(this.boundaryHelper.getSphere(), options);
     }
 
+    private getFocusSphereSnapshot(sphere: Sphere3D, options?: Partial<CameraFocusOptions> & { principalAxes?: PrincipalAxes, positionToFlip?: Vec3 }) {
+        const { canvas3d } = this.plugin;
+        if (!canvas3d) return;
+
+        const { extraRadius, minRadius } = { ...DefaultCameraFocusOptions, ...options };
+        const radius = Math.max(sphere.radius + extraRadius, minRadius);
+
+        if (options?.principalAxes) {
+            return pcaFocus(this.plugin, radius, options as { principalAxes: PrincipalAxes, positionToFlip?: Vec3 });
+        } else {
+            return canvas3d.camera.getFocus(sphere.center, radius);
+        }
+    }
+
+    private focusSnapshot(snapshot: Partial<Camera.Snapshot> | undefined, options?: Partial<CameraFocusOptions>) {
+        if (!this.plugin.canvas3d || !snapshot) return;
+
+        const durationMs = options?.durationMs ?? DefaultCameraFocusOptions.durationMs;
+        if (!options?.zoomOut) {
+            this.plugin.canvas3d.requestCameraReset({ snapshot, durationMs });
+            return;
+        }
+
+        const sphere = this.plugin.canvas3d.boundingSphere;
+        const zoomOut = this.getFocusSphereSnapshot(sphere, options) as Camera.Snapshot;
+        const current = this.plugin.canvas3d?.camera.getSnapshot()!;
+
+        const distA = Vec3.distance(current.position, zoomOut.position);
+        const distB = Vec3.distance(zoomOut.position, snapshot.position!);
+
+        const t = distA / (distA + distB);
+        const durationFactor = options?.zoomOutOptions?.durationFactor ?? DefaultCameraFocusOptions.zoomOutOptions.durationFactor;
+        const df = 1 + durationFactor * Math.min(t, 0.5);
+
+        this.plugin.canvas3d.requestCameraReset({
+            snapshot,
+            durationMs: df * durationMs,
+            keyframes: t > 0.05 ? [
+                { t, snapshot: zoomOut, easing: 'cubic-out' },
+                { t: 1, snapshot, easing: 'cubic-in' },
+            ] : undefined
+        });
+    }
+
     focusSphere(sphere: Sphere3D, options?: Partial<CameraFocusOptions> & { principalAxes?: PrincipalAxes, positionToFlip?: Vec3 }) {
         const { canvas3d } = this.plugin;
         if (!canvas3d) return;
 
-        const { extraRadius, minRadius, durationMs } = { ...DefaultCameraFocusOptions, ...options };
-        const radius = Math.max(sphere.radius + extraRadius, minRadius);
+        const snapshot = this.getFocusSphereSnapshot(sphere, options);
+        if (!snapshot) return;
 
-        if (options?.principalAxes) {
-            const snapshot = pcaFocus(this.plugin, radius, options as { principalAxes: PrincipalAxes, positionToFlip?: Vec3 });
-            this.plugin.canvas3d?.requestCameraReset({ durationMs, snapshot });
-        } else {
-            const snapshot = canvas3d.camera.getFocus(sphere.center, radius);
-            canvas3d.requestCameraReset({ durationMs, snapshot });
-        }
-    }
+        this.focusSnapshot(snapshot, options);
+     }
 
     /** Focus on a set of plugin state object cells (if `options.targets` is non-empty) or on the whole scene (if `options.targets` is empty). */
     focusObject(options: PluginState.SnapshotFocusInfo & { minRadius?: number, durationMs?: number }) {
@@ -139,7 +260,7 @@ export class CameraManager {
             targets: options.targets?.map(t => ({ ...t, extraRadius: t.extraRadius ?? DefaultCameraFocusOptions.extraRadius })),
             minRadius: options.minRadius ?? DefaultCameraFocusOptions.minRadius,
         });
-        this.plugin.canvas3d.requestCameraReset({ snapshot, durationMs: options.durationMs ?? DefaultCameraFocusOptions.durationMs });
+        this.focusSnapshot(snapshot, options);
     }
 
     /** Align PCA axes of `structures` (default: all loaded structures) to the screen axes. */

src/mol-plugin-ui/structure/focus.tsx

@@ -1,7 +1,8 @@
 /**
- * Copyright (c) 2020-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ * @author David Sehnal <david.sehnal@gmail.com>
  */
 
 import { OrderedSet, SortedArray } from '../../mol-data/int';
@@ -184,14 +185,23 @@ export class StructureFocusControls extends PluginUIComponent<{}, StructureFocus
         } else {
             this.plugin.managers.structure.focus.set(f);
         }
-        this.focusCamera();
+        this.focusCamera(true);
     };
 
+    focusCamera(optimizeDirection?: boolean) {
+        const { current } = this.plugin.managers.structure.focus;
+        if (!current) return;
+
+        this.plugin.managers.camera.focusLoci(current.loci, {
+            optimizeDirection,
+        });
+    }
+
+
     toggleAction = () => this.setState({ showAction: !this.state.showAction });
 
-    focusCamera = () => {
-        const { current } = this.plugin.managers.structure.focus;
-        if (current) this.plugin.managers.camera.focusLoci(current.loci);
+    focusCameraClick = () => {
+        this.focusCamera(false);
     };
 
     clear = () => {
@@ -231,7 +241,7 @@ export class StructureFocusControls extends PluginUIComponent<{}, StructureFocus
 
         return <>
             <div className='msp-flex-row'>
-                <Button noOverflow onClick={this.focusCamera} title={title} onMouseEnter={this.highlightCurrent} onMouseLeave={this.clearHighlights} disabled={this.isDisabled || !current}
+                <Button noOverflow onClick={this.focusCameraClick} title={title} onMouseEnter={this.highlightCurrent} onMouseLeave={this.clearHighlights} disabled={this.isDisabled || !current}
                     style={{ textAlignLast: current ? 'left' : void 0 }}>
                     {label}
                 </Button>

tsconfig.commonjs.json

@@ -1,6 +1,7 @@
 {
     "extends": "./tsconfig.json",
     "compilerOptions": {
+        "moduleResolution": "node",
         "module": "CommonJS",
         "outDir": "lib/commonjs"
     }