@pixerate/editor 0.237.0 → 0.239.0

package/dist/gradient/sample.d.cts

@@ -0,0 +1,69 @@
+/**
+ * Gradients from sampled colours: `simplifyGradientStops` reduces a noisy run of colours (pixels
+ * read along a line from a photo, a paint stroke or a shape) to the few stops that reproduce it
+ * within a perceptual tolerance, and `sampleGradientFromLine` reads those colours from any pixel
+ * reader and returns a linear gradient.
+ *
+ * Distances are Euclidean in OKLab (ΔE OK, about 0.02 is a just-noticeable step), against the
+ * OKLab interpolation the returned gradients use, so what is measured is what is drawn.
+ */
+import type { Gradient, GradientStop } from './types.cjs';
+export interface SimplifyGradientStopsOptions {
+    /** Largest perceptual error left between the samples and the stops, in OKLab ΔE (default 0.06). */
+    tolerance?: number;
+    /** Fewest stops to return (default 2, at least 2). */
+    minStops?: number;
+    /** Most stops to return (default 5, at least `minStops`). */
+    maxStops?: number;
+    /**
+     * Samples on each side averaged into each one before fitting, to ignore grain, JPEG noise and
+     * brush texture (default 2; 0 fits the raw samples).
+     */
+    smoothing?: number;
+}
+export interface RawGradientSample {
+    /** Position along the line, 0..1. */
+    offset: number;
+    /** Any CSS colour, or RGBA bytes `[r, g, b, a]` (0..255). */
+    color: string | readonly [number, number, number, number];
+}
+export interface SimplifiedGradientStops {
+    stops: GradientStop[];
+    /** The largest OKLab distance left between a (smoothed) sample and the stops. */
+    maxError: number;
+}
+/**
+ * Like `simplifyGradientStops`, with the largest error left. Throws a sentence when the input
+ * can't make a gradient (fewer than two readable samples, or options out of range).
+ */
+export declare function fitGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): SimplifiedGradientStops;
+/**
+ * Reduces colours sampled along a line (offsets 0..1) to a minimal set of gradient stops. The
+ * first and last stops sit at 0 and 1; stops are added where the colour turns most until every
+ * sample is within `tolerance` (OKLab ΔE) of the OKLab blend between its stops, or `maxStops` is
+ * reached. Samples that can't be read (a bad colour string) are skipped. Throws when fewer than two
+ * samples can be read.
+ */
+export declare function simplifyGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): GradientStop[];
+export interface LineSamplingOptions extends SimplifyGradientStopsOptions {
+    /** Colours read along the line, ends included (default 32, 2..1024). */
+    sampleCount?: number;
+    /** Snap the line's angle to multiples of this many degrees (e.g. 15, for Shift), keeping its length. */
+    snapStep?: number;
+}
+/**
+ * Reads colours along the line from `start` to `end` with `readPixel` (which returns a CSS colour,
+ * RGBA bytes, or null where there is nothing to read) and returns a linear gradient (OKLab
+ * interpolation) whose angle is the line's (CSS degrees) and whose stops are the simplified
+ * colours, offsets measured along the line. Returns null when fewer than two points could be read.
+ */
+export declare function sampleGradientFromLine(readPixel: (point: {
+    x: number;
+    y: number;
+}) => string | readonly [number, number, number, number] | null, start: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, options?: LineSamplingOptions): Gradient | null;

package/dist/gradient/sample.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Gradients from sampled colours: `simplifyGradientStops` reduces a noisy run of colours (pixels
+ * read along a line from a photo, a paint stroke or a shape) to the few stops that reproduce it
+ * within a perceptual tolerance, and `sampleGradientFromLine` reads those colours from any pixel
+ * reader and returns a linear gradient.
+ *
+ * Distances are Euclidean in OKLab (ΔE OK, about 0.02 is a just-noticeable step), against the
+ * OKLab interpolation the returned gradients use, so what is measured is what is drawn.
+ */
+import type { Gradient, GradientStop } from './types.js';
+export interface SimplifyGradientStopsOptions {
+    /** Largest perceptual error left between the samples and the stops, in OKLab ΔE (default 0.06). */
+    tolerance?: number;
+    /** Fewest stops to return (default 2, at least 2). */
+    minStops?: number;
+    /** Most stops to return (default 5, at least `minStops`). */
+    maxStops?: number;
+    /**
+     * Samples on each side averaged into each one before fitting, to ignore grain, JPEG noise and
+     * brush texture (default 2; 0 fits the raw samples).
+     */
+    smoothing?: number;
+}
+export interface RawGradientSample {
+    /** Position along the line, 0..1. */
+    offset: number;
+    /** Any CSS colour, or RGBA bytes `[r, g, b, a]` (0..255). */
+    color: string | readonly [number, number, number, number];
+}
+export interface SimplifiedGradientStops {
+    stops: GradientStop[];
+    /** The largest OKLab distance left between a (smoothed) sample and the stops. */
+    maxError: number;
+}
+/**
+ * Like `simplifyGradientStops`, with the largest error left. Throws a sentence when the input
+ * can't make a gradient (fewer than two readable samples, or options out of range).
+ */
+export declare function fitGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): SimplifiedGradientStops;
+/**
+ * Reduces colours sampled along a line (offsets 0..1) to a minimal set of gradient stops. The
+ * first and last stops sit at 0 and 1; stops are added where the colour turns most until every
+ * sample is within `tolerance` (OKLab ΔE) of the OKLab blend between its stops, or `maxStops` is
+ * reached. Samples that can't be read (a bad colour string) are skipped. Throws when fewer than two
+ * samples can be read.
+ */
+export declare function simplifyGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): GradientStop[];
+export interface LineSamplingOptions extends SimplifyGradientStopsOptions {
+    /** Colours read along the line, ends included (default 32, 2..1024). */
+    sampleCount?: number;
+    /** Snap the line's angle to multiples of this many degrees (e.g. 15, for Shift), keeping its length. */
+    snapStep?: number;
+}
+/**
+ * Reads colours along the line from `start` to `end` with `readPixel` (which returns a CSS colour,
+ * RGBA bytes, or null where there is nothing to read) and returns a linear gradient (OKLab
+ * interpolation) whose angle is the line's (CSS degrees) and whose stops are the simplified
+ * colours, offsets measured along the line. Returns null when fewer than two points could be read.
+ */
+export declare function sampleGradientFromLine(readPixel: (point: {
+    x: number;
+    y: number;
+}) => string | readonly [number, number, number, number] | null, start: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, options?: LineSamplingOptions): Gradient | null;