@ewanc26/noise 0.1.0 → 0.1.2

package/README.md

@@ -1,124 +1,13 @@
 # @ewanc26/noise
 
-Generic deterministic value-noise generation from a string seed. Arbitrary dimensions, multi-octave FBM, multiple colour modes. Zero runtime dependencies, works in any environment with a `Uint8ClampedArray` (browsers, Node.js, workers).
-
-Part of the [`@ewanc26/pkgs`](https://github.com/ewanc26/pkgs) monorepo.
-
-## Install
+Deterministic value-noise generation from a string seed — arbitrary dimensions, multi-octave FBM, multiple colour modes. Zero dependencies.
 
 ```bash
 pnpm add @ewanc26/noise
 ```
 
-## Usage
-
-### Raw pixels (no DOM required)
-
-```ts
-import { generateNoisePixels } from '@ewanc26/noise';
-
-const pixels = generateNoisePixels(256, 256, 'my-seed', {
-  octaves: 4,
-  colorMode: { type: 'grayscale' },
-});
-// pixels is a Uint8ClampedArray of RGBA values
-```
-
-### Canvas
-
-```ts
-import { renderNoise } from '@ewanc26/noise';
-
-const canvas = document.querySelector('canvas');
-renderNoise(canvas, 'my-seed', { size: 128, octaves: 3 });
-```
-
-### Svelte action
-
-```svelte
-<script>
-  import { noiseAction } from '@ewanc26/noise';
-
-  let seed = 'my-seed';
-</script>
-
-<canvas use:noiseAction={{ seed, size: 128, octaves: 3 }}></canvas>
-```
-
-## API
-
-### `generateNoisePixels(width, height, seed, options?)`
-
-Generates raw RGBA pixel data — no canvas or DOM needed.
-
-Returns a `Uint8ClampedArray` of length `width * height * 4`.
-
-### `renderNoise(canvas, seed, options?)`
-
-Renders noise onto an existing `HTMLCanvasElement` (resizes it to `width`/`height`/`size`).
-
-### `noiseAction(canvas, params)`
-
-Svelte action wrapper around `renderNoise`. Re-renders reactively when `params` changes via `update`.
-
-Params object: `{ seed, ...NoiseOptions, width?, height?, size? }`
-
----
-
-### Noise options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `gridSize` | `number` | `5` | Noise grid resolution |
-| `octaves` | `number` | `1` | FBM octave count (1 = plain value noise) |
-| `persistence` | `number` | `0.5` | FBM amplitude falloff per octave |
-| `lacunarity` | `number` | `2` | FBM frequency multiplier per octave |
-| `colorMode` | `ColorMode` | `{ type: 'hsl' }` | How noise values map to colours |
-
-### Render options (canvas/action only)
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `width` | `number` | `64` | Canvas width in pixels |
-| `height` | `number` | `64` | Canvas height in pixels |
-| `size` | `number` | — | Shorthand to set width and height equally |
-
-### Colour modes
-
-**`{ type: 'hsl' }`** — hue derived from seed, noise shifts hue/saturation/lightness.
-
-| Option | Type | Default |
-|---|---|---|
-| `hueRange` | `number` | `60` |
-| `saturationRange` | `[number, number]` | `[45, 70]` |
-| `lightnessRange` | `[number, number]` | `[40, 70]` |
-
-**`{ type: 'grayscale' }`** — noise value maps to luminance.
-
-| Option | Type | Default |
-|---|---|---|
-| `range` | `[number, number]` | `[0, 255]` |
-
-**`{ type: 'palette', colors }`** — noise value interpolates through an ordered list of RGB colours.
-
-```ts
-colorMode: {
-  type: 'palette',
-  colors: [[0, 0, 128], [0, 200, 255], [255, 255, 255]],
-}
-```
-
----
-
-### Core primitives
-
-| Export | Description |
-|---|---|
-| `hash32(str)` | djb2 hash → unsigned 32-bit integer |
-| `makePrng(seed)` | Seeded LCG PRNG → `() => float in [0, 1)` |
-| `hslToRgb(h, s, l)` | HSL (components in `[0, 1]`) → RGB triple (`[0, 255]`) |
-| `makeValueNoiseSampler(gridSize, rng)` | Returns `(nx, ny) → float in [0, 1]` value-noise sampler |
+Full documentation at **[docs.ewancroft.uk](https://docs.ewancroft.uk/projects/noise)**.
 
 ## Licence
 
-AGPL-3.0-only
+AGPL-3.0-only.

package/dist/index.cjs

@@ -0,0 +1,172 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  generateNoisePixels: () => generateNoisePixels,
+  hash32: () => hash32,
+  hslToRgb: () => hslToRgb,
+  makePrng: () => makePrng,
+  makeValueNoiseSampler: () => makeValueNoiseSampler,
+  noiseAction: () => noiseAction,
+  renderNoise: () => renderNoise
+});
+module.exports = __toCommonJS(index_exports);
+function hash32(str) {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) h = Math.imul(33, h) ^ str.charCodeAt(i);
+  return h >>> 0;
+}
+function makePrng(seed) {
+  let s = seed >>> 0;
+  return () => {
+    s = Math.imul(1664525, s) + 1013904223 >>> 0;
+    return s / 4294967296;
+  };
+}
+function hslToRgb(h, s, l) {
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => {
+    const k = (n + h * 12) % 12;
+    return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)];
+}
+function applyColorMode(noiseValue, mode, baseHue) {
+  switch (mode.type) {
+    case "hsl": {
+      const hueRange = mode.hueRange ?? 60;
+      const [sMin, sMax] = mode.saturationRange ?? [45, 70];
+      const [lMin, lMax] = mode.lightnessRange ?? [40, 70];
+      const hue = (baseHue + noiseValue * hueRange) % 360;
+      const sat = sMin + noiseValue * (sMax - sMin);
+      const light = lMin + noiseValue * (lMax - lMin);
+      return hslToRgb(hue / 360, sat / 100, light / 100);
+    }
+    case "grayscale": {
+      const [lo, hi] = mode.range ?? [0, 255];
+      const v = Math.round(lo + noiseValue * (hi - lo));
+      return [v, v, v];
+    }
+    case "palette": {
+      const colors = mode.colors;
+      if (colors.length === 0) return [0, 0, 0];
+      if (colors.length === 1) return colors[0];
+      const scaled = noiseValue * (colors.length - 1);
+      const lo = Math.floor(scaled);
+      const hi = Math.min(lo + 1, colors.length - 1);
+      const t = scaled - lo;
+      const [r1, g1, b1] = colors[lo];
+      const [r2, g2, b2] = colors[hi];
+      return [
+        Math.round(r1 + t * (r2 - r1)),
+        Math.round(g1 + t * (g2 - g1)),
+        Math.round(b1 + t * (b2 - b1))
+      ];
+    }
+  }
+}
+function smoothstep(t) {
+  return t * t * (3 - 2 * t);
+}
+function makeValueNoiseSampler(gridSize, rng) {
+  const G = gridSize + 1;
+  const grid = Array.from({ length: G * G }, () => rng());
+  const at = (gx, gy) => grid[gy * G + gx];
+  return (nx, ny) => {
+    const fx = nx * gridSize;
+    const fy = ny * gridSize;
+    const gx = Math.floor(fx);
+    const gy = Math.floor(fy);
+    const tx = smoothstep(fx - gx);
+    const ty = smoothstep(fy - gy);
+    return (1 - ty) * ((1 - tx) * at(gx, gy) + tx * at(gx + 1, gy)) + ty * ((1 - tx) * at(gx, gy + 1) + tx * at(gx + 1, gy + 1));
+  };
+}
+function generateNoisePixels(width, height, seed, options = {}) {
+  const {
+    gridSize = 5,
+    octaves = 1,
+    persistence = 0.5,
+    lacunarity = 2,
+    colorMode = { type: "hsl" }
+  } = options;
+  const seedNum = hash32(seed);
+  const baseHue = seedNum % 360;
+  const samplers = Array.from({ length: octaves }, (_, i) => {
+    const rng = makePrng(hash32(`${seed}|oct${i}`));
+    return makeValueNoiseSampler(gridSize * Math.pow(lacunarity, i), rng);
+  });
+  const pixels = new Uint8ClampedArray(width * height * 4);
+  for (let py = 0; py < height; py++) {
+    for (let px = 0; px < width; px++) {
+      const nx = px / width;
+      const ny = py / height;
+      let value = 0;
+      let amplitude = 1;
+      let maxAmplitude = 0;
+      for (let o = 0; o < octaves; o++) {
+        value += samplers[o](nx, ny) * amplitude;
+        maxAmplitude += amplitude;
+        amplitude *= persistence;
+      }
+      value /= maxAmplitude;
+      const [r, g, b] = applyColorMode(value, colorMode, baseHue);
+      const idx = (py * width + px) * 4;
+      pixels[idx] = r;
+      pixels[idx + 1] = g;
+      pixels[idx + 2] = b;
+      pixels[idx + 3] = 255;
+    }
+  }
+  return pixels;
+}
+function renderNoise(canvas, seed, options = {}) {
+  const { size, width: wOpt, height: hOpt, ...noiseOpts } = options;
+  const width = wOpt ?? size ?? 64;
+  const height = hOpt ?? size ?? 64;
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return;
+  const pixels = generateNoisePixels(width, height, seed, noiseOpts);
+  const imageData = new ImageData(new Uint8ClampedArray(pixels), width, height);
+  ctx.putImageData(imageData, 0, 0);
+}
+function noiseAction(canvas, params) {
+  const { seed, ...opts } = params;
+  renderNoise(canvas, seed, opts);
+  return {
+    update(newParams) {
+      const { seed: newSeed, ...newOpts } = newParams;
+      renderNoise(canvas, newSeed, newOpts);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateNoisePixels,
+  hash32,
+  hslToRgb,
+  makePrng,
+  makeValueNoiseSampler,
+  noiseAction,
+  renderNoise
+});

package/dist/index.d.cts

@@ -0,0 +1,147 @@
+/**
+ * @ewanc26/noise
+ *
+ * Generic deterministic value-noise generation.
+ *
+ * Produces consistent noise from an arbitrary string seed — same seed always
+ * gives the same output. Supports arbitrary dimensions, multi-octave FBM, and
+ * several colour modes. Zero runtime dependencies; works anywhere with a
+ * Uint8ClampedArray (Node.js, browsers, workers).
+ *
+ * Canvas and Svelte action helpers are also exported for convenience.
+ */
+/**
+ * djb2 hash — returns an unsigned 32-bit integer for any string.
+ */
+declare function hash32(str: string): number;
+/**
+ * Seeded LCG pseudo-random number generator.
+ * Returns a function that produces floats in [0, 1).
+ */
+declare function makePrng(seed: number): () => number;
+/**
+ * Convert HSL (each component in [0, 1]) to an RGB triple ([0, 255] each).
+ */
+declare function hslToRgb(h: number, s: number, l: number): [number, number, number];
+/**
+ * HSL colour mode — hue derived from seed, noise value shifts hue/sat/light.
+ */
+interface HslColorMode {
+    type: 'hsl';
+    /** Hue spread in degrees around the seed-derived base hue. @default 60 */
+    hueRange?: number;
+    /** Saturation [min, max] as percentages. @default [45, 70] */
+    saturationRange?: [number, number];
+    /** Lightness [min, max] as percentages. @default [40, 70] */
+    lightnessRange?: [number, number];
+}
+/**
+ * Grayscale colour mode — noise value maps to a luminance range.
+ */
+interface GrayscaleColorMode {
+    type: 'grayscale';
+    /** Luminance [min, max] in [0, 255]. @default [0, 255] */
+    range?: [number, number];
+}
+/**
+ * Palette colour mode — noise value indexes into a list of RGB colours
+ * using smooth interpolation between adjacent entries.
+ */
+interface PaletteColorMode {
+    type: 'palette';
+    /** At least two RGB triples, e.g. [[255,0,128],[0,200,255]]. */
+    colors: [number, number, number][];
+}
+type ColorMode = HslColorMode | GrayscaleColorMode | PaletteColorMode;
+/**
+ * Build a value-noise grid and return a sampler for normalised coordinates.
+ *
+ * @param gridSize  Number of grid cells along each axis.
+ * @param rng       Seeded PRNG from `makePrng`.
+ * @returns         A function `(nx, ny) → float in [0, 1]` where nx, ny ∈ [0, 1].
+ */
+declare function makeValueNoiseSampler(gridSize: number, rng: () => number): (nx: number, ny: number) => number;
+interface NoiseOptions {
+    /**
+     * Side length of the noise grid (higher = finer detail).
+     * @default 5
+     */
+    gridSize?: number;
+    /**
+     * Number of FBM octaves. 1 = plain value noise. More octaves add
+     * finer detail at the cost of a little extra work.
+     * @default 1
+     */
+    octaves?: number;
+    /**
+     * FBM persistence — how much each successive octave contributes.
+     * @default 0.5
+     */
+    persistence?: number;
+    /**
+     * FBM lacunarity — how much each successive octave's frequency increases.
+     * @default 2
+     */
+    lacunarity?: number;
+    /**
+     * How noise values map to colours.
+     * @default { type: 'hsl' }
+     */
+    colorMode?: ColorMode;
+}
+/**
+ * Generate raw RGBA pixel data for a noise texture.
+ *
+ * Works in any environment that has `Uint8ClampedArray` (all modern runtimes).
+ * No canvas or DOM required.
+ *
+ * @param width   Output width in pixels.
+ * @param height  Output height in pixels.
+ * @param seed    Arbitrary string — same seed always produces the same image.
+ * @param options Noise and colour options.
+ * @returns       A `Uint8ClampedArray` of length `width * height * 4` (RGBA).
+ */
+declare function generateNoisePixels(width: number, height: number, seed: string, options?: NoiseOptions): Uint8ClampedArray;
+interface RenderNoiseOptions extends NoiseOptions {
+    /**
+     * Rendered canvas width in pixels. Defaults to `size` if set, else 64.
+     */
+    width?: number;
+    /**
+     * Rendered canvas height in pixels. Defaults to `size` if set, else 64.
+     */
+    height?: number;
+    /**
+     * Shorthand to set both width and height to the same value.
+     */
+    size?: number;
+}
+/**
+ * Render a deterministic noise texture onto an existing `HTMLCanvasElement`.
+ *
+ * @param canvas  Target canvas (will be resized).
+ * @param seed    Arbitrary string — same seed always produces the same image.
+ * @param options Render and noise options.
+ */
+declare function renderNoise(canvas: HTMLCanvasElement, seed: string, options?: RenderNoiseOptions): void;
+interface NoiseActionParams extends RenderNoiseOptions {
+    seed: string;
+}
+/**
+ * Svelte action that renders noise onto a canvas and re-renders reactively
+ * when params change.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { noiseAction } from '@ewanc26/noise';
+ * </script>
+ *
+ * <canvas use:noiseAction={{ seed: 'my-seed', size: 128, octaves: 3 }}></canvas>
+ * ```
+ */
+declare function noiseAction(canvas: HTMLCanvasElement, params: NoiseActionParams): {
+    update(newParams: NoiseActionParams): void;
+};
+
+export { type ColorMode, type GrayscaleColorMode, type HslColorMode, type NoiseActionParams, type NoiseOptions, type PaletteColorMode, type RenderNoiseOptions, generateNoisePixels, hash32, hslToRgb, makePrng, makeValueNoiseSampler, noiseAction, renderNoise };

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @ewanc26/noise
+ *
+ * Generic deterministic value-noise generation.
+ *
+ * Produces consistent noise from an arbitrary string seed — same seed always
+ * gives the same output. Supports arbitrary dimensions, multi-octave FBM, and
+ * several colour modes. Zero runtime dependencies; works anywhere with a
+ * Uint8ClampedArray (Node.js, browsers, workers).
+ *
+ * Canvas and Svelte action helpers are also exported for convenience.
+ */
+/**
+ * djb2 hash — returns an unsigned 32-bit integer for any string.
+ */
+declare function hash32(str: string): number;
+/**
+ * Seeded LCG pseudo-random number generator.
+ * Returns a function that produces floats in [0, 1).
+ */
+declare function makePrng(seed: number): () => number;
+/**
+ * Convert HSL (each component in [0, 1]) to an RGB triple ([0, 255] each).
+ */
+declare function hslToRgb(h: number, s: number, l: number): [number, number, number];
+/**
+ * HSL colour mode — hue derived from seed, noise value shifts hue/sat/light.
+ */
+interface HslColorMode {
+    type: 'hsl';
+    /** Hue spread in degrees around the seed-derived base hue. @default 60 */
+    hueRange?: number;
+    /** Saturation [min, max] as percentages. @default [45, 70] */
+    saturationRange?: [number, number];
+    /** Lightness [min, max] as percentages. @default [40, 70] */
+    lightnessRange?: [number, number];
+}
+/**
+ * Grayscale colour mode — noise value maps to a luminance range.
+ */
+interface GrayscaleColorMode {
+    type: 'grayscale';
+    /** Luminance [min, max] in [0, 255]. @default [0, 255] */
+    range?: [number, number];
+}
+/**
+ * Palette colour mode — noise value indexes into a list of RGB colours
+ * using smooth interpolation between adjacent entries.
+ */
+interface PaletteColorMode {
+    type: 'palette';
+    /** At least two RGB triples, e.g. [[255,0,128],[0,200,255]]. */
+    colors: [number, number, number][];
+}
+type ColorMode = HslColorMode | GrayscaleColorMode | PaletteColorMode;
+/**
+ * Build a value-noise grid and return a sampler for normalised coordinates.
+ *
+ * @param gridSize  Number of grid cells along each axis.
+ * @param rng       Seeded PRNG from `makePrng`.
+ * @returns         A function `(nx, ny) → float in [0, 1]` where nx, ny ∈ [0, 1].
+ */
+declare function makeValueNoiseSampler(gridSize: number, rng: () => number): (nx: number, ny: number) => number;
+interface NoiseOptions {
+    /**
+     * Side length of the noise grid (higher = finer detail).
+     * @default 5
+     */
+    gridSize?: number;
+    /**
+     * Number of FBM octaves. 1 = plain value noise. More octaves add
+     * finer detail at the cost of a little extra work.
+     * @default 1
+     */
+    octaves?: number;
+    /**
+     * FBM persistence — how much each successive octave contributes.
+     * @default 0.5
+     */
+    persistence?: number;
+    /**
+     * FBM lacunarity — how much each successive octave's frequency increases.
+     * @default 2
+     */
+    lacunarity?: number;
+    /**
+     * How noise values map to colours.
+     * @default { type: 'hsl' }
+     */
+    colorMode?: ColorMode;
+}
+/**
+ * Generate raw RGBA pixel data for a noise texture.
+ *
+ * Works in any environment that has `Uint8ClampedArray` (all modern runtimes).
+ * No canvas or DOM required.
+ *
+ * @param width   Output width in pixels.
+ * @param height  Output height in pixels.
+ * @param seed    Arbitrary string — same seed always produces the same image.
+ * @param options Noise and colour options.
+ * @returns       A `Uint8ClampedArray` of length `width * height * 4` (RGBA).
+ */
+declare function generateNoisePixels(width: number, height: number, seed: string, options?: NoiseOptions): Uint8ClampedArray;
+interface RenderNoiseOptions extends NoiseOptions {
+    /**
+     * Rendered canvas width in pixels. Defaults to `size` if set, else 64.
+     */
+    width?: number;
+    /**
+     * Rendered canvas height in pixels. Defaults to `size` if set, else 64.
+     */
+    height?: number;
+    /**
+     * Shorthand to set both width and height to the same value.
+     */
+    size?: number;
+}
+/**
+ * Render a deterministic noise texture onto an existing `HTMLCanvasElement`.
+ *
+ * @param canvas  Target canvas (will be resized).
+ * @param seed    Arbitrary string — same seed always produces the same image.
+ * @param options Render and noise options.
+ */
+declare function renderNoise(canvas: HTMLCanvasElement, seed: string, options?: RenderNoiseOptions): void;
+interface NoiseActionParams extends RenderNoiseOptions {
+    seed: string;
+}
+/**
+ * Svelte action that renders noise onto a canvas and re-renders reactively
+ * when params change.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { noiseAction } from '@ewanc26/noise';
+ * </script>
+ *
+ * <canvas use:noiseAction={{ seed: 'my-seed', size: 128, octaves: 3 }}></canvas>
+ * ```
+ */
+declare function noiseAction(canvas: HTMLCanvasElement, params: NoiseActionParams): {
+    update(newParams: NoiseActionParams): void;
+};
+
+export { type ColorMode, type GrayscaleColorMode, type HslColorMode, type NoiseActionParams, type NoiseOptions, type PaletteColorMode, type RenderNoiseOptions, generateNoisePixels, hash32, hslToRgb, makePrng, makeValueNoiseSampler, noiseAction, renderNoise };