g@m8sh.su 5da27bc65f banner: regenerate with fidelity-tuned parameters
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.
2026-11-06 16:47:20 +03:00
2026-11-03 23:29:35 +00:00

govec banner — testdata/chill.png traced to SVG by this very library

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 and dlopened.
  • 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, poster and photo starting 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, so Trace is 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 crate govec-native: a thin C ABI (govec.h, six exported symbols) over the vtracer pipeline, built as a cdylib. The pipeline runs under catch_unwind, so Rust panics become GOVEC_ERR_PANIC errors instead of undefined behavior.
  • assets/lib/<goos>_<goarch>/ — prebuilt shared libraries (libgovec.so / govec.dll / libgovec.dylib), committed to the repository. Build-tagged go:embed files 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_LIBRARY environment 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).
  • vtracer and visioncortex (compiled into the vendored libraries): MIT OR Apache-2.0.
S
Description
Golang CPU image vectorization library.
Readme GPL-3.0
5.3 MiB
0 Stars 1 Watchers 0 Forks
Languages
Go 70.8%
Rust 14.2%
C 13.7%
Makefile 1.3%