Skip to content

Unlock custom brushes, natural fill effects and intuitive hatching in p5.js

14.6 KB
Raw Blame
import { Cwidth, Cheight } from "./target.js";
import { isMixReady, State } from "./color.js";
import {
  randInt2,
  noise2,
  rr2,
  sin,
  cos,
  cossin,
  map,
  toDegreesSigned,
} from "./utils.js";
import { getAffineMatrix } from "./runtime.js";

// =============================================================================
// Section: Matrix transformations
// =============================================================================

// =============================================================================
// Section: Field Initialization
// =============================================================================

let isLoaded = false;

/**
 * Ensures the field system is initialized and ready for use.
 * If the field is not loaded, it initializes the mixing system and creates the field.
 */
export function isFieldReady() {
  if (!isLoaded) {
    isMixReady(); // Ensure the mixing system is ready
    createField(); // Initialize the field
    isLoaded = true;
  }
}

// =============================================================================
// Section: Position Class
// =============================================================================

/**
 * The Position class represents a point within a two-dimensional space, which can interact with a vector field.
 * It provides methods to update the position based on the field's flow and to check whether the position is
 * within certain bounds (e.g., within the field or canvas).
 */
export class Position {
  /**
   * Constructs a new Position instance.
   * @param {number} x - The initial x-coordinate.
   * @param {number} y - The initial y-coordinate.
   */
  constructor(x, y) {
    isFieldReady();
    const m = getAffineMatrix();
    this.mx = m.x;
    this.my = m.y;
    this.update(x, y);
    this.plotted = 0; // Tracks the total distance plotted
  }

  /**
   * Updates the position's coordinates and calculates its offsets and indices within the flow field.
   * @param {number} x - The new x-coordinate.
   * @param {number} y - The new y-coordinate.
   */
  update(x, y) {
    this.x = x;
    this.y = y;
    if (State.field.isActive) {
      this.colIdx = Math.round((x + this.mx - left_x) / resolution);
      this.rowIdx = Math.round((y + this.my - top_y) / resolution);
    }
  }

  /**
   * Resets the 'plotted' property to 0.
   */
  reset() {
    this.plotted = 0;
  }

  /**
   * Checks if the position is within the active flow field's bounds.
   * @returns {boolean} - True if the position is within the flow field, false otherwise.
   */
  isIn() {
    return State.field.isActive
      ? Position.isIn(this.colIdx, this.rowIdx)
      : this.isInCanvas(this.x, this.y);
  }

  /**
   * Checks if the position is within the canvas bounds (with a margin).
   * @returns {boolean} - True if the position is within bounds, false otherwise.
   */
  isInCanvas() {
    const margin = 0.5;
    const w = Cwidth;
    const h = Cheight;
    const x = this.x + this.mx;
    const y = this.y + this.my;
    return (
      x >= -margin * w &&
      x <= (1 + margin) * w &&
      y >= -margin * h &&
      y <= (1 + margin) * h
    );
  }

  /**
   * Calculates the angle of the flow field at the position's current coordinates.
   * @returns {number} - The internal flow angle in degrees, or 0 if the position is not in the field or if no field is active.
   */
  angle(skipCheck = false) {
    if (!State.field.isActive) return 0;
    return skipCheck || this.isIn()
      ? flow_field()[this.colIdx][this.rowIdx] * State.field.wiggle
      : 0;
  }

  /**
   * Moves the position along the flow field by a certain length.
   * @param {number} _dir - The direction of movement, interpreted using the current runtime angle units.
   * @param {number} _length - The length to move along the field.
   * @param {number} _step_length - The length of each step.
   */
  moveTo(_dir, _length, _step_length = 1) {
    const dir = toDegreesSigned(_dir);
    if (State.field.isActive) {
      this.movePos(dir, _length, _step_length);
    } else {
      this._moveConstant(dir, _length, _step_length);
    }
  }

  /**
   * Internal variant of moveTo() that expects a degree value already normalized to the library's internal representation.
   */
  _moveToDegrees(_dir, _length, _step_length = 1) {
    if (State.field.isActive) {
      this.movePos(_dir, _length, _step_length);
    } else {
      this._moveConstant(_dir, _length, _step_length);
    }
  }

  /**
   * Fast constant-direction movement (no field, no plot).
   * Precomputes trig once and applies dx/dy directly.
   */
  _moveConstant(_dir, _length, _step) {
    if (!this.isIn()) {
      this.plotted += _step;
      return;
    }
    const steps = _length / _step;
    const _cs = cossin(-_dir);
    const dx = _step * _cs[0],
      dy = _step * _cs[1];
    for (let i = 0; i < steps; i++) {
      this.x += dx;
      this.y += dy;
      this.plotted += _step;
    }
  }

  /**
   * Plots a point to another position within the flow field, following a Plot object
   * @param {Position} _plot - The Plot path object.
   * @param {number} _length - The length to move towards the target position.
   * @param {number} _step_length - The length of each step.
   * @param {number} _scale - The scaling factor for the plotting path.
   */
  plotTo(
    _plot,
    _length,
    _step_length,
    _scale = 1,
    precomputedAngle = undefined,
  ) {
    this.movePos(_plot, _length, _step_length, _scale, precomputedAngle);
  }

