@pixerate/editor 0.274.0 → 0.275.0

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

@@ -0,0 +1,156 @@
+/**
+ * Smart inks: UV-fluorescent ink (`doc.fluor[layerId]` + `uvLight`) and thermochromic ink
+ * (`doc.thermo[layerId]` + `doc.heat`).
+ *
+ * - **Fluorescent ink**: a per-layer 4-channel RGBA surface (`[R, G, B, intensity]`) in layer
+ *   space, painted alongside strokes when `brush.fluorescence.amount > 0`. With
+ *   `brush.fluorescence.invisible: true`, no daylight pigment is laid onto the layer's normal
+ *   surface, so the mark stays invisible under normal light. When the virtual UV blacklight
+ *   (`uvLight.on`) is switched on, normal layers dim to `uvLight.ambient` and fluorescent pixels
+ *   emit their colour and cast a Linear Dodge spill halo (reusing `computeSpill` from `./light`).
+ * - **Thermochromic ink**: a per-layer 4-channel RGBA surface (`[hotR, hotG, hotB, thresholdByte]`)
+ *   in layer space, painted when `brush.thermochromic.hotColor` is set. A document-level coarse
+ *   heat field (`HEAT_SCALE = 4`, 1/4 canvas resolution) stores local temperature in `0..1`,
+ *   painted by `paintHeatField` and stepped with 5-point Laplacian diffusion + Newtonian cooling
+ *   by `advanceHeatField`. At render time, thermochromic pixels blend smoothly from their cold
+ *   paint colour to `hotColor` around `threshold` based on bilinearly sampled temperature, and
+ *   tiles heated past `HEAT_DRY_THRESHOLD` dry any wet paint on them.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.cjs';
+import { type PaintBrush } from './brushes.cjs';
+import { type PaperSettings } from './paper.cjs';
+/** View / document UV blacklight setting. */
+export interface UvLightSettings {
+    /** Whether the UV blacklight is switched on (default false). */
+    on: boolean;
+    /** Emission and halo strength under UV, 0..2 (default 1). */
+    strength: number;
+    /** How much normal daylight colour remains visible when UV is on, 0 (pitch dark) .. 1 (default 0.15). */
+    ambient: number;
+}
+export declare const DEFAULT_UV_LIGHT: Readonly<UvLightSettings>;
+export declare function normalizeUvLight(raw?: Partial<UvLightSettings>, base?: UvLightSettings): UvLightSettings;
+export declare function uvLightKey(uv: UvLightSettings): string;
+/** The paper dimmed to `uv.ambient` while the UV blacklight is on (cached by paper reference). */
+export declare function uvPaper(paper: PaperSettings, uv: UvLightSettings): PaperSettings;
+export declare function emptyFluor(): TiledSurface;
+export declare function emptyThermo(): TiledSurface;
+/**
+ * Twin brush that writes or moves the per-layer 4-channel fluorescence surface (`doc.fluor[id]`).
+ * When `brush.fluorescence.amount > 0`, it lays the stroke's colour scaled by `fluorescence.amount`;
+ * erasers, smudges and blenders act on the existing fluorescence; plain opaque paint dims it.
+ */
+export declare function fluorTwinBrush(brush: PaintBrush): PaintBrush;
+/**
+ * Twin brush that writes or moves the per-layer 4-channel thermochromic surface (`doc.thermo[id]`).
+ */
+export declare function thermoTwinBrush(brush: PaintBrush): PaintBrush;
+/**
+ * Encodes `threshold` (`0.05..0.95`) into channel 3 (`1..255`) of a thermochromic surface after a
+ * twin stroke painted `hotColor` with coverage in channel 3. Existing thermochromic pixels blend
+ * smoothly with the new `hotColor` and `threshold` by the twin's coverage.
+ */
+export declare function finalizeThermoStroke(twinOut: TiledSurface, before: TiledSurface, hotRgb: readonly [number, number, number], threshold: number): TiledSurface;
+/** Scales the alpha channel of a 4-channel RGBA surface (`fluor`) by `k` (0..1). */
+export declare function scaleFluor(surface: TiledSurface, k: number): TiledSurface;
+/** Merges two 4-channel surfaces (`above` over `below`) when merging layers down. */
+export declare function mergeFourChannel(below: TiledSurface | undefined, above: TiledSurface | undefined): TiledSurface | null;
+/** Computes the UV spill halo for a layer's `fluor` surface, reusing `computeSpill` from `./light`. */
+export declare function computeUvSpill(fluor: TiledSurface, strength: number): TiledSurface | null;
+/**
+ * Tile cache for UV blacklight rendering on one layer: dims daylight pixels to `uvLight.ambient`
+ * and adds fluorescent emission from `doc.fluor[id]` (even where daylight alpha is 0 for invisible ink).
+ */
+export declare class UvCache {
+    private readonly tiles;
+    private spillCache;
+    render(color: TiledSurface, fluor: TiledSurface | undefined, uv: UvLightSettings): TiledSurface;
+    spill(fluor: TiledSurface, uv: UvLightSettings): TiledSurface | null;
+}
+/** Coarse grid scale: 1 heat cell per 4×4 canvas pixels. */
+export declare const HEAT_SCALE = 4;
+/** Explicit 2D diffusion rate per step (≤ 0.25 for stability). */
+export declare const HEAT_DIFFUSION = 0.18;
+/** Newtonian cooling fraction per step. */
+export declare const HEAT_COOLING = 0.03;
+/** Temperature above which a heated cell dries wet paint. */
+export declare const HEAT_DRY_THRESHOLD = 0.5;
+export interface HeatField {
+    width: number;
+    height: number;
+    gridWidth: number;
+    gridHeight: number;
+    /** Row-major temperatures in 0..1 (`gridWidth * gridHeight`). */
+    cells: Float64Array;
+    max: number;
+    revision: number;
+}
+export interface HeatSample {
+    x: number;
+    y: number;
+    temperature: number;
+}
+export declare function createHeatField(width: number, height: number): HeatField;
+export declare function cloneHeatField(field: HeatField): HeatField;
+export interface HeatStats {
+    max: number;
+    mean: number;
+    hotCells: number;
+    bounds: RasterRect | null;
+}
+export declare function heatStats(field: HeatField | undefined): HeatStats;
+/** Bounding document-space rectangle of all coarse cells with temperature ≥ `threshold`, or `null`. */
+export declare function hotCellsBounds(field: HeatField, threshold?: number): RasterRect | null;
+/**
+ * Paints heat (or cools when `temperature` is below current cell heat) along `points` with `radius`
+ * in document pixels. Returns the affected document-space bounding box and updated field statistics.
+ */
+export declare function paintHeatField(field: HeatField, points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>, radius?: number, temperature?: number): {
+    bounds: RasterRect;
+    stats: HeatStats;
+};
+/**
+ * Advances the heat field by `steps` iterations of 5-point Laplacian diffusion and Newtonian cooling.
+ */
+export declare function advanceHeatField(field: HeatField, steps?: number): HeatStats;
+/** Clears the heat field to 0 everywhere. */
+export declare function clearHeatField(field: HeatField): boolean;
+/** Bilinearly samples temperature (0..1) at document coordinates `(x, y)`. */
+export declare function sampleHeatAt(field: HeatField, x: number, y: number): number;
+/** Shifts and resizes a heat field when `extendCanvas` shifts the document by `(dx, dy)`. */
+export declare function shiftHeatField(field: HeatField, dx: number, dy: number, newWidth: number, newHeight: number): HeatField;
+/**
+ * Tile cache for thermochromic colour shifting on one layer: blends cold pixels toward `hotColor`
+ * around `threshold` where the coarse heat field is warm.
+ */
+export declare class ThermoCache {
+    private readonly tiles;
+    render(color: TiledSurface, thermo: TiledSurface | undefined, offset: {
+        x: number;
+        y: number;
+    }, heat: HeatField): TiledSurface;
+}
+export interface SavedLayerFluor {
+    rect: RasterRect;
+    /** 4-channel RGBA PNG data URL of the layer's fluorescence. */
+    fluor: string;
+}
+export interface SavedLayerThermo {
+    rect: RasterRect;
+    /** 4-channel RGBA PNG data URL of the layer's thermochromic `[hotR, hotG, hotB, thresholdByte]`. */
+    thermo: string;
+}
+export interface SavedHeatField {
+    gridWidth: number;
+    gridHeight: number;
+    cells: number[];
+}
+export declare function fluorToJSON(fluor: TiledSurface | undefined): SavedLayerFluor | null;
+export declare function fluorFromJSON(raw: unknown): TiledSurface;
+export declare function thermoToJSON(thermo: TiledSurface | undefined): SavedLayerThermo | null;
+export declare function thermoFromJSON(raw: unknown): TiledSurface;
+export declare function heatToJSON(field: HeatField | undefined): SavedHeatField | null;
+export declare function heatFromJSON(raw: unknown, width: number, height: number): HeatField | null;

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

