❤️ SWHeart Reference

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

SWHeart represents a heart shape defined by the parametric equations:

  x(t) = a · sin³(t)
  y(t) = b · cos(t) + c · cos(2t) + d · cos(3t) + e · cos(4t)

for t ∈ [0, 2π], scaled by 'scale' and offset by 'center':

  user_x = center.x + scale · x(t)
  user_y = center.y + scale · y(t)

  center (SWPoint) — origin of the heart in user (grid) coordinates
  a (number)       — width coefficient; sin³(t) gives the x-curve its
                     characteristic smooth lobe shape
  b, c, d, e       — cosine coefficients that together shape the y-curve;
                     their interplay produces the two top lobes and the sharp
                     bottom tip of the heart
  scale (number)   — maps parametric coordinates to grid units

Suggested 'good heart' defaults:
  a=16, b=13, c=−5, d=−2, e=−1, scale=0.5

At these defaults the heart spans approximately ±8 grid units wide and
fits comfortably within a standard [−10, 10] × [−10, 10] SWGrid.

Orientation (at default values):
  Two lobes sit at the top (positive y in user space), the sharp tip at
  the bottom.  The parametric origin (0, 0) lies at roughly mid-height.

Beat animation:
  Oscillate 'scale' sinusoidally to simulate a heartbeat:
    beatScale = baseScale + depth · sin(2π · speed · t)
  At speed = 1.2 Hz this is approximately 72 BPM — a normal resting heart
  rate.  Implemented in the sketch layer via setScale().

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.
  SWHeart handles the y-flip internally; always pass CCW degrees.

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

console.log("[swHeart.js] SWHeart class loaded.");

class SWHeart {

    static SAMPLE_COUNT = 200;  // sample points around the full t ∈ [0, 2π] curve

    /**
     * @param {SWPoint} center          - Center of the heart in user (grid) coordinates
     * @param {number}  [a=16]          - Width coefficient (sin³ term)
     * @param {number}  [b=13]          - Primary cosine coefficient
     * @param {number}  [c=-5]          - Second cosine coefficient
     * @param {number}  [d=-2]          - Third cosine coefficient
     * @param {number}  [e=-1]          - Fourth cosine coefficient
     * @param {SWColor} [fillColor]     - Fill color (undefined = no fill)
     * @param {SWColor} [strokeColor]   - Stroke / border color (undefined = no stroke)
     * @param {number}  [thickness=2]   - Stroke weight in pixels
     * @param {number}  [scale=0.5]     - Maps parametric coords to grid units
     * @param {number}  [rotationDeg=0] - Static base rotation in CCW degrees
     */
    constructor(center, a = 16, b = 13, c = -5, d = -2, e = -1,
                fillColor = undefined, strokeColor = undefined,
                thickness = 2, scale = 0.5, rotationDeg = 0) {

        this.center      = center;
        this.a           = a;
        this.b           = b;
        this.c           = c;
        this.d           = d;
        this.e           = e;
        this.fillColor   = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.strokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.thickness   = thickness;
        this.scale       = scale;
        this.rotationDeg = rotationDeg;
        this.rotation    = 0;   // accumulated via rotate(); cleared by reset()

        // ── Originals for reset() ──────────────────────────────────────────────
        this.originalA           = a;
        this.originalB           = b;
        this.originalC           = c;
        this.originalD           = d;
        this.originalE           = e;
        this.originalFillColor   = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.originalStrokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.originalThickness   = thickness;
        this.originalScale       = scale;
        this.originalRotationDeg = rotationDeg;

    }//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 for t ∈ [0, 2π].
     * @returns {{ x: number, y: number }[]}
     */
    _buildUserPts() {
        const cx  = this.center.x;
        const cy  = this.center.y;
        const n   = SWHeart.SAMPLE_COUNT;
        const pts = [];

        for (let i = 0; i <= n; i++) {
            const t    = (i / n) * 2 * Math.PI;
            const sinT = Math.sin(t);
            const lx   = this.scale * this.a * sinT * sinT * sinT;
            const ly   = this.scale * (
                this.b * Math.cos(t) +
                this.c * Math.cos(2 * t) +
                this.d * Math.cos(3 * t) +
                this.e * Math.cos(4 * t)
            );
            const rot = this._rotateLocal(lx, ly);
            pts.push({ x: cx + rot.x, y: cy + rot.y });
        }
        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 n   = SWHeart.SAMPLE_COUNT;
        const pts = [];

        for (let i = 0; i <= n; i++) {
            const t    = (i / n) * 2 * Math.PI;
            const sinT = Math.sin(t);
            const lx   = this.scale * this.a * sinT * sinT * sinT;
            const ly   = this.scale * (
                this.b * Math.cos(t) +
                this.c * Math.cos(2 * t) +
                this.d * Math.cos(3 * t) +
                this.e * Math.cos(4 * t)
            );
            const rot = this._rotateLocal(lx, ly);
            pts.push({ x: cx + rot.x, y: cy - rot.y });   // y-flip for screen
        }
        return pts;
    }