  movePos(
    _dirPlot,
    _length,
    _step,
    _scale = false,
    precomputedAngle = undefined,
  ) {
    const scaleFactor = _scale || 1;
    if (!this.isIn()) {
      this.plotted += _step / scaleFactor;
      return;
    }
    const steps = _length / _step;
    const fieldActive = State.field.isActive;
    const usePlot = !!_scale;
    for (let i = 0; i < steps; i++) {
      const plotAngle =
        usePlot && precomputedAngle !== undefined && i === 0
          ? precomputedAngle
          : usePlot
            ? _dirPlot.angle(this.plotted)
            : _dirPlot;
      const angle = (fieldActive ? this.angle(true) : 0) - plotAngle;
      // Calculate new position — cossin() computes the index once for both cos and sin
      const _cs = cossin(angle);
      this.update(this.x + _step * _cs[0], this.y + _step * _cs[1]);
      this.plotted += _step / scaleFactor;
    }
  }

  // Static Methods

  /**
   * Gets the row index for a given y-coordinate.
   * @param {number} y - The y-coordinate.
   * @returns {number} - The row index.
   */
  static getRowIndex(y, d = 1) {
    const y_offset = y + getAffineMatrix().y - top_y;
    return Math.round(y_offset / resolution / d);
  }

  /**
   * Gets the column index for a given x-coordinate.
   * @param {number} x - The x-coordinate.
   * @returns {number} - The column index.
   */
  static getColIndex(x, d = 1) {
    const x_offset = x + getAffineMatrix().x - left_x;
    return Math.round(x_offset / resolution / d);
  }

  /**
   * Checks if a column and row index are within the flow field bounds.
   * @param {number} col - The column index.
   * @param {number} row - The row index.
   * @returns {boolean} - True if the indices are within bounds, false otherwise.
   */
  static isIn(col, row) {
    return col >= 0 && row >= 0 && col < num_columns && row < num_rows;
  }
}

// =============================================================================
// Section: VectorField
// =============================================================================

/**
 * Represents the state of the vector field.
 * @property {boolean} isActive - Indicates if the vector field is active.
 * @property {string|null} current - The name of the currently active vector field.
 */
State.field = {
  isActive: false,
  current: null,
  wiggle: 1,
};

// Internal variables for field configuration
let list = new Map();
let resolution, left_x, top_y, num_columns, num_rows;
const FIELD_ANGLE_MODES = new Set(["degrees", "radians"]);

/**
 * Initializes the field grid and sets up the vector field's structure based on the renderer's dimensions.
 */
function createField() {
  resolution = Cwidth * 0.01; // Determine the resolution of the field grid
  left_x = -0.5 * Cwidth; // Left boundary of the field
  top_y = -0.5 * Cheight; // Top boundary of the field
  num_columns = Math.round((2 * Cwidth) / resolution); // Number of columns in the grid
  num_rows = Math.round((2 * Cheight) / resolution); // Number of columns in the grid
  addStandard(); // Add default vector field
}

/**
 * Retrieves the field values for the current vector field.
 * @returns {Float32Array[]} The current vector field grid.
 */
function flow_field() {
  return list.get(State.field.current).field;
}

function normalizeFieldAngleMode(options = {}) {
  const config =
    typeof options === "string" ? { angleMode: options } : options || {};
  const angleMode = config.angleMode ?? "degrees";

  if (!FIELD_ANGLE_MODES.has(angleMode)) {
    throw new Error(
      `Invalid field angle mode "${angleMode}". Use "degrees" or "radians".`,
    );
  }

  return angleMode;
}

function normalizeFieldAngles(field, angleMode) {
  if (angleMode !== "radians") return field;

  for (let c = 0; c < field.length; c++) {
    for (let r = 0; r < field[c].length; r++) {
      field[c][r] = toDegreesSigned(field[c][r], true);
    }
  }

  return field;
}

function generateField(entry, t) {
  return normalizeFieldAngles(entry.gen(t, genField()), entry.angleMode);
}

/**
 * Regenerates the current vector field using its associated generator function.
 * @param {number} [t=0] - An optional time parameter that can affect field generation.
 */
export function refreshField(t = 0) {
  if (!State.field.isActive || !State.field.current) {
    throw new Error(
      "No field is currently active. Call brush.field('name') to activate one before refreshing.",
    );
  }
  const currentField = list.get(State.field.current);
  currentField.field = generateField(currentField, t);
}

/**
 * Generates an empty field array.
 * Reuses existing arrays to reduce memory allocation overhead.
 * @returns {Float32Array[]} Empty vector field grid.
 */
function genField() {
  return new Array(num_columns)
    .fill(null)
    .map(() => new Float32Array(num_rows));
}

/**
 * Activates a specific vector field by name, ensuring it's ready for use.
 * @param {string} a - The name of the vector field to activate.
 */
