SketchWave Point Reference

/*
File: swPoint.js
Date: 2026-01-30
Author: klp
Workspace: SWaveJS2026-01-30-StgC
Purpose: SWPoint class for SketchWaveJS
Comment(s):

TODO:

=== Notes ===:
- This class assumes p5.js and SWColor are loaded in the environment.
- SWPoint class represents points or vectors in 2D or 3D space with styling options.
- Includes properties for position (x, y, z), stroke weight, and stroke color.
- Supports pen trail functionality to track and draw the path of the point.
- Designed to be compatible with p5.js and the SWColor class.
- Methods for drawing the point and its trail in screen coordinates.
- Additional methods for movement and vector math can be added as needed.
- For heavy math, consider extending or wrapping p5.Vector.
- strokeColor should be an SWColor instance for consistency.
- Optionally, you can add fillColor or other style properties.
- Pen trail logic includes enabling/disabling the pen, storing trail points, and limiting trail length.
- You can extend this class for animated or interactive points.
*/

console.log("[swPoint.js] SWPoint class loaded.");

class SWPoint {
    /**
     * @param {number} x - X coordinate
     * @param {number} y - Y coordinate
     * @param {number} [z] - Z coordinate (optional, for 3D)
     * @param {number} [strokeWeight=1] - Stroke weight
     * @param {SWColor} [strokeColor] - Stroke color (SWColor instance)
     */
    
    constructor(x, y, z = undefined, strokeWeight = 1, strokeColor = undefined) {
        this.x = x;
        this.y = y;
        this.z = z;
        this.strokeWeight = strokeWeight;
        this.strokeColor = strokeColor; // Always store SWColor instance

        // Pen trail logic
        this.penOn = false;
        this.trail = [];
        this.maxTrailLength = 500; // default, can be changed
    }//end constructor

    /**
     * Draws the point using p5.js in screen coordinates
     */
    draw() {
        if (this.strokeColor && this.strokeColor.col) {
            stroke(this.strokeColor.col);
        }
        strokeWeight(this.strokeWeight);
        if (this.z !== undefined) {
            point(this.x, this.y, this.z);
        } else {
            point(this.x, this.y);
        }
        noStroke();
        strokeWeight(1);
    }//end draw

    /**
     * Draws the point using user (grid) coordinates mapped by the given SWGrid
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        const {x: px, y: py} = grid.userToScreen(this.x, this.y);
        if (this.strokeColor && this.strokeColor.col) {
            stroke(this.strokeColor.col);
        }
        strokeWeight(this.strokeWeight);
        if (this.z !== undefined) {
            point(px, py, this.z);
        } else {
            point(px, py);
        }
        noStroke();
        strokeWeight(1);
    }//end drawOnGrid

    /**
     * Pen trail enhancements:
     * - penOn: whether the pen is active
     * - trail: array of previous positions [{x, y, z}]
     * - maxTrailLength: maximum number of points in the trail
     */
    /**
     * Draws the pen trail in screen coordinates
     */
    drawTrail() {
        if (!this.penOn || this.trail.length < 2) return;
        noFill();
        stroke(this.strokeColor && this.strokeColor.col ? this.strokeColor.col : 0);
        strokeWeight(Math.max(1, this.strokeWeight / 2));
        beginShape();
        for (const pt of this.trail) {
            if (this.z !== undefined && pt.z !== undefined) {
                vertex(pt.x, pt.y, pt.z);
            } else {
                vertex(pt.x, pt.y);
            }
        }
        endShape();
        noStroke();
        strokeWeight(1);
    }//end drawTrail

    /**
     * Draws the pen trail in user (grid) coordinates
     * @param {SWGrid} grid
     */
    drawTrailOnGrid(grid) {
        if (!this.penOn || this.trail.length < 2) return;
        noFill();
        stroke(this.strokeColor && this.strokeColor.col ? this.strokeColor.col : 0);
        strokeWeight(Math.max(1, this.strokeWeight / 2));
        beginShape();
        for (const pt of this.trail) {
            const {x, y} = grid.userToScreen(pt.x, pt.y);
            vertex(x, y);
        }
        endShape();
        noStroke();
        strokeWeight(1);
    }//end drawTrailOnGrid

    /**
     * Moves the point by dx, dy, dz
     * If pen is on, records the new position in the trail
     */
    move(dx, dy, dz = 0) {
        this.x += dx;
        this.y += dy;
        if (this.z !== undefined) this.z += dz;
        this._updateTrail();
    }//end move

    /**
     * Call this after manually setting x/y/z to update the trail if pen is on
     * Private method: do not call directly (as indicated by underscore prefix)
     */
    _updateTrail() {
        if (this.penOn) {
            // Only add if position changed
            if (
                this.trail.length === 0 ||
                this.trail[this.trail.length - 1].x !== this.x ||
                this.trail[this.trail.length - 1].y !== this.y ||
                this.trail[this.trail.length - 1].z !== this.z
            ) {
                this.trail.push({ x: this.x, y: this.y, z: this.z });
                if (this.trail.length > this.maxTrailLength) {
                    this.trail.shift();
                }
            }
        }
    }//end _updateTrail

    /**
     * Enable or disable the pen trail
     * @param {boolean} on
     */
    setPen(on = true) {
        this.penOn = on;
        if (!on) this.trail = [];
    }//end setPen

    /**
     * Set the maximum trail length
     * @param {number} n
     */
    setMaxTrailLength(n) {
        this.maxTrailLength = n;
        if (this.trail.length > n) {
            this.trail = this.trail.slice(-n);
        }
    }//end setMaxTrailLength

    /**
     * Clears the pen trail history, regardless of pen state
     */
    clearTrail() {
        this.trail = [];
    }//end clearTrail

    /**
     * Sets the stroke color
     * @param {SWColor} swColor
     */
    setStrokeColor(swColor) {
        this.strokeColor = swColor;
    }//end setStrokeColor

    /**
     * Sets the stroke weight
     * @param {number} w
     */
    setStrokeWeight(w) {
        this.strokeWeight = w;
    }//end setStrokeWeight

    /**
     * Returns a string representation
     */
    toString() {
        return `SWPoint(x: ${this.x}, y: ${this.y}` +
            (this.z !== undefined ? `, z: ${this.z}` : '') +
            `, strokeWeight: ${this.strokeWeight}, strokeColor: ${this.strokeColor ? this.strokeColor.toString() : 'none'}, penOn: ${this.penOn}, trailLen: ${this.trail.length})`;
    }//end toString

    /**
     * Returns the Euclidean distance to another SWPoint in user coordinates
     * @param {SWPoint} otherSWPt
     * @returns {number}
     */
    distanceTo(otherSWPt) {
        const dx = this.x - otherSWPt.x;
        const dy = this.y - otherSWPt.y;
        // If both have z, use 3D distance; otherwise, 2D
        if (this.z !== undefined && otherSWPt.z !== undefined) {
            const dz = this.z - otherSWPt.z;
            return Math.sqrt(dx * dx + dy * dy + dz * dz);
        } else {
            return Math.sqrt(dx * dx + dy * dy);
        }
    }//end distanceTo
}//end SWPoint class