◯ SWBumpyCircle Reference

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

SWBumpyCircle draws a polar curve where the radius oscillates sinusoidally
around a base circle, adapted from the legacy TNTBumpyCircle class:

  r(θ) = radius + amplitude · sin(frequency · θ)^power
  x(θ) = r(θ) · cos(θ)
  y(θ) = r(θ) · sin(θ)
  θ ∈ [0, 2π) × numRevolutions

Parameters:
  radius        – base circle radius (grid units)
  amplitude     – peak height of each bump above the base circle
  frequency     – number of full sine cycles per revolution (integer recommended);
                  for integer frequency, one revolution closes the curve perfectly
  power         – exponent applied to sin(frequency · θ):
                  power = 1 → smooth sinusoidal bumps and dents
                  power even → only bumps outward (negative sin^even is positive)
                  power odd > 1 → more pointed bumps with subtler dents
  numRevolutions – full θ revolutions to trace before closing;
                   use 1 for integer frequency; for frequency p/q (lowest terms), use q

Angle convention (same as all SketchWaveJS classes):
  User space: CCW positive, y increases upward.
  p5 screen:  CW  positive, y increases downward.
  SWBumpyCircle handles the y-flip internally in draw() and drawOnGrid().

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

console.log("[swBumpyCircle.js] SWBumpyCircle class loaded.");

class SWBumpyCircle {

    static SAMPLE_COUNT = 1000;  // samples per revolution

    /**
     * @param {SWPoint} center              – Center in user (grid) coordinates
     * @param {number}  [radius=5]          – Base circle radius (grid units, min 0.01)
     * @param {number}  [amplitude=1.5]     – Bump height in grid units (0 = plain circle)
     * @param {number}  [frequency=6]       – Bumps per revolution (integer recommended)
     * @param {number}  [power=1]           – Exponent on sin term (positive integer; 1 = smooth)
     * @param {SWColor} [fillColor]         – Fill color (undefined = no fill)
     * @param {SWColor} [strokeColor]       – Stroke color (undefined = no stroke)
     * @param {number}  [thickness=2]       – Stroke weight in pixels
     * @param {number}  [rotationDeg=0]     – Static base rotation in CCW degrees
     * @param {number}  [numRevolutions=1]  – Full θ revolutions to trace for closure
     */
    constructor(
        center,
        radius         = 5,
        amplitude      = 1.5,
        frequency      = 6,
        power          = 1,
        fillColor      = undefined,
        strokeColor    = undefined,
        thickness      = 2,
        rotationDeg    = 0,
        numRevolutions = 1
    ) {
        this.center         = center;
        this.radius         = Math.max(0.01, radius);
        this.amplitude      = amplitude;
        this.frequency      = Math.max(0, frequency);
        this.power          = Math.max(1, Math.round(Math.abs(power)));
        this.fillColor      = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.strokeColor    = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.thickness      = thickness;
        this.rotationDeg    = rotationDeg;
        this.rotation       = 0;          // accumulated via rotate()
        this.numRevolutions = Math.max(1, Math.round(numRevolutions));

        // Originals for reset()
        this.originalRadius         = this.radius;
        this.originalAmplitude      = this.amplitude;
        this.originalFrequency      = this.frequency;
        this.originalPower          = this.power;
        this.originalFillColor      = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.originalStrokeColor    = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.originalThickness      = thickness;
        this.originalRotationDeg    = rotationDeg;
        this.originalNumRevolutions = this.numRevolutions;

    }//end constructor

    // — Internal helpers ———————————————————————————————————————————————————————————

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

    /**
     * Compute the bumped radius at angle theta (in radians).
     * r(θ) = radius + amplitude · sin(frequency · θ)^power
     * Note: Math.pow preserves sign when power is odd, always positive when even.
     */
    _rFlux(theta) {
        if (this.frequency === 0 || this.amplitude === 0) return this.radius;
        const s = Math.sin(this.frequency * theta);
        return this.radius + this.amplitude * Math.pow(s, this.power);
    }

    /**
     * Build an array of {x, y} points in user (grid) space, rotation applied.
     */
    _buildUserPts() {
        const N      = SWBumpyCircle.SAMPLE_COUNT * this.numRevolutions;
        const cx     = this.center.x;
        const cy     = this.center.y;
        const rotRad = this._totalRotDeg() * Math.PI / 180;
        const cosR   = Math.cos(rotRad);
        const sinR   = Math.sin(rotRad);
        const pts    = [];
        const sweep  = this.numRevolutions * 2 * Math.PI;

        for (let i = 0; i <= N; i++) {
            const theta = (i / N) * sweep;
            const r     = this._rFlux(theta);
            const lx    = r * Math.cos(theta);
            const ly    = r * Math.sin(theta);
            // Apply CCW rotation in user space
            pts.push({
                x: cx + lx * cosR - ly * sinR,
                y: cy + lx * sinR + ly * cosR
            });
        }
        return pts;
    }

