npm - p5.tree - Versions diffs - 0.0.1 → 0.0.2 - Mend

p5.tree 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,4 +1,5 @@
 # p5.tree
+[![npm version](https://img.shields.io/npm/v/p5.tree)](https://www.npmjs.com/package/p5.tree)
 Shader development, camera keyframes interpolation and space transformations for [WEBGL](https://p5js.org/reference/#/p5/WEBGL) / WebGPU-ready [p5.js v2](https://beta.p5js.org/).
@@ -188,8 +189,8 @@ This section covers matrix operations, matrix/frustum queries, and coordinate sp
 ## Coordinate space conversions
-1. `transformPosition(point = p5.Tree.ORIGIN, [{ [from = p5.Tree.EYE], [to = p5.Tree.WORLD], [pMatrix], [vMatrix], [eMatrix], [pvMatrix], [ipvMatrix] }])`
-2. `transformDirection(vector = p5.Tree._k, [{ [from = p5.Tree.EYE], [to = p5.Tree.WORLD], [vMatrix], [eMatrix], [pMatrix] }])`
+1. `mapLocation(point = p5.Tree.ORIGIN, [{ [from = p5.Tree.EYE], [to = p5.Tree.WORLD], [pMatrix], [vMatrix], [eMatrix], [pvMatrix], [ipvMatrix] }])`
+2. `mapDirection(vector = p5.Tree._k, [{ [from = p5.Tree.EYE], [to = p5.Tree.WORLD], [vMatrix], [eMatrix], [pMatrix] }])`
 Pass matrix parameters when you have **cached** those matrices (see [Matrix queries](#matrix-queries)) to speed up repeated conversions:
@@ -200,8 +201,8 @@ function draw() {
   cachedPVI = ipvMatrix() // compute once per frame
   // many fast conversions using the cached matrix
-  const a = transformPosition([0, 0, 0], { from: p5.Tree.WORLD, to: p5.Tree.SCREEN, ipvMatrix: cachedPVI })
-  const b = transformPosition([100, 0, 0], { from: p5.Tree.WORLD, to: p5.Tree.SCREEN, ipvMatrix: cachedPVI })
+  const a = mapLocation([0, 0, 0], { from: p5.Tree.WORLD, to: p5.Tree.SCREEN, ipvMatrix: cachedPVI })
+  const b = mapLocation([100, 0, 0], { from: p5.Tree.WORLD, to: p5.Tree.SCREEN, ipvMatrix: cachedPVI })
   // ...
 }
 ```
@@ -222,7 +223,7 @@ function draw() {
   pop()
   // screen projection of the model origin
-  const s = transformPosition(p5.Tree.ORIGIN, { from: model, to: p5.Tree.SCREEN })
+  const s = mapLocation(p5.Tree.ORIGIN, { from: model, to: p5.Tree.SCREEN })
   beginHUD()
   bullsEye({ x: s.x, y: s.y, size: 30 })
   endHUD()
@@ -234,8 +235,8 @@ function draw() {
 1. Returned vectors are `p5.Vector` instances.
 2. `from` and `to` may be matrices or any of: `p5.Tree.WORLD`, `p5.Tree.EYE`, `p5.Tree.SCREEN`, `p5.Tree.NDC`, `p5.Tree.MODEL`.
 3. When no matrix params are passed, current renderer values are used.
-4. The default `transformPosition()` call (i.e. eye → world at origin) returns the camera world position.
-5. The default `transformDirection()` call returns the normalized camera viewing direction.
+4. The default `mapLocation()` call (i.e. eye → world at origin) returns the camera world position.
+5. The default `mapDirection()` call returns the normalized camera viewing direction.
 6. Useful vector constants: `p5.Tree.ORIGIN`, `p5.Tree._k`, `p5.Tree.i`, `p5.Tree.j`, `p5.Tree.k`, `p5.Tree._i`, `p5.Tree._j`.
 ## Heads Up Display
@@ -272,36 +273,98 @@ Debug / teaching primitives for visualizing common 3D concepts:
 ---
-# Installation
+# Releases
-Link `p5.tree.js` after you have linked in `p5.js`. For example:
+- **Latest (v0.0.2):**
+  These links always point to the latest published version on npm.
+  - [p5.tree.js (unminified, IIFE)](https://cdn.jsdelivr.net/npm/p5.tree/dist/p5.tree.js)
+  - [p5.tree.min.js (minified, IIFE)](https://cdn.jsdelivr.net/npm/p5.tree/dist/p5.tree.min.js)
+  - [p5.tree.esm.js (ES module)](https://cdn.jsdelivr.net/npm/p5.tree/dist/p5.tree.esm.js)
+  - [npm package](https://www.npmjs.com/package/p5.tree)
-```html
-<!doctype html>
-<html>
-<head>
-  <script src="p5.js"></script>
-  <script src="p5.sound.js"></script>
-  <script src=https://cdn.jsdelivr.net/gh/VisualComputing/p5.tree/p5.tree.js></script>
-  <script src="sketch.js"></script>
-</head>
-<body>
-</body>
-</html>
-```
+- **Current tagged version (v0.0.2):**
+  Use these if you want to lock to a specific version.
+  - [p5.tree@0.0.2.js (unminified, IIFE)](https://cdn.jsdelivr.net/npm/p5.tree@0.0.2/dist/p5.tree.js)
+  - [p5.tree@0.0.2.min.js (minified, IIFE)](https://cdn.jsdelivr.net/npm/p5.tree@0.0.2/dist/p5.tree.min.js)
+  - [p5.tree@0.0.2.esm.js (ES module)](https://cdn.jsdelivr.net/npm/p5.tree@0.0.2/dist/p5.tree.esm.js)
+  - [npm package (v0.0.2)](https://www.npmjs.com/package/p5.tree/v/0.0.2)
+---
+# Usage
+The library works in two setups:
+- **[CDN](#cdn)**: Use the [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE)
+  (Immediately Invoked Function Expression) format with `<script>` tags directly in the browser,
+  along with [p5.js](https://beta.p5js.org/).
+- **[npm](#npm-esm)**: Use the
+  [ES module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
+  version in modern projects with [Vite](https://vitejs.dev/) or another bundler.
+## CDN
-To include the minified build (when available):
+Include both libraries using `<script>` tags, which run in both [global](https://github.com/processing/p5.js/wiki/Global-and-instance-mode) and [instance mode](https://github.com/processing/p5.js/wiki/Global-and-instance-mode).
 ```html
-<script src=https://cdn.jsdelivr.net/gh/VisualComputing/p5.tree/p5.tree.min.js></script>
+<!-- index.html -->
+<!-- Load p5.js first (required by p5.tree) -->
+<script src="https://cdn.jsdelivr.net/npm/p5/lib/p5.min.js"></script>
+<!-- Load p5.tree (latest stable version) -->
+<script src="https://cdn.jsdelivr.net/npm/p5.tree/dist/p5.tree.js"></script>
+<script>
+  function setup() {
+    createCanvas(600, 400, WEBGL)
+    // Example: draw world axes
+    axes(100)
+  }
+  function draw() {
+    background(0.15)
+    orbitControl()
+  }
+</script>
+````
+You can run the example, which uses global mode, by opening the `index.html` file in a browser, or by using
+[VSCodium](https://vscodium.com/) (recommended) or [Visual Studio Code](https://code.visualstudio.com/)
+with the [Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer).
+## npm (ESM)
+Install both [`p5`](https://www.npmjs.com/package/p5) and [`p5.tree`](https://www.npmjs.com/package/p5.tree) as dependencies:
+```bash
+npm i p5 p5.tree
 ```
-# [vs-code](https://code.visualstudio.com/) & [vs-codium](https://vscodium.com/) & [gitpod](https://www.gitpod.io/) hacking instructions
+Then import them in your project’s entry file (e.g. `main.js`) using a
+modern bundler like [Vite](https://vitejs.dev/), which runs in
+[instance mode](https://github.com/processing/p5.js/wiki/Global-and-instance-mode) only:
-Clone the repo (`git clone https://github.com/VisualComputing/p5.tree`) and open it with your favorite editor.
+```js
+// main.js
+import p5 from 'p5'
+import 'p5.tree'
+const sketch = p => {
+  p.setup = () => {
+    p.createCanvas(600, 400, p.WEBGL)
+    // Example: draw world axes
+    p.axes(100)
+  }
+  p.draw = () => {
+    p.background(0.15)
+    p.orbitControl()
+  }
+}
-If you are developing against p5 v2, keep an eye on:
+new p5(sketch)
+```
-1. [Creating libraries](https://beta.p5js.org/contribute/creating_libraries/)
-2. [p5.js source architecture](https://github.com/processing/p5.js/blob/main/src/core/README.md)
-3. [WEBGL mode architecture](https://github.com/processing/p5.js/blob/main/contributor_docs/webgl_mode_architecture.md)
+This approach provides full modularity, clean instance isolation, and compatibility with modern JavaScript tooling.

package/dist/p5.tree.esm.js CHANGED Viewed

@@ -2,7 +2,7 @@ import p5 from 'p5';
 /**
  * @file Adds Tree rendering functions to the p5 prototype.
- * @version 0.0.1
+ * @version 0.0.2
  * @author JP Charalambos
  * @license GPL-3.0-only
  *
@@ -38,7 +38,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
   const CONST = value => ({ value, writable: false, enumerable: true, configurable: false });
   Object.defineProperties(p5.Tree, {
-    VERSION: CONST('0.0.1'),
+    VERSION: CONST('0.0.2'),
     NONE: CONST(0),
@@ -301,7 +301,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
   /**
    * lMatrix({ from, to }):
-   * Location transform (mat4) mapping points from `from` space to `to` space.
+   * Position transform (mat4) mapping points from `from` space to `to` space.
    * treegl semantics: to^-1 * from.
    * @param {object} [opts]
    * @param {p5.Matrix} [opts.from=new p5.Matrix()] Source frame matrix.
@@ -317,7 +317,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
   /**
    * lMatrix({ from, to }):
-   * Location transform (mat4) mapping points from `from` space to `to` space.
+   * Position transform (mat4) mapping points from `from` space to `to` space.
    * Requires WEBGL.
    * @param {object} [opts]
    * @param {p5.Matrix} [opts.from]
@@ -815,7 +815,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
   /**
    * Interpolate camera pose at normalized global t in [0..1] along the whole path.
-   * Also updates internal seg/f so playPath resumes from that location.
+   * Also updates internal seg/f so playPath resumes from that position.
    */
   const seekGlobal = function (cam, t) {
     const path = ensurePath(cam);
@@ -1441,7 +1441,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
   };
   // ---------------------------------------------------------------------------
-  // Space transforms: transformPosition / transformDirection
+  // Space transforms: mapLocation / mapDirection
   // ---------------------------------------------------------------------------
   p5.RendererGL.prototype._parseTransformArgs = function (defaultMainArg, ...args) {
@@ -1461,8 +1461,8 @@ p5.registerAddon((p5, fn, lifecycles) => {
   // Points (positions)
   // ---------------------------------------------------------------------------
-  fn.transformPosition = function (...args) {
-    return _rendererGL(this)?.transformPosition(...args);
+  fn.mapLocation = function (...args) {
+    return _rendererGL(this)?.mapLocation(...args);
   };
   /**
@@ -1479,12 +1479,12 @@ p5.registerAddon((p5, fn, lifecycles) => {
    * @param {p5.Matrix} [opts.ipvMatrix]
    * @returns {p5.Vector}
    */
-  p5.RendererGL.prototype.transformPosition = function (...args) {
+  p5.RendererGL.prototype.mapLocation = function (...args) {
     const { mainArg, options } = this._parseTransformArgs(p5.Tree.ORIGIN, ...args);
-    return this._position(mainArg, options);
+    return this._location(mainArg, options);
   };
-  p5.RendererGL.prototype._position = function (
+  p5.RendererGL.prototype._location = function (
     point = p5.Tree.ORIGIN,
     {
       from = p5.Tree.EYE,
@@ -1598,7 +1598,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     if (from == p5.Tree.EYE && to instanceof p5.Matrix) {
       return to.copy().invert(to).mult4((eMatrix ?? this.eMatrix()).mult4(point));
     }
-    console.error('couldn\'t parse your transformPosition query!');
+    console.error('couldn\'t parse your mapLocation query!');
     return point;
   };
@@ -1670,8 +1670,8 @@ p5.registerAddon((p5, fn, lifecycles) => {
   // Directions (vector displacements)
   // ---------------------------------------------------------------------------
-  fn.transformDirection = function (...args) {
-    return _rendererGL(this)?.transformDirection(...args);
+  fn.mapDirection = function (...args) {
+    return _rendererGL(this)?.mapDirection(...args);
   };
   /**
@@ -1686,7 +1686,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
    * @param {p5.Matrix} [opts.pMatrix]
    * @returns {p5.Vector}
    */
-  p5.RendererGL.prototype.transformDirection = function (...args) {
+  p5.RendererGL.prototype.mapDirection = function (...args) {
     const { mainArg, options } = this._parseTransformArgs(p5.Tree._k, ...args);
     return this._direction(mainArg, options);
   };
@@ -1781,7 +1781,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
         this._screenToWorldDirection(this._ndcToScreenDirection(vector), pMatrix)
       );
     }
-    console.error('[p5.tree] transformDirection: could not parse query.');
+    console.error('[p5.tree] mapDirection: could not parse query.');
     return vector;
   };
@@ -1792,7 +1792,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     let dy = eyeVector.y;
     const perspective = pMatrix.mat4[15] === 0;
     if (perspective) {
-      const zEye = this._position(p5.Tree.ORIGIN, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z;
+      const zEye = this._location(p5.Tree.ORIGIN, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z;
       const k = Math.abs(zEye * Math.tan(pMatrix.fov() / 2));
       dx /= 2 * k / this.height;
       dy /= 2 * k / this.height;
@@ -1814,7 +1814,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     const perspective = pMatrix.mat4[15] === 0;
     if (perspective) {
-      const zEye = this._position(p5.Tree.ORIGIN, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z;
+      const zEye = this._location(p5.Tree.ORIGIN, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z;
       const k = Math.abs(zEye * Math.tan(pMatrix.fov() / 2));
       dx *= 2 * k / this.height;
       dy *= 2 * k / this.height;
@@ -1869,7 +1869,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     return this.isOrtho()
       ? Math.abs(this.tPlane() - this.bPlane()) / this.height
       : 2 * Math.abs(
-        this.transformPosition(point, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z
+        this.mapLocation(point, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z
       ) * Math.tan(this.fov() / 2) / this.height;
   };
@@ -2158,10 +2158,10 @@ p5.registerAddon((p5, fn, lifecycles) => {
     // If target screen position not provided, derive it from mMatrix.
     // In that case, treat `size` as world units and convert to pixels locally.
     if (x == null || y == null) {
-      const screen = this.transformPosition({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
+      const screen = this.mapLocation({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
       x = screen.x;
       y = screen.y;
-      const world = this.transformPosition({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
+      const world = this.mapLocation({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
       size = size / this.pixelRatio(world);
     }
     const r = size / 2.0;
@@ -2262,10 +2262,10 @@ p5.registerAddon((p5, fn, lifecycles) => {
     if (!p) return;
     if (x == null || y == null) {
-      const screen = this.transformPosition({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
+      const screen = this.mapLocation({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
       x = screen.x;
       y = screen.y;
-      const world = this.transformPosition({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
+      const world = this.mapLocation({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
       size = size / this.pixelRatio(world);
     }
     const half = size / 2.0;
@@ -2315,10 +2315,10 @@ p5.registerAddon((p5, fn, lifecycles) => {
     const p = this._pInst;
     if (!p) return;
     if (x == null || y == null) {
-      const screen = this.transformPosition({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
+      const screen = this.mapLocation({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
       x = screen.x;
       y = screen.y;
-      const world = this.transformPosition({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
+      const world = this.mapLocation({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
       size = size / this.pixelRatio(world);
     }
     const half = size / 2.0;
@@ -2666,7 +2666,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     const normals = Array(6);
     const distances = Array(6);
     // Camera position and basis in world space.
-    const pos = this._position([0, 0, 0], { from: p5.Tree.EYE, to: p5.Tree.WORLD, eMatrix });
+    const pos = this._location([0, 0, 0], { from: p5.Tree.EYE, to: p5.Tree.WORLD, eMatrix });
     const viewDir = this._direction([0, 0, -1], { from: p5.Tree.EYE, to: p5.Tree.WORLD, vMatrix });
     const up = this._direction([0, 1, 0], { from: p5.Tree.EYE, to: p5.Tree.WORLD, vMatrix });
     const right = this._direction([1, 0, 0], { from: p5.Tree.EYE, to: p5.Tree.WORLD, vMatrix });