@weasel-js/kernel3d 1.10.1 → 1.11.1

package/README.md

@@ -36,6 +36,18 @@ One thing does not:
 - **`ViewApi` has no orientation**, so an orbit camera cannot travel through
   the kit's `view`. The kernel declares a `camera3d` dep of its own.
 
+## The camera's actions
+
+`camera.orbit` turns the `camera3d` dep on a drag, `camera.pan` slides its
+target across the screen plane, `camera.dolly` answers the wheel and both
+trackpad pinches, `camera.pinchDolly` two fingers, and `camera.home` returns it
+to the dep's `home()`. Both dollies go through `dollyToward`, which keeps the
+point in the target's plane under the pointer still, as a 2D wheel zoom does,
+measured against the dep's `size()`. Each holds the camera inside the dep's `limits()` — an
+`OrbitLimits` in the scene's own units, defaulting to `DEFAULT_ORBIT_LIMITS` —
+through `clampCamera`, which `orbitBy` and `dollyBy` take as well. labkit's
+`orbit` capability is these actions on a dep the trial owns.
+
 ## The depth a screen rectangle does not name
 
 `PoseDescriptor` reads `Bounds` as the screen box a solid covers. `getBounds`

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { Vec3, Mat4, Quat, Aabb, Ray } from '@weasel-js/geom/3d';
-import { SceneNode, Scene, NodeId, AreaSelectDep, InsertExtras, InsertDep, NodeAtPointDep, PoseDescriptor, SnapDep, OngoingHandle, Action, Tool } from '@weasel-js/core';
+import { SceneNode, Scene, SnapSource, SnapOutcomeStore, NodeId, AreaSelectDep, NodeAtPointDep, PoseDescriptor, SnapDep, InsertExtras, InsertDep, SnapMark, OngoingHandle, Action, Tool } from '@weasel-js/core';
+import { KitSettingsStore } from '@weasel-js/react';
+import * as _weasel_js_prefs from '@weasel-js/prefs';
 
 /**
  * An orbit camera: a target, two angles and a distance. Immutable — every
@@ -34,11 +36,45 @@ declare function cameraEye(camera: Camera3d): Vec3;
 declare function cameraView(camera: Camera3d): Mat4;
 /** World-to-clip matrix for a pane of the given width/height `aspect`. */
 declare function cameraViewProjection(camera: Camera3d, aspect: number): Mat4;
-/** The camera turned about its target by the given radians. Pitch is clamped
- *  to ±`MAX_PITCH`; yaw is not wrapped. */
-declare function orbitBy(camera: Camera3d, deltaYaw: number, deltaPitch: number): Camera3d;
-/** The camera with its distance multiplied by `factor`, clamped to 0.5..500. */
-declare function dollyBy(camera: Camera3d, factor: number): Camera3d;
+/** How far an orbit camera may turn and travel. Distances are in world units,
+ *  so a scene measured in millimeters and one in kilometers want different ones. */
+interface OrbitLimits {
+    minDistance: number;
+    maxDistance: number;
+    /** Radians. Held inside ±`MAX_PITCH` whatever is asked for. */
+    minPitch: number;
+    maxPitch: number;
+}
+/** Pitch short of the poles, distance 0.5..500. */
+declare const DEFAULT_ORBIT_LIMITS: OrbitLimits;
+/** The camera with its pitch and distance inside `limits`. Returns `camera`
+ *  itself when it already holds. */
+declare function clampCamera(camera: Camera3d, limits?: Partial<OrbitLimits>): Camera3d;
+/** The camera turned about its target by the given radians, pitch held inside
+ *  `limits`. Yaw is not wrapped. */
+declare function orbitBy(camera: Camera3d, deltaYaw: number, deltaPitch: number, limits?: Partial<OrbitLimits>): Camera3d;
+/** The camera with its distance multiplied by `factor`, held inside `limits`. */
+declare function dollyBy(camera: Camera3d, factor: number, limits?: Partial<OrbitLimits>): Camera3d;
+/**
+ * The camera with its target slid across the screen plane, so the point at the
+ * target follows a pointer that moved `dx`, `dy` CSS pixels in a pane
+ * `paneHeight` pixels tall. Neither angle nor distance changes.
+ */
+declare function panBy(camera: Camera3d, dx: number, dy: number, paneHeight: number): Camera3d;
+/**
+ * `dollyBy` about a point on the pane rather than its middle: the point in the
+ * target's screen-facing plane under `at` — CSS pixels from the pane's
+ * top-left, in a pane of `pane` size — stays under it, as a 2D camera's wheel
+ * zoom keeps the point under the pointer. The target slides toward that point
+ * by as much as the distance shrank, so the next turn pivots nearer it.
+ */
+declare function dollyToward(camera: Camera3d, factor: number, at: {
+    x: number;
+    y: number;
+}, pane: {
+    width: number;
+    height: number;
+}, limits?: Partial<OrbitLimits>): Camera3d;
 
 /**
  * A 3D pose, and the two things every consumer of one needs: its matrix, and
@@ -137,14 +173,6 @@ declare function rayThroughScreenPoint(point: {
  */
 declare function projectAabbToScreen(box: Aabb, viewProjection: Mat4, rect: ScreenBox): ScreenBox | null;
 
