@pixerate/editor 0.194.0 → 0.195.0

package/dist/image-editor/selection/magnetic.d.cts

@@ -0,0 +1,60 @@
+/**
+ * Magnetic Lasso: an outline that follows the edges of the image (live-wire, Mortensen & Barrett,
+ * "Intelligent Scissors", 1995). Each step between neighbouring pixels costs less where it runs
+ * along a strong edge (gradient magnitude), on a Laplacian zero-crossing and in the edge's
+ * direction; the outline between two points is the cheapest path, found with Dijkstra in a corridor
+ * around them. The direction term ignores which side of the edge is darker, so the path holds to an
+ * edge whichever way round it is traced.
+ */
+import type { ImagePoint } from '../types.cjs';
+import type { PixelBuffer } from './mask.cjs';
+export interface MagneticEdgeOptions {
+    /** Detection width in px: a point snaps to the strongest edge this close to it (default 10). */
+    width?: number;
+    /** 0..1: edges with less contrast than this are ignored (default 0.1, Photoshop's 10 %). */
+    contrast?: number;
+}
+/**
+ * The edge features of an image, computed lazily in 64 px blocks as the outline reaches them, so a
+ * click on a large image costs one luminance pass, not a full-image edge map.
+ */
+export declare class EdgeMap {
+    readonly width: number;
+    readonly height: number;
+    readonly contrast: number;
+    private readonly luma;
+    private readonly blocks;
+    constructor(pixels: PixelBuffer, options?: Pick<MagneticEdgeOptions, 'contrast'>);
+    /** Edge strength at (x, y) in whole pixels, 0..1 (0 outside the image or below the contrast). */
+    strength(x: number, y: number): number;
+    private block;
+    private computeBlock;
+    /** Features of the pixel at (x, y), which must be inside the image. */
+    features(x: number, y: number): {
+        strength: number;
+        dirX: number;
+        dirY: number;
+        zero: number;
+    };
+}
+/**
+ * `point` moved onto the strongest edge within `width` px (the nearest of equal ones); unchanged
+ * when there is no edge above the contrast that close. Returns a pixel centre.
+ */
+export declare function snapToEdge(map: EdgeMap, point: ImagePoint, width?: number): ImagePoint;
+/**
+ * The cheapest path along the edges from `from` to `to` (pixel centres, both included), searched
+ * in a corridor around the straight line between them: `band` px either side (default the larger
+ * of 16 px and a quarter of the distance). Points inside the image.
+ */
+export declare function liveWire(map: EdgeMap, from: ImagePoint, to: ImagePoint, band?: number): ImagePoint[];
+/** `points` with runs along one straight line reduced to their ends (exact for 8-connected paths). */
+export declare function simplifyPixelPath(points: readonly ImagePoint[]): ImagePoint[];
+/**
+ * The Magnetic Lasso for a given outline (the agent path): each point snaps to the strongest edge
+ * within `width` px, and consecutive points are joined by the live-wire path between them (the
+ * last back to the first). Points should run along the edge in order, a few dozen px apart.
+ */
+export declare function snapPolygonToEdges(pixels: PixelBuffer | EdgeMap, points: readonly ImagePoint[], options?: MagneticEdgeOptions): ImagePoint[];
+/** Path length in px between auto-placed anchors for a Frequency of 0..100 (Photoshop's default 57). */
+export declare function magneticAnchorSpacing(frequency?: number): number;

