⌒ SWArc Reference

/*
File: swArc.js
Date: 2026-03-28
Author: klp
App:  SketchWaveTNT2026-03-19-Stg7
Purpose: SWArc class for SketchWaveJS

SWArc represents a circular arc — just the "crust" of the pizza, without the
filling.  It is the stroke-only counterpart to SWSector.  Defined by:
  - A center SWPoint (the center of the underlying circle)
  - A radius (in user units)
  - A theta (angular size in degrees)
  - A startAngle (degrees CCW from the +x axis, where the arc begins)
  - A rotation offset (degrees, accumulated via rotate())
  - A thickness (stroke weight in pixels — the primary visual variable)
  - A strokeColor (SWColor instance)
  - A capStyle (end-cap type: 'round' | 'butt' | 'square')

Key difference from SWSector:
  SWArc has NO FILL — it is drawn in OPEN arc mode (pure stroke).
  The arc's thickness becomes the primary visual/animation variable.

New animation vs SWSector:
  breatheThickness(sinusoid, t): oscillates the stroke weight.

All SWSector animations also apply:
  rotate(delta):                spin the arc about its center.
  breatheRadius(sinusoid, t):   oscillate the radius.
  breatheTheta(sinusoid, t):    oscillate the angular size.

Angle convention (identical to SWSector):
  User space (math):   angles are CCW from +x axis, y increases upward.
  p5 / screen space:   angles are CW  from +x axis, y increases downward.
  Conversion:          p5_angle = -user_angle  (negate because y is flipped).

Drawing an arc of size theta starting at totalAngle = startAngle + rotation:
  p5 arc start = -radians(totalAngle + theta)
  p5 arc stop  = -radians(totalAngle)
  arc(cx, cy, 2r, 2r, p5Start, p5Stop, OPEN)   — OPEN mode = no lines to center.

capStyle values (raw HTML canvas lineCap strings accepted by p5 strokeCap()):
  'round'  = ROUND   — smooth semicircular ends
  'butt'   = SQUARE  — flat ends, flush with arc endpoints
  'square' = PROJECT — flat ends that extend past endpoint by half thickness
*/

console.log("[swArc.js] SWArc class loaded.");

class SWArc {

    /**
     * @param {SWPoint} center         - Center of the underlying circle (SWPoint)
     * @param {number}  radius         - Radius in user units (> 0)
     * @param {number}  theta          - Angular size in degrees (clamped 0–360)
     * @param {number}  [startAngle=0]    - Arc start angle (degrees CCW from +x axis)
     * @param {number}  [thickness=6]     - Stroke weight in pixels (the primary visual variable)
     * @param {SWColor} [strokeColor]     - Arc color (SWColor instance)
     * @param {string}  [capStyle='round'] - End-cap: 'round', 'butt', or 'square'
     */
    constructor(center, radius, theta, startAngle = 0, thickness = 6,
                strokeColor = undefined, capStyle = 'round') {

        this.center     = center;
        this.radius     = radius;
        this.theta      = theta;
        this.startAngle = startAngle;
        this.rotation   = 0;               // accumulated rotation (degrees, CCW)
        this.thickness  = thickness;

        // Always copy color to avoid mutating shared objects
        this.strokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.capStyle    = capStyle;       // 'round' | 'butt' | 'square'

        // Originals for reset()
        this.originalRadius      = radius;
        this.originalTheta       = theta;
        this.originalStartAngle  = startAngle;
        this.originalRotation    = 0;
        this.originalThickness   = thickness;
        this.originalStrokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;

        this.shouldShowCenter = true;      // draw center point marker

        this._updateGeometry();
    }//end constructor

    // ─── Geometry ──────────────────────────────────────────────────────────────

    _updateGeometry() {
        this.theta     = Math.max(0, Math.min(360, this.theta));
        this.arcLength = (this.theta / 360) * 2 * Math.PI * this.radius;
    }//end _updateGeometry

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

    draw() {
        this._drawArc(this.center.x, this.center.y, this.radius);
        if (this.shouldShowCenter && this.center && this.center.draw) {
            this.center.draw(this.strokeColor);
        }
    }//end draw

