npm package: @genart-dev/plugin-trace
Description: Image tracing and vectorization plugin for genart.dev — edge detection, contour extraction, Bezier spline fitting, stipple/hatching, threshold presets, multi-pass refinement
Author: genart.dev
Latest version: 0.2.0

# @genart-dev/plugin-trace

Classical computer vision image tracing plugin for [genart.dev](https://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](https://genart.dev) — a generative art platform with an MCP server, desktop app, and IDE extensions.

## Examples

![Edge detection, contour extraction, and line detection](test-renders/edge-contour-line.png)

Canny edge detection, RDP contour simplification, and Hough line detection on a landscape scene and geometric shapes. ([source](test-renders/edge-contour-line.genart))

![Color regions, value mapping, shape and corner detection](test-renders/region-value-shape.png)

K-means color segmentation, quantized value mapping, shape classification, and Harris corner detection. ([source](test-renders/region-value-shape.genart))

## Install

```bash
npm install @genart-dev/plugin-trace
```

## Usage

```typescript
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](https://github.com/genart-dev/cli):

```bash
bash test-renders/render.sh
# → test-renders/edge-contour-line.png
# → test-renders/region-value-shape.png
```

## Related Packages

| Package | Purpose |
|---------|---------|
| [`@genart-dev/core`](https://github.com/genart-dev/core) | Plugin host, layer system (dependency) |
| [`@genart-dev/mcp-server`](https://github.com/genart-dev/mcp-server) | MCP server that surfaces plugin tools to AI agents |

## Support

Questions, bugs, or feedback — [support@genart.dev](mailto:support@genart.dev) or [open an issue](https://github.com/genart-dev/plugin-trace/issues).

## License

MIT