☘ SWShamrock Reference

/*
File: swShamrock.js
Date: 2026-05-10
Author: klp
App:  SketchWaveTNT2026-05-01-Stg9
Purpose: SWShamrock class for SketchWaveJS

SWShamrock draws a three-lobed shamrock shape using a polar parametric equation
derived from the original TNTShamrock legacy code:

  r(θ) = SCALE · radius · (sin(3θ/2) + sin(9θ/2)/5)²
  x(θ) = r(θ) · cos(θ)
  y(θ) = r(θ) · sin(θ)

for θ ∈ [0, 2π), where SCALE = 1.31 (empirically determined so that the
nominal `radius` parameter approximates the visual petal-tip distance from center).

The curve passes through the origin at θ = 0, 2π/3, 4π/3, and 2π, tracing
three rounded lobes — the classic shamrock / three-leaf clover shape ☘.

The polar formula can be understood as:
  The dominant term sin(3θ/2) has period 4π/3, producing three zero crossings
  in [0, 2π] that separate the three lobes.
  The secondary term sin(9θ/2)/5 (period 4π/9) adds subtle asymmetric ruffling
  to each lobe, creating the characteristic shamrock silhouette rather than a
  smooth epicycloid petal.

Rotation:
  rotationDeg -- static base rotation (CCW degrees); default = 30 orients
                 one lobe pointing upward.  Persists across reset().
  rotation    -- accumulated rotation (degrees); incremented by rotate().
                 Starts at 0; reset() returns it to 0.
  Effective rotation = rotationDeg + rotation.

Stem:
  When shouldShowStem is true, a SWSpire arch stem is drawn below the figure.
  The SWSpire uses halfShape=true so only the top arch (t∈[0,π]) is drawn:
  the cusp apex is anchored at the shamrock center; the arch body extends
  away in the stem direction. The stem color and thickness match the body.
  Parameters:
    stemLength  – height of the arch from center to cusp tip (grid units)
    stemWidth   – half-width of the arch at the flat base (grid units)
    stemPower   – shape exponent; odd integers give cusped tips (5 = default)
    stemRotationOffset – additional CCW rotation of the stem relative to the
                         shamrock body (degrees)

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

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

console.log("[swShamrock.js] SWShamrock class loaded.");

class SWShamrock {

    static SAMPLE_COUNT = 600;
    static SCALE_FACTOR = 1.31;

    constructor(center, radius = 5,
                fillColor = undefined, strokeColor = undefined,
                thickness = 2, rotationDeg = 30, shouldShowStem = true,
                stemLength = 6.0, stemWidth = 1.5, stemPower = 5,
                stemRotationOffset = 150) {

        this.center         = center;
        this.radius         = Math.max(0.01, radius);
        this.fillColor      = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.strokeColor    = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.thickness      = thickness;
        this.rotationDeg    = rotationDeg;
        this.rotation       = 0;
        this.shouldShowStem = shouldShowStem;

        this.stemLength         = Math.max(0.1,  stemLength);
        this.stemWidth          = Math.max(0.05, stemWidth);
        this.stemPower          = Math.max(1,    stemPower);
        this.stemRotationOffset = stemRotationOffset;

        this.originalRadius         = this.radius;
        this.originalFillColor      = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.originalStrokeColor    = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.originalThickness      = thickness;
        this.originalRotationDeg    = rotationDeg;
        this.originalShouldShowStem = shouldShowStem;
        this.originalStemLength         = this.stemLength;
        this.originalStemWidth          = this.stemWidth;
        this.originalStemPower          = this.stemPower;
        this.originalStemRotationOffset = this.stemRotationOffset;

        const stemCenter = new SWPoint(center.x, center.y);
        stemCenter.shouldShow = false;
        this._stem = new SWSpire(
            stemCenter,
            this.stemWidth, this.stemLength, this.stemPower,
            fillColor   ? SWColor.copy(fillColor)   : undefined,
            strokeColor ? SWColor.copy(strokeColor) : undefined,
            thickness,
            rotationDeg + 180 + stemRotationOffset,
            true
        );
    }

    _totalRotDeg() { return this.rotationDeg + this.rotation; }

    _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 };
    }

    _buildUserPts() {
        const cx = this.center.x;
        const cy = this.center.y;
        const N  = SWShamrock.SAMPLE_COUNT;
        const pR = SWShamrock.SCALE_FACTOR * this.radius;
        const pts = [];
        for (let i = 0; i < N; i++) {
            const t  = (i / N) * (2 * Math.PI);
            const s1 = Math.sin(3 * t / 2);
            const s2 = Math.sin(9 * t / 2) / 5;
            const r  = pR * (s1 + s2) * (s1 + s2);
            const lx = r * Math.cos(t);
            const ly = r * Math.sin(t);
            const rot = this._rotateLocal(lx, ly);
            pts.push({ x: cx + rot.x, y: cy + rot.y });
        }
        return pts;
    }

    _buildScreenPtsGrid(grid) {
        return this._buildUserPts().map(pt => grid.userToScreen(pt.x, pt.y));
    }

    _buildScreenPtsDirect() {
        const cx = this.center.x;
        const cy = this.center.y;
        const N  = SWShamrock.SAMPLE_COUNT;
        const pR = SWShamrock.SCALE_FACTOR * this.radius;
        const pts = [];
        for (let i = 0; i < N; i++) {
            const t  = (i / N) * (2 * Math.PI);
            const s1 = Math.sin(3 * t / 2);
            const s2 = Math.sin(9 * t / 2) / 5;
            const r  = pR * (s1 + s2) * (s1 + s2);
            const lx = r * Math.cos(t);
            const ly = r * Math.sin(t);
            const rot = this._rotateLocal(lx, ly);
            pts.push({ x: cx + rot.x, y: cy - rot.y });
        }
        return pts;
    }

    _drawShape(screenPts) {
        if (screenPts.length < 2) return;
        if (this.fillColor && this.fillColor.col) {
            fill(this.fillColor.col);
            noStroke();
            beginShape();
            for (const sp of screenPts) vertex(sp.x, sp.y);
            endShape(CLOSE);
        }
        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);
    }

    _syncStem() {
        const totalRot     = this._totalRotDeg();
        const effectiveRot = totalRot + 180 + this.stemRotationOffset;
        const effectiveRad = effectiveRot * Math.PI / 180;
        this._stem.center.x    = this.center.x + this.stemLength * Math.sin(effectiveRad);
        this._stem.center.y    = this.center.y - this.stemLength * Math.cos(effectiveRad);
        this._stem.radiusX     = this.stemWidth;
        this._stem.radiusY     = this.stemLength;
        this._stem.power       = this.stemPower;
        this._stem.rotationDeg = effectiveRot;
        this._stem.rotation    = 0;
        this._stem.halfShape   = true;
        this._stem.fillColor   = this.fillColor;
        this._stem.strokeColor = this.strokeColor;
        this._stem.thickness   = this.thickness;
    }

    draw() {
        if (this.shouldShowStem) { this._syncStem(); this._stem.draw(); }
        const screenPts = this._buildScreenPtsDirect();
        this._drawShape(screenPts);
        if (this.center && this.center.shouldShow !== false && this.center.draw) {
            this.center.draw(this.strokeColor);
        }
    }

    drawOnGrid(grid) {
        if (this.shouldShowStem) { this._syncStem(); this._stem.drawOnGrid(grid); }
        const screenPts = this._buildScreenPtsGrid(grid);
        this._drawShape(screenPts);
        if (this.center && this.center.shouldShow !== false && this.center.drawOnGrid) {
            this.center.drawOnGrid(grid, this.strokeColor);
        }
    }

    rotate(deltaAngle) { this.rotation += deltaAngle; }

    setRadius(r)               { this.radius               = Math.max(0.01, r); }
    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; }
    setShouldShowStem(v)       { this.shouldShowStem        = !!v; }
    setStemLength(l)           { this.stemLength            = Math.max(0.1,  l); }
    setStemWidth(w)            { this.stemWidth             = Math.max(0.05, w); }
    setStemPower(p)            { this.stemPower             = Math.max(1,    p); }
    setStemRotationOffset(deg) { this.stemRotationOffset    = deg; }

    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);
        }
    }

    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() {
        this.radius         = this.originalRadius;
        this.fillColor      = this.originalFillColor   ? SWColor.copy(this.originalFillColor)   : undefined;
        this.strokeColor    = this.originalStrokeColor ? SWColor.copy(this.originalStrokeColor) : undefined;
        this.thickness      = this.originalThickness;
        this.rotationDeg    = this.originalRotationDeg;
        this.rotation       = 0;
        this.shouldShowStem         = this.originalShouldShowStem;
        this.stemLength             = this.originalStemLength;
        this.stemWidth              = this.originalStemWidth;
        this.stemPower              = this.originalStemPower;
        this.stemRotationOffset     = this.originalStemRotationOffset;
    }

    static copy(other) {
        if (!(other instanceof SWShamrock)) {
            throw new Error('Argument to SWShamrock.copy must be an SWShamrock instance');
        }
        const c = new SWShamrock(
            SWPoint.copy(other.center),
            other.radius,
            other.fillColor   ? SWColor.copy(other.fillColor)   : undefined,
            other.strokeColor ? SWColor.copy(other.strokeColor) : undefined,
            other.thickness,
            other.rotationDeg,
            other.shouldShowStem,
            other.stemLength,
            other.stemWidth,
            other.stemPower,
            other.stemRotationOffset
        );
        c.rotation = other.rotation;
        return c;
    }

    toString() {
        return `SWShamrock(center:(${this.center.x.toFixed(2)}, ${this.center.y.toFixed(2)}), ` +
               `radius:${this.radius.toFixed(2)}, rotation:${(this.rotationDeg + this.rotation).toFixed(1)}°, ` +
               `stem:${this.shouldShowStem}, stemLength:${this.stemLength.toFixed(2)}, ` +
               `stemWidth:${this.stemWidth.toFixed(2)}, stemPower:${this.stemPower}, ` +
               `stemOffset:${this.stemRotationOffset.toFixed(1)}°)`;
    }

}//end class SWShamrock