package/dist/image-editor/selection/magnetic.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Magnetic Lasso: an outline that follows the edges of the image (live-wire, Mortensen & Barrett,
+ * "Intelligent Scissors", 1995). Each step between neighbouring pixels costs less where it runs
+ * along a strong edge (gradient magnitude), on a Laplacian zero-crossing and in the edge's
+ * direction; the outline between two points is the cheapest path, found with Dijkstra in a corridor
+ * around them. The direction term ignores which side of the edge is darker, so the path holds to an
+ * edge whichever way round it is traced.
+ */
+import type { ImagePoint } from '../types.js';
+import type { PixelBuffer } from './mask.js';
+export interface MagneticEdgeOptions {
+    /** Detection width in px: a point snaps to the strongest edge this close to it (default 10). */
+    width?: number;
+    /** 0..1: edges with less contrast than this are ignored (default 0.1, Photoshop's 10 %). */
+    contrast?: number;
+}
+/**
+ * The edge features of an image, computed lazily in 64 px blocks as the outline reaches them, so a
+ * click on a large image costs one luminance pass, not a full-image edge map.
+ */
+export declare class EdgeMap {
+    readonly width: number;
+    readonly height: number;
+    readonly contrast: number;
+    private readonly luma;
+    private readonly blocks;
+    constructor(pixels: PixelBuffer, options?: Pick<MagneticEdgeOptions, 'contrast'>);
+    /** Edge strength at (x, y) in whole pixels, 0..1 (0 outside the image or below the contrast). */
+    strength(x: number, y: number): number;
+    private block;
+    private computeBlock;
+    /** Features of the pixel at (x, y), which must be inside the image. */
+    features(x: number, y: number): {
+        strength: number;
+        dirX: number;
+        dirY: number;
+        zero: number;
+    };
+}
+/**
+ * `point` moved onto the strongest edge within `width` px (the nearest of equal ones); unchanged
+ * when there is no edge above the contrast that close. Returns a pixel centre.
+ */
+export declare function snapToEdge(map: EdgeMap, point: ImagePoint, width?: number): ImagePoint;
+/**
+ * The cheapest path along the edges from `from` to `to` (pixel centres, both included), searched
+ * in a corridor around the straight line between them: `band` px either side (default the larger
+ * of 16 px and a quarter of the distance). Points inside the image.
+ */
+export declare function liveWire(map: EdgeMap, from: ImagePoint, to: ImagePoint, band?: number): ImagePoint[];
+/** `points` with runs along one straight line reduced to their ends (exact for 8-connected paths). */
+export declare function simplifyPixelPath(points: readonly ImagePoint[]): ImagePoint[];
+/**
+ * The Magnetic Lasso for a given outline (the agent path): each point snaps to the strongest edge
+ * within `width` px, and consecutive points are joined by the live-wire path between them (the
+ * last back to the first). Points should run along the edge in order, a few dozen px apart.
+ */
+export declare function snapPolygonToEdges(pixels: PixelBuffer | EdgeMap, points: readonly ImagePoint[], options?: MagneticEdgeOptions): ImagePoint[];
+/** Path length in px between auto-placed anchors for a Frequency of 0..100 (Photoshop's default 57). */
+export declare function magneticAnchorSpacing(frequency?: number): number;

package/dist/image-editor/selection/tool-options.d.cts

@@ -2,7 +2,7 @@ import { type SelectionMask, type SelectionMode } from './mask.cjs';
 import type { ColorDistance, ColorRangePreset } from './wand.cjs';
 import type { RefineEdgeParams } from './refine.cjs';
 /** Selection tools of the image editor UI. */
