p5.tree 0.0.2 → 0.0.3

package/README.md

@@ -266,7 +266,7 @@ A small collection of helpers commonly needed in interactive 3D sketches:
 Debug / teaching primitives for visualizing common 3D concepts:
 
 1. `axes({ size, colors, bits })`
-2. `grid({ size, subdivisions, style })`
+2. `grid({ size, subdivisions })`
 3. `cross({ mMatrix, x, y, size, ... })`
 4. `bullsEye({ mMatrix, x, y, size, shape, ... })`
 5. `viewFrustum({ pg, bits, viewer, eMatrix, pMatrix, vMatrix })`
@@ -275,19 +275,19 @@ Debug / teaching primitives for visualizing common 3D concepts:
 
 # Releases
 
-- **Latest (v0.0.2):**  
+- **Latest (v0.0.3):**  
   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)
 
-- **Current tagged version (v0.0.2):**  
+- **Current tagged version (v0.0.3):**  
   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)
+  - [p5.tree@0.0.3.js (unminified, IIFE)](https://cdn.jsdelivr.net/npm/p5.tree@0.0.3/dist/p5.tree.js)
+  - [p5.tree@0.0.3.min.js (minified, IIFE)](https://cdn.jsdelivr.net/npm/p5.tree@0.0.3/dist/p5.tree.min.js)
+  - [p5.tree@0.0.3.esm.js (ES module)](https://cdn.jsdelivr.net/npm/p5.tree@0.0.3/dist/p5.tree.esm.js)
+  - [npm package (v0.0.3)](https://www.npmjs.com/package/p5.tree/v/0.0.3)
 
 ---
 
@@ -295,12 +295,8 @@ Debug / teaching primitives for visualizing common 3D concepts:
 
 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](#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
 
@@ -329,9 +325,7 @@ Include both libraries using `<script>` tags, which run in both [global](https:/
 </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).
+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)
 
@@ -341,9 +335,7 @@ Install both [`p5`](https://www.npmjs.com/package/p5) and [`p5.tree`](https://ww
 npm i p5 p5.tree
 ```
 
-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:
+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:
 
 ```js
 // main.js

package/dist/p5.tree.esm.js

@@ -2,7 +2,7 @@ import p5 from 'p5';
 
 /**
  * @file Adds Tree rendering functions to the p5 prototype.
- * @version 0.0.2
+ * @version 0.0.3
  * @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.2'),
+    VERSION: CONST('0.0.3'),
                           
     NONE: CONST(0),
   
@@ -48,6 +48,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     NDC: CONST('NDC'),
     SCREEN: CONST('SCREEN'),
     MODEL: CONST('MODEL'),
+    OBJECT: CONST('MODEL'), // alias of MODEL (shader terminology)
   
     // Points and vectors
     ORIGIN: CONST(Object.freeze([0, 0, 0])),
@@ -68,9 +69,6 @@ p5.registerAddon((p5, fn, lifecycles) => {
     Z: CONST(1 << 4),
     _Z: CONST(1 << 5),
     LABELS: CONST(1 << 6),
-    
-    DOTS: CONST(0),
-    SOLID: CONST(1),
                           
     // bullsEye
     CIRCLE: CONST(0),
@@ -301,7 +299,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
 
   /**
    * lMatrix({ from, to }):
-   * Position transform (mat4) mapping points from `from` space to `to` space.
+   * Location 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 +315,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
 
   /**
    * lMatrix({ from, to }):
-   * Position transform (mat4) mapping points from `from` space to `to` space.
+   * Location transform (mat4) mapping points from `from` space to `to` space.
    * Requires WEBGL.
    * @param {object} [opts]
    * @param {p5.Matrix} [opts.from]
@@ -1506,25 +1504,25 @@ p5.registerAddon((p5, fn, lifecycles) => {
       to = this.mMatrix({ eMatrix });
     }
     if ((from == p5.Tree.WORLD) && (to == p5.Tree.SCREEN)) {
-      return this._worldToScreenPosition({ point, pMatrix, vMatrix, pvMatrix });
+      return this._worldToScreenLocation({ point, pMatrix, vMatrix, pvMatrix });
     }
     if ((from == p5.Tree.SCREEN) && (to == p5.Tree.WORLD)) {
-      return this._screenToWorldPosition({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix });
+      return this._screenToWorldLocation({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix });
     }
     if (from == p5.Tree.SCREEN && to == p5.Tree.NDC) {
-      return this._screenToNDCPosition(point);
+      return this._screenToNDCLocation(point);
     }
     if (from == p5.Tree.NDC && to == p5.Tree.SCREEN) {
-      return this._ndcToScreenPosition(point);
+      return this._ndcToScreenLocation(point);
     }
     if (from == p5.Tree.WORLD && to == p5.Tree.NDC) {
-      return this._screenToNDCPosition(
-        this._worldToScreenPosition({ point, pMatrix, vMatrix, pvMatrix })
+      return this._screenToNDCLocation(
+        this._worldToScreenLocation({ point, pMatrix, vMatrix, pvMatrix })
       );
     }
     if (from == p5.Tree.NDC && to == p5.Tree.WORLD) {
-      return this._screenToWorldPosition({
-        point: this._ndcToScreenPosition(point),
+      return this._screenToWorldLocation({
+        point: this._ndcToScreenLocation(point),
         pMatrix,
         vMatrix,
         pvMatrix,
@@ -1536,8 +1534,8 @@ p5.registerAddon((p5, fn, lifecycles) => {
         ? (vMatrix ?? this.vMatrix())
         : to.copy().invert(to)
       ).mult4(
-        this._screenToWorldPosition({
-          point: this._ndcToScreenPosition(point),
+        this._screenToWorldLocation({
+          point: this._ndcToScreenLocation(point),
           pMatrix,
           vMatrix,
           pvMatrix,
@@ -1546,8 +1544,8 @@ p5.registerAddon((p5, fn, lifecycles) => {
       );
     }
     if ((from instanceof p5.Matrix || from == p5.Tree.EYE) && to == p5.Tree.NDC) {
-      return this._screenToNDCPosition(
-        this._worldToScreenPosition({
+      return this._screenToNDCLocation(
+        this._worldToScreenLocation({
           point: (from == p5.Tree.EYE
             ? (eMatrix ?? this.eMatrix())
             : from
@@ -1578,11 +1576,11 @@ p5.registerAddon((p5, fn, lifecycles) => {
         ? (vMatrix ?? this.vMatrix())
         : to.copy().invert(to)
       ).mult4(
-        this._screenToWorldPosition({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix })
+        this._screenToWorldLocation({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix })
       );
     }
     if ((from instanceof p5.Matrix || from == p5.Tree.EYE) && to == p5.Tree.SCREEN) {
-      return this._worldToScreenPosition({
+      return this._worldToScreenLocation({
         point: (from == p5.Tree.EYE
           ? (eMatrix ?? this.eMatrix())
           : from
@@ -1602,7 +1600,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     return point;
   };
   
-  p5.RendererGL.prototype._ndcToScreenPosition = function (point) {
+  p5.RendererGL.prototype._ndcToScreenLocation = function (point) {
     return new p5.Vector(
       p5.prototype.map(point.x, -1, 1, 0, this.width),
       p5.prototype.map(point.y, -1, 1, 0, this.height),
@@ -1610,7 +1608,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     );
   };
   
-  p5.RendererGL.prototype._screenToNDCPosition = function (point) {
+  p5.RendererGL.prototype._screenToNDCLocation = function (point) {
     return new p5.Vector(
       p5.prototype.map(point.x, 0, this.width, -1, 1),
       p5.prototype.map(point.y, 0, this.height, -1, 1),
@@ -1618,7 +1616,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     );
   };
   
-  p5.RendererGL.prototype._worldToScreenPosition = function ({
+  p5.RendererGL.prototype._worldToScreenLocation = function ({
     point = new p5.Vector(0, 0, 0.5),
     pMatrix,
     vMatrix,
@@ -1641,7 +1639,7 @@ p5.registerAddon((p5, fn, lifecycles) => {
     return new p5.Vector(target[0], target[1], target[2]);
   };
   
-  p5.RendererGL.prototype._screenToWorldPosition = function ({
+  p5.RendererGL.prototype._screenToWorldLocation = function ({
     point = new p5.Vector(this.width / 2, this.height / 2, 0.5),
     pMatrix,
     vMatrix,
@@ -1965,6 +1963,49 @@ p5.registerAddon((p5, fn, lifecycles) => {
     return this;
   };
   
+  /**
+   * Draws 3D reference axes (X, Y, Z) centered at the origin in model space.
+   *
+   * Each axis can be enabled independently using bitwise flags, and optional
+   * axis labels (X, Y, Z) can be rendered near the positive ends.
+   *
+   * This is a WEBGL-only utility intended for debugging, teaching, and spatial
+   * orientation. Axes are drawn on the current Z=0 plane using the current
+   * stroke settings.
+   *
+   * @method axes
+   * @for p5.RendererGL
+   * @param {Object} [opts] Axes options.
+   * @param {Number} [opts.size=100] Length of each axis in world units.
+   * @param {Array<String>} [opts.colors=['Red','Lime','DodgerBlue']]
+   *        Stroke colors for X, Y, and Z axes respectively.
+   * @param {Number} [opts.bits=p5.Tree.LABELS | p5.Tree.X | p5.Tree.Y | p5.Tree.Z]
+   *        Bitmask controlling which axes and labels are drawn.
+   *
+   * @example
+   * function draw() {
+   *   background(30);
+   *   orbitControl();
+   *   axes({ size: 300 });
+   * }
+   *
+   * @example
+   * // Draw only X and Z axes, no labels
+   * axes({
+   *   size: 200,
+   *   bits: p5.Tree.X | p5.Tree.Z
+   * });
+   *
+   * @example
+   * // Draw full axes in both positive and negative directions
+   * axes({
+   *   size: 150,
+   *   bits: p5.Tree.X | p5.Tree._X |
+   *         p5.Tree.Y | p5.Tree._Y |
+   *         p5.Tree.Z | p5.Tree._Z |
+   *         p5.Tree.LABELS
+   * });
+   */
   p5.RendererGL.prototype.axes = function ({
     size = 100,
     colors = ['Red', 'Lime', 'DodgerBlue'],
@@ -2014,47 +2055,38 @@ p5.registerAddon((p5, fn, lifecycles) => {
     return this;
   };
   
+  /**
+   * Draws a simple X/Y reference grid on the Z=0 plane in the current model space.
+   *
+   * The grid is centered at the origin and spans from `-size` to `+size` on both X and Y.
+   * It draws `subdivisions + 1` lines in each direction (including the borders).
+   *
+   * This is a WEBGL-only utility intended for debugging and spatial reference.
+   *
+   * @method grid
+   * @for p5.RendererGL
+   * @param {Object} [opts] Grid options.
+   * @param {Number} [opts.size=100] Half-extent of the grid in world units.
+   * @param {Number} [opts.subdivisions=10] Number of subdivisions per side (must be >= 1).
+   * @example
+   * function draw() {
+   *   background(30);
+   *   orbitControl();
+   *   grid({ size: 300, subdivisions: 20 });
+   * }
+   */
   p5.RendererGL.prototype.grid = function ({
     size = 100,
-    subdivisions = 10,
-    style = p5.Tree.SOLID,
-    weight = 1,
-    minorSubdivisions = 5
+    subdivisions = 10
   } = {}) {
     const p = this._pInst;
-    if (!p) return;
+    if (!p) return;  
+    subdivisions = Math.max(1, subdivisions);
     p.push();
-    if (style === p5.Tree.DOTS) {
-      let posi = 0;
-      let posj = 0;
-      p.strokeWeight(weight * 2);
-      p.beginShape(p.POINTS);
-      for (let i = 0; i <= subdivisions; ++i) {
-        posi = size * (2.0 * i / subdivisions - 1.0);
-        for (let j = 0; j <= subdivisions; ++j) {
-          posj = size * (2.0 * j / subdivisions - 1.0);
-          p.vertex(posi, posj, 0);
-        }
-      }
-      p.endShape();
-      const internalSub = Math.max(1, minorSubdivisions | 0);
-      const subSubdivisions = subdivisions * internalSub;
-      p.strokeWeight(weight);
-      p.beginShape(p.POINTS);
-      for (let i = 0; i <= subSubdivisions; ++i) {
-        posi = size * (2.0 * i / subSubdivisions - 1.0);
-        for (let j = 0; j <= subSubdivisions; ++j) {
-          posj = size * (2.0 * j / subSubdivisions - 1.0);
-          ((i % internalSub) !== 0 || (j % internalSub) !== 0) && p.vertex(posi, posj, 0);
-        }
-      }
-      p.endShape();
-    } else {
-      for (let i = 0; i <= subdivisions; ++i) {
-        const pos = size * (2.0 * i / subdivisions - 1.0);
-        p.line(pos, -size, 0, pos, +size, 0);
-        p.line(-size, pos, 0, size, pos, 0);
-      }
+    for (let i = 0; i <= subdivisions; ++i) {
+      const pos = size * (2.0 * i / subdivisions - 1.0);
+      p.line(pos, -size, 0, pos, +size, 0);
+      p.line(-size, pos, 0, +size, pos, 0);
     }
     p.pop();
   };