💧 SketchWave TearDrop Class Reference

/*
File:    swTearDrop.js
Date:    2026-05-19
Author:  klp
Workspace: SketchWaveTNT2026-05-01-Stg9
Purpose: SWTearDrop class — a parametric teardrop (water-drop) shape based on:

           x(t) = b · sin(t) · sin^m(t / 2)
           y(t) = –a · cos(t)

         where t ∈ [0, 2π].

         Parameters:
           a  — half-height (distance from bounding-box centre to tip, and
                to the bottom of the bulge)
           b  — width scale (max half-width ≈ 0.77 × b for m = 1)
           m  — curve-power exponent (m ≥ 0)
                  0    → perfect ellipse
                  1.0  → classic teardrop
                  2+   → elongated, more pointed tip

         Default orientation: tip at TOP (minimum y), bulge at BOTTOM.
         At t = 0:  (0, –a) → tip at the top ✓
         At t = π:  (0, +a) → bottom of bulge ✓
         Width is maximum near t ≈ 109° (y ≈ +a/3, one-third down from centre).

Features:
  - Configurable fill colour, stroke colour, and stroke weight
  - Breathing animation via SWSinusoid (scales both a and b proportionally)
  - Rotation about the shape's bounding-box centre OR about its tip:
      'center' — the tip traces a circle around the centre point
      'tip'    — the tip stays fixed; the bulge swings like a pendulum
  - draw()          — pixel coordinates (screen space)
  - drawOnGrid(grid) — user coordinates mapped through a SWGrid

Dependencies: p5.js, swColor.js, swSinusoid.js (for breathe()), swGrid.js (for drawOnGrid())
Notes: assumes p5.js is running in colorMode(HSB, 360, 100, 100, 100)
*/

console.log("[swTearDrop.js] SWTearDrop class loaded.");

class SWTearDrop {

    /**
     * @param {number}   cx          - Centre x (bounding-box midpoint, pixels for draw())
     * @param {number}   cy          - Centre y (bounding-box midpoint — midway between tip and bottom)
     * @param {number}   a           - Half-height ≥ 1: distance from centre to tip (and to bottom)
     * @param {number}   b           - Width parameter ≥ 1: max half-width ≈ 0.77 × b
     * @param {SWColor}  fillColor   - Fill colour (null = no fill)
     * @param {Object}  [options]
     *   strokeColor   {SWColor}  Outline colour (null = no stroke)        (default null)
     *   strokeWeight  {number}   Stroke weight in pixels                  (default 2)
     *   m             {number}   Curve-power exponent ≥ 0                 (default 1.0)
     *   numPoints     {number}   Vertex count for smoothness              (default 120)
     *   rotOrigin     {string}   'center' | 'tip'                         (default 'center')
     */
    constructor(cx, cy, a, b, fillColor, options = {}) {
        this.cx = cx;
        this.cy = cy;
        this.a         = max(1, a);
        this.b         = max(1, b);
        this.originalA = this.a;
        this.originalB = this.b;

        this.fillColor    = fillColor           ? SWColor.copy(fillColor)           : null;
        this.strokeColor  = options.strokeColor ? SWColor.copy(options.strokeColor) : null;
        this.strokeWeight = options.strokeWeight ?? 2;
        this.m            = max(0, options.m ?? 1.0);
        this.numPoints    = max(3, options.numPoints ?? 120);
        this.rotOrigin    = options.rotOrigin ?? 'center';  // 'center' | 'tip'

        // Animation state
        this._rotAngle  = 0;     // accumulated rotation in degrees
        this._currentA  = this.a;
        this._currentB  = this.b;
    }//end constructor

    // ─── Drawing ─────────────────────────────────────────────────────────────

    /** Draw in screen (pixel) coordinates. */
    draw() {
        this._drawAtPx(this.cx, this.cy, this._currentA, this._currentB);
    }//end draw

