⛅ SWCloud Reference

/*
File: swCloud.js
Date: 2026-05-08
Author: klp + GitHub Copilot
Workspace: SketchWaveTNT2026-05-01-Stg9
Purpose: SWCloud class for SketchWaveJS

SWCloud represents a cumulus-style cloud shape built from N overlapping SWEllipse "puffs".
Each puff is a horizontally-elongated ellipse. Puffs are placed at random normalized offsets
(dx, dy each in −1..+1) around the cloud center, scaled by spreadH × puffWidth and
spreadV × puffHeight. Each puff also gets a random size scale (0.70–1.00).
The offsets are stored so sliders can rescale the cloud without changing its random shape.

Animations:
  breathe(sinX, sinY, t)  — each puff breathes independently with a configurable
                            phase stagger (seconds) between adjacent puffs.
  update(t, deltaT, ...)  — advances horizontal drift (with canvas wrap-around) and
                            applies per-puff Perlin-noise morphing so the cloud shape
                            shifts organically over time.

Constructor:
  new SWCloud(center, options)

  center  : SWPoint  — anchor of the cloud
  options :
    puffCount     : number  — number of ellipse puffs (default 5; min 1)
    puffWidth     : number  — base horizontal radius of puffs in user units (default 1.8)
    puffHeight    : number  — base vertical   radius of puffs in user units (default 1.0)
    spread        : number  — horizontal scatter scale; 0 = all puffs at center (default 1.0)
    spreadV       : number  — vertical   scatter scale (default 0.6)
    fillColor     : SWColor — fill color (default: undefined = no fill)
    strokeColor   : SWColor — border color (default: undefined = no border)
    strokeWeight  : number  — border thickness (default 1)
    showCenters   : boolean — show SWPoint dots at each puff center (default false)
    breatheStagger: number  — phase offset in seconds between adjacent puff breaths (default 0.3)
    driftSpeed    : number  — horizontal drift speed in user units/sec; + = rightward (default 0)
    noiseAmp      : number  — Perlin-noise morph amplitude in user units (default 0.3)
    noiseSpeed    : number  — Perlin-noise time scale (higher = faster morphing) (default 0.3)

Key methods:
  drawOnGrid(grid)              — draw all puffs in user/grid coordinates
  draw()                        — draw all puffs in screen (pixel) coordinates
  breathe(sinX, sinY, t)        — animate puff sizes with staggered phase
  update(t, deltaT, ...)        — advance drift and/or apply per-puff Perlin noise morph
  randomize()                   — generate a new set of random puff offsets and rebuild
  reset()                       — restore all factory-default properties and rebuild puffs
  setShowCenters(bool)          — toggle SWPoint center dots on all puffs
  setPuffCount(n)               — change puff count and rebuild (new random offsets)
  setPuffWidth(w)               — change base puff radiusX and rebuild
  setPuffHeight(h)              — change base puff radiusY and rebuild
  setSpread(s)                  — change horizontal scatter scale and rebuild
  setSpreadV(v)                 — change vertical   scatter scale and rebuild
  setCenter(x, y)               — reposition cloud anchor and rebuild
  setFillColor(col)             — update fill color on all puffs (no rebuild)
  setStrokeColor(col)           — update border color on all puffs (no rebuild)
  setStrokeWeight(w)            — update border weight on all puffs (no rebuild)
  setBreatheStagger(s)          — update phase stagger between puffs (no rebuild)
  setDriftSpeed(v)              — update horizontal drift speed (no rebuild)
  setNoiseAmp(v)                — update Perlin-noise morph amplitude (no rebuild)
  setNoiseSpeed(v)              — update Perlin-noise time scale (no rebuild)

Getters:
  width   — approximate total width of the cloud in user coords
  height  — approximate total height of the cloud in user coords

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

console.log("[swCloud.js] SWCloud class loaded.");

class SWCloud {

    /**
     * @param {SWPoint} center       - Anchor point (baseline of cloud center)
     * @param {Object}  [options={}]
     *   puffCount     : number  — number of ellipse puffs (default 5)
     *   puffWidth     : number  — base radiusX of each puff (user units, default 1.8)
     *   puffHeight    : number  — base radiusY of each puff (user units, default 1.0)
     *   spread        : number  — spacing multiplier (default 1.0)
     *   fillColor     : SWColor — fill color
     *   strokeColor   : SWColor — border color
     *   strokeWeight  : number  — border thickness (default 1)
     *   showCenters   : boolean — show SWPoint dots at puff centers (default false)
     *   breatheStagger: number  — phase offset (seconds) between adjacent puff breaths (default 0.3)
     *   driftSpeed    : number  — horizontal drift speed (user units/sec); + = rightward (default 0)
     *   noiseAmp      : number  — Perlin-noise morph amplitude in user units (default 0.3)
     *   noiseSpeed    : number  — Perlin-noise time scale (higher = faster morphing) (default 0.3)
     */
    constructor(center, options = {}) {
        this.center        = center;
        this.puffCount     = options.puffCount     !== undefined ? Math.max(1, Math.round(options.puffCount)) : 5;
        this.puffWidth     = options.puffWidth     !== undefined ? options.puffWidth     : 1.8;
        this.puffHeight    = options.puffHeight    !== undefined ? options.puffHeight    : 1.0;
        this.spread        = options.spread        !== undefined ? options.spread        : 1.0;
        this.spreadV       = options.spreadV       !== undefined ? options.spreadV       : 0.6;
        this.fillColor     = options.fillColor     ? SWColor.copy(options.fillColor)    : undefined;
        this.strokeColor   = options.strokeColor   ? SWColor.copy(options.strokeColor)  : undefined;
        this.strokeWeight  = options.strokeWeight  !== undefined ? options.strokeWeight  : 1;
        this.showCenters   = options.showCenters   !== undefined ? options.showCenters   : false;
        this.breatheStagger = options.breatheStagger !== undefined ? options.breatheStagger : 0.3;
        this.driftSpeed  = options.driftSpeed  !== undefined ? options.driftSpeed  : 0;
        this.noiseAmp    = options.noiseAmp    !== undefined ? options.noiseAmp    : 0.3;
        this.noiseSpeed  = options.noiseSpeed  !== undefined ? options.noiseSpeed  : 0.3;
        this.wrapGap     = options.wrapGap     !== undefined ? options.wrapGap     : 2.0;

        // Store originals for reset()
        this.originalCenter      = new SWPoint(center.x, center.y);
        this.originalPuffCount   = this.puffCount;
        this.originalPuffWidth   = this.puffWidth;
        this.originalPuffHeight  = this.puffHeight;
        this.originalSpread      = this.spread;
        this.originalSpreadV     = this.spreadV;
        this.originalDriftSpeed  = this.driftSpeed;
        this.originalNoiseAmp    = this.noiseAmp;
        this.originalNoiseSpeed  = this.noiseSpeed;
        this.originalWrapGap     = this.wrapGap;

        // Generate initial random offsets and store them for reset()
        this._offsets = [];
        this._generateOffsets(this.puffCount);
        this.originalOffsets = this._offsets.map(o => ({ dx: o.dx, dy: o.dy, size: o.size }));

        this._puffs = [];
        this._buildPuffs();
    }//end constructor

    // —— Internal: puff layout ———————————————————————

    /**
     * Builds the _puffs array from current properties.
     * Called by the constructor and by all setters that affect shape or layout.
     */
    _buildPuffs() {
        this._puffs = [];
        const N = this.puffCount;

        // Ensure random offsets exist and match current puff count
        if (!this._offsets || this._offsets.length !== N) {
            this._generateOffsets(N);
        }

        for (let i = 0; i < N; i++) {
            const off = this._offsets[i];

            // Puff center — random offset scaled by spread magnitudes and puff dimensions
            const px = this.center.x + off.dx * this.spread  * this.puffWidth;
            const py = this.center.y + off.dy * this.spreadV * this.puffHeight;

            // Per-puff size variation stored in the offset
            const rX = this.puffWidth  * off.size;
            const rY = this.puffHeight * off.size;

            const puffCenter = new SWPoint(px, py);
            const puff = new SWEllipse(
                puffCenter, rX, rY,
                this.fillColor  ? SWColor.copy(this.fillColor)  : undefined,
                {
                    strokeColor:  this.strokeColor ? SWColor.copy(this.strokeColor) : undefined,
                    strokeWeight: this.strokeWeight,
                    showCenter:   this.showCenters,
                }
            );
            this._puffs.push(puff);
        }
    }//end _buildPuffs

    /**
     * Generates N random normalized offsets for puff placement.
     * Each offset has dx/dy in −1..+1 (horizontal/vertical scatter) and
     * a random size scale in 0.70..1.00.
     * When N=1 the single puff is always placed at the center (dx=dy=0).
     * @param {number} n
     */
    _generateOffsets(n) {
        this._offsets = [];
        if (n === 1) {
            // Single puff always centered regardless of spread
            this._offsets.push({ dx: 0, dy: 0, size: 1.0 });
            return;
        }
        for (let i = 0; i < n; i++) {
            this._offsets.push({
                dx:   Math.random() * 2 - 1,        // −1 .. +1  horizontal scatter
                dy:   Math.random() * 2 - 1,        // −1 .. +1  vertical scatter
                size: 0.70 + Math.random() * 0.30,  // 0.70 .. 1.00  size variation
            });
        }
    }//end _generateOffsets

    // —— Getters ————————————————————————————————————

    /**
     * Approximate total width of the cloud in user coords
     * (from left edge of leftmost puff to right edge of rightmost puff).
     */
    get width() {
        if (this._puffs.length === 0) return 0;
        let minX = Infinity, maxX = -Infinity;
        for (const p of this._puffs) {
            minX = Math.min(minX, p.center.x - p.radiusX);
            maxX = Math.max(maxX, p.center.x + p.radiusX);
        }
        return maxX - minX;
    }//end width

    /**
     * Approximate total height of the cloud in user coords
     * (from bottom edge of edge puffs to top edge of center puff).
     */
    get height() {
        if (this._puffs.length === 0) return 0;
        let minY = Infinity, maxY = -Infinity;
        for (const p of this._puffs) {
            minY = Math.min(minY, p.center.y - p.radiusY);
            maxY = Math.max(maxY, p.center.y + p.radiusY);
        }
        return maxY - minY;
    }//end height

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

    /** Show or hide the SWPoint dot at each puff center. */
    setShowCenters(show = true) {
        this.showCenters = show;
        for (const p of this._puffs) p.setShowCenter(show);
    }//end setShowCenters

    /** Change the number of puffs and rebuild. Clamps to ≥ 1. */
    setPuffCount(n) {
        this.puffCount = Math.max(1, Math.round(n));
        this._buildPuffs();
    }//end setPuffCount

    /** Change the base puff radiusX (horizontal) and rebuild. */
    setPuffWidth(w) {
        this.puffWidth = w;
        this._buildPuffs();
    }//end setPuffWidth

    /** Change the base puff radiusY (vertical) and rebuild. */
    setPuffHeight(h) {
        this.puffHeight = h;
        this._buildPuffs();
    }//end setPuffHeight

    /** Change the horizontal scatter magnitude and rebuild. */
    setSpread(s) {
        this.spread = s;
        this._buildPuffs();
    }//end setSpread

    /** Change the vertical scatter magnitude and rebuild. */
    setSpreadV(v) {
        this.spreadV = v;
        this._buildPuffs();
    }//end setSpreadV

    /** Reposition the cloud anchor and rebuild all puffs around the new center. */
    setCenter(x, y) {
        this.center.x = x;
        this.center.y = y;
        this._buildPuffs();
    }//end setCenter

    /** Apply a new fill color to all puffs without rebuilding. */
    setFillColor(col) {
        this.fillColor = col ? SWColor.copy(col) : undefined;
        for (const p of this._puffs) {
            p.fillColor = this.fillColor ? SWColor.copy(this.fillColor) : undefined;
        }
    }//end setFillColor

    /** Apply a new stroke color to all puffs without rebuilding. */
    setStrokeColor(col) {
        this.strokeColor = col ? SWColor.copy(col) : undefined;
        for (const p of this._puffs) {
            p.strokeColor = this.strokeColor ? SWColor.copy(this.strokeColor) : undefined;
        }
    }//end setStrokeColor

    /** Apply a new stroke weight to all puffs without rebuilding. */
    setStrokeWeight(w) {
        this.strokeWeight = w;
        for (const p of this._puffs) p.strokeWeight = w;
    }//end setStrokeWeight

    /** Update the phase offset (seconds) between adjacent puff breaths. */
    setBreatheStagger(s) {
        this.breatheStagger = s;
    }//end setBreatheStagger

    /** Change the horizontal drift speed (user units / second; positive = rightward). */
    setDriftSpeed(v) {
        this.driftSpeed = v;
    }//end setDriftSpeed

    /** Change the Perlin-noise morph amplitude (user units; 0 = no displacement). */
    setNoiseAmp(v) {
        this.noiseAmp = v;
    }//end setNoiseAmp

    /** Change how fast the Perlin-noise pattern evolves (higher = faster morphing). */
    setNoiseSpeed(v) {
        this.noiseSpeed = v;
    }//end setNoiseSpeed

    /** Change how far (user units) past the canvas edge the cloud travels before wrapping back. 0 = instant reappear. */
    setWrapGap(v) {
        this.wrapGap = Math.max(0, v);
    }//end setWrapGap

    /**
     * Generates a completely new set of random puff offsets and rebuilds.
     * Use this to get a fresh random cloud shape without changing any parameters.
     */
    randomize() {
        this._generateOffsets(this.puffCount);
        this._buildPuffs();
    }//end randomize

    /**
     * Advances cloud drift and applies per-puff Perlin-noise morphing each frame.
     * Call once per frame from draw() when drift or noise-morph is active.
     * Updates puff center positions in-place — does not rebuild SWEllipse objects.
     *
     * @param {number}  t              - elapsed time in seconds
     * @param {number}  deltaT         - seconds since last frame
     * @param {number}  [wrapLeft=-15] - left wrap boundary in user coords
     * @param {number}  [wrapRight=15] - right wrap boundary in user coords
     * @param {boolean} [doDrift=true] - advance center.x and wrap horizontally
     * @param {boolean} [doNoise=true] - apply per-puff Perlin noise displacement
     */
    update(t, deltaT, wrapLeft = -15, wrapRight = 15, doDrift = true, doNoise = true, wrapTop = 10, wrapBottom = -10) {
        // 1. Advance drift — move center.x and wrap when cloud exits the canvas
        if (doDrift) {
            this.center.x += this.driftSpeed * deltaT;
            // wrapGap: user-controlled distance past the canvas edge before wrapping
            const margin = this.wrapGap;
            // Vertical nudge applied on every wrap: ±1.5× puffHeight, clamped to canvas
            const maxNudge = this.puffHeight * 1.5;
            const nudge    = (Math.random() * 2 - 1) * maxNudge;
            const halfH    = this.puffHeight * Math.max(this.spreadV, 0.5) * (this.puffCount * 0.3 + 1);
            if (this.driftSpeed >= 0 && this.center.x - margin > wrapRight) {
                this.center.x  = wrapLeft - margin;
                this.center.y  = Math.min(wrapTop    - halfH,
                                 Math.max(wrapBottom + halfH, this.center.y + nudge));
            } else if (this.driftSpeed < 0 && this.center.x + margin < wrapLeft) {
                this.center.x  = wrapRight + margin;
                this.center.y  = Math.min(wrapTop    - halfH,
                                 Math.max(wrapBottom + halfH, this.center.y + nudge));
            }
        }

        // 2. Reposition each puff: base offset from _offsets, plus optional Perlin noise
        for (let i = 0; i < this._puffs.length; i++) {
            const off   = this._offsets[i];
            const baseX = this.center.x + off.dx * this.spread  * this.puffWidth;
            const baseY = this.center.y + off.dy * this.spreadV * this.puffHeight;
            if (doNoise) {
                // Spatially distinct noise per puff via prime-number multipliers on i
                const nx = (noise(i * 1.73,      t * this.noiseSpeed) * 2 - 1) * this.noiseAmp;
                const ny = (noise(i * 3.17 + 50, t * this.noiseSpeed) * 2 - 1) * this.noiseAmp * 0.5;
                this._puffs[i].center.x = baseX + nx;
                this._puffs[i].center.y = baseY + ny;
            } else {
                this._puffs[i].center.x = baseX;
                this._puffs[i].center.y = baseY;
            }
        }
    }//end update

    // —— Rendering ————————————————————————————————————

    /**
     * Draws all puffs in user/grid coordinates via the given SWGrid.
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        for (const p of this._puffs) p.drawOnGrid(grid);
    }//end drawOnGrid

    /**
     * Draws all puffs in screen (pixel) coordinates.
     * radiusX / radiusY are treated as pixel values.
     */
    draw() {
        for (const p of this._puffs) p.draw();
    }//end draw

    // —— Animation ————————————————————————————————————

    /**
     * Scales each puff's radiusX and/or radiusY using SWSinusoid instances.
     * Adjacent puffs breathe with a configurable phase stagger, producing
     * an organic, billowing cloud effect.
     *
     * @param {SWSinusoid|null} sinusoidX — horizontal scale driver (or null)
     * @param {SWSinusoid|null} sinusoidY — vertical   scale driver (or null)
     * @param {number}          t         — elapsed time in seconds
     */
    breathe(sinusoidX, sinusoidY, t) {
        for (let i = 0; i < this._puffs.length; i++) {
            this._puffs[i].breathe(sinusoidX, sinusoidY, t + i * this.breatheStagger);
        }
    }//end breathe

    /**
     * Resets the cloud to its original construction parameters and rebuilds all puffs.
     * Also restores the center position.
     */
    reset() {
        this.center.x   = this.originalCenter.x;
        this.center.y   = this.originalCenter.y;
        this.puffCount  = this.originalPuffCount;
        this.puffWidth  = this.originalPuffWidth;
        this.puffHeight = this.originalPuffHeight;
        this.spread     = this.originalSpread;
        this.spreadV    = this.originalSpreadV;
        this.driftSpeed = this.originalDriftSpeed;
        this.noiseAmp   = this.originalNoiseAmp;
        this.noiseSpeed = this.originalNoiseSpeed;
        this.wrapGap    = this.originalWrapGap;
        // Restore the original random offsets so reset returns the exact original cloud shape
        this._offsets   = this.originalOffsets.map(o => ({ dx: o.dx, dy: o.dy, size: o.size }));
        this._buildPuffs();
    }//end reset

}//end class SWCloud