p5.tree 0.0.1 → 0.0.3

package/dist/p5.tree.js

@@ -3,7 +3,7 @@
 
   /**
    * @file Adds Tree rendering functions to the p5 prototype.
-   * @version 0.0.1
+   * @version 0.0.3
    * @author JP Charalambos
    * @license GPL-3.0-only
    *
@@ -39,7 +39,7 @@
     const CONST = value => ({ value, writable: false, enumerable: true, configurable: false });
     
     Object.defineProperties(p5.Tree, {
-      VERSION: CONST('0.0.1'),
+      VERSION: CONST('0.0.3'),
                             
       NONE: CONST(0),
     
@@ -49,6 +49,7 @@
       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])),
@@ -69,9 +70,6 @@
       Z: CONST(1 << 4),
       _Z: CONST(1 << 5),
       LABELS: CONST(1 << 6),
-      
-      DOTS: CONST(0),
-      SOLID: CONST(1),
                             
       // bullsEye
       CIRCLE: CONST(0),
@@ -816,7 +814,7 @@
 
     /**
      * 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);
@@ -1442,7 +1440,7 @@
     };
     
     // ---------------------------------------------------------------------------
-    // Space transforms: transformPosition / transformDirection
+    // Space transforms: mapLocation / mapDirection
     // ---------------------------------------------------------------------------
     
     p5.RendererGL.prototype._parseTransformArgs = function (defaultMainArg, ...args) {
@@ -1462,8 +1460,8 @@
     // Points (positions)
     // ---------------------------------------------------------------------------
     
-    fn.transformPosition = function (...args) {
-      return _rendererGL(this)?.transformPosition(...args);
+    fn.mapLocation = function (...args) {
+      return _rendererGL(this)?.mapLocation(...args);
     };
     
     /**
@@ -1480,12 +1478,12 @@
      * @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,
@@ -1507,25 +1505,25 @@
         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,
@@ -1537,8 +1535,8 @@
           ? (vMatrix ?? this.vMatrix())
           : to.copy().invert(to)
         ).mult4(
-          this._screenToWorldPosition({
-            point: this._ndcToScreenPosition(point),
+          this._screenToWorldLocation({
+            point: this._ndcToScreenLocation(point),
             pMatrix,
             vMatrix,
             pvMatrix,
@@ -1547,8 +1545,8 @@
         );
       }
       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
@@ -1579,11 +1577,11 @@
           ? (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
@@ -1599,11 +1597,11 @@
       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;
     };
     
-    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),
@@ -1611,7 +1609,7 @@
       );
     };
     
-    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),
@@ -1619,7 +1617,7 @@
       );
     };
     
-    p5.RendererGL.prototype._worldToScreenPosition = function ({
+    p5.RendererGL.prototype._worldToScreenLocation = function ({
       point = new p5.Vector(0, 0, 0.5),
       pMatrix,
       vMatrix,
@@ -1642,7 +1640,7 @@
       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,
@@ -1671,8 +1669,8 @@
     // Directions (vector displacements)
     // ---------------------------------------------------------------------------
     
-    fn.transformDirection = function (...args) {
-      return _rendererGL(this)?.transformDirection(...args);
+    fn.mapDirection = function (...args) {
+      return _rendererGL(this)?.mapDirection(...args);
     };
     
     /**
@@ -1687,7 +1685,7 @@
      * @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);
     };
@@ -1782,7 +1780,7 @@
           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;
     };
     
@@ -1793,7 +1791,7 @@
       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;
@@ -1815,7 +1813,7 @@
     
       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;
@@ -1870,7 +1868,7 @@
       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;
     };
 
@@ -1966,6 +1964,49 @@
       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'],
@@ -2015,47 +2056,38 @@
       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();
     };
@@ -2159,10 +2191,10 @@
       // 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;
@@ -2263,10 +2295,10 @@
       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;
@@ -2316,10 +2348,10 @@
       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;
@@ -2667,7 +2699,7 @@
       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 });