export function field(a) {
  if (!State.field.wiggle) {
    State.field.wiggle = 1;
  } // Set default wiggle value
  isFieldReady();
  if (!list.has(a)) {
    throw new Error(
      `Field "${a}" does not exist. Available fields: ${Array.from(list.keys()).join(", ")}.`,
    );
  }
  State.field.isActive = true;
  State.field.current = a;
  const entry = list.get(a);
  if (!entry.field) entry.field = generateField(entry, 0);
}

/**
 * Deactivates the current vector field.
 */
export function noField() {
  isFieldReady();
  State.field.isActive = false;
}

/**
 * Adds a new vector field to the field list with a unique name and a generator function.
 * @param {string} name - The unique name for the new vector field.
 * @param {Function} funct - The function that generates the field values.
 * @param {object} [options] - Optional field configuration.
 * @param {"degrees"|"radians"} [options.angleMode="degrees"] - How the generator's output angles should be interpreted.
 */
export function addField(name, funct, options = {}) {
  list.set(name, {
    gen: funct,
    field: null,
    angleMode: normalizeFieldAngleMode(options),
  });
}

/**
 * Retrieves a list of all available vector field names.
 * @returns {string[]} An array of all the field names.
 */
export function listFields() {
  isFieldReady();
  return Array.from(list.keys());
}

export function wiggle(a = 1) {
  field("hand");
  State.field.wiggle = a;
}

/**
 * Fills every cell of a field grid using a callback (c, r) => angle.
 */
function fillField(field, fn) {
  for (let c = 0; c < num_columns; c++)
    for (let r = 0; r < num_rows; r++) field[c][r] = fn(c, r);
  return field;
}

/**
 * Adds standard predefined vector fields to the list with unique behaviors.
 */
function addStandard() {
  // Organic noise — basis for brush.wiggle()
  addField("hand", (t, field) => {
    const bs = rr2(0.2, 0.8),
      ba = randInt2(5, 10);
    return fillField(field, (c, r) => {
      const angle = 0.5 * ba * sin(bs * r * c + randInt2(15, 25));
      return 0.2 * angle * cos(t) + noise2(c, r) * ba * 0.7;
    });
  });
  // Smooth large-scale noise curves
  addField("curved", (t, field) => {
    let ar = randInt2(-10, 10);
    if (randInt2(0, 100) % 2 == 0) ar *= -1;
    return fillField(
      field,
      (c, r) =>
        3 *
        map(noise2(c * 0.02 + t * 0.03, r * 0.02 + t * 0.03), 0, 1, -ar, ar),
    );
  });
  // Sharp alternating angles per cell — herringbone / wicker look
  addField("zigzag", (t, field) => {
    let ar = randInt2(-30, -15) + Math.abs(44 * sin(t));
    if (randInt2(0, 100) % 2 == 0) ar *= -1;
    let dif = ar,
      angle = 0;
    for (let c = 0; c < num_columns; c++) {
      for (let r = 0; r < num_rows; r++) {
        field[c][r] = angle;
        angle += dif;
        dif *= -1;
      }
      angle += dif;
      dif *= -1;
    }
    return field;
  });
  // Sinusoidal wave bands
  addField("waves", (t, field) => {
    const sr = randInt2(10, 15) + 5 * sin(t),
      cr = randInt2(3, 6) + 3 * cos(t),
      ba = randInt2(20, 35);
    return fillField(
      field,
      (c, r) => sin(sr * c) * ba * cos(r * cr) + randInt2(-3, 3),
    );
  });
  // Dense oscillation from row×col product
  addField("seabed", (t, field) => {
    const bs = rr2(0.4, 0.8),
      ba = randInt2(18, 26);
    return fillField(
      field,
      (c, r) => 1.1 * ba * sin(bs * r * c + randInt2(15, 20)) * cos(t),
    );
  });
  // Radial vortex — angles spiral around the field centre
  addField("spiral", (_t, field) => {
    const n = randInt2(5, 10);
    const dir = randInt2(0, 2) * 2 - 1;
    const offset = randInt2(65, 80); // <90 = inward spiral
    const attractors = Array.from({ length: n }, () => ({
      x: rr2(0.1, 0.9) * num_columns,
      y: rr2(0.1, 0.9) * num_rows,
    }));
    return fillField(field, (c, r) => {
      let wx = 0,
        wy = 0;
      for (const att of attractors) {
        const dx = c - att.x,
          dy = r - att.y;
        const w = 1 / (dx * dx + dy * dy + 1);
        const a = Math.atan2(dy, dx) * (180 / Math.PI);
        const angle = (dir * (a + offset) * Math.PI) / 180;
        wx += w * Math.cos(angle);
        wy += w * Math.sin(angle);
      }
      return Math.atan2(wy, wx) * (180 / Math.PI);
    });
  });
  // Column-banded stripes — parallel rake marks
  addField("columns", (_t, field) => {
    const freq = randInt2(3, 8),
      amp = randInt2(25, 45);
    return fillField(field, (c, _r) => sin(c * freq) * amp);
  });
}