Running GetVect

Getting started

Clone, install, start

Not building from source? Take the dmg from the latest release — macOS on Apple Silicon, signed and notarized, with platform notes on the download section of the front page.

To build it yourself you need 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

Presets and candidate palettes rather than a wall of generic sliders, so the control you reach for matches the kind of image you are converting.

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

GetVect has two network touchpoints, both in your control: AI Enhance, and a once-per-launch update check against GitHub Releases (disable with GETVECT_NO_UPDATE_CHECK=1). AI Enhance is the only one that sends anything — your image, to Google, under your own key. 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.

Updates

It tells you. It does not install.

Once per launch, GetVect asks GitHub Releases whether there is a newer version. If there is, a small dismissible banner appears in the corner with a Download link; dismiss it and that version never asks again. Nothing is downloaded in the background and nothing is installed behind your back.

On macOS that changes from v0.1.4. Squirrel — the machinery Electron apps update through — checks the replacement's signature against the running app's, and on a signed build that check passes. So the app downloads in the background and then offers Restart; choosing it exchanges the bundle and reopens on the new version. It is never installed without you asking. What it downloads is the -mac.zip named in latest-mac.yml, and it refuses to install anything whose sha512 does not match the digest in that file; both the digest and the signature on the app inside are checked by the release pipeline before publishing, and again against the asset re-downloaded afterwards.

Windows keeps notifying until there is an Authenticode certificate. An updater that pulls 117 MB and then fails at a verification step it cannot pass is worse than no updater at all.

v0.1.3 notifies on both platforms; installing itself starts with the build after it. On either platform GETVECT_NO_UPDATE_CHECK=1 stops the whole thing before any request is made — not just the banner, the check.

The check sends no identifier, asks one question, and fails silently when you are offline. To turn it off:

GETVECT_NO_UPDATE_CHECK=1 open -a GetVect
# or, permanently:
launchctl setenv GETVECT_NO_UPDATE_CHECK 1

Along with AI Enhance, that is the complete list of things this app does on a network: two touchpoints, both in your control.

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 benchmark web vectorizer's 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.

Is it signed?

macOS: yes, since v0.1.3. The dmg is signed with an Apple Developer ID and notarized by Apple, with the ticket stapled, so it opens with no Gatekeeper warning and the check works offline. Verify it yourself with spctl -a -t install -vv GetVect-0.1.3-arm64.dmg — it answers accepted / source=Notarized Developer ID — and codesign -dvvv shows Team ID 6UV93L24YL.

Windows: not yet. There is no Authenticode certificate, so SmartScreen warns on first launch. It is one-time and the steps below clear it.

What it sends: a once-per-launch check for a newer version (opt out with GETVECT_NO_UPDATE_CHECK=1), and, only if you turn it on, AI Enhance under your own API key. Nothing else leaves your machine.

"GetVect is damaged and can't be opened"

The published dmg should not produce this any more — since v0.1.3 it is signed and notarized, and spctl -a -t install -vv on it answers accepted. If you see it, check which build you have first:

spctl -a -vv /Applications/GetVect.app

A v0.1.2 or earlier download is genuinely unsigned; the fix is to get the current release rather than to work around it. A build from npm run dist is unsigned on purpose and will always do this — that one is yours, so removing the quarantine attribute is reasonable:

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

Only ever do that for a bundle you built yourself. For a downloaded one, the point of a signature is that you should not have to.

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. On Windows the engine contracts run in CI before every release; the full Electron acceptance suite is driven on macOS only.

Removing GetVect completely

macOS: drag GetVect.app out of Applications, then remove the state the app created (settings, and the encrypted AI key if you saved one):

rm -rf ~/Library/Application\ Support/GetVect
rm -rf ~/Library/Caches/getvect-updater

Windows: Settings → Apps → GetVect → Uninstall. The uninstaller removes the app, the Start Menu entry and its registry key, but leaves two things behind — measured, not guessed:

Remove-Item -Recurse "$env:APPDATA\GetVect"
Remove-Item -Recurse "$env:LOCALAPPDATA\getvect-updater"

The second one is a ~100 MB cached copy of the installer that the install itself creates and the uninstaller does not clean up. Until that is fixed, these two lines are the difference between "uninstalled" and "gone".

Going deeper

The documents this page is a summary of