🌙 SWCircleSegment Reference

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

SWCircleSegment represents a circular segment -- the region between a chord
and its subtended arc -- defined by:
  - A center SWPoint (center of the generating circle)
  - A radius (in user units)
  - A theta (angular size / central angle in degrees, clamped 0-360)
  - A startAngle (degrees CCW from the +x axis, where the arc begins)
  - A rotation offset (degrees, accumulated via rotate())

Unlike SWSector (pizza slice), a segment does NOT connect to the center.
The shape is closed by a chord drawn directly from one arc endpoint to the
other. In p5.js this is the CHORD arc mode.

Default orientation: arc begins along the +x axis and sweeps CCW through
theta degrees. Set startAngle to establish a different static starting
position before rotation begins.

Animations (all independent, all composable):
  - rotate(delta): spins the segment about the circle's center.
  - breatheRadius(sinusoid, t): oscillates the radius with an SWSinusoid.
  - breatheTheta(sinusoid, t):  oscillates the angular size with an SWSinusoid.

Color cycling: mutate fillColor.h and rebuild fillColor.col before drawing,
  just like SWSector / SWDisk.

Angle convention:
  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 a segment whose arc start is at totalAngle = startAngle + rotation,
spanning theta degrees CCW:
  p5 arc start = -radians(totalAngle + theta)
  p5 arc stop  = -radians(totalAngle)
  arc(cx, cy, 2r, 2r, p5Start, p5Stop, CHORD)  -- p5 arc is clockwise.

Geometric extras (recomputed by _updateGeometry):
  arcLength   = (theta/360) * 2*PI * r
  chordLength = 2 * r * sin(theta_rad / 2)
  sagitta     = r * (1 - cos(theta_rad / 2))   (height of the segment)
  area        = (theta_rad/2 - sin(theta_rad)/2) * r^2  (segment area formula)

Notes:
  - Assumes p5.js, SWColor, SWPoint, SWGrid, SWSinusoid are loaded.
  - Consistent API with SWSector, SWDisk, SWLine, SWTriangle, etc.
  - setFillAlpha / setStrokeAlpha clamp alpha to [0, 100].
*/

console.log("[swCircleSegment.js] SWCircleSegment class loaded.");

class SWCircleSegment {

    constructor(center, radius, theta, startAngle = 0, thickness = 2,
                fillColor = undefined, strokeColor = undefined) {

        this.center     = center;
        this.radius     = radius;
        this.theta      = theta;
        this.startAngle = startAngle;
        this.rotation   = 0;
        this.thickness  = thickness;

        this.fillColor   = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.strokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;

        this.originalRadius     = radius;
        this.originalTheta      = theta;
        this.originalStartAngle = startAngle;
        this.originalRotation   = 0;
        this.originalFillColor  = fillColor ? SWColor.copy(fillColor) : undefined;

        this.shouldShowCenter = true;

        this._updateGeometry();
    }

    _updateGeometry() {
        this.theta          = Math.max(0, Math.min(360, this.theta));
        const thetaRad      = this.theta * Math.PI / 180;
        this.arcLength      = (this.theta / 360) * 2 * Math.PI * this.radius;
        this.chordLength    = 2 * this.radius * Math.sin(thetaRad / 2);
        this.sagitta        = this.radius * (1 - Math.cos(thetaRad / 2));
        this.area           = 0.5 * this.radius * this.radius * (thetaRad - Math.sin(thetaRad));
    }

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

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

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

        if (this.fillColor && this.fillColor.col) {
            fill(this.fillColor.col);
        } else {
            noFill();
        }
        if (this.strokeColor && this.strokeColor.col) {
            stroke(this.strokeColor.col);
        } else {
            noStroke();
        }
        strokeWeight(this.thickness);
        arc(cx, cy, 2 * r, 2 * r, p5Start, p5Stop, CHORD);
        noStroke();
        noFill();
        strokeWeight(1);
    }

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

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

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

    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.theta      = this.originalTheta;
        this.startAngle = this.originalStartAngle;
        this.rotation   = this.originalRotation;
        if (this.originalFillColor) {
            this.fillColor = SWColor.copy(this.originalFillColor);
        }
        this._updateGeometry();
    }

    resetFillColor() {
        if (this.originalFillColor) {
            this.fillColor = SWColor.copy(this.originalFillColor);
        }
    }

    setFillColor(swColor)    { this.fillColor   = swColor ? SWColor.copy(swColor) : undefined; }
    setStrokeColor(swColor)  { this.strokeColor = swColor ? SWColor.copy(swColor) : undefined; }
    setStrokeWeight(w)       { this.thickness   = w; }
    setRadius(r)             { this.radius      = r; this._updateGeometry(); }
    setTheta(degrees)        { this.theta       = degrees; this._updateGeometry(); }
    setStartAngle(degrees)   { this.startAngle  = degrees; }
    setShowCenter(show = true) { this.shouldShowCenter = show; }

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

    toString() {
        return `SWCircleSegment(center: ${this.center.toString()}, ` +
               `radius: ${this.radius.toFixed(2)}, theta: ${this.theta.toFixed(1)}°, ` +
               `startAngle: ${this.startAngle}°, rotation: ${this.rotation.toFixed(1)}°, ` +
               `chordLength: ${this.chordLength.toFixed(2)}, sagitta: ${this.sagitta.toFixed(2)}, ` +
               `area: ${this.area.toFixed(2)}, arcLength: ${this.arcLength.toFixed(2)})`;
    }

}//end SWCircleSegment class