@@ -0,0 +1,156 @@
+/**
+ * Smart inks: UV-fluorescent ink (`doc.fluor[layerId]` + `uvLight`) and thermochromic ink
+ * (`doc.thermo[layerId]` + `doc.heat`).
+ *
+ * - **Fluorescent ink**: a per-layer 4-channel RGBA surface (`[R, G, B, intensity]`) in layer
+ *   space, painted alongside strokes when `brush.fluorescence.amount > 0`. With
+ *   `brush.fluorescence.invisible: true`, no daylight pigment is laid onto the layer's normal
+ *   surface, so the mark stays invisible under normal light. When the virtual UV blacklight
+ *   (`uvLight.on`) is switched on, normal layers dim to `uvLight.ambient` and fluorescent pixels
+ *   emit their colour and cast a Linear Dodge spill halo (reusing `computeSpill` from `./light`).
+ * - **Thermochromic ink**: a per-layer 4-channel RGBA surface (`[hotR, hotG, hotB, thresholdByte]`)
+ *   in layer space, painted when `brush.thermochromic.hotColor` is set. A document-level coarse
+ *   heat field (`HEAT_SCALE = 4`, 1/4 canvas resolution) stores local temperature in `0..1`,
+ *   painted by `paintHeatField` and stepped with 5-point Laplacian diffusion + Newtonian cooling
+ *   by `advanceHeatField`. At render time, thermochromic pixels blend smoothly from their cold
+ *   paint colour to `hotColor` around `threshold` based on bilinearly sampled temperature, and
+ *   tiles heated past `HEAT_DRY_THRESHOLD` dry any wet paint on them.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.js';
+import { type PaintBrush } from './brushes.js';
+import { type PaperSettings } from './paper.js';
+/** View / document UV blacklight setting. */
+export interface UvLightSettings {
+    /** Whether the UV blacklight is switched on (default false). */
+    on: boolean;
+    /** Emission and halo strength under UV, 0..2 (default 1). */
+    strength: number;
+    /** How much normal daylight colour remains visible when UV is on, 0 (pitch dark) .. 1 (default 0.15). */
+    ambient: number;
+}
+export declare const DEFAULT_UV_LIGHT: Readonly<UvLightSettings>;
+export declare function normalizeUvLight(raw?: Partial<UvLightSettings>, base?: UvLightSettings): UvLightSettings;
+export declare function uvLightKey(uv: UvLightSettings): string;
+/** The paper dimmed to `uv.ambient` while the UV blacklight is on (cached by paper reference). */
+export declare function uvPaper(paper: PaperSettings, uv: UvLightSettings): PaperSettings;
+export declare function emptyFluor(): TiledSurface;
+export declare function emptyThermo(): TiledSurface;
+/**
+ * Twin brush that writes or moves the per-layer 4-channel fluorescence surface (`doc.fluor[id]`).
+ * When `brush.fluorescence.amount > 0`, it lays the stroke's colour scaled by `fluorescence.amount`;
+ * erasers, smudges and blenders act on the existing fluorescence; plain opaque paint dims it.
+ */
+export declare function fluorTwinBrush(brush: PaintBrush): PaintBrush;
+/**
+ * Twin brush that writes or moves the per-layer 4-channel thermochromic surface (`doc.thermo[id]`).
+ */
+export declare function thermoTwinBrush(brush: PaintBrush): PaintBrush;
+/**
+ * Encodes `threshold` (`0.05..0.95`) into channel 3 (`1..255`) of a thermochromic surface after a
+ * twin stroke painted `hotColor` with coverage in channel 3. Existing thermochromic pixels blend
+ * smoothly with the new `hotColor` and `threshold` by the twin's coverage.
+ */
+export declare function finalizeThermoStroke(twinOut: TiledSurface, before: TiledSurface, hotRgb: readonly [number, number, number], threshold: number): TiledSurface;
+/** Scales the alpha channel of a 4-channel RGBA surface (`fluor`) by `k` (0..1). */
+export declare function scaleFluor(surface: TiledSurface, k: number): TiledSurface;
+/** Merges two 4-channel surfaces (`above` over `below`) when merging layers down. */
+export declare function mergeFourChannel(below: TiledSurface | undefined, above: TiledSurface | undefined): TiledSurface | null;
+/** Computes the UV spill halo for a layer's `fluor` surface, reusing `computeSpill` from `./light`. */
+export declare function computeUvSpill(fluor: TiledSurface, strength: number): TiledSurface | null;
+/**
+ * Tile cache for UV blacklight rendering on one layer: dims daylight pixels to `uvLight.ambient`
+ * and adds fluorescent emission from `doc.fluor[id]` (even where daylight alpha is 0 for invisible ink).
+ */
+export declare class UvCache {
+    private readonly tiles;
+    private spillCache;
+    render(color: TiledSurface, fluor: TiledSurface | undefined, uv: UvLightSettings): TiledSurface;
+    spill(fluor: TiledSurface, uv: UvLightSettings): TiledSurface | null;
+}
+/** Coarse grid scale: 1 heat cell per 4×4 canvas pixels. */
+export declare const HEAT_SCALE = 4;
+/** Explicit 2D diffusion rate per step (≤ 0.25 for stability). */
+export declare const HEAT_DIFFUSION = 0.18;
+/** Newtonian cooling fraction per step. */
+export declare const HEAT_COOLING = 0.03;
+/** Temperature above which a heated cell dries wet paint. */
+export declare const HEAT_DRY_THRESHOLD = 0.5;
+export interface HeatField {
+    width: number;
+    height: number;
+    gridWidth: number;
+    gridHeight: number;
+    /** Row-major temperatures in 0..1 (`gridWidth * gridHeight`). */
+    cells: Float64Array;
+    max: number;
+    revision: number;
+}
+export interface HeatSample {
+    x: number;
+    y: number;
+    temperature: number;
+}
+export declare function createHeatField(width: number, height: number): HeatField;
+export declare function cloneHeatField(field: HeatField): HeatField;
+export interface HeatStats {
+    max: number;
+    mean: number;
+    hotCells: number;
+    bounds: RasterRect | null;
+}
+export declare function heatStats(field: HeatField | undefined): HeatStats;
+/** Bounding document-space rectangle of all coarse cells with temperature ≥ `threshold`, or `null`. */
+export declare function hotCellsBounds(field: HeatField, threshold?: number): RasterRect | null;
+/**
+ * Paints heat (or cools when `temperature` is below current cell heat) along `points` with `radius`
+ * in document pixels. Returns the affected document-space bounding box and updated field statistics.
+ */
+export declare function paintHeatField(field: HeatField, points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>, radius?: number, temperature?: number): {
+    bounds: RasterRect;
+    stats: HeatStats;
+};
+/**
+ * Advances the heat field by `steps` iterations of 5-point Laplacian diffusion and Newtonian cooling.
+ */
+export declare function advanceHeatField(field: HeatField, steps?: number): HeatStats;
+/** Clears the heat field to 0 everywhere. */
+export declare function clearHeatField(field: HeatField): boolean;
+/** Bilinearly samples temperature (0..1) at document coordinates `(x, y)`. */
+export declare function sampleHeatAt(field: HeatField, x: number, y: number): number;
+/** Shifts and resizes a heat field when `extendCanvas` shifts the document by `(dx, dy)`. */
+export declare function shiftHeatField(field: HeatField, dx: number, dy: number, newWidth: number, newHeight: number): HeatField;
+/**
+ * Tile cache for thermochromic colour shifting on one layer: blends cold pixels toward `hotColor`
+ * around `threshold` where the coarse heat field is warm.
+ */
+export declare class ThermoCache {
+    private readonly tiles;
+    render(color: TiledSurface, thermo: TiledSurface | undefined, offset: {
+        x: number;
+        y: number;
+    }, heat: HeatField): TiledSurface;
+}
+export interface SavedLayerFluor {
+    rect: RasterRect;
+    /** 4-channel RGBA PNG data URL of the layer's fluorescence. */
+    fluor: string;
+}
+export interface SavedLayerThermo {
+    rect: RasterRect;
+    /** 4-channel RGBA PNG data URL of the layer's thermochromic `[hotR, hotG, hotB, thresholdByte]`. */
+    thermo: string;
+}
+export interface SavedHeatField {
+    gridWidth: number;
+    gridHeight: number;
+    cells: number[];
+}
+export declare function fluorToJSON(fluor: TiledSurface | undefined): SavedLayerFluor | null;
+export declare function fluorFromJSON(raw: unknown): TiledSurface;
+export declare function thermoToJSON(thermo: TiledSurface | undefined): SavedLayerThermo | null;
+export declare function thermoFromJSON(raw: unknown): TiledSurface;
+export declare function heatToJSON(field: HeatField | undefined): SavedHeatField | null;
+export declare function heatFromJSON(raw: unknown, width: number, height: number): HeatField | null;