🌀 SWSpiral Reference

/*
File: swSpiral.js
Date: 2026-04-27
Author: klp
App:  SketchWaveTNT2026-04-21-Stg8
Purpose: SWSpiral class for SketchWaveJS

SWSpiral represents an Archimedean spiral defined by the polar equation
r = k · θ / π  in a coordinate system centered at a given center point:

  center (SWPoint) — the origin of the spiral (where θ = 0, r = 0)
  k (number)       — growth coefficient controlling arm spacing:
                     r = k · θ / π
                     At θ = π  (half turn) : r = k
                     At θ = 2π (one full turn): r = 2k
                     After n full turns     : r = 2kn
  revolutions (number) — how many full 360° turns the spiral traces (must be > 0)
  clockwise (boolean)  — if true, spiral winds clockwise; if false, CCW (default)

In Cartesian (user-space, y-up):
  x = r · cos(θ)    y = r · sin(θ)   for CCW
  x = r · cos(θ)    y = −r · sin(θ)  for CW  (same as θ → −θ)

The drawn shape is a closed polygon: the spiral arc sampled at
SAMPLE_COUNT × revolutions points from the center outward to the tip,
then a straight line back to the center.  Fill is applied to the
enclosed interior; stroke is drawn along the full outline.

Fill semantics:
  The fill color covers the interior of the spiral polygon.  With multiple
  revolutions the p5.js non-zero-winding fill naturally shades the regions
  between the arms, giving the appearance of the fill color showing through
  the gaps in the spiral stroke.  Use a semi-transparent fill for the best
  visual layering effect.

Rotation:
  rotationDeg — static base rotation (CCW degrees), set by setRotation().
                Persists across frames; survives reset().
  rotation    — accumulated rotation (degrees), incremented by rotate().
                Starts at 0; reset() returns it to 0.
  Effective rotation = rotationDeg + rotation.  All rotation is CCW positive.
  All rotation is applied about the CENTER point.

Angle convention (same as all SketchWaveJS classes):
  User space:  CCW positive, y increases upward (standard math/Cartesian).
  p5 screen:   CW  positive, y increases downward.
  SWSpiral handles the y-flip internally; always pass CCW degrees.

Dependencies: p5.js, SWColor, SWPoint, SWGrid.
*/

console.log("[swSpiral.js] SWSpiral class loaded.");

class SWSpiral {

    static SAMPLE_COUNT = 120;  // sample points per full revolution

    /**
     * @param {SWPoint} center           - Center of the spiral in user (grid) coordinates
     * @param {number}  k                - Growth coefficient (r = k·θ/π). Larger = wider arm spacing.
     * @param {number}  [revolutions=3]  - Number of full turns to draw (must be > 0)
     * @param {SWColor} [strokeColor]    - Spiral line / border color (undefined = no stroke)
     * @param {SWColor} [fillColor]      - Fill color for spiral interior (undefined = no fill)
     * @param {number}  [thickness=2]    - Stroke weight in pixels
     * @param {boolean} [clockwise=false]- Wind clockwise (true) or counter-clockwise (false)
     * @param {number}  [rotationDeg=0]  - Static base rotation in CCW degrees
     */
    constructor(center, k, revolutions = 3,
                strokeColor = undefined, fillColor = undefined,
                thickness = 2, clockwise = false, rotationDeg = 0) {

        this.center      = center;
        this.k           = k;
        this.revolutions = Math.max(0.25, revolutions);
        this.strokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.fillColor   = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.thickness   = thickness;
        this.clockwise   = clockwise;
        this.rotationDeg = rotationDeg;
        this.rotation    = 0;   // accumulated via rotate(); cleared by reset()

        // ── Originals for reset() ──────────────────────────────────────────────
        this.originalK           = k;
        this.originalRevolutions = this.revolutions;
        this.originalStrokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.originalFillColor   = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.originalThickness   = thickness;
        this.originalClockwise      = clockwise;
        this.originalRotationDeg    = rotationDeg;
        this.showClosingLine        = false;   // default: no line from tip back to center
        this.originalShowClosingLine = false;

    }//end constructor

    // ── Internal helpers ──────────────────────────────────────────────────────

    /** @returns {number} Total effective rotation in degrees. */
    _totalRotDeg() { return this.rotationDeg + this.rotation; }

