img2svg

A high-performance image to SVG converter written in Rust. Transform raster images (PNG, JPEG, etc.) into scalable vector graphics with advanced algorithms for color quantization, contour tracing, and path optimization.

Why img2svg?

The Problem

Converting raster images to vector format is essential for:

• Scalability: Vector graphics scale infinitely without quality loss
• File size optimization: Simple shapes often result in smaller SVG files than raster counterparts
• Editability: Vectors can be modified in design tools (Illustrator, Inkscape, Figma)
• Web performance: SVGs are code-based and can be optimized, animated, and styled with CSS

Why img2svg?

Key Advantages

1. Smart Color Quantization: Median-cut algorithm preserves visual quality while reducing colors
2. Sub-pixel Accuracy: Marching squares algorithm produces precise contours
3. Path Optimization: RDP simplification creates compact SVG files without losing detail
4. Flexible Usage: CLI tool, Rust library, and MCP server
5. Zero Dependencies: No external image processing libraries required

Installation

CLI Tool

# From crates.io
cargo install img2svg

# From source
git clone https://github.com/yingkitw/img2svg.git
cd img2svg
cargo install --path .

Library

Add to your Cargo.toml:

[dependencies]
img2svg = "0.1"

MCP Server

cd mcp-server
cargo install --path .

Usage

CLI Tool

# Basic conversion
img2svg -i input.png -o output.svg

# High-quality conversion with more colors
img2svg -i photo.jpg -o photo.svg -c 32 -s 7

# Simple logo with fewer colors
img2svg -i logo.png -o logo.svg -c 8 -s 2

# Batch convert multiple files
for img in *.png; do
    img2svg -i "$img" -o "${img%.png}.svg"
done

Options

Rust Library

use img2svg::{convert, ConversionOptions};
use std::path::Path;

// Simple conversion with defaults
let options = ConversionOptions::default();
convert(
    Path::new("input.png"),
    Path::new("output.svg"),
    &options
)?;

// Custom options for better quality
let options = ConversionOptions {
    num_colors: 32,
    smooth_level: 7,
    threshold: 0.05,
    ..Default::default()
};
convert(Path::new("photo.jpg"), Path::new("photo.svg"), &options)?;

// Low-detail conversion for simple graphics
let options = ConversionOptions {
    num_colors: 8,
    smooth_level: 2,
    ..Default::default()
};

MCP Server

The MCP (Model Context Protocol) server is built into the same codebase and allows AI assistants (like Claude Desktop) to convert images to SVG directly.

Installation

The MCP server binary is built automatically with the main project:

# Build both CLI and MCP server
cargo build --release

# Or install both binaries
cargo install --path .

The binaries will be:

• img2svg - CLI tool
• img2svg-mcp - MCP server

Configuration for Claude Desktop

Add to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "img2svg": {
      "command": "/path/to/img2svg-mcp",
      "args": []
    }
  }
}

Replace /path/to/img2svg-mcp with the full path to the installed binary:

• If installed via cargo install: Run which img2svg-mcp to find the path
• If built locally: Usually at target/release/img2svg-mcp

Usage

Once configured, restart Claude Desktop and use the tool directly in conversations:

"Convert the image at /path/to/logo.png to SVG with 8 colors"

The MCP server provides one tool:

• convert_image_to_svg: Converts raster images to SVG format
  • input_path (required): Path to input image
  • output_path (required): Path for output SVG
  • num_colors (optional): Number of colors (1-64, default: 16)
  • smooth_level (optional): Smoothing level (0-10, default: 5)
  • threshold (optional): Edge detection threshold (0.0-1.0, default: 0.1)

Algorithm

img2svg uses a sophisticated multi-stage pipeline:

1. Color Quantization: Median-cut algorithm reduces the palette while preserving color distribution
2. Pixel Grouping: Groups pixels by quantized color, sorted by area for proper z-order
3. Contour Tracing: Marching squares on per-color binary masks produces sub-pixel-accurate boundaries
4. Path Smoothing: Gaussian neighbor averaging reduces jaggedness without adding points
5. Path Simplification: Ramer-Douglas-Peucker algorithm reduces point count (epsilon=2.0)
6. Edge Snapping: Points near image boundaries are snapped to exact edges
7. SVG Generation: Background rect + one <path> per color with merged M...Z subpaths

Examples & Quality

The examples/ directory contains sample conversions demonstrating quality:

Simple Graphics (8 colors)

Input: examples/input/simple.png (50x50, basic shapes) Output: examples/output/simple.svg

• Command: img2svg -i simple.png -o simple.svg -c 8 -s 3
• Result: Clean vector shapes with perfect edges
• File size: Often smaller than original PNG

Gradients (16 colors)

Input: examples/input/gradient.png (100x100, smooth gradient) Output: examples/output/gradient.svg

• Command: img2svg -i gradient.png -o gradient.svg -c 16 -s 5
• Result: Smooth color transitions with banding minimized

Complex Illustrations (32 colors)

Input: examples/input/complex.png (200x200, detailed) Output: examples/output/complex.svg

• Command: img2svg -i complex.png -o complex.svg -c 32 -s 7
• Result: Preserves fine details while reducing complexity

Comparison with Alternatives

# ImageMagick trace (often produces jagged edges)
convert input.png svg:output-imagemagick.svg

# img2svg (smooth curves, better color accuracy)
img2svg -i input.png -o img2svg.svg -c 16 -s 5

Quality Differences:

• img2svg: Smooth curves, accurate colors, compact paths
• ImageMagick: Often produces jagged edges, limited color optimization
• Potrace: B&W only, requires pre-processing for color images

Performance

img2svg is optimized for speed and memory:

• Speed: Typical 1000x1000 image converts in <1 second
• Memory: Efficient streaming processing, suitable for large images
• Parallelization: Color quantization can be parallelized for large palettes

Benchmarks (1000x1000px image):

Tips for Best Results

For Logos and Icons

• Use fewer colors (8-16)
• Lower smoothing (2-4)
• Higher threshold (0.15-0.2)

For Photos

• More colors (32-64)
• Higher smoothing (6-10)
• Lower threshold (0.05-0.1)

For Illustrations

• Medium colors (16-32)
• Medium smoothing (4-6)
• Default threshold (0.1)

Limitations

• Best with images having clear color boundaries
• Photorealistic images may need higher color counts
• Very complex gradients may show some banding
• Extremely detailed images may produce large SVG files

Contributing

Contributions are welcome! Please see TODO.md for planned improvements.

License

Apache License 2.0 - see LICENSE for details.

Acknowledgments

• Median-cut algorithm: Paul Heckbert (1980)
• Marching squares: William E. Lorensen (1987)
• RDP algorithm: Ramer & Douglas & Peucker (1972-1973)