    /**
     * Draw using user coordinates mapped through a SWGrid.
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        const { x: sx, y: sy } = grid.userToScreen(this.cx, this.cy);
        const sa = this._currentA * grid.xScale;
        const sb = this._currentB * grid.xScale;
        this._drawAtPx(sx, sy, sa, sb);
    }//end drawOnGrid

    /**
     * Core rendering: translate to pivot, rotate, then draw the parametric shape.
     *
     * Parametric equations (relative to bounding-box centre at origin):
     *   vx(t) = b · sin(t) · sin^m(t / 2)
     *   vy(t) = –a · cos(t)   [tip at (0, –a); bottom at (0, +a)]
     *
     * When rotOrigin === 'tip', the pivot is the tip (cx, cy – a):
     *   We translate to the tip, rotate, then offset vy by +a so the tip
     *   sits at the pivot origin:  vy_rel = –a·cos(t) + a = a·(1 – cos(t))
     *
     * @param {number} cx   Centre x in screen pixels
     * @param {number} cy   Centre y in screen pixels
     * @param {number} a    Current half-height in screen pixels
     * @param {number} b    Current width parameter in screen pixels
     */
    _drawAtPx(cx, cy, a, b) {
        push();

        // ── Appearance ────────────────────────────────────────────────────
        if (this.fillColor) {
            fill(this.fillColor.col);
        } else {
            noFill();
        }
        if (this.strokeColor) {
            stroke(this.strokeColor.col);
            strokeWeight(this.strokeWeight);
            strokeJoin(ROUND);
            strokeCap(ROUND);
        } else {
            noStroke();
        }

        // ── Transform: translate to pivot, then rotate ────────────────────
        // pivotOffY = shift from bounding-box centre to rotation pivot
        //   'center' pivot: offset = 0   (pivot at centre)
        //   'tip'    pivot: offset = –a  (pivot at top of teardrop)
        const pivotOffY = (this.rotOrigin === 'tip') ? -a : 0;
        translate(cx, cy + pivotOffY);
        rotate(radians(this._rotAngle));

        // ── Parametric vertices (relative to pivot) ───────────────────────
        //   vx(t) = b · sin(t) · sin^m(t / 2)
        //   vy(t) = –a · cos(t) – pivotOffY
        //     For 'center': vy = –a·cos(t)           (tip at y = –a above pivot)
        //     For 'tip':    vy = –a·cos(t) + a = a·(1 – cos(t))  (tip at y = 0)
        beginShape();
        for (let i = 0; i <= this.numPoints; i++) {
            const t  = (i / this.numPoints) * TWO_PI;
            const vx = b * sin(t) * pow(sin(t / 2), this.m);
            const vy = -a * cos(t) - pivotOffY;
            vertex(vx, vy);
        }
        endShape(CLOSE);

        pop();
    }//end _drawAtPx

    // ─── Animation ────────────────────────────────────────────────────────────

    /**
     * Scales the teardrop proportionally via a SWSinusoid.
     * Both a and b scale together, preserving the shape's aspect ratio.
     * @param {SWSinusoid} sinusoid
     * @param {number}     t - Elapsed time in seconds
     */
    breathe(sinusoid, t) {
        const scale    = sinusoid.getValue(t);
        this._currentA = this.originalA * scale;
        this._currentB = this.originalB * scale;
    }//end breathe

    /**
     * Rotates the teardrop. Accumulates continuously as t increases.
     * Positive values rotate clockwise in screen coordinates.
     * Pivot is set by this.rotOrigin ('center' or 'tip').
     * @param {number} degPerSec - Rotation speed (degrees per second)
     * @param {number} t         - Accumulated elapsed time in seconds
     */
    rotate(degPerSec, t) {
        this._rotAngle = degPerSec * t;
    }//end rotate

    /**
     * Combines breathing and rotation in one call.
     * Mirrors the transform() API on SWSun, SWLine, and SWArrow.
     * @param {Object}     [options]
     * @param {SWSinusoid} [options.sinusoid=null]  - Breathing sinusoid (null = no breathe)
     * @param {number}     [options.t=0]            - Time in seconds
     * @param {number}     [options.degPerSec=null] - Rotation rate in deg/sec (null = no rotate)
     */
    transform({ sinusoid = null, t = 0, degPerSec = null } = {}) {
        if (sinusoid  !== null) this.breathe(sinusoid, t);
        if (degPerSec !== null) this.rotate(degPerSec, t);
    }//end transform

    /**
     * Resets all animation state to initial (factory) values.
     */
    reset() {
        this._rotAngle = 0;
        this._currentA = this.originalA;
        this._currentB = this.originalB;
    }//end reset

    // ─── Setters ──────────────────────────────────────────────────────────────

    /** Move the shape's centre point. */
    setCenter(cx, cy) {
        this.cx = cx;
        this.cy = cy;
    }//end setCenter

    /** Set the half-height and reset the breathing baseline. */
    setA(a) {
        this.a         = max(1, a);
        this.originalA = this.a;
        this._currentA = this.a;
    }//end setA

    /** Set the width parameter and reset the breathing baseline. */
    setB(b) {
        this.b         = max(1, b);
        this.originalB = this.b;
        this._currentB = this.b;
    }//end setB

    /** Set the curve-power exponent (≥ 0; 0 = perfect ellipse). */
    setM(m)            { this.m            = max(0, m); }//end setM

    /** Set the number of vertices for the shape outline (≥ 3). */
    setNumPoints(n)    { this.numPoints    = max(3, floor(n)); }//end setNumPoints

    /** Set the fill colour (pass null for no fill). */
    setFillColor(c)    { this.fillColor    = c ? SWColor.copy(c) : null; }//end setFillColor

    /** Set the stroke colour (pass null for no stroke). */
    setStrokeColor(c)  { this.strokeColor  = c ? SWColor.copy(c) : null; }//end setStrokeColor

    /** Set the stroke weight in pixels. */
    setStrokeWeight(w) { this.strokeWeight = max(0, w); }//end setStrokeWeight

    /** Set the rotation pivot: 'center' or 'tip'. */
    setRotOrigin(o)    { this.rotOrigin    = o; }//end setRotOrigin

    /** @returns {string} */
    toString() {
        return `SWTearDrop(cx:${this.cx.toFixed(1)}, cy:${this.cy.toFixed(1)}, ` +
               `a:${this._currentA.toFixed(1)}, b:${this._currentB.toFixed(1)}, m:${this.m})`;
    }//end toString

}//end class SWTearDrop