@genart-dev/plugin-trace

Classical computer vision image tracing plugin for genart.dev — extract edges, lines, contours, color regions, value maps, shapes, and corners from reference images. All algorithms are pure JavaScript on Canvas2D pixel data (no ML, no native dependencies). Includes MCP tools for AI-agent control.

Part of genart.dev — a generative art platform with an MCP server, desktop app, and IDE extensions.

Examples

Canny edge detection, RDP contour simplification, and Hough line detection on a landscape scene and geometric shapes.

K-means color segmentation, quantized value mapping, shape classification, and Harris corner detection.

Install

npm install @genart-dev/plugin-trace

Usage

import tracePlugin from "@genart-dev/plugin-trace";
import { createDefaultRegistry } from "@genart-dev/core";

const registry = createDefaultRegistry();
registry.registerPlugin(tracePlugin);

// Or use algorithms directly
import {
  detectEdges,
  detectLines,
  extractContours,
  segmentRegions,
  computeValueMap,
  detectShapes,
  detectCorners,
} from "@genart-dev/plugin-trace";

Algorithms (7)

Edge Detection — Canny (detectEdges)

Gaussian blur, Sobel gradients, non-maximum suppression, hysteresis thresholding.

| Option | Type | Default | Description | |--------|------|---------|-------------| | sigma | number | 1.4 | Gaussian blur sigma | | lowThreshold | number | 50 | Lower hysteresis threshold (0–255) | | highThreshold | number | 100 | Upper hysteresis threshold (0–255) |

Returns { edges: Uint8Array, magnitude: Float64Array, direction: Float64Array, width, height }.

Line Detection — Hough (detectLines)

Accumulator-based line detection from a binary edge map.

| Option | Type | Default | Description | |--------|------|---------|-------------| | threshold | number | 50 | Minimum votes to detect a line | | minLineLength | number | 30 | Minimum segment length in pixels | | maxLineGap | number | 10 | Maximum gap between segments to merge |

Returns LineSegment[] with start, end, angle, length.

Contour Extraction — RDP (extractContours)

Traces connected edge pixels and simplifies with Ramer-Douglas-Peucker.

| Option | Type | Default | Description | |--------|------|---------|-------------| | epsilon | number | 2.0 | RDP simplification tolerance (higher = simpler) | | minLength | number | 10 | Minimum contour length in pixels | | closeTolerance | number | 5 | Max gap to auto-close a contour |

Returns Contour[] with points, closed, length.

Color Region Segmentation — K-Means (segmentRegions)

Clusters pixels by color using k-means++ initialization.

| Option | Type | Default | Description | |--------|------|---------|-------------| | k | number | 5 | Number of color clusters | | maxIterations | number | 20 | Max k-means iterations | | seed | number | 42 | Random seed for deterministic results |

Returns ColorRegion[] with color, hex, pixels, percentage, bounds, mask.

Value Mapping (computeValueMap)

Converts to luminosity with optional quantization, inversion, and contrast.

| Option | Type | Default | Description | |--------|------|---------|-------------| | levels | number | 0 | Quantize to N levels (0 = continuous) | | sigma | number | 0 | Pre-blur sigma (0 = none) | | invert | boolean | false | Invert the value map | | contrast | number | 0 | Contrast adjustment (−1 to 1) |

Returns { values: Float64Array, histogram: Uint32Array, width, height }.

Shape Detection (detectShapes)

Classifies closed contours as geometric primitives by circularity, vertex count, and rectangularity.

| Option | Type | Default | Description | |--------|------|---------|-------------| | circularityThreshold | number | 0.85 | Circularity threshold for circles | | rectangularityThreshold | number | 0.85 | Area ratio threshold for rectangles | | minConfidence | number | 0.5 | Minimum confidence to report |

Returns DetectedShape[] with type (circle | ellipse | rectangle | triangle | polygon), center, bounds, points, confidence.

Corner Detection — Harris (detectCorners)

Structure tensor, Harris response, non-maximum suppression.

| Option | Type | Default | Description | |--------|------|---------|-------------| | k | number | 0.04 | Harris sensitivity parameter | | sigma | number | 1.5 | Gaussian blur sigma | | threshold | number | 0.01 | Response threshold (relative to max) | | nmsRadius | number | 5 | Non-maximum suppression radius | | maxCorners | number | 200 | Maximum corners to return |

Returns Corner[] with x, y, strength.

Layer Type (1)

Trace Reference (trace:reference)

Renders traced data as a visual overlay layer. Set via MCP tools or programmatically.

| Property | Type | Default | Description | |----------|------|---------|-------------| | traceType | select | "edges" | Which trace to display | | strokeColor | color | "#000000" | Stroke color for edges/contours/lines | | strokeWidth | number | 1 | Stroke width | | fillRegions | boolean | true | Fill color regions | | showCornerMarkers | boolean | true | Show corner dots | | cornerMarkerSize | number | 4 | Corner marker radius |

MCP Tools (7)

Exposed to AI agents through the MCP server when this plugin is registered:

| Tool | Description | |------|-------------| | trace_edges | Canny edge detection with configurable thresholds | | trace_lines | Hough line segment detection | | trace_contours | Contour extraction with RDP simplification | | trace_regions | K-means color region segmentation | | trace_values | Value (luminosity) map generation | | trace_shapes | Geometric shape detection from contours | | trace_to_layers | Full analysis — creates multiple trace layers at once |

All tools accept an optional sourceId to trace a reference image asset, or default to the current canvas composite. Set createLayer: false to get analysis results without creating a layer.

Render Tests

Generate visual test outputs:

yarn build
node render-test.cjs
# → test-renders/edge-contour-line.png
# → test-renders/region-value-shape.png

Related Packages

| Package | Purpose | |---------|---------| | @genart-dev/core | Plugin host, layer system (dependency) | | @genart-dev/mcp-server | MCP server that surfaces plugin tools to AI agents |

Support

Questions, bugs, or feedback — [email protected] or open an issue.

License

MIT