-/**
- * The kit's deps, implemented against a 3D world.
- *
- * Every one of these takes its camera from a thunk rather than an argument:
- * the dispatcher keeps handing actions two numbers, and what makes them mean
- * something in 3D is the camera each dep already closes over.
- */
-
 /** The camera and the pane it draws into; `width`/`height` are the pane's
  *  size in the same units as the pointer points. */
 interface Viewport3d {
@@ -161,6 +189,17 @@ interface Viewport3d {
 }
 /** Read on every dep call, so a dep always sees the current camera and pane. */
 type ViewportSource = () => Viewport3d;
+type Point$1 = {
+    x: number;
+    y: number;
+};
+/** Where `p` draws in the viewport, or null when it is behind the near plane
+ *  or projects to nothing finite. */
+declare function projectPoint(p: Vec3, viewport: Viewport3d): Point$1 | null;
+
+/** The 3D world every dep is built from: core's scene with a `Pose3`, the
+ *  viewport it is seen through, and how wide each node is. */
+
 /** A 3D scene is core's scene with a `Pose3`. Nothing wraps it. */
 type Scene3d<TData, TLayer extends string> = Scene<TData, TLayer, Pose3>;
 /** A node of a `Scene3d`. */
@@ -182,6 +221,15 @@ interface World3d<TData, TLayer extends string> {
     /** The axis gestures resolve against. Default `+y`. */
     up?: Vec3;
 }
+
+/**
+ * The kit's deps, implemented against a 3D world.
+ *
+ * Every one of these takes its camera from a thunk rather than an argument:
+ * the dispatcher keeps handing actions two numbers, and what makes them mean
+ * something in 3D is the camera each dep already closes over.
+ */
+
 /** The screen box a node covers, or null when it projects to nothing visible. */
 declare function screenBoxOf<TData, TLayer extends string>(world: World3d<TData, TLayer>, id: NodeId, viewport: Viewport3d): ScreenBox | null;
 /**
@@ -197,8 +245,46 @@ declare function createAreaSelect<TData, TLayer extends string>(world: World3d<T
     get(): readonly NodeId[];
     set(ids: NodeId[]): void;
 }): AreaSelectDep;
-/** No grid in 3D yet; the identity keeps `insertAction` happy without lying. */
-declare function createSnap(): SnapDep;
+/** Options for `createSnap`. */
+interface Snap3dOptions {
+    /** What a gesture snaps to, in order: earlier wins a full tie. Two sharing
+     *  an id throw. Default none, which leaves only the gesture's own constraint. */
+    sources?: readonly SnapSource<Vec3>[];
+    /** The reach of a source that sets none, in screen px. Overrides the kit
+     *  setting `targets.snapPx`. */
+    reachPx?: number;
+    /** Where `targets.snapPx` is read, when each gesture begins. Absent, and
+     *  with no `reachPx`, reach is `DEFAULT_SNAP_PX`. */
+    kitSettings?: KitSettingsStore;
+    /** Where the marks of the snap in flight are written, for a host to draw
+     *  with `projectSnapMarks`. */
+    store?: SnapOutcomeStore<Vec3>;
+}
+/**
+ * The `snap` dep over a 3D world. A gesture's `omit` is honored; its 2D
+ * `sources` are not asked. A move snaps its subject's world box on the
+ * plane it already moves on; an insert snaps the pointer on the ground. Both
+ * answer in screen points, which `translate` and `createInsert` cast back
+ * onto the same plane, landing exactly where the snap put them.
+ */
+declare function createSnap<TData, TLayer extends string>(world: World3d<TData, TLayer>, opts?: Snap3dOptions): SnapDep;
+/**
+ * `PoseDescriptor` over a 3D pose, with `Bounds` read as the screen box the
+ * node covers.
+ *
+ * `forNode` is what lets a sphere bound itself as a sphere: the shape lives
+ * on `node.data`. Unspecialized — the kit calling with only a pose in hand —
+ * it answers with the default local box, which is the looser of the two.
+ *
+ * `remapBounds` and `fromBounds` take a screen rectangle, which names a pose
+ * only once something supplies a depth. Both resolve it against the plane
+ * through the pose they were handed, facing the camera, so nothing they
+ * produce changes depth.
+ */
+declare function createPoseDescriptor<TData, TLayer extends string>(world: World3d<TData, TLayer>): PoseDescriptor<Pose3, Node3d<TData, TLayer>>;
+
+/** The `insert` dep over a 3D world: a drag becomes a footprint on the ground. */
+
 /** The ground-plane rectangle a drag swept out, in world units. */
 interface Footprint {
     /** Centre of the swept rectangle, on the ground plane. */
@@ -208,14 +294,11 @@ interface Footprint {
     depth: number;
 }
 /**
- * A drag rectangle becomes a footprint on the ground plane: its four corners
- * are cast onto the plane and the hit points give the extent. What node that
- * implies is the consumer's answer — the kernel does not know what it is
- * inserting.
- *
- * The kit's `InsertDep.commit` hands over a screen-space AABB and nothing else:
- * the depth the 2D contract cannot express comes from the plane, not from the
- * caller.
+ * A drag becomes a footprint on the ground plane: its ends, or without them
+ * its box's four corners, are cast onto the plane and the hit points give the
+ * extent. What node that implies is the consumer's answer — the kernel does
+ * not know what it is inserting. The depth the 2D contract cannot express
+ * comes from the plane, not from the caller.
  */
 declare function createInsert(opts: {
     viewport: ViewportSource;
@@ -224,20 +307,67 @@ declare function createInsert(opts: {
     minExtent?: number;
     mint(footprint: Footprint, extras: InsertExtras): NodeId | null;
 }): InsertDep;
+
+/** What a 3D scene offers a snap session: its boxes' corners, edges, faces
+ *  and centers, the planes through their sides and centers, and a grid on
+ *  the ground. */
+
 /**
- * `PoseDescriptor` over a 3D pose, with `Bounds` read as the screen box the
- * node covers.
- *
- * `forNode` is what lets a sphere bound itself as a sphere: the shape lives
- * on `node.data`. Unspecialized — the kit calling with only a pose in hand —
- * it answers with the default local box, which is the looser of the two.
- *
- * `remapBounds` and `fromBounds` take a screen rectangle, which names a pose
- * only once something supplies a depth. Both resolve it against the plane
- * through the pose they were handed, facing the camera, so nothing they
- * produce changes depth.
+ * Each node's world box as targets for geometry and pointer probes: its 8
+ * corners and its center as points, its 12 edges as segments, and its 6
+ * faces as bounded planes. Targets past the reach are not offered.
  */
-declare function createPoseDescriptor<TData, TLayer extends string>(world: World3d<TData, TLayer>): PoseDescriptor<Pose3, Node3d<TData, TLayer>>;
+declare function boxSnapSource<TData, TLayer extends string>(world: World3d<TData, TLayer>): SnapSource<Vec3>;
+/**
+ * The planes through each node's world box at its min, center and max on
+ * every axis, as targets for box and pointer probes: alignment in depth as
+ * well as across. Boxes sharing a plane offer it once, and its mark reaches
+ * each of them.
+ */
+declare function alignPlaneSource<TData, TLayer extends string>(world: World3d<TData, TLayer>): SnapSource<Vec3>;
+/** Options for `groundGridSource`. */
+interface GroundGridSourceOptions {
+    /** The grid's pitch, in world units. */
+    step: number;
+    /** The ground's normal; the grid lies on `up · p = 0`. Default `+y`. */
+    up?: Vec3;
+}
+/**
+ * A grid on the ground plane as snap targets: for each pointer or geometry
+ * probe on the ground, the grid line on either side of it along each of the
+ * ground's two axes. Its reach is unlimited and it is a fallback, so it
+ * holds every axis no target claims and never displaces one.
+ */
+declare function groundGridSource(opts: GroundGridSourceOptions): SnapSource<Vec3>;
+
+type Point = {
+    x: number;
+    y: number;
+};
+/** A snap mark's segment on screen: a line, a gap, or a distance. */
+interface ScreenLine {
+    from: Point;
+    to: Point;
+    /** A gap's or distance's value, in world units. */
+    value?: number;
+    color?: string;
+}
+/** A snap mark's point on screen. */
+interface ScreenPoint {
+    at: Point;
+    glyph: string;
+    label?: string;
+    color?: string;
+}
+/**
+ * The marks a 3D snap session draws, in the viewport's screen space, for a
+ * host to draw through its own renderer. A mark with any point that does not
+ * project — behind the camera — is dropped whole.
+ */
+declare function projectSnapMarks(marks: readonly SnapMark<Vec3>[], viewport: Viewport3d): {
+    lines: ScreenLine[];
+    points: ScreenPoint[];
+};
 
 /**
  * What a host paints for a gesture that proposes chrome rather than a pose.
@@ -269,13 +399,26 @@ declare function collectOverlayBoxes(handles: Iterable<OngoingHandle>, origin: {
  */
 
 /** `camera.orbit`: an ongoing drag that turns the `camera3d` dep about its
- *  target, relative to the camera as it was when the drag began. */
+ *  target. */
 declare const orbitAction: Action;
-/** `camera.dolly`: moves the `camera3d` dep toward or away from its target by
- *  the wheel's `deltaY`. Bound to the wheel by default, in every tool. */
+/** `camera.pan`: an ongoing drag that slides the `camera3d` dep's target
+ *  across the screen plane, so the point at the target follows the pointer. */
+declare const panAction: Action;
+/** `camera.dolly`: moves the `camera3d` dep in or out about the point under
+ *  the pointer, as a 2D camera's wheel zooms about it. A wheel's `deltaY`, and
+ *  a trackpad pinch delivered as ctrl+wheel, dolly by `exp(deltaY × rate)` —
+ *  one rate for both, as a 2D camera zooms by both. Safari's pinch arrives as
+ *  a `scale` and divides the distance by it. Bound to all three by default, in
+ *  every tool. */
 declare const dollyAction: Action;
-/** A tool that binds drag to `camera.orbit`. Register `orbitAction` alongside
- *  it; the tool only declares the binding. */
+/** `camera.pinchDolly`: two fingers spreading dolly the `camera3d` dep in and
+ *  closing dolly it out, by the ratio of their spread, about where they began. */
+declare const pinchDollyAction: Action;
+/** `camera.home`: returns the `camera3d` dep to its `home`. Bound to a double
+ *  click by default. */
+declare const homeAction: Action;
+/** A tool that binds a drag to `camera.orbit` and Shift+drag to `camera.pan`.
+ *  Register both actions alongside it; the tool only declares the bindings. */
 declare function useOrbitTool(): Tool;
 
 /**
@@ -297,6 +440,11 @@ interface Camera3dDep {
         width: number;
         height: number;
     };
+    /** How far the camera actions may turn and dolly it. Omitted,
+     *  `DEFAULT_ORBIT_LIMITS`. */
+    limits?(): Partial<OrbitLimits>;
+    /** Where `camera.home` returns it. Omitted, `camera.home` does nothing. */
+    home?(): Camera3d;
 }
 declare module '@weasel-js/core' {
     interface DepSchema {
@@ -304,4 +452,32 @@ declare module '@weasel-js/core' {
     }
 }
 
-export { type Camera3d, type Camera3dDep, type ChromeBox, type Footprint, MAX_PITCH, type Node3d, type NodeBounds, type Pose3, type Scene3d, type ScreenBox, UNIT_CUBE, type Viewport3d, type ViewportSource, type World3d, aabbOfPose, cameraEye, cameraView, cameraViewProjection, collectOverlayBoxes, createAreaSelect, createCamera, createInsert, createNodeAtPoint, createPoseDescriptor, createSnap, dollyAction, dollyBy, ndcToScreen, orbitAction, orbitBy, pose3, poseMatrix, projectAabbToScreen, rayThroughScreenPoint, screenBoxOf, screenToNdc, useOrbitTool };
+/** The `orbit3d` kit settings area: how far the camera tools move per input. */
+interface Orbit3dKitSettings {
+    /** Radians of orbit per CSS pixel of drag. */
+    orbitRate: number;
+    /** Dolly exponent per unit of wheel `deltaY`. */
+    dollyRate: number;
+}
+declare module '@weasel-js/react' {
+    interface KitSettings {
+        orbit3d: Orbit3dKitSettings;
+    }
+}
+/** The `orbit3d` area as a prefs group whose paths are the `KitSettings` paths. */
+declare const kernel3dKitSettingsSchema: Omit<_weasel_js_prefs.PrefGroup, "children"> & {
+    children: {
+        readonly orbit3d: Omit<_weasel_js_prefs.PrefGroup, "children"> & {
+            children: {
+                readonly orbitRate: _weasel_js_prefs.PrefNumber & {
+                    default: number;
+                };
+                readonly dollyRate: _weasel_js_prefs.PrefNumber & {
+                    default: number;
+                };
+            };
+        };
+    };
+};
+
+export { type Camera3d, type Camera3dDep, type ChromeBox, DEFAULT_ORBIT_LIMITS, type Footprint, type GroundGridSourceOptions, MAX_PITCH, type Node3d, type NodeBounds, type Orbit3dKitSettings, type OrbitLimits, type Pose3, type Scene3d, type ScreenBox, type ScreenLine, type ScreenPoint, type Snap3dOptions, UNIT_CUBE, type Viewport3d, type ViewportSource, type World3d, aabbOfPose, alignPlaneSource, boxSnapSource, cameraEye, cameraView, cameraViewProjection, clampCamera, collectOverlayBoxes, createAreaSelect, createCamera, createInsert, createNodeAtPoint, createPoseDescriptor, createSnap, dollyAction, dollyBy, dollyToward, groundGridSource, homeAction, kernel3dKitSettingsSchema, ndcToScreen, orbitAction, orbitBy, panAction, panBy, pinchDollyAction, pose3, poseMatrix, projectAabbToScreen, projectPoint, projectSnapMarks, rayThroughScreenPoint, screenBoxOf, screenToNdc, useOrbitTool };