    drawOnGrid(grid) {
        const { x: cx, y: cy } = grid.userToScreen(this.center.x, this.center.y);
        const rScreen = (grid.xScale * this.radius + grid.yScale * this.radius) / 2;
        this._drawArc(cx, cy, rScreen);
        if (this.shouldShowCenter && this.center && this.center.drawOnGrid) {
            this.center.drawOnGrid(grid, this.strokeColor);
        }
    }//end drawOnGrid

    _drawArc(cx, cy, r) {
        const totalAngle = this.startAngle + this.rotation;
        const p5Start = -radians(totalAngle + this.theta);
        const p5Stop  = -radians(totalAngle);

        noFill();

        if (this.strokeColor && this.strokeColor.col) {
            stroke(this.strokeColor.col);
        } else {
            noStroke();
        }

        strokeWeight(this.thickness);
        strokeCap(this.capStyle);
        arc(cx, cy, 2 * r, 2 * r, p5Start, p5Stop, OPEN);

        noStroke();
        strokeWeight(1);
        strokeCap(ROUND);
    }//end _drawArc

    // ─── Rotation animation ────────────────────────────────────────────────────

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

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

    breatheRadius(sinusoid, t) {
        this.radius = Math.max(0.01, sinusoid.getValue(t));
        this._updateGeometry();
    }//end breatheRadius

    breatheTheta(sinusoid, t) {
        this.theta = sinusoid.getValue(t);
        this._updateGeometry();
    }//end breatheTheta

    breatheThickness(sinusoid, t) {
        this.thickness = Math.max(1, sinusoid.getValue(t));
    }//end breatheThickness

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

    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
            );
        }
    }//end setStrokeAlpha

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

    reset() {
        this.radius     = this.originalRadius;
        this.theta      = this.originalTheta;
        this.startAngle = this.originalStartAngle;
        this.rotation   = this.originalRotation;
        this.thickness  = this.originalThickness;
        if (this.originalStrokeColor) {
            this.strokeColor = SWColor.copy(this.originalStrokeColor);
        }
        this._updateGeometry();
    }//end reset

    resetStrokeColor() {
        if (this.originalStrokeColor) {
            this.strokeColor = SWColor.copy(this.originalStrokeColor);
        }
    }//end resetStrokeColor

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

    setStrokeColor(swColor) {
        this.strokeColor = swColor ? SWColor.copy(swColor) : undefined;
    }//end setStrokeColor

    setStrokeWeight(w) {
        this.thickness = w;
    }//end setStrokeWeight

    setRadius(r) {
        this.radius = r;
        this._updateGeometry();
    }//end setRadius

    setTheta(degrees) {
        this.theta = degrees;
        this._updateGeometry();
    }//end setTheta

    setStartAngle(degrees) {
        this.startAngle = degrees;
    }//end setStartAngle

    setCapStyle(cap) {
        this.capStyle = cap;
    }//end setCapStyle

    setShowCenter(show = true) {
        this.shouldShowCenter = show;
    }//end setShowCenter

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

    static copy(other) {
        if (!(other instanceof SWArc)) {
            throw new Error('Argument to SWArc.copy must be an SWArc instance');
        }
        const a = new SWArc(
            SWPoint.copy(other.center),
            other.originalRadius,
            other.originalTheta,
            other.originalStartAngle,
            other.originalThickness,
            other.strokeColor,
            other.capStyle
        );
        a.radius           = other.radius;
        a.theta            = other.theta;
        a.startAngle       = other.startAngle;
        a.rotation         = other.rotation;
        a.thickness        = other.thickness;
        a.shouldShowCenter = other.shouldShowCenter;
        a._updateGeometry();
        return a;
    }//end copy

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

    toString() {
        return `SWArc(center: ${this.center.toString()}, ` +
               `radius: ${this.radius.toFixed(2)}, theta: ${this.theta.toFixed(1)}°, ` +
               `startAngle: ${this.startAngle}°, rotation: ${this.rotation.toFixed(1)}°, ` +
               `thickness: ${this.thickness.toFixed(1)}, cap: '${this.capStyle}', ` +
               `arcLength: ${this.arcLength.toFixed(2)})`;
    }//end toString

}//end SWArc class