🌉 SWArch Reference

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

SWArch represents a parabolic arch shape defined by the quadratic function
y = a·x² in a local coordinate system centered at the vertex:

  vertex (SWPoint) — the extremum of the arch:
                     a < 0  → vertex is the HIGHEST point (∩ rainbow/arch shape)
                     a > 0  → vertex is the LOWEST  point (∪ bowl shape)

  a (number)       — quadratic coefficient controlling curvature and orientation
  xLeft (number)   — horizontal distance from vertex to the left  endpoint (> 0)
  xRight (number)  — horizontal distance from vertex to the right endpoint (> 0)

In local space (vertex at origin):
  left  endpoint: (−xLeft,  a · xLeft²)
  right endpoint: ( xRight, a · xRight²)
  curve:           y = a · x²   for x ∈ [−xLeft, xRight]

Rotation:
  rotationDeg — static base rotation (CCW degrees from no-rotation), set by
                setRotation().  Persists across frames; survives reset().
  rotation    — accumulated rotation (degrees), incremented by rotate().
                Starts at 0; reset() returns it to 0.
  Effective rotation used for drawing = rotationDeg + rotation.
  All rotation is about the VERTEX.

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

The drawn shape is a closed polygon: the parabolic arc sampled at SAMPLE_COUNT
points from the left to right endpoint, closed by a straight base line.
Fill and stroke are applied to the full outline.

Animations (call once per frame in the p5 draw loop):
  rotate(delta)         — spins the arch about its vertex
  breatheA(sinusoid, t) — oscillates ‘a’ to open/close the arch curvature

Point visibility:
  shouldShowVertex    — shows/hides the SWPoint dot at the vertex
  shouldShowEndpoints — shows/hides SWPoint dots at the left and right endpoints

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

console.log("[swArch.js] SWArch class loaded.");

class SWArch {

    static SAMPLE_COUNT = 60;   // arc smoothness (points sampled along parabola)

    /**
     * @param {SWPoint} vertex        - Arch extremum in user (grid) coordinates
     * @param {number}  a             - Quadratic coefficient (a < 0 → arch ∩;  a > 0 → bowl ∪)
     * @param {number}  [xLeft=3]     - Left-side horizontal extent from vertex (positive)
     * @param {number}  [xRight=3]    - Right-side horizontal extent from vertex (positive)
     * @param {SWColor} [fillColor]   - Fill color (undefined = no fill)
     * @param {SWColor} [strokeColor] - Border color (undefined = no stroke)
     * @param {number}  [thickness=2] - Border stroke weight
     * @param {number}  [rotationDeg=0] - Static base rotation in CCW degrees
     */
    constructor(vertex, a, xLeft = 3, xRight = 3,
                fillColor = undefined, strokeColor = undefined,
                thickness = 2, rotationDeg = 0) {

        this.vertex      = vertex;
        this.a           = a;
        this.xLeft       = Math.abs(xLeft);
        this.xRight      = Math.abs(xRight);
        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(); cleared by reset()

        this.shouldShowVertex    = true;
        this.shouldShowEndpoints = true;
        // When true (default), endShape(CLOSE) draws a straight line connecting
        // the two endpoints to close the polygon (base line visible).
        // Set to false to draw only the parabolic arc with no closing base line.
        this.shouldCloseShape    = true;

        // —— Originals for reset() —————————————————————————
        this.originalA           = a;
        this.originalXLeft       = Math.abs(xLeft);
        this.originalXRight      = Math.abs(xRight);
        this.originalFillColor   = fillColor   ? SWColor.copy(fillColor)   : undefined;
        this.originalStrokeColor = strokeColor ? SWColor.copy(strokeColor) : undefined;
        this.originalThickness   = thickness;
        this.originalRotationDeg = rotationDeg;

    }//end constructor

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

    /** @returns {number} Total effective rotation in degrees. */
    _totalRotDeg() { return this.rotationDeg + this.rotation; }

