🌉 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
  breatheBase(sinusoid, t)  — oscillates xLeft and xRight to expand/contract base width

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;

        // —— 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(CLOSE) from pre-computed screen points. */
    _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);
        }
        endShape(CLOSE);
        noStroke();
        noFill();
        strokeWeight(1);
    }

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

    /**
     * Returns the left endpoint as an SWPoint in user (grid) space.
     * strokeWeight=7 gives a visible dot; color is supplied at draw time.
     * @returns {SWPoint}
     */
    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);
    }

    /**
     * Returns the right endpoint as an SWPoint in user (grid) space.
     * strokeWeight=7 gives a visible dot; color is supplied at draw time.
     * @returns {SWPoint}
     */
    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 —————————————————————————————————————————————————————————————————————————————————————————————

    /**
     * Draws the arch in raw screen (pixel) coordinates.
     * Prefer drawOnGrid() for standard canvas use.
     */
    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

    /**
     * Draws the arch mapped through the given SWGrid's coordinate system.
     * This is the standard drawing method to use in a p5.js draw() loop.
     * @param {SWGrid} grid
     */
    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 ————————————————————————————————————————————————————————————————————————————————————————————

    /**
     * Spins the arch about its vertex by deltaAngle degrees (CCW+, CW−).
     * Accumulates into this.rotation.  Call once per frame in draw().
     * @param {number} deltaAngle  degrees per frame (typically speed × deltaT)
     */
    rotate(deltaAngle) { this.rotation += deltaAngle; }

    /**
     * Oscillates the ‘a’ coefficient to open and close the arch curvature.
     * Larger |a| → sharper arch; smaller |a| → flatter arch; a crossing zero
     * → arch flips between ∩ and ∪.
     * Call each frame; when the animation is disabled, restore arch.a via
     * setA() or reset().
     * @param {SWSinusoid} sinusoid  configured with min/max a values
     * @param {number}     t         elapsed time in seconds
     */
    breatheA(sinusoid, t) { this.a = sinusoid.getValue(t); }

    /**
     * Oscillates xLeft and xRight together symmetrically to expand and contract
     * the base of the arch — like wings opening and closing.
     * The sinusoid should be configured with positive min/max extent values.
     * Call each frame; when the animation is disabled, restore xLeft and xRight
     * via setXLeft()/setXRight() or reset().
     * @param {SWSinusoid} sinusoid  configured with min/max extent values (both > 0)
     * @param {number}     t         elapsed time in seconds
     */
    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); }

    /** Sets the static base rotation in CCW degrees. Does not affect accumulated rotation. */
    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; }

    /**
     * Sets the fill alpha (0–100) and rebuilds the p5 color object.
     * @param {number} alpha  0 = transparent, 100 = opaque
     */
    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; }

    /** Convenience: show/hide both the vertex marker and the endpoint markers. */
    setShowPoints(show = true) {
        this.shouldShowVertex    = show;
        this.shouldShowEndpoints = show;
    }

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

    /**
     * Restores all animated/slider-driven properties to original constructor values.
     * Clears accumulated spin rotation.  Does NOT move the vertex position.
     */
    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

    /**
     * Creates a deep copy of the given SWArch, preserving all current and original state.
     * @param {SWArch} other
     * @returns {SWArch}
     */
    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)})`;
    }

}//end SWArch class