@pixerate/editor 0.276.0 → 0.278.0

package/dist/paint-editor/ferro.d.cts

@@ -0,0 +1,134 @@
+/**
+ * Ferrofluid paint: a per-layer liquid ferrofluid channel (`doc.ferro`, one byte 0..255 per pixel
+ * in layer space, like `doc.light`) and document-space magnets (`doc.magnets`).
+ *
+ * Where the analytical dipole magnetic field `|B|` exceeds the critical threshold `Bc` and
+ * `ferro > 0`, the liquid rises into a hexagonal Rosensweig spike relief field whose spacing
+ * follows the capillary wavelength, whose amplitude scales as `sqrt(1 - Bc / |B|) * ferro`, and
+ * whose peaks tilt along `B`. Adding or moving a magnet runs deterministic advection steps on
+ * `doc.ferro` so the liquid gathers toward the magnets.
+ *
+ * At render time, the spike height combines with `doc.thick` height and defaults to a dark,
+ * glossy metallic material where `ferro > 0`, so `lightTile` shades the spikes with the canvas
+ * lighting. `cure_ferrofluid` bakes the current spikes into `doc.thick` and clears `doc.ferro`.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.cjs';
+import { DEFAULT_FERRO, normalizeFerro as normalizeFerroSettings, type FerroSettings, type PaintBrush } from './brushes.cjs';
+import { type ThickChannels } from './thick.cjs';
+export { DEFAULT_FERRO, normalizeFerroSettings, type FerroSettings };
+/** A dipole magnet on the canvas (document pixel coordinates). */
+export interface PaintMagnet {
+    id: string;
+    x: number;
+    y: number;
+    /** Dipole strength and polarity (-1 .. 1). */
+    strength: number;
+    /** Characteristic dipole falloff radius in canvas pixels (8 .. 2000). */
+    radius: number;
+}
+export declare const DEFAULT_MAGNET_STRENGTH = 0.75;
+export declare const DEFAULT_MAGNET_RADIUS = 72;
+/** Dark carrier fluid sRGB colour (`#111827`) for advected ferrofluid outside existing pigment. */
+export declare const FERRO_CARRIER_RGB: readonly [number, number, number];
+/** Default glossy metallic material for ferrofluid (`gloss ≈ 0.88`, `metallic ≈ 0.65`, `rim ≈ 0.25`). */
+export declare const FERRO_DEFAULT_GLOSS = 224;
+export declare const FERRO_DEFAULT_METALLIC = 166;
+export declare const FERRO_DEFAULT_RIM = 64;
+/** Validates and normalizes a magnet; throws a descriptive Error when a field is out of range. */
+export declare function normalizeMagnet(raw: Partial<PaintMagnet> & {
+    id: string;
+    x: number;
+    y: number;
+}, base?: PaintMagnet): PaintMagnet;
+export declare function emptyFerro(): TiledSurface;
+/** The ferrofluid channel as grey paint for a stroke's twin: white, with alpha = ferro. */
+export declare function ferroToShadow(ferro: TiledSurface): TiledSurface;
+/** A twin's grey paint back as ferrofluid: grey × alpha. */
+export declare function shadowToFerro(shadow: TiledSurface): TiledSurface;
+/** The brush a stroke's ferrofluid twin paints with: same geometry, normal blend, RGB mixing. */
+export declare function ferroTwinBrush(brush: PaintBrush): PaintBrush;
+/** Ferrofluid scaled by `k` (0..1), e.g. under a fill that covers it. */
+export declare function scaleFerro(ferro: TiledSurface, k: number): TiledSurface;
+/** Ferrofluid of an upper layer merged down onto the one below (both in lower layer's space). */
+export declare function mergeFerro(lower: TiledSurface | undefined, upper: TiledSurface | undefined, upperColor: TiledSurface): TiledSurface | undefined;
+export interface FerroFieldSample {
+    bx: number;
+    by: number;
+    bz: number;
+    magnitude: number;
+}
+/**
+ * Analytical 3D magnetic dipole field `B = (bx, by, bz)` at canvas point `(x, y)` from a set of
+ * dipole magnets placed on the canvas plane (`z = -radius`).
+ */
+export declare function ferroFieldAt(x: number, y: number, magnets: readonly PaintMagnet[]): FerroFieldSample;
+/**
+ * Hexagonal Rosensweig instability spike height (0..255) at canvas coordinate `(x, y)` for a pixel
+ * with liquid ferrofluid byte `ferroByte` (0..255).
+ *
+ * Where `|B| > threshold` and `ferroByte > 0`, spikes rise with amplitude `∝ sqrt(1 - Bc / |B|) * ferro`
+ * at the capillary `wavelength` and tilt along the tangential field `(bx, by)`.
+ */
+export declare function ferroSpikeHeightAt(x: number, y: number, ferroByte: number, magnets: readonly PaintMagnet[], settings?: FerroSettings): number;
+/**
+ * Runs deterministic mass-gathering advection steps on a layer's `ferro` surface toward `magnets`.
+ * Each step transports liquid ferrofluid along the dipole attraction field via bilinear splatting.
+ */
+export declare function advectFerro(ferro: TiledSurface, magnets: readonly PaintMagnet[], offset?: {
+    x: number;
+    y: number;
+}, steps?: number): TiledSurface;
+export interface FerroStats {
+    bounds: RasterRect | null;
+    peak: number;
+    liquidPixels: number;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    magnetCount: number;
+}
+/**
+ * Inspects a layer's liquid ferrofluid channel and active Rosensweig spike relief under `magnets`.
+ */
+export declare function ferroInfo(ferro: TiledSurface | undefined, magnets?: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): FerroStats;
+export interface FerroLayerInput {
+    surface: TiledSurface;
+    magnets: readonly PaintMagnet[];
+    settings: FerroSettings;
+    offset: {
+        x: number;
+        y: number;
+    };
+}
+export declare function ferroCacheKey(ferro: FerroLayerInput | null | undefined): string;
+/**
+ * Bakes a layer's liquid ferrofluid and active Rosensweig spikes into permanent `ThickChannels`
+ * (and ensures carrier colour covers advected ferrofluid pixels) for `cure_ferrofluid`.
+ */
+export declare function bakeFerroIntoThick(color: TiledSurface, ferro: TiledSurface, thick: ThickChannels | undefined, magnets: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): {
+    color: TiledSurface;
+    thick: ThickChannels;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    curedPixels: number;
+};
+/** A layer's liquid ferrofluid as saved: its rect (layer space), grey PNG, and spike settings. */
+export interface SavedFerro {
+    rect: RasterRect;
+    ferro: string;
+    wavelength?: number;
+    threshold?: number;
+}
+export declare function ferroToJSON(ferro: TiledSurface, settings?: FerroSettings): SavedFerro | null;
+/** Saved form → ferrofluid surface and settings; throws a sentence when it cannot be read. */
+export declare function ferroFromJSON(raw: unknown): {
+    surface: TiledSurface;
+    settings: FerroSettings;
+};
+/** Saved magnets array → validated `PaintMagnet[]`. */
+export declare function magnetsFromJSON(raw: unknown): PaintMagnet[];

