@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. (source)

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

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

Regenerate the test images with the genart CLI:

bash test-renders/render.sh
# → 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 — support@genart.dev or open an issue.

License

MIT