    /**
     * Rotates a local math-space point (lx, ly) by totalRotation degrees (CCW+).
     * @returns {{ x: number, y: number }} rotated point in math-space
     */
    _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,
        };
    }

    /**
     * Builds an array of screen-space { x, y } points for drawOnGrid().
     * grid.userToScreen() handles the math-space ↔ screen y-flip.
     */
    _buildScreenPtsGrid(grid) {
        const pts  = [];
        const n    = SWArch.SAMPLE_COUNT;
        const span = this.xLeft + this.xRight;
        const vx   = this.vertex.x;
        const vy   = this.vertex.y;
        for (let i = 0; i <= n; i++) {
            const t  = i / n;
            const lx = -this.xLeft + t * span;
            const ly = this.a * lx * lx;
            const r  = this._rotateLocal(lx, ly);
            const sc = grid.userToScreen(vx + r.x, vy + r.y);
            pts.push(sc);
        }
        return pts;
    }

    /**
     * Builds an array of screen-space { x, y } points for draw() (no grid).
     * r.y (math-space up) is negated to produce the correct screen-space displacement.
     */
    _buildScreenPtsDirect() {
        const pts  = [];
        const n    = SWArch.SAMPLE_COUNT;
        const span = this.xLeft + this.xRight;
        const vx   = this.vertex.x;
        const vy   = this.vertex.y;
        for (let i = 0; i <= n; i++) {
            const t  = i / n;
            const lx = -this.xLeft + t * span;
            const ly = this.a * lx * lx;
            const r  = this._rotateLocal(lx, ly);
            pts.push({ x: vx + r.x, y: vy - r.y });   // y-flip for screen space
        }
        return pts;
    }

    /**
     * Executes beginShape / vertex / endShape from pre-computed screen points.
     * If shouldCloseShape is true (default), endShape(CLOSE) adds a straight
     * line back to the first point, forming a closed polygon with a visible base.
     * If shouldCloseShape is false, endShape() leaves the shape open so only
     * the parabolic arc is drawn — no connecting line between the endpoints.
     */
    _drawShape(screenPts) {
        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);
        beginShape();
        for (const sp of screenPts) {
            vertex(sp.x, sp.y);
        }
        // CLOSE connects the last sampled point back to the first with a straight
        // line (the base/chord).  Omitting it draws only the arc.
        if (this.shouldCloseShape) {
            endShape(CLOSE);
        } else {
            endShape();
        }
        noStroke();
        noFill();
        strokeWeight(1);
    }

    // —— Endpoint helpers ————————————————————————————————

    getLeftEndpoint() {
        const lx = -this.xLeft;
        const ly = this.a * this.xLeft * this.xLeft;
        const r  = this._rotateLocal(lx, ly);
        return new SWPoint(this.vertex.x + r.x, this.vertex.y + r.y, undefined, 7);
    }

    getRightEndpoint() {
        const rx = this.xRight;
        const ry = this.a * this.xRight * this.xRight;
        const r  = this._rotateLocal(rx, ry);
        return new SWPoint(this.vertex.x + r.x, this.vertex.y + r.y, undefined, 7);
    }

    // —— Drawing ————————————————————————————————————————————

    draw() {
        const screenPts = this._buildScreenPtsDirect();
        this._drawShape(screenPts);
        if (this.shouldShowVertex && this.vertex && this.vertex.draw) {
            this.vertex.draw(this.strokeColor);
        }
        if (this.shouldShowEndpoints) {
            const lx = -this.xLeft;
            const ly = this.a * this.xLeft  * this.xLeft;
            const rx =  this.xRight;
            const ry = this.a * this.xRight * this.xRight;
            const lr = this._rotateLocal(lx, ly);
            const rr = this._rotateLocal(rx, ry);
            const lpt = new SWPoint(this.vertex.x + lr.x, this.vertex.y - lr.y, undefined, 7);
            const rpt = new SWPoint(this.vertex.x + rr.x, this.vertex.y - rr.y, undefined, 7);
            if (lpt.draw) lpt.draw(this.strokeColor);
            if (rpt.draw) rpt.draw(this.strokeColor);
        }
    }//end draw

    drawOnGrid(grid) {
        const screenPts = this._buildScreenPtsGrid(grid);
        this._drawShape(screenPts);
        if (this.shouldShowVertex && this.vertex && this.vertex.drawOnGrid) {
            this.vertex.drawOnGrid(grid, this.strokeColor);
        }
        if (this.shouldShowEndpoints) {
            const lep = this.getLeftEndpoint();
            const rep = this.getRightEndpoint();
            if (lep.drawOnGrid) lep.drawOnGrid(grid, this.strokeColor);
            if (rep.drawOnGrid) rep.drawOnGrid(grid, this.strokeColor);
        }
    }//end drawOnGrid

    // —— Animations ————————————————————————————————————————————

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

    breatheA(sinusoid, t) { this.a = sinusoid.getValue(t); }

    breatheBase(sinusoid, t) {
        const v    = Math.abs(sinusoid.getValue(t));
        this.xLeft  = v;
        this.xRight = v;
    }

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

    setA(a)            { this.a           = a; }
    setXLeft(v)        { this.xLeft       = Math.abs(v); }
    setXRight(v)       { this.xRight      = Math.abs(v); }
    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; }

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

    setShowVertex(show = true)    { this.shouldShowVertex    = show; }
    setShowEndpoints(show = true) { this.shouldShowEndpoints = show; }

    setShowPoints(show = true) {
        this.shouldShowVertex    = show;
        this.shouldShowEndpoints = show;
    }

    // —— Reset & Utility ————————————————————————————————————————————————————————————

    reset() {
        this.a           = this.originalA;
        this.xLeft       = this.originalXLeft;
        this.xRight      = this.originalXRight;
        this.rotationDeg = this.originalRotationDeg;
        this.rotation    = 0;
        this.thickness   = this.originalThickness;
        this.fillColor   = this.originalFillColor
            ? SWColor.copy(this.originalFillColor)   : undefined;
        this.strokeColor = this.originalStrokeColor
            ? SWColor.copy(this.originalStrokeColor) : undefined;
    }//end reset

    static copy(other) {
        const c = new SWArch(
            SWPoint.copy(other.vertex),
            other.originalA,
            other.originalXLeft,
            other.originalXRight,
            other.originalFillColor,
            other.originalStrokeColor,
            other.originalThickness,
            other.originalRotationDeg
        );
        c.a           = other.a;
        c.xLeft       = other.xLeft;
        c.xRight      = other.xRight;
        c.rotationDeg = other.rotationDeg;
        c.rotation    = other.rotation;
        c.shouldShowVertex    = other.shouldShowVertex;
        c.shouldShowEndpoints = other.shouldShowEndpoints;
        return c;
    }//end copy

    toString() {
        return `SWArch(vertex=${this.vertex}, a=${this.a.toFixed(4)}, ` +
               `xLeft=${this.xLeft.toFixed(2)}, xRight=${this.xRight.toFixed(2)}, ` +
               `rotationDeg=${this.rotationDeg.toFixed(1)}, ` +
               `rotation=${this.rotation.toFixed(1)})`;
    }

    // —— Static factory helpers ——————————————————————————————————————————————————————

    static fitParabolaToThreePoints(p1, p2, p3) {
        const x1 = p1.x, y1 = p1.y;
        const x2 = p2.x, y2 = p2.y;
        const x3 = p3.x, y3 = p3.y;

        if (Math.abs(x1 - x2) < 1e-9 ||
            Math.abs(x1 - x3) < 1e-9 ||
            Math.abs(x2 - x3) < 1e-9) {
            console.warn("SWArch.fitParabolaToThreePoints: two or more points " +
                         "share an x-coordinate — cannot fit a standard-form parabola.");
            return null;
        }

        const denom1 = x2 - x1;
        const denom2 = x3 - x1;
        const slope12 = (y2 - y1) / denom1;
        const slope13 = (y3 - y1) / denom2;
        const denominatorA = x3 - x2;

        if (Math.abs(denominatorA) < 1e-9) {
            console.warn("SWArch.fitParabolaToThreePoints: degenerate system.");
            return null;
        }

        const a = (slope13 - slope12) / denominatorA;

        if (Math.abs(a) < 1e-9) {
            console.warn("SWArch.fitParabolaToThreePoints: computed a ≈ 0 — " +
                         "the three points appear to be collinear.");
            return null;
        }

        const b = slope12 - a * (x2 + x1);
        const c = y1 - a * x1 * x1 - b * x1;

        return { a, b, c };
    }//end fitParabolaToThreePoints

    static fromThreePoints(p1, p2, p3,
                           fillColor = undefined, strokeColor = undefined,
                           thickness = 2, rotationDeg = 0) {

        const coeffs = SWArch.fitParabolaToThreePoints(p1, p2, p3);
        if (!coeffs) return null;

        const { a, b, c } = coeffs;

        const h = -b / (2 * a);
        const k = c - (b * b) / (4 * a);

        const localXs  = [p1.x - h, p2.x - h, p3.x - h];
        const minLocalX = Math.min(...localXs);
        const maxLocalX = Math.max(...localXs);
        const xLeft  = Math.abs(minLocalX);
        const xRight = Math.abs(maxLocalX);

        const vertexPt = new SWPoint(h, k);
        return new SWArch(vertexPt, a, xLeft, xRight,
                          fillColor, strokeColor, thickness, rotationDeg);
    }//end fromThreePoints

}//end SWArch class