-export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -31,6 +31,12 @@ export interface SelectionToolOptions {
     localized?: number;
     /** Color Range: select everything except the sampled colours. */
     rangeInvert?: boolean;
+    /** Magnetic Lasso: snap to the strongest edge within this many px (1..256, default 10). */
+    magneticWidth?: number;
+    /** Magnetic Lasso: ignore edges with less contrast than this, in % (1..100, default 10). */
+    magneticContrast?: number;
+    /** Magnetic Lasso: how often anchors are placed as the pointer moves (0..100, default 57). */
+    magneticFrequency?: number;
     /** Type Mask: the text to select (default "Type"). A click places its first baseline. */
     typeText?: string;
     /** Type Mask: font size in px (default 72). */

package/dist/image-editor/selection/tool-options.d.ts

@@ -2,7 +2,7 @@ import { type SelectionMask, type SelectionMode } from './mask.js';
 import type { ColorDistance, ColorRangePreset } from './wand.js';
 import type { RefineEdgeParams } from './refine.js';
 /** Selection tools of the image editor UI. */
-export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -31,6 +31,12 @@ export interface SelectionToolOptions {
     localized?: number;
     /** Color Range: select everything except the sampled colours. */
     rangeInvert?: boolean;
+    /** Magnetic Lasso: snap to the strongest edge within this many px (1..256, default 10). */
+    magneticWidth?: number;
+    /** Magnetic Lasso: ignore edges with less contrast than this, in % (1..100, default 10). */
+    magneticContrast?: number;
+    /** Magnetic Lasso: how often anchors are placed as the pointer moves (0..100, default 57). */
+    magneticFrequency?: number;
     /** Type Mask: the text to select (default "Type"). A click places its first baseline. */
     typeText?: string;
     /** Type Mask: font size in px (default 72). */

package/package.json

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

package/skills/pixerate-image-editor/SKILL.md

@@ -252,7 +252,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `select_rect` | Rectangular marquee: `x`, `y`, `width`, `height` (natural px), `mode` (replace, add, subtract, intersect), `feather` px, `antiAlias`. Returns the summary. |
 | `select_ellipse` | Elliptical marquee inscribed in `x`, `y`, `width`, `height`; same options. A feathered ellipse makes a vignette. Returns the summary. |
 | `select_line` | Single row or column marquee: `orientation` `row` (at y) or `column` (at x), `position` in natural px, `mode`. A 1 px line across the image. Returns the summary. |
-| `select_polygon` | The lasso: `points` (at least 3 `{x, y}` along the outline, closed automatically), `mode`, `feather`, `antiAlias`. Trace a subject's contour, not its box. Returns the summary. |
+| `select_polygon` | The lasso: `points` (at least 3 `{x, y}` along the outline, closed automatically), `mode`, `feather`, `antiAlias`; `snapToEdges: {width, contrast}` makes it the Magnetic Lasso (points snap to edges, the outline follows them). Trace a subject's contour, not its box. Returns the summary (plus `outlinePoints` when snapped). |
 | `magic_wand` | Select similar colour from `x`, `y`: `tolerance` 0..255 (default 32), `contiguous` (default true), `distance` `rgb` or `perceptual`, `sampleMerged`, `sample` (`composite` or `active-layer`), `mode`, `feather`. For flat backdrops and solid colours. Returns the summary. |
 | `select_color_range` | Color Range, soft: `samples` (`[{color, x?, y?}]`) or a `preset` (reds … magentas, highlights, midtones, shadows, skinTones); `fuzziness` (samples 0..200, default 40; tone presets' falloff, default 20), `localized` px radius around positioned samples, `invert`, `sample`, `mode`, `feather`. Returns the summary. |
 | `load_selection_from_image` | Load a mask image (`image` data URL or URL; white = selected) by `channel` (luminance, alpha, red, green, blue), with `threshold`, `invert`, `mode`. For AI or saved mattes; then `refine_selection`. Returns the summary. |

package/skills/pixerate-image-selection-masking/SKILL.md

@@ -96,7 +96,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 | Subject | Method |
 | --- | --- |
 | Geometric areas: a frame, a screen, a band | `select_rect` / `select_ellipse`, with `feather` for soft transitions |
-| A subject with a clear outline (product, person, animal) | `select_subject` if the host has a model; else `select_polygon` along the contour (20–60 points), then `refine_selection` |
+| A subject with a clear outline (product, person, animal) | `select_subject` if the host has a model; else `select_polygon` with `snapToEdges` (12–30 points within `width` of the edge), then `refine_selection` |
+| A low-contrast or busy outline the edges don't follow | `select_polygon` without `snapToEdges`, along the contour (20–60 points) |
 | Flat backdrop or solid colour (studio white, green screen, sky without clouds) | `magic_wand` on the backdrop (`tolerance` 20–40; `distance: "perceptual"` for gradients), then `invert_selection` |
 | A colour spread across the image (all the reds, a dress) | `select_color_range` with `samples` (several picks) or a hue `preset`; `localized` to keep one area |
 | Tones (shadows, highlights, a luminosity mask) | `select_color_range` with `preset` `shadows` / `midtones` / `highlights` |
@@ -155,6 +156,10 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
   30–60), check `percent`, and grow with `mode: "add"`.
 - **Box instead of outline:** `select_rect` around a subject masks its background too. Trace
   the contour.
+- **Magnetic outline jumps to the wrong edge:** `snapToEdges` follows the strongest edge near
+  each point, which can be a shadow or a texture. Put points within `width` of the edge you
+  want, add points where it turns or runs past another edge, raise `contrast` on a busy
+  background, and drop `snapToEdges` where the edge is too faint.
 - **Over-feathering hard objects:** a 10 px feather on a product looks like a glow. Keep hard
   edges at 0–2 px and refine soft ones instead.
 - **Halo:** the old background shows as a light or dark fringe. `contract` 1–2 px or
@@ -183,7 +188,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `get_selection`: empty, bounds, area and percent after every step
 - `select_all`, `deselect`, `invert_selection`: whole-image selections
 - `select_rect`, `select_ellipse`: marquees
-- `select_polygon`: the lasso, along a contour
+- `select_polygon`: the lasso, along a contour; with `snapToEdges`, the Magnetic Lasso
 - `select_line`: a single row or column
 - `select_layer_transparency`: a layer's own pixels
 - `grow_selection`, `select_similar`: add similar colour, connected or anywhere