ADR 0003: Potrace and Sharp for the conversion pipeline

Decision: Potrace for tracing, Sharp for preprocessing. Why: Potrace is purpose-built for monochrome path extraction; Sharp is fast enough (~50 ms) for a real-time preview loop. Both are npm-native, no cross-platform binary packaging required.

Context

Two libraries sit at the heart of this app: one does raster-to-vector tracing (PNG → SVG paths), one does image preprocessing (decode, composite, greyscale, threshold, the inputs the tracer consumes). Picking them correctly is the most consequential technical decision in the project, everything else is UI and state around that pipeline.

Two constraints shaped the choice:

  1. Monochrome scope. v1 is committed to monochrome tracing (ADR 0013). Single fill colour, threshold-based conversion. Colour, if the user wants it, is a one-attribute edit on the output SVG, the file is XML, the fill is a string. This narrows the tracer field dramatically: I do not need a general-purpose vectoriser.
  2. Real-time preview latency budget. The preview updates as the user drags the threshold slider, not after they release it. Every frame of that live update runs the full preprocessing pipeline over the source PNG. That puts a hard cap on how long preprocessing can take per frame, roughly tens of milliseconds. A sluggish preprocess pass destroys the slider feel.

This ADR also closes a forward-reference from ADR 0001: the Electron runtime was chosen over Tauri in part because the Node ecosystem gives me Sharp and Potrace as first-class, npm-installable dependencies. Picking those libraries now is not an independent decision, it is the decision that the runtime choice anticipated.

Options considered

For tracing:

For image preprocessing:

Decision

Rationale

Why Potrace

Built for the problem. Potrace is not a generalist tracer. It is an algorithm designed from the outset for monochrome path extraction, with a published paper, a well-understood set of parameters (corner policy, curve optimisation, turd size), and decades of use in real-world tools (Inkscape’s Trace Bitmap, for example). At the scope ADR 0013 commits to, it is the most purpose-fit option.

Integration surface is minimal. npm install pulls a pure-ish JS port. The API is a buffer in, an SVG string out, running inline in the Node main process. No child processes, no platform-specific binaries, no build-time compilation step. That simplicity is worth real architectural points, every dependency that packs clean reduces the surface area of things that can go wrong at build and release time.

Rejected alternatives had concrete costs against them:

Why Sharp

Real-time preview is a UX requirement. When the user drags the threshold slider, they expect to see the vectorisation respond as they drag. Every intermediate value of the slider re-runs the preprocessing pipeline: flatten, optionally negate (ADR 0012), greyscale, threshold, encode. The budget for that pipeline to feel live is in the tens of milliseconds, well under 100 ms per frame.

Sharp, via libvips, does that pipeline in ~50 ms on typical inputs. Jimp, by comparison, measures in hundreds to low thousands of milliseconds, the slider would feel broken. Shell-out to ImageMagick or GraphicsMagick adds process-spawn overhead to every frame, which is catastrophic for a live interaction.

API fit matches the pipeline. Sharp’s method-chain shape (.flatten().negate().greyscale().threshold()) maps directly onto what ADR 0012’s inversion preprocessing requires.

Consequences

Positive

Negative

Follow-up

Code: src/main/services/ConversionService.ts, convertPngToSvg(), runSharpPreprocessPipeline()