    /**
     * Rotates a local math-space displacement (lx, ly) by totalRotation degrees (CCW+).
     * @returns {{ x: number, y: number }} rotated displacement in math-space
     */
    _rotateLocal(lx, ly) {
        const rad  = this._totalRotDeg() * Math.PI / 180;
        const cosR = Math.cos(rad);
        const sinR = Math.sin(rad);
        return {
            x: lx * cosR - ly * sinR,
            y: lx * sinR + ly * cosR,
        };
    }

    /**
     * Builds an array of { x, y } positions in user (math) space.
     * The final entry is the center point, closing the polygon back to the origin.
     * @returns {{ x: number, y: number }[]}
     */
    _buildUserPts() {
        const cx         = this.center.x;
        const cy         = this.center.y;
        const maxTheta   = 2 * Math.PI * this.revolutions;
        const totalSteps = Math.max(3, Math.round(SWSpiral.SAMPLE_COUNT * this.revolutions));
        const dir        = this.clockwise ? -1 : 1;
        const pts        = [];

        for (let i = 0; i <= totalSteps; i++) {
            const theta = (i / totalSteps) * maxTheta;
            const r     = (this.k * theta) / Math.PI;
            const lx    = r * Math.cos(dir * theta);
            const ly    = r * Math.sin(dir * theta);
            const rot   = this._rotateLocal(lx, ly);
            pts.push({ x: cx + rot.x, y: cy + rot.y });
        }

        // Close back to center so the polygon fills correctly
        pts.push({ x: cx, y: cy });
        return pts;
    }

    /**
     * Builds screen-space { x, y } points using the given SWGrid.
     * grid.userToScreen() handles the math-space ↔ screen y-flip.
     */
    _buildScreenPtsGrid(grid) {
        return this._buildUserPts().map(p => grid.userToScreen(p.x, p.y));
    }

    /**
     * Builds screen-space { x, y } points for draw() (no grid).
     * The math-space y-displacement is negated to produce correct screen-space y (down).
     */
    _buildScreenPtsDirect() {
        const cx         = this.center.x;
        const cy         = this.center.y;
        const maxTheta   = 2 * Math.PI * this.revolutions;
        const totalSteps = Math.max(3, Math.round(SWSpiral.SAMPLE_COUNT * this.revolutions));
        const dir        = this.clockwise ? -1 : 1;
        const pts        = [];

        for (let i = 0; i <= totalSteps; i++) {
            const theta = (i / totalSteps) * maxTheta;
            const r     = (this.k * theta) / Math.PI;
            const lx    = r * Math.cos(dir * theta);
            const ly    = r * Math.sin(dir * theta);
            const rot   = this._rotateLocal(lx, ly);
            pts.push({ x: cx + rot.x, y: cy - rot.y });   // y-flip for screen
        }

        // Close back to center
        pts.push({ x: cx, y: cy });
        return pts;
    }

    /**
     * Executes two-pass draw: fill (always closed) then stroke (closed only when showClosingLine).
     * screenPts includes the explicit center closing point at the end.
     */
    _drawShape(screenPts) {
        // ── Fill pass: always close so the interior fills correctly ──────────────
        if (this.fillColor && this.fillColor.col) {
            fill(this.fillColor.col);
            noStroke();
            beginShape();
            for (const sp of screenPts) vertex(sp.x, sp.y);
            endShape(CLOSE);
        }

        // ── Stroke pass: close (tip→center) only when showClosingLine is true ────
        if (this.strokeColor && this.strokeColor.col) {
            noFill();
            stroke(this.strokeColor.col);
            strokeWeight(this.thickness);
            if (this.showClosingLine) {
                // Draw full polygon including the closing line tip→center
                beginShape();
                for (const sp of screenPts) vertex(sp.x, sp.y);
                endShape(CLOSE);
            } else {
                // Draw only the spiral arc — omit the explicit closing center point
                beginShape();
                const arcPts = screenPts.slice(0, -1);
                for (const sp of arcPts) vertex(sp.x, sp.y);
                endShape();
            }
        }

        noStroke();
        noFill();
        strokeWeight(1);
    }

    // ── Drawing ───────────────────────────────────────────────────────────────

    /**
     * Draws the spiral in raw screen (pixel) coordinates.
     * Prefer drawOnGrid() for standard canvas use.
     */
    draw() {
        const screenPts = this._buildScreenPtsDirect();
        this._drawShape(screenPts);
        if (this.center && this.center.draw) {
            this.center.draw(this.strokeColor);
        }
    }//end draw