package/dist/paint-editor/ferro.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Ferrofluid paint: a per-layer liquid ferrofluid channel (`doc.ferro`, one byte 0..255 per pixel
+ * in layer space, like `doc.light`) and document-space magnets (`doc.magnets`).
+ *
+ * Where the analytical dipole magnetic field `|B|` exceeds the critical threshold `Bc` and
+ * `ferro > 0`, the liquid rises into a hexagonal Rosensweig spike relief field whose spacing
+ * follows the capillary wavelength, whose amplitude scales as `sqrt(1 - Bc / |B|) * ferro`, and
+ * whose peaks tilt along `B`. Adding or moving a magnet runs deterministic advection steps on
+ * `doc.ferro` so the liquid gathers toward the magnets.
+ *
+ * At render time, the spike height combines with `doc.thick` height and defaults to a dark,
+ * glossy metallic material where `ferro > 0`, so `lightTile` shades the spikes with the canvas
+ * lighting. `cure_ferrofluid` bakes the current spikes into `doc.thick` and clears `doc.ferro`.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.js';
+import { DEFAULT_FERRO, normalizeFerro as normalizeFerroSettings, type FerroSettings, type PaintBrush } from './brushes.js';
+import { type ThickChannels } from './thick.js';
+export { DEFAULT_FERRO, normalizeFerroSettings, type FerroSettings };
+/** A dipole magnet on the canvas (document pixel coordinates). */
+export interface PaintMagnet {
+    id: string;
+    x: number;
+    y: number;
+    /** Dipole strength and polarity (-1 .. 1). */
+    strength: number;
+    /** Characteristic dipole falloff radius in canvas pixels (8 .. 2000). */
+    radius: number;
+}
+export declare const DEFAULT_MAGNET_STRENGTH = 0.75;
+export declare const DEFAULT_MAGNET_RADIUS = 72;
+/** Dark carrier fluid sRGB colour (`#111827`) for advected ferrofluid outside existing pigment. */
+export declare const FERRO_CARRIER_RGB: readonly [number, number, number];
+/** Default glossy metallic material for ferrofluid (`gloss ≈ 0.88`, `metallic ≈ 0.65`, `rim ≈ 0.25`). */
+export declare const FERRO_DEFAULT_GLOSS = 224;
+export declare const FERRO_DEFAULT_METALLIC = 166;
+export declare const FERRO_DEFAULT_RIM = 64;
+/** Validates and normalizes a magnet; throws a descriptive Error when a field is out of range. */
+export declare function normalizeMagnet(raw: Partial<PaintMagnet> & {
+    id: string;
+    x: number;
+    y: number;
+}, base?: PaintMagnet): PaintMagnet;
+export declare function emptyFerro(): TiledSurface;
+/** The ferrofluid channel as grey paint for a stroke's twin: white, with alpha = ferro. */
+export declare function ferroToShadow(ferro: TiledSurface): TiledSurface;
+/** A twin's grey paint back as ferrofluid: grey × alpha. */
+export declare function shadowToFerro(shadow: TiledSurface): TiledSurface;
+/** The brush a stroke's ferrofluid twin paints with: same geometry, normal blend, RGB mixing. */
+export declare function ferroTwinBrush(brush: PaintBrush): PaintBrush;
+/** Ferrofluid scaled by `k` (0..1), e.g. under a fill that covers it. */
+export declare function scaleFerro(ferro: TiledSurface, k: number): TiledSurface;
+/** Ferrofluid of an upper layer merged down onto the one below (both in lower layer's space). */
+export declare function mergeFerro(lower: TiledSurface | undefined, upper: TiledSurface | undefined, upperColor: TiledSurface): TiledSurface | undefined;
+export interface FerroFieldSample {
+    bx: number;
+    by: number;
+    bz: number;
+    magnitude: number;
+}
+/**
+ * Analytical 3D magnetic dipole field `B = (bx, by, bz)` at canvas point `(x, y)` from a set of
+ * dipole magnets placed on the canvas plane (`z = -radius`).
+ */
+export declare function ferroFieldAt(x: number, y: number, magnets: readonly PaintMagnet[]): FerroFieldSample;
+/**
+ * Hexagonal Rosensweig instability spike height (0..255) at canvas coordinate `(x, y)` for a pixel
+ * with liquid ferrofluid byte `ferroByte` (0..255).
+ *
+ * Where `|B| > threshold` and `ferroByte > 0`, spikes rise with amplitude `∝ sqrt(1 - Bc / |B|) * ferro`
+ * at the capillary `wavelength` and tilt along the tangential field `(bx, by)`.
+ */
+export declare function ferroSpikeHeightAt(x: number, y: number, ferroByte: number, magnets: readonly PaintMagnet[], settings?: FerroSettings): number;
+/**
+ * Runs deterministic mass-gathering advection steps on a layer's `ferro` surface toward `magnets`.
+ * Each step transports liquid ferrofluid along the dipole attraction field via bilinear splatting.
+ */
+export declare function advectFerro(ferro: TiledSurface, magnets: readonly PaintMagnet[], offset?: {
+    x: number;
+    y: number;
+}, steps?: number): TiledSurface;
+export interface FerroStats {
+    bounds: RasterRect | null;
+    peak: number;
+    liquidPixels: number;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    magnetCount: number;
+}
+/**
+ * Inspects a layer's liquid ferrofluid channel and active Rosensweig spike relief under `magnets`.
+ */
+export declare function ferroInfo(ferro: TiledSurface | undefined, magnets?: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): FerroStats;
+export interface FerroLayerInput {
+    surface: TiledSurface;
+    magnets: readonly PaintMagnet[];
+    settings: FerroSettings;
+    offset: {
+        x: number;
+        y: number;
+    };
+}
+export declare function ferroCacheKey(ferro: FerroLayerInput | null | undefined): string;
+/**
+ * Bakes a layer's liquid ferrofluid and active Rosensweig spikes into permanent `ThickChannels`
+ * (and ensures carrier colour covers advected ferrofluid pixels) for `cure_ferrofluid`.
+ */
+export declare function bakeFerroIntoThick(color: TiledSurface, ferro: TiledSurface, thick: ThickChannels | undefined, magnets: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): {
+    color: TiledSurface;
+    thick: ThickChannels;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    curedPixels: number;
+};
+/** A layer's liquid ferrofluid as saved: its rect (layer space), grey PNG, and spike settings. */
+export interface SavedFerro {
+    rect: RasterRect;
+    ferro: string;
+    wavelength?: number;
+    threshold?: number;
+}
+export declare function ferroToJSON(ferro: TiledSurface, settings?: FerroSettings): SavedFerro | null;
+/** Saved form → ferrofluid surface and settings; throws a sentence when it cannot be read. */
+export declare function ferroFromJSON(raw: unknown): {
+    surface: TiledSurface;
+    settings: FerroSettings;
+};
+/** Saved magnets array → validated `PaintMagnet[]`. */
+export declare function magnetsFromJSON(raw: unknown): PaintMagnet[];