The Vectorize / Trace Bitmap generator converts raster images into smooth
vector polylines using the potrace algorithm
(via the optional potracer Python binding). It produces clean filled-shape
outlines with smooth cubic Bézier curves flattened to plotter-friendly
polylines.
The generator is shipped as a plugin (plugins/vectorize_trace.py) and
registers automatically at startup. However, tracing requires an extra
package that is not installed by default:
pip install potracerIf potracer is absent the generator appears in the UI and accepts parameters
normally, but clicking Generate raises a clear error message directing you
to run the command above. No other generator is affected.
| Component | Licence |
|---|---|
| Plottter application | MIT |
plugins/vectorize_trace.py plugin |
MIT |
potracer Python package |
GPLv2 (wraps the potrace C library, also GPLv2) |
Because potracer is an optional, user-installed dependency — loaded at
generation time and never bundled with Plottter — the GPL licence does not
propagate to the rest of the codebase. This is the same pattern used by other
optional dependencies such as pydub (audio import) and numba (JIT
acceleration).
If you need a fully MIT-clean workflow, use the built-in Contour Lines generator (Image → Lines mode) which implements sub-pixel isoline extraction without any external licence dependency.
Load image → Mode: Image to Lines → Algorithm: Vectorize / Trace Bitmap
→ Adjust parameters → Generate
- Switch to Image to Lines mode.
- Load a source image (JPG, PNG, WebP).
- Select Vectorize / Trace Bitmap from the Algorithm dropdown.
- Adjust parameters (see below).
- Click Generate.
For multi-layer tonal output set Tone Levels > 1 before generating — each threshold level lands on its own layer automatically.
| Parameter | Default | Description |
|---|---|---|
| Image Fit | fill |
fill — image covers the full drawing area; fit — scale to fit preserving aspect ratio; custom — explicit width/height in mm. |
| Width (mm) | 200 | Output width when Image Fit is custom. |
| Height (mm) | 200 | Output height when Image Fit is custom. |
| Offset X (mm) | 0 | Horizontal offset from the centred position (fit/custom modes). |
| Offset Y (mm) | 0 | Vertical offset from the centred position (fit/custom modes). |
| Parameter | Default | Range | Description |
|---|---|---|---|
| Threshold | 128 | 1–254 | Pixels darker than this value are treated as foreground and traced. Lower values trace only very dark regions; higher values trace more of the image. |
| Curve Tolerance (mm) | 0.2 | 0.01–5.0 | Bézier flattening tolerance. Smaller = smoother/more detailed polylines; larger = fewer points. |
| Despeckle | 2 | 0–500 | Suppress speckles and small regions (area in pixels). Increase to remove noise. |
| Corner Sharpness | 1.0 | 0.0–1.334 | Corner detection threshold. Lower → sharper corners; higher → rounder corners. |
| Optimize Tolerance | 0.2 | 0.0–1.0 | potrace's internal Bézier optimisation tolerance. Higher = fewer, coarser curves. |
| Parameter | Default | Range | Description |
|---|---|---|---|
| Tone Levels | 1 | 1–8 | Number of threshold levels to trace. 1 = single silhouette; >1 = one layer per tone band, thresholds spaced evenly from 32 up to the configured Threshold. |
Setting Tone Levels > 1 enables layered tonal tracing: the generator
computes N evenly-spaced threshold values between a dark anchor (~32) and the
configured Threshold, then runs potrace once per level. Each level is
returned as a separate LayerSpec and placed on its own canvas layer.
This is useful for pen-plotting portraits or photographs where you want different pens (or hatch densities) to represent different tonal zones.
Given num_levels = N and a configured threshold = T:
step = T // N
thresholds = [step, 2*step, …, N*step] # sorted, duplicates removed
For example, num_levels=4, threshold=200 → [50, 100, 150, 200].
Each generated layer is named Level N (thr=T) and assigned a colour from a
built-in palette so the layers are visually distinct in the layer panel. When
only one level is used the layer is named simply Trace.
The built-in Tonal Layers (4) preset uses:
threshold = 200
num_levels = 4
turdsize = 4 (suppress small speckles)
alphamax = 1.0
opttolerance = 0.2
curve_tolerance_mm = 0.3
image_fit_mode = fill
This preset works well for portrait photos and high-contrast illustrations.
| Preset | Description |
|---|---|
| Logo / Silhouette | Clean single-threshold trace of a high-contrast image. Best for logos, icons, and bold linework. |
| Tonal Layers (4) | Four threshold levels for shaded tonal output — assign a different pen to each layer. |
| Fine Detail | Tight curve tolerance (0.05 mm) and no despeckle for highly detailed artwork. |
| Vectorize / Trace Bitmap | Contour Lines | |
|---|---|---|
| Algorithm | potrace (Bézier curves → polylines) | Sub-pixel isoline extraction (OpenCV) |
| Extra dependency | pip install potracer (GPLv2) |
None (MIT) |
| Output style | Filled-shape outlines | Isovalue contour bands |
| Multi-layer tonal | Yes (Tone Levels param) | Yes (via Levels param) |
| Best for | Logos, silhouettes, clean linework | Halftone, topographic shading |
"The potracer package is required…"
Run pip install potracer in the same Python environment as Plottter.
Jagged or staircase outlines
Decrease Curve Tolerance (try 0.05–0.1 mm) or lower Corner Sharpness.
Too much noise / small speckles Increase Despeckle to 10–50.
Multi-level layers all look identical Lower the Threshold value so the tone bands are spread across the actual tonal range of the image, or increase the image contrast during preprocessing.