    /**
     * Executes fill + stroke passes from pre-computed screen points.
     * The heart is always a closed shape.
     */
    _drawShape(screenPts) {
        // ── Fill pass ────────────────────────────────────────────────────────────
        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 ──────────────────────────────────────────────────────────
        if (this.strokeColor && this.strokeColor.col) {
            noFill();
            stroke(this.strokeColor.col);
            strokeWeight(this.thickness);
            beginShape();
            for (const sp of screenPts) vertex(sp.x, sp.y);
            endShape(CLOSE);
        }

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

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

    /**
     * Draws the heart 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 heart 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 heart 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 ───────────────────────────────────────────────────────────────

    setA(a)            { this.a          = a; }
    setB(b)            { this.b          = b; }
    setC(c)            { this.c          = c; }
    setD(d)            { this.d          = d; }
    setE(e)            { this.e          = e; }
    setScale(s)        { this.scale      = Math.max(0.01, s); }

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

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

    /**
     * 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.a           = this.originalA;
        this.b           = this.originalB;
        this.c           = this.originalC;
        this.d           = this.originalD;
        this.e           = this.originalE;
        this.scale       = this.originalScale;
        this.rotationDeg = this.originalRotationDeg;
        this.rotation    = 0;
        this.thickness   = this.originalThickness;
        this.fillColor   = this.originalFillColor
            ? SWColor.copy(this.originalFillColor)   : undefined;
        this.strokeColor = this.originalStrokeColor
            ? SWColor.copy(this.originalStrokeColor) : undefined;
    }//end reset

    /**
     * Creates a deep copy of the given SWHeart, preserving all current and original state.
     * @param {SWHeart} other
     * @returns {SWHeart}
     */
    static copy(other) {
        const c = new SWHeart(
            SWPoint.copy(other.center),
            other.originalA, other.originalB, other.originalC,
            other.originalD, other.originalE,
            other.originalFillColor, other.originalStrokeColor,
            other.originalThickness, other.originalScale,
            other.originalRotationDeg
        );
        c.a           = other.a;
        c.b           = other.b;
        c.c           = other.c;
        c.d           = other.d;
        c.e           = other.e;
        c.scale       = other.scale;
        c.rotationDeg = other.rotationDeg;
        c.rotation    = other.rotation;
        return c;
    }//end copy

    toString() {
        return `SWHeart(center=${this.center}, a=${this.a}, b=${this.b}, c=${this.c}, ` +
               `d=${this.d}, e=${this.e}, scale=${this.scale.toFixed(3)}, ` +
               `rotationDeg=${this.rotationDeg.toFixed(1)}, rotation=${this.rotation.toFixed(1)})`;
    }

}//end SWHeart class