    /**
     * Map user points to screen pixels via the SWGrid (handles y-flip).
     */
    _buildScreenPtsGrid(grid) {
        return this._buildUserPts().map(pt => grid.userToScreen(pt.x, pt.y));
    }

    /**
     * Build screen points for direct pixel drawing (no grid): y-flip applied manually.
     * In this mode center.x / center.y are treated as pixel offsets.
     */
    _buildScreenPtsDirect() {
        const N      = SWBumpyCircle.SAMPLE_COUNT * this.numRevolutions;
        const cx     = this.center.x;
        const cy     = this.center.y;
        const rotRad = this._totalRotDeg() * Math.PI / 180;
        const cosR   = Math.cos(rotRad);
        const sinR   = Math.sin(rotRad);
        const pts    = [];
        const sweep  = this.numRevolutions * 2 * Math.PI;

        for (let i = 0; i <= N; i++) {
            const theta = (i / N) * sweep;
            const r     = this._rFlux(theta);
            const lx    = r * Math.cos(theta);
            const ly    = r * Math.sin(theta);
            pts.push({
                x:  cx + lx * cosR - ly * sinR,
                y:  cy - (lx * sinR + ly * cosR)   // y-flip for screen
            });
        }
        return pts;
    }

    /**
     * Draw filled and/or stroked shape from an array of {x,y} screen points.
     */
    _drawShape(screenPts) {
        if (screenPts.length < 2) return;

        // 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 && this.thickness > 0) {
            noFill();
            stroke(this.strokeColor.col);
            strokeWeight(this.thickness);
            beginShape();
            for (const sp of screenPts) vertex(sp.x, sp.y);
            endShape(CLOSE);
        }

        // Reset drawing state
        noStroke();
        noFill();
        strokeWeight(1);
    }

    // — Public drawing API —————————————————————————————————————————————————————————

    /**
     * Draw in raw pixel space (center.x/y are pixel coordinates, y increases downward).
     */
    draw() {
        const screenPts = this._buildScreenPtsDirect();
        this._drawShape(screenPts);
        if (this.center && this.center.shouldShow !== false && this.center.draw) {
            this.center.draw(this.strokeColor);
        }
    }

    /**
     * Draw mapped through the given SWGrid (center.x/y are user/grid coordinates).
     */
    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);
        }
    }

    // — Animation ———————————————————————————————————————————————————————————————————

    /** Accumulate a CCW rotation (degrees). */
    rotate(deltaAngle) { this.rotation += deltaAngle; }

    // — Setters ———————————————————————————————————————————————————————————————————————————————

    setRadius(r)         { this.radius    = Math.max(0.01, r); }
    setAmplitude(a)      { this.amplitude = a; }
    setFrequency(f)      { this.frequency = Math.max(0, f); }
    setPower(p)          { this.power     = Math.max(1, Math.round(Math.abs(p))); }
    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; }
    setNumRevolutions(n) { this.numRevolutions = Math.max(1, Math.round(n)); }

    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 —————————————————————————————————————————————————————————————————————————————————————

    reset() {
        this.radius         = this.originalRadius;
        this.amplitude      = this.originalAmplitude;
        this.frequency      = this.originalFrequency;
        this.power          = this.originalPower;
        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.numRevolutions = this.originalNumRevolutions;
    }

    // — Static copy —————————————————————————————————————————————————————————————————————————————————

    static copy(other) {
        if (!(other instanceof SWBumpyCircle)) {
            throw new Error('Argument to SWBumpyCircle.copy must be an SWBumpyCircle instance.');
        }
        const c = new SWBumpyCircle(
            SWPoint.copy(other.center),
            other.radius,
            other.amplitude,
            other.frequency,
            other.power,
            other.fillColor   ? SWColor.copy(other.fillColor)   : undefined,
            other.strokeColor ? SWColor.copy(other.strokeColor) : undefined,
            other.thickness,
            other.rotationDeg,
            other.numRevolutions
        );
        c.rotation = other.rotation;
        return c;
    }

    // — Utility —————————————————————————————————————————————————————————————————————————————————————

    toString() {
        return `SWBumpyCircle(center:(${this.center.x.toFixed(2)}, ${this.center.y.toFixed(2)}), ` +
               `radius:${this.radius.toFixed(2)}, amplitude:${this.amplitude.toFixed(2)}, ` +
               `frequency:${this.frequency}, power:${this.power}, ` +
               `rotation:${(this.rotationDeg + this.rotation).toFixed(1)}°, ` +
               `numRevolutions:${this.numRevolutions})`;
    }

}//end class SWBumpyCircle