@pixerate/editor 0.238.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;

package/dist/image-editor/index.cjs

@@ -1,6 +1,10 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6; var _class7; var _class8; var _class9; var _class10; var _class11; var _class12; var _class13; var _class14; var _class15; var _class16; var _class17; var _class18;
 
 
+var _chunkS6OT6CTScjs = require('../chunk-S6OT6CTS.cjs');
+
+
+
 
 
 
@@ -17538,7 +17542,50 @@ function createImagePaintTools(controller) {
       return { color, foreground: controller.getState().paint.foreground };
     }
   };
-  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2];
+  const sampleGradient = {
+    name: "sample_gradient",
+    title: "Sample a gradient along a line",
+    description: "Reads the composite colours along a line from start to end (document pixels), smooths away grain and fits the fewest gradient stops that reproduce them within tolerance. Changes nothing. Returns a linear gradient (CSS angle of the line, oklab interpolation, stops with offsets along the line), its CSS, and how many points could be read. Pass the gradient to a gradient tool (set_gradient) or its stops as paint (set_paint).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        start: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where the gradient starts (offset 0)." },
+        end: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where it ends (offset 1)." },
+        sampleCount: { type: "integer", minimum: 2, maximum: 1024, description: "Points read along the line, ends included (default 32)." },
+        sampleSize: { type: "integer", minimum: 1, maximum: 101, description: "Square averaged at each point, in pixels (default 3)." },
+        tolerance: { type: "number", exclusiveMinimum: 0, maximum: 1, description: "Largest error left, OKLab \u0394E (default 0.06; 0.02 is a just-noticeable step)." },
+        maxStops: { type: "integer", minimum: 2, maximum: 64, description: "Most stops (default 5)." },
+        snapStep: { type: "number", exclusiveMinimum: 0, maximum: 180, description: "Snap the line to multiples of this many degrees, keeping its length (default no snapping)." }
+      },
+      required: ["start", "end"],
+      additionalProperties: false
+    },
+    annotations: { title: "Sample a gradient along a line", ...READ4 },
+    handler: (args) => {
+      const start = args.start;
+      const end = args.end;
+      const size = _nullishCoalesce(args.sampleSize, () => ( 3));
+      let read = 0;
+      let gradient;
+      try {
+        gradient = _chunkS6OT6CTScjs.sampleGradientFromLine.call(void 0, 
+          (p) => {
+            const c = controller.sampleColor(p, { size, setForeground: false });
+            if (c) read++;
+            return c;
+          },
+          start,
+          end,
+          { sampleCount: args.sampleCount, tolerance: args.tolerance, maxStops: args.maxStops, snapStep: args.snapStep }
+        );
+      } catch (e) {
+        throw new (0, _chunkBBUE3UJLcjs.LayerOperationError)(e.message);
+      }
+      if (!gradient) throw new (0, _chunkBBUE3UJLcjs.LayerOperationError)(`Fewer than two points along the line could be read: it runs outside the canvas or over transparent pixels. Read the canvas size with get_image_info and draw the line across visible pixels.`);
+      return { gradient, css: _chunkS6OT6CTScjs.gradientToCss.call(void 0, gradient), pointsRead: read };
+    }
+  };
+  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2, sampleGradient];
 }
 
 // src/image-editor/color-tools.ts

package/dist/image-editor/index.js

@@ -1,3 +1,7 @@
+import {
+  gradientToCss,
+  sampleGradientFromLine
+} from "../chunk-KMPM5JM5.js";
 import {
   bendSegment,
   loadOpenTypeFont,
@@ -17538,7 +17542,50 @@ function createImagePaintTools(controller) {
       return { color, foreground: controller.getState().paint.foreground };
     }
   };
-  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2];
+  const sampleGradient = {
+    name: "sample_gradient",
+    title: "Sample a gradient along a line",
+    description: "Reads the composite colours along a line from start to end (document pixels), smooths away grain and fits the fewest gradient stops that reproduce them within tolerance. Changes nothing. Returns a linear gradient (CSS angle of the line, oklab interpolation, stops with offsets along the line), its CSS, and how many points could be read. Pass the gradient to a gradient tool (set_gradient) or its stops as paint (set_paint).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        start: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where the gradient starts (offset 0)." },
+        end: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where it ends (offset 1)." },
+        sampleCount: { type: "integer", minimum: 2, maximum: 1024, description: "Points read along the line, ends included (default 32)." },
+        sampleSize: { type: "integer", minimum: 1, maximum: 101, description: "Square averaged at each point, in pixels (default 3)." },
+        tolerance: { type: "number", exclusiveMinimum: 0, maximum: 1, description: "Largest error left, OKLab \u0394E (default 0.06; 0.02 is a just-noticeable step)." },
+        maxStops: { type: "integer", minimum: 2, maximum: 64, description: "Most stops (default 5)." },
+        snapStep: { type: "number", exclusiveMinimum: 0, maximum: 180, description: "Snap the line to multiples of this many degrees, keeping its length (default no snapping)." }
+      },
+      required: ["start", "end"],
+      additionalProperties: false
+    },
+    annotations: { title: "Sample a gradient along a line", ...READ4 },
+    handler: (args) => {
+      const start = args.start;
+      const end = args.end;
+      const size = args.sampleSize ?? 3;
+      let read = 0;
+      let gradient;
+      try {
+        gradient = sampleGradientFromLine(
+          (p) => {
+            const c = controller.sampleColor(p, { size, setForeground: false });
+            if (c) read++;
+            return c;
+          },
+          start,
+          end,
+          { sampleCount: args.sampleCount, tolerance: args.tolerance, maxStops: args.maxStops, snapStep: args.snapStep }
+        );
+      } catch (e) {
+        throw new LayerOperationError(e.message);
+      }
+      if (!gradient) throw new LayerOperationError(`Fewer than two points along the line could be read: it runs outside the canvas or over transparent pixels. Read the canvas size with get_image_info and draw the line across visible pixels.`);
+      return { gradient, css: gradientToCss(gradient), pointsRead: read };
+    }
+  };
+  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2, sampleGradient];
 }
 
 // src/image-editor/color-tools.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.238.0",
+  "version": "0.239.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",