@pixerate/editor 0.190.0 → 0.191.0

package/dist/vector/index.js

@@ -9,9 +9,14 @@ import {
   pathfinder
 } from "../chunk-65MDXWA7.js";
 import {
+  VECTOR_TRACE_MAX_PIXELS,
   loadOpenTypeFont,
-  parseOpenTypeFont
-} from "../chunk-M7XIC2FC.js";
+  parseOpenTypeFont,
+  quantizeVectorTraceColors,
+  traceField,
+  traceVectorImage,
+  vectorTraceContours
+} from "../chunk-RQ2EM5TY.js";
 import {
   applyHomography,
   homographyFromPoints,
@@ -533,8 +538,7 @@ import {
 import {
   fitCubicWithTangents,
   fitCubics,
-  parseSvgPath,
-  simplifyRing
+  parseSvgPath
 } from "../chunk-PWBZH3FK.js";
 import {
   EffectUnsupportedError,
@@ -575,293 +579,6 @@ import "../chunk-YBAPT7NL.js";
 import "../chunk-MHLU6GRJ.js";
 import "../chunk-6ONMQ6WF.js";
 
-// src/vector/trace.ts
-var VECTOR_TRACE_MAX_PIXELS = 4e6;
-function signedArea(p) {
-  let a = 0;
-  for (let i = 0; i < p.length; i++) {
-    const [x0, y0] = p[i];
-    const [x1, y1] = p[(i + 1) % p.length];
-    a += x0 * y1 - x1 * y0;
-  }
-  return a / 2;
-}
-function pointInPoly(p, poly) {
-  let inside = false;
-  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
-    const [xi, yi] = poly[i];
-    const [xj, yj] = poly[j];
-    if (yi > p[1] !== yj > p[1] && p[0] < (xj - xi) * (p[1] - yi) / (yj - yi) + xi) inside = !inside;
-  }
-  return inside;
-}
-function vectorTraceContours(field, w, h, threshold) {
-  const gw = w + 2;
-  const gh = h + 2;
-  const val = (i, j) => i === 0 || j === 0 || i > w || j > h ? -Infinity : field[(j - 1) * w + (i - 1)];
-  const inside = (i, j) => val(i, j) >= threshold;
-  const pos = (i, j) => [i - 0.5, j - 0.5];
-  const cross2 = (a, b) => {
-    const va = val(a[0], a[1]);
-    const vb = val(b[0], b[1]);
-    let t;
-    if (Number.isFinite(va) && Number.isFinite(vb) && Math.abs(vb - va) > 1e-12) t = Math.min(1, Math.max(0, (threshold - va) / (vb - va)));
-    else if (Number.isFinite(va)) t = va >= threshold ? 0.5 : 0;
-    else t = vb >= threshold ? 0.5 : 1;
-    const pa = pos(a[0], a[1]);
-    const pb = pos(b[0], b[1]);
-    return [pa[0] + (pb[0] - pa[0]) * t, pa[1] + (pb[1] - pa[1]) * t];
-  };
-  const hid = (i, j) => 2 * (j * gw + i);
-  const vid = (i, j) => 2 * (j * gw + i) + 1;
-  const next = /* @__PURE__ */ new Map();
-  const point = /* @__PURE__ */ new Map();
-  for (let j = 0; j < gh - 1; j++) {
-    for (let i = 0; i < gw - 1; i++) {
-      const tl = inside(i, j);
-      const tr = inside(i + 1, j);
-      const br = inside(i + 1, j + 1);
-      const bl = inside(i, j + 1);
-      const code = +tl << 3 | +tr << 2 | +br << 1 | +bl;
-      if (code === 0 || code === 15) continue;
-      const top = hid(i, j);
-      const bottom = hid(i, j + 1);
-      const left = vid(i, j);
-      const right = vid(i + 1, j);
-      const seg = (a, b) => next.set(a, b);
-      const mean = () => (val(i, j) + val(i + 1, j) + val(i + 1, j + 1) + val(i, j + 1)) / 4;
-      switch (code) {
-        case 1:
-          seg(left, bottom);
-          break;
-        case 2:
-          seg(bottom, right);
-          break;
-        case 3:
-          seg(left, right);
-          break;
-        case 4:
-          seg(right, top);
-          break;
-        case 5:
-          if (mean() >= threshold) {
-            seg(left, top);
-            seg(right, bottom);
-          } else {
-            seg(left, bottom);
-            seg(right, top);
-          }
-          break;
-        case 6:
-          seg(bottom, top);
-          break;
-        case 7:
-          seg(left, top);
-          break;
-        case 8:
-          seg(top, left);
-          break;
-        case 9:
-          seg(top, bottom);
-          break;
-        case 10:
-          if (mean() >= threshold) {
-            seg(top, right);
-            seg(bottom, left);
-          } else {
-            seg(top, left);
-            seg(bottom, right);
-          }
-          break;
-        case 11:
-          seg(top, right);
-          break;
-        case 12:
-          seg(right, left);
-          break;
-        case 13:
-          seg(right, bottom);
-          break;
-        case 14:
-          seg(bottom, left);
-          break;
-      }
-      const edges = [
-        [top, [i, j], [i + 1, j]],
-        [bottom, [i, j + 1], [i + 1, j + 1]],
-        [left, [i, j], [i, j + 1]],
-        [right, [i + 1, j], [i + 1, j + 1]]
-      ];
-      for (const [e, a, b] of edges) if (inside(a[0], a[1]) !== inside(b[0], b[1]) && !point.has(e)) point.set(e, cross2(a, b));
-    }
-  }
-  const out = [];
-  for (const start of [...next.keys()].sort((a, b) => a - b)) {
-    if (!next.has(start)) continue;
-    const poly = [];
-    let e = start;
-    for (; ; ) {
-      const n2 = next.get(e);
-      if (n2 === void 0) break;
-      next.delete(e);
-      const p = point.get(e);
-      if (p) poly.push(p);
-      e = n2;
-      if (e === start) break;
-    }
-    if (poly.length >= 3) out.push(poly);
-  }
-  return out;
-}
-function loopsOf(field, w, h, threshold, tolerance, minArea) {
-  const loops = [];
-  for (const raw of vectorTraceContours(field, w, h, threshold)) {
-    const area = signedArea(raw);
-    if (Math.abs(area) < Math.max(0, minArea)) continue;
-    const simple = simplifyRing(raw, Math.max(0.01, tolerance));
-    if (simple.length < 3) continue;
-    loops.push({ raw, simple, area, depth: 0 });
-  }
-  for (const l of loops) l.depth = loops.filter((o) => o !== l && Math.abs(o.area) > Math.abs(l.area) && pointInPoly(l.simple[0], o.simple)).length;
-  return loops.sort((a, b) => a.depth - b.depth || Math.abs(b.area) - Math.abs(a.area));
-}
-function loopSubpath(l, tolerance, roundness) {
-  if (roundness <= 0) return { closed: true, anchors: l.simple.map(([x, y]) => ({ x, y })) };
-  const cornerAngleDeg = 25 + roundness * 125;
-  const cubics = fitCubics(l.raw, Math.max(0.05, tolerance), {
-    closed: true,
-    cornerAngleDeg
-  });
-  if (!cubics.length) return { closed: true, anchors: l.simple.map(([x, y]) => ({ x, y })) };
-  const anchors = cubics.map((c, k) => {
-    const prev = cubics[(k - 1 + cubics.length) % cubics.length];
-    return {
-      x: c.p0[0],
-      y: c.p0[1],
-      in: { x: prev.p2[0], y: prev.p2[1] },
-      out: { x: c.p1[0], y: c.p1[1] }
-    };
-  });
-  return { closed: true, anchors };
-}
-function traceField(field, w, h, threshold, o) {
-  const tolerance = o.tolerance ?? 1;
-  const roundness = Math.min(1, Math.max(0, o.cornerRoundness ?? 0.5));
-  return loopsOf(field, w, h, threshold, tolerance, o.minArea ?? 10).map((l) => loopSubpath(l, tolerance, roundness));
-}
-function quantizeVectorTraceColors(pixels, count) {
-  const n2 = pixels.width * pixels.height;
-  const d = pixels.data;
-  const opaque = [];
-  for (let i = 0; i < n2; i++) if (d[i * 4 + 3] >= 128) opaque.push(i);
-  const boxes = opaque.length ? [opaque] : [];
-  const range = (box, c) => {
-    let lo = 255;
-    let hi = 0;
-    for (const i of box) {
-      const v = d[i * 4 + c];
-      if (v < lo) lo = v;
-      if (v > hi) hi = v;
-    }
-    return hi - lo;
-  };
-  while (boxes.length < count) {
-    let best = -1;
-    let bestRange = 0;
-    let bestC = 0;
-    boxes.forEach((b, k) => {
-      if (b.length < 2) return;
-      for (let c = 0; c < 3; c++) {
-        const r = range(b, c);
-        if (r > bestRange) {
-          bestRange = r;
-          best = k;
-          bestC = c;
-        }
-      }
-    });
-    if (best < 0) break;
-    const box = boxes[best].slice().sort((a, b) => d[a * 4 + bestC] - d[b * 4 + bestC]);
-    const key = (k) => d[box[k] * 4 + bestC];
-    const v = key(box.length >> 1);
-    let mid = box.findIndex((_, k) => key(k) >= v);
-    if (mid <= 0) mid = box.findIndex((_, k) => key(k) > v);
-    boxes.splice(best, 1, box.slice(0, mid), box.slice(mid));
-  }
-  const palette = boxes.map((b) => {
-    const s = [0, 0, 0];
-    for (const i of b) for (let c = 0; c < 3; c++) s[c] += d[i * 4 + c];
-    return [Math.round(s[0] / b.length), Math.round(s[1] / b.length), Math.round(s[2] / b.length)];
-  });
-  const index = new Int16Array(n2).fill(-1);
-  const counts = palette.map(() => 0);
-  for (const i of opaque) {
-    let best = 0;
-    let bestD = Infinity;
-    palette.forEach((p, k) => {
-      const dd = (d[i * 4] - p[0]) ** 2 + (d[i * 4 + 1] - p[1]) ** 2 + (d[i * 4 + 2] - p[2]) ** 2;
-      if (dd < bestD) {
-        bestD = dd;
-        best = k;
-      }
-    });
-    index[i] = best;
-    counts[best]++;
-  }
-  return { palette, index, counts };
-}
-var hex = (c) => `#${c.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}`;
-function traceVectorImage(pixels, options = {}) {
-  const { width: w, height: h, data } = pixels;
-  if (!(w > 0 && h > 0) || data.length < w * h * 4) throw new Error("The image has no pixels (or fewer than width \xD7 height \xD7 4 values).");
-  if (w * h > VECTOR_TRACE_MAX_PIXELS) throw new Error(`The image has ${w * h} pixels; scale it down to at most ${VECTOR_TRACE_MAX_PIXELS} to trace it.`);
-  const n2 = w * h;
-  if ((options.mode ?? "threshold") === "threshold") {
-    const field = new Float32Array(n2);
-    const byAlpha = options.channel === "alpha";
-    for (let i = 0; i < n2; i++) {
-      const a = data[i * 4 + 3] / 255;
-      field[i] = byAlpha ? a : a * (1 - (0.2126 * data[i * 4] + 0.7152 * data[i * 4 + 1] + 0.0722 * data[i * 4 + 2]) / 255);
-    }
-    const subpaths = traceField(field, w, h, Math.min(1, Math.max(0, options.threshold ?? 0.5)), options);
-    return subpaths.length ? [
-      {
-        id: "trace-1",
-        type: "path",
-        name: "Trace",
-        fill: options.color ?? "#000000",
-        stroke: null,
-        fillRule: "evenodd",
-        subpaths
-      }
-    ] : [];
-  }
-  const count = Math.min(32, Math.max(2, Math.round(options.colors ?? 6)));
-  const q = quantizeVectorTraceColors(pixels, count);
-  const order = q.palette.map((_, k) => k).filter((k) => q.counts[k] > 0).sort((a, b) => q.counts[b] - q.counts[a]);
-  const rank = new Map(order.map((k, r) => [k, r]));
-  const out = [];
-  order.forEach((k, r) => {
-    const field = new Uint8Array(n2);
-    for (let i = 0; i < n2; i++) {
-      const ix = q.index[i];
-      field[i] = ix >= 0 && rank.get(ix) >= r ? 1 : 0;
-    }
-    const subpaths = traceField(field, w, h, 0.5, options);
-    if (subpaths.length)
-      out.push({
-        id: `trace-${out.length + 1}`,
-        type: "path",
-        name: hex(q.palette[k]),
-        fill: hex(q.palette[k]),
-        stroke: null,
-        fillRule: "evenodd",
-        subpaths
-      });
-  });
-  return out;
-}
-
 // src/vector/stylize.ts
 var VECTOR_STYLIZE_STYLES = ["mosaic", "halftone", "lowPoly", "hatch"];
 var VECTOR_STYLIZE_LABELS = { mosaic: "Mosaic", halftone: "Halftone", lowPoly: "Low Poly", hatch: "Engraving" };
@@ -889,7 +606,7 @@ function sampleBox(px, cx, cy, size) {
   return [s[0] / s[3], s[1] / s[3], s[2] / s[3], s[3] / count];
 }
 var darkness = (c) => (1 - (0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]) / 255) * (c[3] / 255);
-var hex2 = (c) => `#${c.slice(0, 3).map((v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0")).join("")}`;
+var hex = (c) => `#${c.slice(0, 3).map((v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0")).join("")}`;
 function paletteOf(colors, count) {
   const data = new Uint8ClampedArray(colors.length * 4);
   colors.forEach((c, i) => {
@@ -899,7 +616,7 @@ function paletteOf(colors, count) {
     data[i * 4 + 3] = c[3];
   });
   const q = quantizeVectorTraceColors({ width: colors.length, height: 1, data }, Math.min(32, Math.max(2, Math.round(count))));
-  return { palette: q.palette.map(hex2), index: q.index };
+  return { palette: q.palette.map(hex), index: q.index };
 }
 function byColour(shapes, palette, index, name, extra = {}) {
   const groups = palette.map(() => []);
@@ -3835,8 +3552,8 @@ function vectorPaintToHex(paint) {
   if (typeof paint !== "string") return null;
   const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(paint.trim());
   if (!m) return null;
-  const hex3 = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];
-  return `#${hex3.toLowerCase()}`;
+  const hex2 = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];
+  return `#${hex2.toLowerCase()}`;
 }
 var VECTOR_GRADIENT_TYPE_LABELS = { linear: "Linear", radial: "Radial", conic: "Conic", reflected: "Reflected", diamond: "Diamond" };
 var VECTOR_GRADIENT_SPREAD_LABELS = { pad: "Pad", reflect: "Reflect", repeat: "Repeat" };
@@ -4728,8 +4445,8 @@ function subpathOf(prop, frame) {
 }
 function cssColor(c) {
   const k = c.slice(0, 3).some((v) => v > 1) ? 255 : 1;
-  const hex3 = (v) => Math.round(Math.min(1, Math.max(0, v / k)) * 255).toString(16).padStart(2, "0");
-  return `#${hex3(c[0] ?? 0)}${hex3(c[1] ?? 0)}${hex3(c[2] ?? 0)}`;
+  const hex2 = (v) => Math.round(Math.min(1, Math.max(0, v / k)) * 255).toString(16).padStart(2, "0");
+  return `#${hex2(c[0] ?? 0)}${hex2(c[1] ?? 0)}${hex2(c[2] ?? 0)}`;
 }
 function geometryOf(it, frame, notes) {
   switch (it.ty) {
@@ -19228,6 +18945,7 @@ export {
   toVectorKeyInput,
   toVectorModifiers,
   toVectorPointerInput,
+  traceField,
   traceVectorImage,
   transformVectorEffects,
   transformVectorGradient,

package/dist/vector/trace.d.cts

@@ -11,7 +11,7 @@
  * stacked: a colour's shape covers the colours traced above it too, so no gaps open between them.
  */
 import type { Point } from '../canvas/types.cjs';
-import type { VectorPathNode } from './types.cjs';
+import type { VectorPathNode, VectorSubpath } from './types.cjs';
 /** RGBA pixels, row by row (8 bits a channel). */
 export interface VectorTracePixels {
     width: number;
@@ -36,6 +36,11 @@ export interface VectorTraceOptions {
     minArea?: number;
     /** 0: straight sides and sharp corners; 1: as smooth as the outline allows (default 0.5). */
     cornerRoundness?: number;
+    /**
+     * Give hard pixel edges their square corners back: marching squares cuts each corner where an
+     * axis-aligned edge turns with a half-pixel diagonal, which skews a traced rectangle (default false).
+     */
+    squareCorners?: boolean;
 }
 /** The most pixels traced (larger images are refused; scale them down first). */
 export declare const VECTOR_TRACE_MAX_PIXELS = 4000000;
@@ -44,6 +49,8 @@ export declare const VECTOR_TRACE_MAX_PIXELS = 4000000;
  * y + 0.5)): the closed contours where the field reaches `threshold`, in pixel coordinates.
  */
 export declare function vectorTraceContours(field: ArrayLike<number>, w: number, h: number, threshold: number): Point[][];
+/** The subpaths of a field's outline (holes included; fill even-odd), in its pixel coordinates (pixel centres at +0.5). */
+export declare function traceField(field: ArrayLike<number>, w: number, h: number, threshold: number, o: VectorTraceOptions): VectorSubpath[];
 /**
  * The palette of the opaque pixels quantised to `count` colours (median cut on RGB) and each
  * pixel's palette index (−1 for transparent pixels), with how many pixels each colour got.

package/dist/vector/trace.d.ts

@@ -11,7 +11,7 @@
  * stacked: a colour's shape covers the colours traced above it too, so no gaps open between them.
  */
 import type { Point } from '../canvas/types.js';
-import type { VectorPathNode } from './types.js';
+import type { VectorPathNode, VectorSubpath } from './types.js';
 /** RGBA pixels, row by row (8 bits a channel). */
 export interface VectorTracePixels {
     width: number;
@@ -36,6 +36,11 @@ export interface VectorTraceOptions {
     minArea?: number;
     /** 0: straight sides and sharp corners; 1: as smooth as the outline allows (default 0.5). */
     cornerRoundness?: number;
+    /**
+     * Give hard pixel edges their square corners back: marching squares cuts each corner where an
+     * axis-aligned edge turns with a half-pixel diagonal, which skews a traced rectangle (default false).
+     */
+    squareCorners?: boolean;
 }
 /** The most pixels traced (larger images are refused; scale them down first). */
 export declare const VECTOR_TRACE_MAX_PIXELS = 4000000;
@@ -44,6 +49,8 @@ export declare const VECTOR_TRACE_MAX_PIXELS = 4000000;
  * y + 0.5)): the closed contours where the field reaches `threshold`, in pixel coordinates.
  */
 export declare function vectorTraceContours(field: ArrayLike<number>, w: number, h: number, threshold: number): Point[][];
+/** The subpaths of a field's outline (holes included; fill even-odd), in its pixel coordinates (pixel centres at +0.5). */
+export declare function traceField(field: ArrayLike<number>, w: number, h: number, threshold: number, o: VectorTraceOptions): VectorSubpath[];
 /**
  * The palette of the opaque pixels quantised to `count` colours (median cut on RGB) and each
  * pixel's palette index (−1 for transparent pixels), with how many pixels each colour got.

package/package.json

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

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

@@ -314,11 +314,13 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `remove_shape_component` | Delete one component (not the last: delete the layer instead). Returns the shape. |
 | `merge_shape_components` | Merge Shape Components: the combined area becomes one plain component (live shapes become paths); the look does not change. Returns the shape. |
 | `get_vector_mask` | Read-only. A layer's vector mask: enabled, linked, inverted, fill rule, density, feather, bounds and components (subpaths in document px), or null. Read it before editing the path. |
-| `add_vector_mask` | Layer › Vector Mask on any layer but a shape: `from` `path` (a `shape`, `subpaths` or `components`, like `add_shape_layer`), `reveal-all` or `hide-all` (empty path). Reveals inside the path, sharp at any size; it combines with the raster mask. Returns the vector mask. |
+| `add_vector_mask` | Layer › Vector Mask on any layer but a shape: `from` `path` (a `shape`, `subpaths` or `components`, like `add_shape_layer`), `selection` (traced, `tolerance` px), `reveal-all` or `hide-all` (empty path). Reveals inside the path, sharp at any size; it combines with the raster mask. Returns the vector mask. |
 | `set_vector_mask_path` | Replace the vector mask's path (properties kept). Returns the vector mask. |
 | `set_vector_mask_properties` | `enabled`, `linked` (false: stays put when the layer moves), `inverted`, `density`, `feather` px; the path is kept. Returns the vector mask. |
 | `rasterize_vector_mask` | Multiply the path into the raster mask (adding one) and drop the vector mask, so it can be painted. Returns the mask summary. |
 | `remove_vector_mask` | Delete the vector mask (the raster mask stays). |
+| `selection_to_path` | Read-only. Make Work Path: the selection's outline as closed Bézier subpaths (`tolerance` px, `cornerRoundness`, `minArea`); returns `svg` and `fillRule: "evenodd"` to pass to `add_vector_mask`, `set_vector_mask_path` or `add_shape_layer`. |
+| `path_to_selection` | Make Selection: fill a path (`shape`, `subpaths`, `components`) into the selection by `mode`, with `feather` and `antiAlias`. Returns the selection. |
 | `convert_to_smart_object` | Convert sibling `layerIds` (default the active layer) to one smart object at the top one's position, optional `name`. One pixel layer keeps its id, look and properties (filters become smart filters); several layers, groups or adjustments nest as a layer document. Returns the `layer` and the `smartObject` summary. |
 | `rasterize_smart_object` | Turn a smart object into a pixel layer holding what it shows now (smart filters baked; same id, mask, effects, opacity, blend). Destructive: the contents and filters are gone. Returns the layer. |
 | `set_smart_object_transform` | Set a smart object's transform absolutely: `corners`, `matrix` (contents → document), or `scaleX` / `scaleY` (percent of the contents), `rotate`, `skewX`, `skewY`, `x`, `y` (where the contents' centre goes; unset numbers keep their values); `warp` preset or mesh in contents px, `null` removes it; `interpolation`. Re-renders from the contents. Returns `placement`, `masksMoved` and `bounds`. |

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

@@ -67,8 +67,10 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
      `add_smart_filter`) are also limited to an active selection.
    - A cutout: `layer_via_copy` (the original stays), or `add_layer_mask` `from: "selection"` on
      the layer itself. For a hard geometric or traced edge that must stay sharp and editable
-     (a product, a screen, a window), `add_vector_mask` with the path instead; it moves and
-     transforms with the layer, and `rasterize_vector_mask` turns it into paintable pixels.
+     (a product, a screen, a window), `add_vector_mask` with the path instead (`from:
+     "selection"` traces the current selection); it moves and transforms with the layer, and
+     `rasterize_vector_mask` turns it into paintable pixels. Trace with `tolerance` 0.5–1 px for
+     a tight edge; check the result with `set_mask_view` before you go on.
    - Painting or fills inside it: keep the selection active and paint; `stroke_selection` for
      an outline that follows it.
    - Removing what it covers: `content_aware_fill` `output: "new-layer"`.
@@ -103,6 +105,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 | An existing layer mask | `load_selection_from_mask` (`source: "vector"` for a vector mask) |
 | A cutout, shape or text already on its own layer | `select_layer_transparency` (exact, soft where the layer is) |
 | A dead pixel row or column | `select_line`, then fill or heal it |
+| Smooth curves you can describe (a logo, a road, a lens) | `path_to_selection` with Bézier `subpaths` or SVG path data |
 
 ## Recipes
 
@@ -199,6 +202,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `set_mask_view`: a layer mask alone in grey or as a red overlay, to check it
 - `add_vector_mask`, `set_vector_mask_path`, `set_vector_mask_properties`, `get_vector_mask`: sharp, editable path masks
 - `rasterize_vector_mask`, `remove_vector_mask`: turn a vector mask into pixels, or drop it
+- `selection_to_path`, `path_to_selection`: a selection's outline as Bézier paths, and a path back into a selection
 - `modify_selection`: expand, contract, feather, border, smooth
 - `refine_selection`: snap the edge to the image
 - `transform_selection`: move or scale the outline only