@thi.ng/scenegraph 1.0.79 → 2.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-02-19T20:59:58Z
+- **Last updated**: 2025-03-09T19:21:53Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,29 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [2.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/scenegraph@2.0.0) (2025-02-25)
+
+#### 🛑 Breaking changes
+
+- switch to using option objects for node ctors ([9b85ae7](https://github.com/thi-ng/umbrella/commit/9b85ae7))
+- BREAKING CHANGE: replace positional ctor args w/ options objects (aka named params)
+  - add `CommonNodeOpts`, `Node2DOpts`, `Node3DOpts`
+  - update all ctors: `ANode`, `Node2D`, `Node3D`
+  - migrate `enabled`/`display` flags to `ISceneNode` interface
+  - update tests
+
+#### 🚀 Features
+
+- add `scaleWithReferencePoint()` ([60b388c](https://github.com/thi-ng/umbrella/commit/60b388c))
+  - add `ISceneNode.scaleWithReferencePoint()` and impls in `Node2D`/`Node3D`
+  - add/update `ISceneNode` doc strings
+  - minor update/cleanup `ANode`
+  - add tests
+- add `scaleWithReferencePoint()` ([3cef74c](https://github.com/thi-ng/umbrella/commit/3cef74c))
+  - add `ISceneNode.scaleWithReferencePoint()` and impls in `Node2D`/`Node3D`
+  - add/update `ISceneNode` doc strings
+  - minor update/cleanup `ANode`
+
 ### [1.0.41](https://github.com/thi-ng/umbrella/tree/@thi.ng/scenegraph@1.0.41) (2024-04-20)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 202 standalone projects, maintained as part
+> This is one of 203 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -68,7 +68,7 @@ For Node.js REPL:
 const sg = await import("@thi.ng/scenegraph");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 975 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 1.11 KB
 
 ## Dependencies
 
@@ -82,15 +82,16 @@ Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 
 ## Usage examples
 
-Three projects in this repo's
+Four projects in this repo's
 [/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
 directory are using this package:
 
-| Screenshot                                                                                                              | Description                                           | Live demo                                              | Source                                                                              |
-|:------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------|:-------------------------------------------------------|:------------------------------------------------------------------------------------|
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/scenegraph.png" width="240"/>       | 2D scenegraph & shape picking                         | [Demo](https://demo.thi.ng/umbrella/scenegraph/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/scenegraph)       |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/scenegraph-image.png" width="240"/> | 2D scenegraph & image map based geometry manipulation | [Demo](https://demo.thi.ng/umbrella/scenegraph-image/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/scenegraph-image) |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/shader-graph.jpg" width="240"/>     | Minimal shader graph developed during livestream #2   | [Demo](https://demo.thi.ng/umbrella/shader-graph/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/shader-graph)     |
+| Screenshot                                                                                                                  | Description                                             | Live demo                                                 | Source                                                                                 |
+|:----------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------|:----------------------------------------------------------|:---------------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/scenegraph.png" width="240"/>           | 2D scenegraph & shape picking                           | [Demo](https://demo.thi.ng/umbrella/scenegraph/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/scenegraph)          |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/scenegraph-image.png" width="240"/>     | 2D scenegraph & image map based geometry manipulation   | [Demo](https://demo.thi.ng/umbrella/scenegraph-image/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/scenegraph-image)    |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/scenegraph-pan-zoom.avif" width="240"/> | Basic 2D scenegraph example with pan/zoom functionality | [Demo](https://demo.thi.ng/umbrella/scenegraph-pan-zoom/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/scenegraph-pan-zoom) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/shader-graph.jpg" width="240"/>         | Minimal shader graph developed during livestream #2     | [Demo](https://demo.thi.ng/umbrella/shader-graph/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/shader-graph)        |
 
 ## API
 

package/anode.d.ts

@@ -1,7 +1,7 @@
 import type { Maybe, Nullable } from "@thi.ng/api";
 import type { Mat } from "@thi.ng/matrices";
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
-import type { ISceneNode, NodeInfo } from "./api.js";
+import type { CommonNodeOpts, ISceneNode, NodeInfo } from "./api.js";
 export declare abstract class ANode<T extends ISceneNode<any>> {
     id: string;
     parent: Nullable<T>;
@@ -11,55 +11,17 @@ export declare abstract class ANode<T extends ISceneNode<any>> {
     invMat: Mat;
     enabled: boolean;
     display: boolean;
-    constructor(id: string, parent?: Nullable<T>, body?: any);
+    constructor({ id, parent, body, enabled, display, }: CommonNodeOpts<T>);
     appendChild(node: T): this;
     insertChild(i: number, node: T): this;
     deleteChild(node: number | T): boolean;
-    abstract update(): void;
     draw<T>(ctx: T): void;
-    /**
-     * Checks all children in reverse order, then (if no child matched)
-     * node itself for containment of given point (in world/screen
-     * coords). Returns `NodeInfo` object with matched node (if any) or
-     * undefined.
-     *
-     * **Important:** Disabled nodes and their children will be skipped!
-     *
-     * @param p -
-     */
     childForPoint(p: ReadonlyVec): Maybe<NodeInfo<T>>;
-    /**
-     * Returns copy of world space point `p`, transformed into this
-     * node's local coordinate system.
-     *
-     * @param p -
-     */
+    containsLocalPoint(_: ReadonlyVec): boolean;
+    abstract update(): void;
     abstract mapGlobalPoint(p: ReadonlyVec): Maybe<Vec>;
-    /**
-     * Returns copy of node local space point `p`, transformed into the global
-     * worldspace.
-     *
-     * @param p
-     */
     abstract mapLocalPointToGlobal(p: ReadonlyVec): Maybe<Vec>;
-    /**
-     * Returns copy of node local space point `p`, transformed into the
-     * coordinate system of `dest` node.
-     *
-     * @param dest -
-     * @param p -
-     */
     abstract mapLocalPointToNode(dest: T, p: ReadonlyVec): Maybe<Vec>;
-    /**
-     * Returns true, if given point is contained within the boundary of
-     * this node. Since this class is used as generic base
-     * implementation for other, more specialized scene graph nodes,
-     * this base impl always returns false (meaning these nodes cannot
-     * will not be selectable by the user unless a subclass overrides
-     * this method).
-     *
-     * @param p -
-     */
-    containsLocalPoint(_: ReadonlyVec): boolean;
+    abstract scaleWithReferencePoint(ref: ReadonlyVec, scale: ReadonlyVec | number): this;
 }
 //# sourceMappingURL=anode.d.ts.map

package/anode.js

@@ -9,7 +9,13 @@ class ANode {
   invMat;
   enabled;
   display;
-  constructor(id, parent, body) {
+  constructor({
+    id,
+    parent,
+    body,
+    enabled = true,
+    display = true
+  }) {
     this.id = id;
     this.parent = parent;
     this.children = [];
@@ -19,8 +25,8 @@ class ANode {
     this.body = body;
     this.mat = [];
     this.invMat = [];
-    this.enabled = true;
-    this.display = true;
+    this.enabled = enabled;
+    this.display = display;
   }
   appendChild(node) {
     this.children.push(node);
@@ -51,16 +57,6 @@ class ANode {
       }
     }
   }
-  /**
-   * Checks all children in reverse order, then (if no child matched)
-   * node itself for containment of given point (in world/screen
-   * coords). Returns `NodeInfo` object with matched node (if any) or
-   * undefined.
-   *
-   * **Important:** Disabled nodes and their children will be skipped!
-   *
-   * @param p -
-   */
   childForPoint(p) {
     if (this.enabled) {
       const children = this.children;
@@ -76,16 +72,6 @@ class ANode {
       }
     }
   }
-  /**
-   * Returns true, if given point is contained within the boundary of
-   * this node. Since this class is used as generic base
-   * implementation for other, more specialized scene graph nodes,
-   * this base impl always returns false (meaning these nodes cannot
-   * will not be selectable by the user unless a subclass overrides
-   * this method).
-   *
-   * @param p -
-   */
   containsLocalPoint(_) {
     return false;
   }

package/api.d.ts

@@ -6,15 +6,78 @@ export interface ISceneNode<T extends ISceneNode<T>> extends IID<string> {
     children: T[];
     mat: Mat;
     invMat: Mat;
+    enabled: boolean;
+    display: boolean;
     appendChild(node: T): this;
     insertChild(i: number, node: T): this;
     deleteChild(node: number | T): boolean;
+    /**
+     * Recursively recomputes this node's (and its children's) transformation
+     * matrices (i.e. {@link ANode.mat} and {@link ANode.invMat}).
+     *
+     * @remarks
+     * This function is a no-op if the node is currently disabled (see
+     * {@link ANode.enabled}).
+     */
     update(): void;
     draw<D>(ctx: D): void;
+    /**
+     * Returns copy of world space point `p`, transformed into this
+     * node's local coordinate system.
+     *
+     * @param p -
+     */
     mapGlobalPoint(p: ReadonlyVec): Maybe<Vec>;
+    /**
+     * Returns copy of node local space point `p`, transformed into the global
+     * worldspace.
+     *
+     * @param p
+     */
+    mapLocalPointToGlobal(p: ReadonlyVec): Maybe<Vec>;
+    /**
+     * Returns copy of node local space point `p`, transformed into the
+     * coordinate system of `dest` node.
+     *
+     * @param dest -
+     * @param p -
+     */
     mapLocalPointToNode(dest: ISceneNode<T>, p: ReadonlyVec): Maybe<Vec>;
+    /**
+     * Returns true, if given point is contained within the boundary of
+     * this node. Since this class is used as generic base
+     * implementation for other, more specialized scene graph nodes,
+     * this base impl always returns false (meaning these nodes cannot
+     * will not be selectable by the user unless a subclass overrides
+     * this method).
+     *
+     * @param p -
+     */
     containsLocalPoint(_: ReadonlyVec): boolean;
+    /**
+     * Checks all children in reverse order, then (if no child matched)
+     * node itself for containment of given point (in world/screen
+     * coords). Returns `NodeInfo` object with matched node (if any) or
+     * undefined.
+     *
+     * **Important:** Disabled nodes and their children will be skipped!
+     *
+     * @param p -
+     */
     childForPoint(p: ReadonlyVec): Maybe<NodeInfo<T>>;
+    /**
+     * Scales node to new given `scale` factor and translates it such that given
+     * `ref`erence point (given in local space) would stay constant in world
+     * space. Useful for zoomable UIs, e.g. for zooming relative to the mouse
+     * position.
+     *
+     * @remarks
+     * This function is a no-op if the node is currently not enabled.
+     *
+     * @param ref
+     * @param scale
+     */
+    scaleWithReferencePoint(ref: ReadonlyVec, scale: ReadonlyVec | number): this;
 }
 /**
  * Node information for mouse picking.
@@ -29,4 +92,32 @@ export interface NodeInfo<T> {
      */
     p?: Vec;
 }
+export interface CommonNodeOpts<T extends ISceneNode<any>> {
+    /**
+     * Node ID
+     */
+    id: string;
+    /**
+     * Parent node (if any).
+     */
+    parent?: Nullable<T>;
+    /**
+     * Arbitrary node data/content
+     */
+    body?: any;
+    /**
+     * If false, node (and its children) will not be updated via
+     * {@link ISceneNode.update}.
+     *
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * If false, node (and its children) will not be processed via
+     * {@link ISceneNode.draw}.
+     *
+     * @defaultValue true
+     */
+    display?: boolean;
+}
 //# sourceMappingURL=api.d.ts.map

package/node2.d.ts

@@ -1,17 +1,23 @@
-import type { ICopy, IToHiccup, Nullable } from "@thi.ng/api";
+import type { ICopy, IToHiccup } from "@thi.ng/api";
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 import { ANode } from "./anode.js";
-import type { ISceneNode } from "./api.js";
+import type { CommonNodeOpts, ISceneNode } from "./api.js";
+export interface Node2DOpts extends CommonNodeOpts<Node2D> {
+    translate?: Vec;
+    rotate?: number;
+    scale?: Vec | number;
+}
 export declare class Node2D extends ANode<Node2D> implements ICopy<Node2D>, ISceneNode<Node2D>, IToHiccup {
     translate: Vec;
     rotate: number;
     scale: Vec | number;
-    constructor(id: string, parent?: Nullable<Node2D>, translate?: Vec, rotate?: number, scale?: Vec | number, body?: any);
+    constructor(opts: Node2DOpts);
     copy(): Node2D;
     update(): void;
     mapGlobalPoint(p: ReadonlyVec): Vec;
     mapLocalPointToGlobal(p: ReadonlyVec): Vec;
     mapLocalPointToNode(dest: Node2D, p: ReadonlyVec): Vec;
+    scaleWithReferencePoint(ref: ReadonlyVec, scale: ReadonlyVec | number): this;
     /**
      * By implementing this method (`IToHiccup` interface), scene graph nodes
      * can be directly used by hdom-canvas, hiccup-canvas, rdom-canvas or

package/node2.js

@@ -3,29 +3,33 @@ import { invert23 } from "@thi.ng/matrices/invert";
 import { mulM23 } from "@thi.ng/matrices/mulm";
 import { mulV23 } from "@thi.ng/matrices/mulv";
 import { transform23 } from "@thi.ng/matrices/transform";
+import { madd2 } from "@thi.ng/vectors/madd";
 import { set2 } from "@thi.ng/vectors/set";
+import { setN2 } from "@thi.ng/vectors/setn";
+import { sub2 } from "@thi.ng/vectors/sub";
 import { ANode } from "./anode.js";
 import { toHiccup } from "./hiccup.js";
 class Node2D extends ANode {
   translate;
   rotate;
   scale;
-  constructor(id, parent, translate = [0, 0], rotate = 0, scale = 1, body) {
-    super(id, parent, body);
-    this.translate = translate;
-    this.rotate = rotate;
+  constructor(opts) {
+    super(opts);
+    this.translate = opts.translate ?? [0, 0];
+    this.rotate = opts.rotate ?? 0;
+    const scale = opts.scale ?? 1;
     this.scale = isNumber(scale) ? [scale, scale] : scale;
     this.update();
   }
   copy() {
-    return new Node2D(
-      this.id,
-      this.parent,
-      set2([], this.translate),
-      this.rotate,
-      set2([], this.scale),
-      this.body
-    );
+    return new Node2D({
+      id: this.id,
+      parent: this.parent,
+      translate: set2([], this.translate),
+      rotate: this.rotate,
+      scale: set2([], this.scale),
+      body: this.body
+    });
   }
   update() {
     if (this.enabled) {
@@ -48,6 +52,17 @@ class Node2D extends ANode {
   mapLocalPointToNode(dest, p) {
     return mulV23(null, dest.invMat, mulV23([], this.mat, p));
   }
+  scaleWithReferencePoint(ref, scale) {
+    if (this.enabled) {
+      const currScale = isNumber(this.scale) ? setN2([], this.scale) : this.scale;
+      const newScale = isNumber(scale) ? setN2([], scale) : scale;
+      const delta = sub2([], currScale, newScale);
+      this.scale = newScale;
+      this.translate = madd2([], ref, delta, this.translate);
+      this.update();
+    }
+    return this;
+  }
   /**
    * By implementing this method (`IToHiccup` interface), scene graph nodes
    * can be directly used by hdom-canvas, hiccup-canvas, rdom-canvas or

package/node3.d.ts

@@ -1,17 +1,23 @@
-import type { ICopy, IToHiccup, Nullable } from "@thi.ng/api";
+import type { ICopy, IToHiccup } from "@thi.ng/api";
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 import { ANode } from "./anode.js";
-import type { ISceneNode } from "./api.js";
+import type { CommonNodeOpts, ISceneNode } from "./api.js";
+export interface Node3DOpts extends CommonNodeOpts<Node3D> {
+    translate?: Vec;
+    rotate?: Vec;
+    scale?: Vec | number;
+}
 export declare class Node3D extends ANode<Node3D> implements ICopy<Node3D>, ISceneNode<Node3D>, IToHiccup {
     translate: Vec;
     rotate: Vec;
     scale: Vec | number;
-    constructor(id: string, parent?: Nullable<Node3D>, translate?: Vec, rotate?: Vec, scale?: Vec | number, body?: any);
+    constructor(opts: Node3DOpts);
     copy(): Node3D;
     update(): void;
     mapGlobalPoint(p: ReadonlyVec): Vec | undefined;
     mapLocalPointToGlobal(p: ReadonlyVec): Vec | undefined;
     mapLocalPointToNode(dest: Node3D, p: ReadonlyVec): Vec | undefined;
+    scaleWithReferencePoint(ref: ReadonlyVec, scale: ReadonlyVec | number): this;
     /**
      * Future support planned. No immediate users of this method in a 3D context
      * available thus far.

package/node3.js

@@ -3,29 +3,33 @@ import { invert44 } from "@thi.ng/matrices/invert";
 import { mulM44 } from "@thi.ng/matrices/mulm";
 import { mulV344 } from "@thi.ng/matrices/mulv";
 import { transform44 } from "@thi.ng/matrices/transform";
+import { madd3 } from "@thi.ng/vectors/madd";
 import { set3 } from "@thi.ng/vectors/set";
+import { setN3 } from "@thi.ng/vectors/setn";
+import { sub3 } from "@thi.ng/vectors/sub";
 import { ANode } from "./anode.js";
 import { toHiccup } from "./hiccup.js";
 class Node3D extends ANode {
   translate;
   rotate;
   scale;
-  constructor(id, parent, translate = [0, 0, 0], rotate = [0, 0, 0], scale = 1, body) {
-    super(id, parent, body);
-    this.translate = translate;
-    this.rotate = rotate;
+  constructor(opts) {
+    super(opts);
+    this.translate = opts.translate ?? [0, 0, 0];
+    this.rotate = opts.rotate ?? [0, 0, 0];
+    const scale = opts.scale ?? 1;
     this.scale = isNumber(scale) ? [scale, scale, scale] : scale;
     this.update();
   }
   copy() {
-    return new Node3D(
-      this.id,
-      this.parent,
-      set3([], this.translate),
-      set3([], this.rotate),
-      set3([], this.scale),
-      this.body
-    );
+    return new Node3D({
+      id: this.id,
+      parent: this.parent,
+      translate: set3([], this.translate),
+      rotate: set3([], this.rotate),
+      scale: set3([], this.scale),
+      body: this.body
+    });
   }
   update() {
     if (this.enabled) {
@@ -48,6 +52,17 @@ class Node3D extends ANode {
   mapLocalPointToNode(dest, p) {
     return mulV344(null, dest.invMat, mulV344([], this.mat, p));
   }
+  scaleWithReferencePoint(ref, scale) {
+    if (this.enabled) {
+      const currScale = isNumber(this.scale) ? setN3([], this.scale) : this.scale;
+      const newScale = isNumber(scale) ? setN3([], scale) : scale;
+      const delta = sub3([], currScale, newScale);
+      this.scale = newScale;
+      this.translate = madd3([], ref, delta, this.translate);
+      this.update();
+    }
+    return this;
+  }
   /**
    * Future support planned. No immediate users of this method in a 3D context
    * available thus far.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/scenegraph",
-  "version": "1.0.79",
+  "version": "2.0.1",
   "description": "Extensible 2D/3D scene graph with @thi.ng/hiccup-canvas support",
   "type": "module",
   "module": "./index.js",
@@ -39,11 +39,11 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.21",
-    "@thi.ng/checks": "^3.7.0",
-    "@thi.ng/errors": "^2.5.27",
-    "@thi.ng/matrices": "^2.4.34",
-    "@thi.ng/vectors": "^7.12.22"
+    "@thi.ng/api": "^8.11.22",
+    "@thi.ng/checks": "^3.7.2",
+    "@thi.ng/errors": "^2.5.28",
+    "@thi.ng/matrices": "^2.4.36",
+    "@thi.ng/vectors": "^7.12.24"
   },
   "devDependencies": {
     "esbuild": "^0.25.0",
@@ -101,5 +101,5 @@
     ],
     "status": "alpha"
   },
-  "gitHead": "2958e6a9881bd9e06de587a2141f6d23c64278db\n"
+  "gitHead": "55987d581e4985b1c3091ba6be3f9b53a0c5eeea\n"
 }