@weasel-js/kernel3d 1.13.0 → 1.14.0

package/README.md

@@ -10,10 +10,13 @@ here touches WebGL.
 ```ts
 import { createScene } from '@weasel-js/core';
 import {
-  createCamera, createNodeAtPoint, createPoseDescriptor, pose3, type Pose3,
+  POSE3_COMPOSITION, createCamera, createNodeAtPoint, createPoseDescriptor, pose3, type Pose3,
 } from '@weasel-js/kernel3d';
 
-const scene = createScene<MyData, 'solids', Pose3>({ systemLayers: [{ id: 'solids' }] });
+const scene = createScene<MyData, 'solids', Pose3>({
+  composition: POSE3_COMPOSITION,
+  systemLayers: [{ id: 'solids' }],
+});
 const world = { scene, viewport: () => ({ camera, width, height }) };
 
 // Every dep takes its camera from a thunk. That is the whole trick: the
@@ -66,12 +69,33 @@ depth. Two consequences:
   is the mean of the two the rectangle gives it, and it reads `scale` as world
   extents — the unit-primitive assumption `aabbOfPose` makes by default.
 
+## Containers
+
+`POSE3_COMPOSITION` stores a child's pose in its container's frame: moving,
+turning or scaling a container carries everything under it. It is exact when a
+container's scale is uniform; under a non-uniform one a turned child keeps its
+own axes rather than shearing, which a `Pose3` cannot hold.
+
+Every world read folds a node's pose up through its containers first: picking,
+the marquee, snap targets and what a move drags. A renderer does the same with
+`worldPoseOf(scene, id)`, which also honors a gesture's in-flight pose; drawing
+`node.pose` draws a nested node at its container-relative position.
+
+A `kind: 'group'` container selects as it does in 2D: a click on a nested node
+selects its outermost container, a double-click enters it, and a click inside
+then selects the next level in. `createNodeAtPoint` answers the solid the ray
+hits and core's select tool walks up from it, so this needs nothing from the
+host but `<SceneCanvas>`'s own select tool.
+
 ## The bounds seam
 
-`World3d.bounds` is how a consumer says how big a node is. The kernel's default
-carries a unit cube by the pose; override it when a primitive knows better. A
-sphere is the case that forces the seam to be shaped this way — its box is the
-same under every rotation, and no transform of a local box reproduces that.
+`World3d.bounds` is how a consumer says how big a node is. It is handed the node
+at its world pose and answers a world box, or `null` for a node that occupies
+nothing, which is then never picked or snapped to. The kernel's default carries
+a unit cube by a mark's pose and gives a group no box; override it when a
+primitive knows better, or when a container draws. A sphere is the case that
+forces the seam to be shaped this way — its box is the same under every
+rotation, and no transform of a local box reproduces that.
 
 ## Aims
 
@@ -79,9 +103,12 @@ A kernel3d viewport answers core's `ViewAim` contract, so a 2D view and a 3D
 pane can mark each other. `aimOf3d(viewport, viewId)` is the `Aim3d` its camera
 sees, whose extent is a `Frustum3d`: the eye and the near and far rectangles.
 Outlined in a 3D space it draws its far rectangle; in a 2D one, its footprint on
-z = 0, or nothing when any corner ray misses that plane. `aimSpace3d` makes a
-pane a target, unprojecting onto z = 0, and `cameraOfAim3d` gives back the camera
-a dragged aim stands for — what an `AimSource`'s `setAim` writes.
+the ground, the plane through the origin at right angles to the `up` option
+(default +y, as `createInsert` reads it), cut off at the far plane. The 2D x and
+y lie along the two axes `up` is not: x and z for a y-up world. `aimSpace3d`
+makes a pane a target, unprojecting onto the same ground, and `cameraOfAim3d`
+gives back the camera a dragged aim stands for — what an `AimSource`'s `setAim`
+writes.
 
 ## Math
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Vec3, Mat4, Quat, Aabb, Ray } from '@weasel-js/geom/3d';
-import { SceneNode, Scene, NodeId, SnapSource, SnapOutcomeStore, AreaSelectDep, NodeAtPointDep, PoseDescriptor, SnapDep, InsertExtras, InsertDep, ViewAim, AimSpace, SnapMark, OngoingHandle, Action, Tool } from '@weasel-js/core';
+import { PoseComposition, SceneNode, Scene, NodeId, SnapSource, SnapOutcomeStore, AreaSelectDep, NodeAtPointDep, PoseDescriptor, SnapDep, InsertExtras, InsertDep, ViewAim, AimSpace, SnapMark, OngoingHandle, Action, Tool } from '@weasel-js/core';
 import { KitSettingsStore } from '@weasel-js/react';
 import * as _weasel_js_prefs from '@weasel-js/prefs';
 
@@ -110,6 +110,22 @@ declare function poseMatrix(pose: Pose3): Mat4;
  */
 declare function aabbOfPose(pose: Pose3, local?: Aabb): Aabb;
 
+/** Container composition for `Pose3`: a child's pose is stored in its
+ *  container's frame, and folds up to world through every frame above it. */
+
+/**
+ * Container composition for a 3D scene: a container's position, rotation and
+ * scale all reach its children, so moving, turning or growing a container
+ * carries everything under it.
+ *
+ * Exact whenever the container's scale is uniform. Under a non-uniform one a
+ * turned child would come out sheared, which no `Pose3` holds; it keeps its
+ * own axes instead and takes the container's scale axis by axis. Either way
+ * `decompose` undoes `compose`, so a node rebased into a frame and read back
+ * lands where it was.
+ */
+declare const POSE3_COMPOSITION: PoseComposition<Pose3>;
+
 /**
  * The screen side of the kernel: where a pointer points, and what rectangle a
  * world box covers. This is the seam weasel's 2D chrome meets — everything
@@ -209,12 +225,18 @@ type Node3d<TData, TLayer extends string> = SceneNode<TData, TLayer, Pose3>;
  * sphere's box is the same under every rotation, and no transform of a local
  * box reproduces that — rotate a cube and it widens.
  *
- * Omitted, a node is a unit cube carried by its pose.
+ * The node it is handed carries its world pose: under container composition,
+ * or mid-gesture, that is not the pose the scene stores. `null` means the node
+ * occupies nothing, so nothing picks it or snaps to it; a container that only
+ * groups its children answers that.
+ *
+ * Omitted, a mark is a unit cube carried by its pose and a group occupies
+ * nothing.
  *
  * A function of the node alone; a result that depends on anything else must
  * come with a scene change, or picks go stale.
  */
-type NodeBounds<TData, TLayer extends string> = (node: Node3d<TData, TLayer>) => Aabb;
+type NodeBounds<TData, TLayer extends string> = (node: Node3d<TData, TLayer>) => Aabb | null;
 /** What every 3D dep is built from: the scene, the viewport, and optionally
  *  each node's world box. */
 interface World3d<TData, TLayer extends string> {
@@ -224,12 +246,19 @@ interface World3d<TData, TLayer extends string> {
     /** The axis gestures resolve against. Default `+y`. */
     up?: Vec3;
 }
+/**
+ * Where `id` is in world, as it is shown: folded up through every container
+ * frame above it under the scene's composition, at the pose an in-flight
+ * gesture published where there is one. What a renderer draws the node at.
+ */
+declare function worldPoseOf<TData, TLayer extends string>(scene: Scene3d<TData, TLayer>, id: NodeId): Pose3 | undefined;
 
 /**
- * The 3D world's pick index: one BVH over every node's world box, rebuilt
- * whole on the first pick after the scene, its overrides or the world's
- * `bounds` function can have changed. A node whose box the tree refuses
- * (non-finite or inverted) is tested on every pick, the way the scan did.
+ * The 3D world's pick index: one BVH over every node's world box as shown,
+ * rebuilt whole on the first pick after the scene, its overrides or the
+ * world's `bounds` function can have changed. A node whose box the tree
+ * refuses (non-finite or inverted) is tested on every pick, the way the scan
+ * did; one that occupies nothing is never picked.
  */
 
 /** The screen box a node covers, or null when it projects to nothing visible. */
@@ -337,10 +366,21 @@ type Aim3d = ViewAim<Frustum3d> & {
     readonly kind: 'frustum';
     readonly viewport: Viewport3d;
 };
-/** The aim of view `viewId` (`null`: a surface's root): the frustum `viewport`'s camera sees. */
-declare function aimOf3d(viewport: Viewport3d, viewId: string | null): Aim3d;
-/** A 3D pane as a target. It projects through `projectPoint` and unprojects onto the plane z = 0, where 2D worlds lie. */
-declare function aimSpace3d(viewport: Viewport3d, viewId: string | null): AimSpace;
+/** How a kernel3d view meets a 2D one. */
+interface Aim3dOptions {
+    /** The axis the ground, where a 2D world lies, is at right angles to: `createInsert`'s `up`. Default `+y`. */
+    up?: Vec3;
+}
+/**
+ * The aim of view `viewId` (`null`: a surface's root): the frustum `viewport`'s camera sees. Drawn into a 2D view, it
+ * outlines its footprint on the ground, the ground's two axes carrying the 2D world's x and y.
+ */
+declare function aimOf3d(viewport: Viewport3d, viewId: string | null, opts?: Aim3dOptions): Aim3d;
+/**
+ * A 3D pane as a target. Its points are aim points: x and y along the ground's two axes and z, height, along `up`,
+ * so a 2D world's points lie on the ground. It projects through `projectPoint` and unprojects onto the ground.
+ */
+declare function aimSpace3d(viewport: Viewport3d, viewId: string | null, opts?: Aim3dOptions): AimSpace;
 /** The camera an aim was read from, which is what a by-value source's writer sets. */
 declare function cameraOfAim3d(aim: Aim3d): Camera3d;
 
@@ -516,4 +556,4 @@ declare const kernel3dKitSettingsSchema: Omit<_weasel_js_prefs.PrefGroup, "child
     };
 };
 
-export { type Aim3d, type Camera3d, type Camera3dDep, type ChromeBox, DEFAULT_ORBIT_LIMITS, type Footprint, type Frustum3d, 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, aimOf3d, aimSpace3d, alignPlaneSource, boxSnapSource, cameraEye, cameraOfAim3d, 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 };
+export { type Aim3d, type Aim3dOptions, type Camera3d, type Camera3dDep, type ChromeBox, DEFAULT_ORBIT_LIMITS, type Footprint, type Frustum3d, type GroundGridSourceOptions, MAX_PITCH, type Node3d, type NodeBounds, type Orbit3dKitSettings, type OrbitLimits, POSE3_COMPOSITION, type Pose3, type Scene3d, type ScreenBox, type ScreenLine, type ScreenPoint, type Snap3dOptions, UNIT_CUBE, type Viewport3d, type ViewportSource, type World3d, aabbOfPose, aimOf3d, aimSpace3d, alignPlaneSource, boxSnapSource, cameraEye, cameraOfAim3d, 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, worldPoseOf };