Running GetVect

Getting started

Clone, install, start

Requires Node 20+ and, for now, macOS. Linux needs xvfb-run -a for the Electron tests; Windows is untested.

git clone https://github.com/craigjmidwinter/getvect.git
cd getvect
npm install     # postinstall de-quarantines + ad-hoc-signs the Electron binary
npm start       # build + launch
npm run dist    # package -> release/mac-arm64/GetVect.app (+ dmg, zip)

npm start always builds the real bundle and launches it. npm run dev runs the Vite dev server with renderer hot reload — good for iteration, and never what the test suite exercises.

npm run dist builds unsigned on purpose: that is right for running your own build and wrong for distribution. The packaging config is electron-builder.yml; the signing and notarization notes are in PUBLISH-CHECKLIST.md.

Using it

• Drop a PNG, JPEG or BMP onto the window, or use the file picker. Anything else is refused with a message that says why.
• Tracing starts automatically on load with the defaults — Clipart, 8 colours, Smart anti-aliasing — and runs off the UI thread with visible progress.
• Load several images: they stack in the sidebar and selecting one switches the workspace to it. Settings are per image.
• Change any setting and the trace re-runs. The preview you are looking at is the SVG that will be exported.

Control surface

Every control on the panel

The settings model is the real product's, captured live rather than guessed: model presets and candidate palettes, not detail/smoothing/despeckle sliders.

Model presets

Input palette

• Candidate palettes are computed from the image and offered at eleven fixed sizes — 1, 2, 3, 4, 5, 6, 8, 12, 15, 16, 18 — as selectable rows, so you pick a palette you can see rather than a number.
• The palette editor can recolour a swatch, merge two swatches, or remove one. Recolouring repaints regions and leaves the geometry byte-identical; an edit is matched against the engine's colour slots, so a merge survives the next setting change.
• Restore puts back the computed palette and the candidate size your edit replaced.
• The colour-count hint says whether a shortfall came from the image (it does not contain that many colours) or from your settings (a cleanup pass merged some) — it will not blame the picture for the app's own fold.

Output colour groups

• Per-colour toggle — switch a colour off and it is omitted from the output entirely. Switching off the background colour is how you get a transparent background; there is no separate transparency mode.
• Merge threshold — percent coverage below which a colour group folds into its neighbour. Set it to 0 to turn the fold off completely (it is your control, and nothing else raises it behind your back).
• Sort order — coverage, brightness or hue. This is the order the layers appear in, in the panel and in the exported SVG.

Quality

Advanced vectorization

Preview

• Original/vector toggle and side-by-side mode.
• Zoom in, out and fit, plus pan — synchronised across both panes, so the crop you are judging is the same crop in both.
• The vector pane is the exported SVG itself, not a re-render of it. That is enforced by a test that exports through the UI and compares it byte-for-byte with the engine run headlessly on the same file.

Export

Five formats, through the native save dialog

Every export goes through the real macOS save dialog with a sensible default filename derived from the image. Nothing is written anywhere else.

A DXF that flattens every fitted cubic into vertex runs is roughly 12× the EPS of the same drawing; the spline variant lands at about 2.2×. If your machine can read splines, keep the default.

AI Enhance

Optional, off by default, bring your own key

AI Enhance is the only thing in GetVect that can touch the network. Everything else runs under a default-src 'self' content security policy with no runtime network calls at all.

Setup

• Get a key from Google AI Studio.
• Paste it into the AI Enhance group in the settings panel and press Save key. The status beside it reads "Key saved" — a boolean, never the value.
• Switch on Enhance with AI before tracing. The toggle is inert until a key exists.
• Clear deletes the stored key from the machine.

Quality tiers

How the key is handled

• Encrypted at rest with Electron's safeStorage (Keychain on macOS) inside the app's data directory.
• It lives only in the main process and is never returned to the UI. The interface can save one, clear one, and ask whether one exists — there is no IPC that hands back key material.
• If the OS has no keystore available, GetVect refuses to store a key rather than writing it in the clear, and says so.

When a run fails

A bad key, no network, or the 60-second timeout each fall back to tracing the un-enhanced image, and the app names the reason — an authentication failure, a rate limit, a timeout. There is no state where the app hangs waiting for a model.

One thing worth knowing: Gemini returns RGB even when asked for transparency, so an enhanced image can come back flattened. GetVect never fabricates an alpha channel to cover that up.

Debugging a bad result

Set GETVECT_AI_DEBUG_DIR before launching and every successful enhance writes its exact input, its output and a small metadata file (provider, model, tier, duration, byte counts) into that directory, so a disappointing result can be inspected after the fact.

GETVECT_AI_DEBUG_DIR=/tmp/getvect-ai npm start

It is off unless the variable is set, because those are your images being written to disk.

Testing & instruments

The three layers that grade this app

npm test              # engine contract tests, then the Playwright acceptance suite
npm run test:engine   # just the engine contracts (pure Node, no Electron)
npm run instruments   # fidelity metrics -> artifacts/metrics.json
npm run screenshots   # a labelled contact sheet of the whole flow

• Acceptance suite — Playwright driving the packaged Electron app, one spec file per reference checklist section, every test title prefixed with its id ([A1]…[D5]). Selectors are data-testid only.
• Engine contracts — node --test over the pure tracing engine: determinism, setting semantics, SVG/EPS/DXF/PDF structure, alpha handling, and rasterized checks that the picture actually changed.
• Instruments — the light meter. For every fixture it traces, rasterizes the SVG back to source dimensions and diffs: mean colour error, structural similarity, ink recall, sub-path count, speck ratio, curve ratio, stroke-width evenness, and ratios against the real vectorizer.io output of the same source.

Do not read artifacts/metrics.json whole — the stdout table is the interface, and the file is meant to be queried with jq.

Troubleshooting

When macOS gets in the way

spawn …/Electron ENOENT on a file that was just there

XProtect deleted the unsigned Electron binary out of node_modules. This is the single most common first-run failure. Re-run the repair hook:

npm run postinstall

It re-fetches if needed, strips com.apple.quarantine and applies an ad-hoc signature. An environment fix that lives in one shell session is not a fix, which is why this is a hook rather than a note.

"GetVect is damaged and can't be opened"

A packaged build from npm run dist is unsigned and not notarized. A downloaded unsigned app is quarantined, and on Apple Silicon Gatekeeper refuses it outright rather than offering the right-click → Open escape hatch. Remove the quarantine attribute yourself:

xattr -dr com.apple.quarantine /Applications/GetVect.app

Only do that for a bundle you built yourself, or one whose provenance you trust.

The Photo preset ignores my colour count

It has a colour floor of 16. Ask for 4 and you will get 10–16; the panel will not display a number the engine is not going to use.

I asked for 8 colours and got 5

Check the colour-count hint. Either the image genuinely does not contain that many distinct colours, or the merge threshold folded near-duplicates. Drag Merge threshold to 0 to turn the fold off — it is the only thing that merges colour groups, and nothing raises it behind your back.

Tests fail on Linux

Electron needs a display. Run the suite under xvfb-run -a. Windows is untested.

Going deeper

The documents this page is a summary of