∿ SketchWave Bell Curve Class Reference

/*
  File:    swBellCurve.js
  Date:    2026-05-18
  Author:  klp
  Workspace: SketchWaveTNT2026-05-01-Stg9
  Purpose: SWBellCurve — draws a bell-shaped (Gaussian) curve as a closed filled
           shape: the Gaussian arc on top and a flat baseline on the bottom.

  Positioning:
    cx, cy = centre of the bounding box.
    Peak is amplitude/2 ABOVE the centre line  (screen y = cy − amplitude/2).
    Baseline is amplitude/2 BELOW the centre line (screen y = cy + amplitude/2).

  Local-coordinate formula (origin at bounding-box centre, y down):
    y = halfAmp − amp × exp(−x² / (2σ²))
    • At x = 0:       y = −halfAmp   (peak, at top)
    • At x = ±range:  y →  halfAmp   (baseline, at bottom)

  Key formulas:
    FWHM  = 2σ √(2 ln 2)  ≈  2.355 σ   (full width at half maximum)
    Area  ≈ amp × σ × √(2π)             (infinite-integral approximation)

  Breathing modes:
    breathe()             — scales both amplitude AND sigma uniformly
    breatheVertical()     — scales amplitude only  (taller / shorter)
    breatheHorizontal()   — scales sigma only      (wider / narrower)

  Dependencies: p5.js, swColor.js, swSinusoid.js, swGrid.js
  Notes: assumes p5.js colorMode(HSB, 360, 100, 100, 100)
*/

console.log("[swBellCurve.js] SWBellCurve class loaded.");

class SWBellCurve {

    constructor(cx, cy, amplitude, sigma, fillColor, options = {}) {
        this.cx        = cx;
        this.cy        = cy;
        this.amplitude = Math.max(1, amplitude);
        this.sigma     = Math.max(1, sigma);

        this.originalAmplitude = this.amplitude;
        this.originalSigma     = this.sigma;

        this.fillColor   = fillColor           ? SWColor.copy(fillColor)           : null;
        this.strokeColor = options.strokeColor ? SWColor.copy(options.strokeColor) : null;
        this.strokeWeight    = options.strokeWeight    ?? 2;
        this.drawRangeFactor = Math.max(1, options.drawRangeFactor ?? 3.5);
        this.resolution      = Math.max(20,  options.resolution     ?? 120);

        this._rotAngle         = 0;
        this._currentAmplitude = this.amplitude;
        this._currentSigma     = this.sigma;
    }

    get fwhm()       { return 2 * this._currentSigma * Math.sqrt(2 * Math.LN2); }
    get totalWidth() { return 2 * this._currentSigma * this.drawRangeFactor; }
    get area()       { return this._currentAmplitude * this._currentSigma * Math.sqrt(2 * Math.PI); }

    draw() {
        this._drawAtPx(this.cx, this.cy, this._currentAmplitude, this._currentSigma);
    }

    drawOnGrid(grid) {
        const { x: sx, y: sy } = grid.userToScreen(this.cx, this.cy);
        const sAmp = this._currentAmplitude * Math.abs(grid.yScale);
        const sSig = this._currentSigma     * grid.xScale;
        this._drawAtPx(sx, sy, sAmp, sSig);
    }

    _drawAtPx(cx, cy, amp, sig) {
        if (amp <= 0 || sig <= 0) return;
        push();
        if (this.fillColor) { fill(this.fillColor.col); } else { noFill(); }
        if (this.strokeColor) {
            stroke(this.strokeColor.col);
            strokeWeight(this.strokeWeight);
        } else { noStroke(); }
        translate(cx, cy);
        rotate(radians(this._rotAngle));
        const range   = sig * this.drawRangeFactor;
        const n       = this.resolution;
        const step    = (2 * range) / n;
        const halfAmp = amp / 2;
        const twoSig2 = 2 * sig * sig;
        beginShape();
        vertex(-range, halfAmp);
        for (let i = 0; i <= n; i++) {
            const x = -range + i * step;
            const y = halfAmp - amp * Math.exp(-(x * x) / twoSig2);
            vertex(x, y);
        }
        vertex(range, halfAmp);
        endShape(CLOSE);
        pop();
    }

    breathe(sinusoid, t) {
        const s = sinusoid.getValue(t);
        this._currentAmplitude = this.originalAmplitude * s;
        this._currentSigma     = this.originalSigma     * s;
    }

    breatheVertical(sinusoid, t) {
        this._currentAmplitude = this.originalAmplitude * sinusoid.getValue(t);
    }

    breatheHorizontal(sinusoid, t) {
        this._currentSigma = this.originalSigma * sinusoid.getValue(t);
    }

    rotate(degPerSec, t)  { this._rotAngle = degPerSec * t; }

    transform({ sinusoid = null, sinusoidV = null, sinusoidH = null,
                t = 0, degPerSec = null } = {}) {
        if (sinusoid  !== null) this.breathe(sinusoid, t);
        if (sinusoidV !== null) this.breatheVertical(sinusoidV, t);
        if (sinusoidH !== null) this.breatheHorizontal(sinusoidH, t);
        if (degPerSec !== null) this.rotate(degPerSec, t);
    }

    reset() {
        this._rotAngle         = 0;
        this._currentAmplitude = this.originalAmplitude;
        this._currentSigma     = this.originalSigma;
    }

    setCenter(cx, cy)     { this.cx = cx; this.cy = cy; }
    setAmplitude(a)       { this.amplitude = this.originalAmplitude = this._currentAmplitude = Math.max(1, a); }
    setSigma(s)           { this.sigma = this.originalSigma = this._currentSigma = Math.max(1, s); }
    setFillColor(c)       { this.fillColor   = c ? SWColor.copy(c) : null; }
    setStrokeColor(c)     { this.strokeColor = c ? SWColor.copy(c) : null; }
    setStrokeWeight(w)    { this.strokeWeight = Math.max(0, w); }
    setDrawRangeFactor(f) { this.drawRangeFactor = Math.max(1, f); }

    toString() {
        return `SWBellCurve(cx:${this.cx.toFixed(1)}, cy:${this.cy.toFixed(1)}, ` +
               `amp:${this._currentAmplitude.toFixed(1)}, sigma:${this._currentSigma.toFixed(1)})`;
    }

}//end class SWBellCurve