The old banner (photo preset, simplify 3.5, precision 1) was the lowest-fidelity variant measurable. Rasterized and compared per-pixel against the original, the new sweet spot is: -preset poster -hierarchical cutout -path-precision 2 -optimize 2 MAE 15.57 -> 8.94, PSNR 17.4 -> 22.7 dB, visibly-off pixels (delta > 16) 23.4% -> 15.9%, 13067 seam-free paths. poster keeps full 8-bit color precision; the cutout mosaic fits each shared boundary once so stacked shapes no longer crack apart; layer difference 8 and filter-speckle 0 were measured and rejected (noise splitting, 356k paths). make banner now reproduces the tuned command.
govec
Go image vectorization library — raster to SVG — built on VTracer. The Rust engine is compiled to a C-compatible shared library, embedded into your binary and loaded on first use: import the package and go, no system packages, no cargo, no runtime setup.
It runs on the standard library image interfaces: any image.Image in
(precisely decoded PNG/JPEG/GIF or anything else you can construct),
SVG documents out as plain bytes — io.WriterTo, String(),
WriteFile(), whatever fits.
Features
- Fully embedded: the govec-native cdylib (vtracer 1.0.0-alpha.4,
statically including the whole pipeline) is baked into your binary via
go:embed, selected per build platform; it is extracted to the user cache directory once anddlopened. - The full VTracer pipeline: color / binary / watershed clustering, stacked or seam-free cutout compositing, pixel / polygon / spline fitting, fixed palettes, auto color quantization, curve simplification, adaptive (Bradley–Roth) thresholding, output optimization levels.
- Presets: VTracer's own
default,bw,posterandphotostarting points, translated by the native library itself so the defaults can never drift. - Panic-safe FFI: the Rust boundary runs under
catch_unwind; a bug inside the pipeline surfaces as a Go error instead of killing your process. The pipeline is pure per-call, soTraceis safe for concurrent use. - Standard library only on the Go side — zero dependencies.
Platforms
| Platform | Arch | Status |
|---|---|---|
linux/amd64 |
x86_64 | ✅ embedded, tested |
linux/arm64 |
AArch64 | ✅ embedded (built with cargo-zigbuild) |
windows/amd64 |
x86_64 | ✅ embedded (built with cargo-zigbuild) |
darwin/arm64 |
Apple Silicon | 🔌 make libs on a Mac, then GOVEC_LIBRARY (embed lands via .github/workflows/build-libs.yml on a GitHub mirror) |
darwin/amd64 |
x86_64 | 🔌 same as above |
| anything else | — | 🔌 bring your own library: GOVEC_LIBRARY |
Install
go get m8sh.su/x/govec
Requires CGO and a C compiler:
# arch/manjaro
sudo pacman -S gcc
# debian/ubuntu
sudo apt install gcc
Usage
One-liner — any image.Image in, *govec.SVG out:
svg, err := govec.Trace(img) // default pipeline
From a file, it is plain standard library:
f, _ := os.Open("input.png")
img, _, err := image.Decode(f) // import _ "image/png" etc.
f.Close()
svg, err := govec.Trace(img, govec.WithPreset(govec.PresetPhoto))
out, _ := os.Create("out.svg")
svg.WriteTo(out)
Options
Options are applied left to right over the base chosen by the (last)
WithPreset; the library validates everything and fails fast with a
Go error:
svg, err := govec.Trace(img,
govec.WithPreset(govec.PresetPhoto), // start from the photo preset
govec.WithMode(govec.FitPolygon), // ...but with straight edges
govec.WithMaxColors(8), // ...and at most 8 colors
govec.WithSimplify(1.5), // paper.js-style curve simplify
)
Already have decoded RGBA pixels? Skip the conversion:
svg, err := govec.TracePixels(pixels, width, height, opts...)
The complete option set, mirroring VTracer's configuration:
| Option | Meaning | Default |
|---|---|---|
WithPreset(p) |
base config: PresetDefault, PresetBw, PresetPoster, PresetPhoto |
default |
WithClustering(c) |
region forming: ClusterColor, ClusterBinary, ClusterWatershed |
color |
WithHierarchical(h) |
Stacked layers or seam-free Cutout mosaic |
stacked |
WithMode(m) |
curve fitting: FitPixel, FitPolygon, FitSpline |
spline |
WithFilterSpeckle(n) |
speckle filter side length (area = n²) | preset |
WithColorPrecision(n) |
significant bits per RGB channel, 1..=8 | preset |
WithLayerDifference(n) |
color difference between gradient layers | preset |
WithCornerThreshold(deg) |
degrees above which a corner stays sharp | preset |
WithLengthThreshold(px) |
minimum spline segment length | preset |
WithMaxIterations(n) |
least-squares refinement iterations | preset |
WithSpliceThreshold(deg) |
tangent difference below which segments join | preset |
WithSimplify(tol) / WithoutSimplify() |
paper.js-style curve simplification (spline mode) | off |
WithPathPrecision(dp) / WithoutPathPrecision() |
output coordinate decimal places | preset |
WithPalette(cs...) |
fixed output palette (wins over WithMaxColors) |
none |
WithMaxColors(n) |
auto-quantize to at most n colors | off |
WithOptimize(level) |
0 = off, 1 = quantize+cleanup, 2 = +shorthands/grouping | 1 |
WithBinaryThreshold(t) |
binary clustering fixed cutoff 0..=255 | 128 |
WithBinaryAdaptive() |
Bradley–Roth adaptive thresholding (binary mode) | off |
WithAdaptiveWindow(px) |
adaptive window side, 0 = auto (~⅛ short side) | 0 |
WithAdaptiveT(t) |
adaptive sensitivity, % below local mean | 15 |
WithWatershedDetail(d) |
watershed hierarchy cut point | 128 |
API
Trace(img image.Image, opts ...Option) (*SVG, error) |
vectorize any image |
TracePixels(pixels []byte, w, h int, opts ...Option) (*SVG, error) |
vectorize raw RGBA8 |
(*SVG).Bytes() / .String() / .Len() / .NumPaths() |
the document |
(*SVG).WriteTo(io.Writer) |
io.WriterTo |
(*SVG).WriteFile(path) |
write to disk (0644) |
Version() (lib, vtracer string, err error) |
loaded govec-native + vtracer versions |
CLI demo
go run ./cmd/govec -o out.svg input.png # defaults
go run ./cmd/govec -preset photo -simplify 1.5 in.jpg # photographic input
go run ./cmd/govec -clustering binary in.png # line art / stencils
go run ./cmd/govec -clustering binary -binary-adaptive scan.png
go run ./cmd/govec -mode polygon -max-colors 8 in.png # flat 8-color poster
go run ./cmd/govec -hierarchical cutout -palette 1b1b1b,e0c088 in.png
go run ./cmd/govec -mode pixel pixelart.gif # pixel art, no smoothing
How the embedding works
native/— the Rust crategovec-native: a thin C ABI (govec.h, six exported symbols) over the vtracer pipeline, built as a cdylib. The pipeline runs undercatch_unwind, so Rust panics becomeGOVEC_ERR_PANICerrors instead of undefined behavior.assets/lib/<goos>_<goarch>/— prebuilt shared libraries (libgovec.so/govec.dll/libgovec.dylib), committed to the repository. Build-taggedgo:embedfiles bake exactly the one for the build target into your binary.- Since shared libraries cannot be
dlopened straight from memory, the bytes are extracted once into the user cache dir (os.UserCacheDir()/govec/govec-native-<hash>/) and loaded from there; subsequent runs reuse the file. - Library resolution order:
GOVEC_LIBRARYenvironment variable → embedded platform library. - The Go side asks the library for its own default/preset
configurations (
govec_default_config/govec_preset_config), so VTracer's defaults are never duplicated in Go.
Performance
CPU-only, roughly: a 1670×941 photograph traces in ~7 s with the photo
preset at full color precision, ~1.5 s with -simplify 1.5, and binary
line art of the same size in ~0.2 s. Trace is safe for concurrent use;
parallel calls scale across cores.
Building from source
Rebuild the vendored shared libraries with:
make libs # or: go run cmd/build/main.go
The script needs the Rust toolchain (rustup.rs) and builds every
target the host can produce: linux/amd64 natively; linux/arm64 and
windows/amd64 via cargo-zigbuild
(cargo install cargo-zigbuild, plus zig on PATH — e.g.
python3 -m pip install ziglang behind a zig wrapper) on Linux;
darwin targets on a macOS host. Missing toolchains are skipped with a
notice. .github/workflows/build-libs.yml reproduces the full matrix
on CI runners and commits the darwin artifacts.
Tests
go test ./... # full suite, includes testdata/chill.png (1670x941)
go test -short ./... # skip the full-resolution trace
go test -cover ./... # statement coverage
Licensing
- Code in this repository: GNU GPL-3.0 (see
LICENSE). vtracerandvisioncortex(compiled into the vendored libraries): MIT OR Apache-2.0.