vtracer

0.6.15 verified Mon Apr 27 auth: no python

Python bindings for the Rust Vtracer raster-to-vector library. Converts bitmap images (PNG, JPG, etc.) to SVG vector graphics with configurable color precision, gradient steps, and hierarchical clustering. Current version 0.6.15, requires Python >=3.7. Active development but infrequent releases.

pip install vtracer

Common errors

error ModuleNotFoundError: No module named 'vtracer' ↓

cause The package is not installed or installed incorrectly.

fix

Run 'pip install vtracer'. Ensure you are using the correct Python environment.

error vtracer.convert_image_to_svg_path() missing 1 required positional argument: 'output_path' ↓

cause The function signature changed; output_path is now required.

fix

Provide both input_path and output_path as positional arguments.

error OSError: [Errno 2] No such file or directory: 'input.png' ↓

cause The input file path is incorrect or file does not exist.

fix

Double-check the file path; use os.path.exists() to verify.

Warnings

gotcha colormode='binary' expects a grayscale image; color images will produce unexpected results. Use colormode='color' for color images. ↓

fix Ensure input is grayscale when using colormode='binary', or convert to grayscale first with Pillow.

gotcha The filter_speckle parameter only applies to binary mode. In color mode it is ignored. ↓

fix Use hierarchical parameters (layer_difference) to control noise in color mode.

breaking Before 0.5.0, the function was named 'convert_image' and had a different parameter set. The API was completely rewritten for 0.6.x. ↓

fix Update imports to use 'convert_image_to_svg_path' or 'convert_image_to_svg' and adjust parameters per current docs.

gotcha The library is a Python binding to a Rust binary; the Rust binary must be compatible with the Python wheel. Some platforms (e.g., ARM64 Linux) may not have precompiled wheels and will build from source via maturin, which requires Rust toolchain. ↓

fix Install Rust via rustup if building from source fails. Alternatively, use a supported platform or check for prebuilt wheels on PyPI.

Imports

convert_image_to_svg_path

wrong

import vtracer; vtracer.convert_image_to_svg_path

correct

from vtracer import convert_image_to_svg_path

The function is at module top level, not a submodule.

convert_image_to_svg
```
from vtracer import convert_image_to_svg
```
Alternative function that accepts similar parameters.

Quickstart

Converts a raster image to SVG with customizable vectorization parameters.

from vtracer import convert_image_to_svg_path

# Convert a PNG to SVG with default settings
input_path = 'input.png'
output_path = 'output.svg'
convert_image_to_svg_path(
    input_path,
    output_path,
    colormode='color',         # 'color' or 'binary'
    hierarchical='stacked',    # 'stacked' or 'cutout'
    mode='spline',             # 'spline' or 'polygon'
    filter_speckle=4,          # Remove speckles smaller than this
    color_precision=6,         # Color quantization bits (0-8)
    layer_difference=16,       # Merge layers if color diff ≤ this
    corner_threshold=60,       # Corner detection angle threshold
    length_threshold=4.0,      # Curve approximation threshold
    max_iterations=10,         # Max iterations per path
    splice_threshold=45,       # Splice detection angle
    path_precision=3           # Path simplification (0=lossless, 3=high quality)
)
print(f'Converted {input_path} to {output_path}')