⭕ SWRing Reference

/*
File: swRing.js
Date: 2026-03-30
Author: klp
App:  SketchWaveTNT2026-03-19-Stg7
Purpose: SWRing class for SketchWaveJS

SWRing represents a single circular ring (circle outline, no fill) defined by:
  - A center SWPoint (the center of the ring)
  - A radius (in user units when using drawOnGrid; pixels when using draw)
  - A thickness (stroke weight in pixels)
  - A strokeColor (SWColor)

Breathing animations (independent, composable):
  - breatheRadius(sinusoid, t):    oscillates the radius
  - breatheThickness(sinusoid, t): oscillates the stroke weight
  - breatheAlpha(sinusoid, t):     oscillates the stroke alpha

Notes:
  - Assumes p5.js, SWColor, SWPoint, SWGrid, SWSinusoid are loaded.
  - Consistent API with SWSector, SWDisk, SWArc, etc.
  - setStrokeAlpha clamps alpha to [0, 100].
  - A ring is purely a stroke shape; noFill() is always applied.
  - draw() uses center.x/y and radius as raw pixel coordinates.
  - drawOnGrid() maps center through SWGrid and scales radius by grid.xScale.
*/

console.log("[swRing.js] SWRing class loaded.");

class SWRing {

    /**
     * @param {SWPoint} center        - Center of the ring (SWPoint instance)
     * @param {number}  radius        - Radius in user units (drawOnGrid) or pixels (draw)
     * @param {number}  [thickness=3] - Stroke weight in pixels
     * @param {SWColor} [strokeColor] - Stroke color (SWColor instance)
     */
    constructor(center, radius, thickness = 3, strokeColor = undefined) {
        this.center      = center;
        this.radius      = radius;
        this.thickness   = thickness;
        this.strokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;

        // Originals for reset()
        this.originalRadius      = radius;
        this.originalThickness   = thickness;
        this.originalStrokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;

        // Show the center point marker (hidden by default)
        this.shouldShowCenter = false;
    }//end constructor

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

    /**
     * Draws the ring in screen (pixel) coordinates.
     * center.x / center.y are treated as pixel positions.
     * Use drawOnGrid() for user-coordinate rendering.
     */
    draw() {
        this._drawRing(this.center.x, this.center.y, this.radius);
    }//end draw

    /**
     * Draws the ring mapped through the given SWGrid.
     * center.x / center.y are user-space coordinates.
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        const pos = grid.userToScreen(this.center.x, this.center.y);
        const r   = this.radius * grid.xScale;
        this._drawRing(pos.x, pos.y, r);
    }//end drawOnGrid

    /**
     * Internal: applies style and draws the ring circle.
     * @param {number} cx - screen x of center
     * @param {number} cy - screen y of center
     * @param {number} r  - radius in screen pixels
     */
    _drawRing(cx, cy, r) {
        push();
        noFill();
        if (this.strokeColor) {
            stroke(this.strokeColor.h, this.strokeColor.s,
                   this.strokeColor.b, this.strokeColor.a);
        } else {
            stroke(0, 0, 0, 100);
        }
        strokeWeight(this.thickness);
        circle(cx, cy, 2 * r);

        if (this.shouldShowCenter) {
            // Small filled dot at the center using stroke hue at full opacity
            fill(
                this.strokeColor ? this.strokeColor.h : 0,
                this.strokeColor ? this.strokeColor.s : 0,
                this.strokeColor ? this.strokeColor.b : 0,
                100
            );
            noStroke();
            circle(cx, cy, 6);
        }
        pop();
    }//end _drawRing

    // ─── Breathing animations ──────────────────────────────────────────────────

    /**
     * Modulates the radius using an SWSinusoid instance.
     * Clamps to a minimum of 0.01.
     * @param {SWSinusoid} sinusoid
     * @param {number} t - elapsed time in seconds
     */
    breatheRadius(sinusoid, t) {
        this.radius = Math.max(0.01, sinusoid.getValue(t));
    }//end breatheRadius

    /**
     * Modulates the stroke thickness using an SWSinusoid instance.
     * Clamps to a minimum of 0.1 pixels.
     * @param {SWSinusoid} sinusoid
     * @param {number} t - elapsed time in seconds
     */
    breatheThickness(sinusoid, t) {
        this.thickness = Math.max(0.1, sinusoid.getValue(t));
    }//end breatheThickness

    /**
     * Modulates the stroke alpha using an SWSinusoid instance.
     * Sinusoid should output values in [0, 100].
     * @param {SWSinusoid} sinusoid
     * @param {number} t - elapsed time in seconds
     */
    breatheAlpha(sinusoid, t) {
        if (this.strokeColor) {
            this.strokeColor.a = Math.max(0, Math.min(100, sinusoid.getValue(t)));
        }
    }//end breatheAlpha

    // ─── Color helpers ─────────────────────────────────────────────────────────

    /**
     * Sets the stroke alpha value. Clamped to [0, 100].
     * @param {number} alpha
     */
    setStrokeAlpha(alpha) {
        if (this.strokeColor) {
            this.strokeColor.a = Math.max(0, Math.min(100, alpha));
        }
    }//end setStrokeAlpha

    // ─── Reset ─────────────────────────────────────────────────────────────────

    /**
     * Resets all animated values to the originals stored at construction time.
     */
    reset() {
        this.radius    = this.originalRadius;
        this.thickness = this.originalThickness;
        if (this.originalStrokeColor) {
            this.strokeColor = SWColor.copy(this.originalStrokeColor);
        }
    }//end reset

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

    /**
     * @param {number} r - new radius in user units
     */
    setRadius(r) {
        this.radius = r;
    }//end setRadius

    /**
     * @param {number} w - stroke weight in pixels
     */
    setThickness(w) {
        this.thickness = w;
    }//end setThickness

    /**
     * @param {SWColor} swColor
     */
    setStrokeColor(swColor) {
        this.strokeColor = SWColor.copy(swColor);
    }//end setStrokeColor

    /**
     * @param {boolean} [show=true]
     */
    setShowCenter(show = true) {
        this.shouldShowCenter = show;
    }//end setShowCenter

    // ─── Copy ──────────────────────────────────────────────────────────────────

    /**
     * Returns a deep copy of the given SWRing instance.
     * @param {SWRing} other
     * @returns {SWRing}
     */
    static copy(other) {
        const newCenter = new SWPoint(other.center.x, other.center.y);
        const r = new SWRing(
            newCenter,
            other.radius,
            other.thickness,
            other.strokeColor ? SWColor.copy(other.strokeColor) : undefined
        );
        r.shouldShowCenter    = other.shouldShowCenter;
        r.originalRadius      = other.originalRadius;
        r.originalThickness   = other.originalThickness;
        r.originalStrokeColor = other.originalStrokeColor
            ? SWColor.copy(other.originalStrokeColor) : undefined;
        return r;
    }//end copy

    // ─── toString ──────────────────────────────────────────────────────────────

    toString() {
        return `SWRing | center: (${this.center.x.toFixed(2)}, ${this.center.y.toFixed(2)}) | ` +
               `radius: ${this.radius.toFixed(2)} | thickness: ${this.thickness.toFixed(1)} | ` +
               `color: ${this.strokeColor}`;
    }//end toString

}//end SWRing class