    /**
     * Draws the spiral mapped through the given SWGrid's coordinate system.
     * This is the standard drawing method to use in a p5.js draw() loop.
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        const screenPts = this._buildScreenPtsGrid(grid);
        this._drawShape(screenPts);
        if (this.center && this.center.drawOnGrid) {
            this.center.drawOnGrid(grid, this.strokeColor);
        }
    }//end drawOnGrid

    // ── Animation ─────────────────────────────────────────────────────────────

    /**
     * Spins the spiral about its center by deltaAngle degrees (CCW+, CW−).
     * Accumulates into this.rotation.  Call once per frame in draw().
     * @param {number} deltaAngle  degrees per frame (typically speed × deltaT)
     */
    rotate(deltaAngle) { this.rotation += deltaAngle; }

    // ── Setters ───────────────────────────────────────────────────────────────

    setK(k)            { this.k           = k; }
    setRevolutions(r)  { this.revolutions  = Math.max(0.25, r); }
    setClockwise(cw)   { this.clockwise    = cw; }

    /** Sets the static base rotation in CCW degrees. Does not affect accumulated rotation. */
    setRotation(deg)   { this.rotationDeg  = deg; }

    setStrokeColor(sc)       { this.strokeColor   = sc ? SWColor.copy(sc) : undefined; }
    setFillColor(fc)         { this.fillColor     = fc ? SWColor.copy(fc) : undefined; }
    setStrokeWeight(w)       { this.thickness     = w; }
    setShowClosingLine(val)  { this.showClosingLine = val; }

    /**
     * Sets the fill alpha (0–100) and rebuilds the p5 color object.
     * @param {number} alpha  0 = transparent, 100 = opaque
     */
    setFillAlpha(alpha) {
        if (this.fillColor) {
            this.fillColor.a   = Math.max(0, Math.min(100, alpha));
            this.fillColor.col = color(
                this.fillColor.h, this.fillColor.s,
                this.fillColor.b, this.fillColor.a
            );
        }
    }

    /**
     * Sets the stroke alpha (0–100) and rebuilds the p5 color object.
     * @param {number} alpha  0 = transparent, 100 = opaque
     */
    setStrokeAlpha(alpha) {
        if (this.strokeColor) {
            this.strokeColor.a   = Math.max(0, Math.min(100, alpha));
            this.strokeColor.col = color(
                this.strokeColor.h, this.strokeColor.s,
                this.strokeColor.b, this.strokeColor.a
            );
        }
    }

    // ── Reset & Utility ───────────────────────────────────────────────────────

    /**
     * Restores all animated/slider-driven properties to original constructor values.
     * Clears accumulated spin rotation.  Does NOT move the center position.
     */
    reset() {
        this.k           = this.originalK;
        this.revolutions = this.originalRevolutions;
        this.clockwise   = this.originalClockwise;
        this.rotationDeg = this.originalRotationDeg;
        this.rotation    = 0;
        this.thickness   = this.originalThickness;
        this.strokeColor      = this.originalStrokeColor
            ? SWColor.copy(this.originalStrokeColor) : undefined;
        this.fillColor       = this.originalFillColor
            ? SWColor.copy(this.originalFillColor)   : undefined;
        this.showClosingLine = this.originalShowClosingLine;
    }//end reset

    /**
     * Creates a deep copy of the given SWSpiral, preserving all current and original state.
     * @param {SWSpiral} other
     * @returns {SWSpiral}
     */
    static copy(other) {
        const c = new SWSpiral(
            SWPoint.copy(other.center),
            other.originalK,
            other.originalRevolutions,
            other.originalStrokeColor,
            other.originalFillColor,
            other.originalThickness,
            other.originalClockwise,
            other.originalRotationDeg
        );
        c.k               = other.k;
        c.revolutions     = other.revolutions;
        c.clockwise       = other.clockwise;
        c.rotationDeg     = other.rotationDeg;
        c.rotation        = other.rotation;
        c.showClosingLine = other.showClosingLine;
        return c;
    }//end copy

    toString() {
        const dir = this.clockwise ? 'CW' : 'CCW';
        return `SWSpiral(center=${this.center}, k=${this.k.toFixed(2)}, ` +
               `revolutions=${this.revolutions.toFixed(2)}, direction=${dir}, ` +
               `rotationDeg=${this.rotationDeg.toFixed(1)}, rotation=${this.rotation.toFixed(1)})`;
    }

}//end SWSpiral class