img2num 0.2.1

A fast and accurate raster image to SVG conversion library

Img2Num

Img2Num is a fast and accurate raster vectorizer.

It converts raster images (like PNGs and JPGs) into clean SVGs with high accuracy and performance.

_{Img2Num is optimized for natural images.}

Contents

Before vs After Why Img2Num? Features Multi-Language Support Community Links

Quick Start License Can't find something? Maintainers Contributors & Credits

Before vs After

Input (Original Raster)	Output (SVG)

What are you waiting for?

Try our image to color-by-number demo!

[!IMPORTANT]

Why Img2Num?

Most raster-to-SVG vectorizers were designed for clean, synthetic input images such as logos, icons, diagrams, and flat illustrations. When applied to real-world photographs, they often struggle with noise, gradients, fine detail, and complex textures, resulting in less accurate vectorizations.

Img2Num takes the opposite approach. It was designed from the ground up for natural images, combining color quantization, contour extraction, and GPU-accelerated processing to produce high-quality SVGs from photographs while still performing well on synthetic artwork.

If your input images are photographs rather than logos or illustrations, Img2Num was built specifically for that use case.

_{What is Img2Num? Think of tools like Potrace or imagetracerjs, but designed with first-class support for natural photographs and other real-world imagery.}

Features

• Built for real-world photos - Designed from the ground up to handle natural, noisy raster images (photographs, scans, etc.), unlike many vectorization libraries that are optimized for clean, synthetic source images (icons, logos, flat illustrations).
• Raster to SVG vectorization - Converts PNG/JPEG images into clean, layered SVG paths using color quantization, contour tracing, and an integrated SVG writer.
• GPU-accelerated processing - Leverages Dawn (Google's WebGPU implementation) for hardware-accelerated quantization and image processing.
• Color quantization & palette control - Reduce an image to any K number of colors (K-Means), with output SVGs organized into logical color groups.
• Precise contour extraction - Edge detection and polygon simplification with tunable fidelity for accuracy vs. performance trade-offs.
• Multi-language bindings - Native C++17 core with first-class bindings for:
  • C - lightweight C API (add as a submodule)
  • Python (pip install img2num) - NumPy arrays in, SVG strings out
  • JavaScript (npm i img2num) - same C++ core compiled to WebAssembly, works in browser and Node
• Zero-copy bindings - Direct memory access via NumPy in Python and TypedArrays in JS, avoiding unnecessary data copying.
• Minimal dependencies - Core library built for speed with only one external runtime dependency (Google's Dawn).
• Cross-platform CI - Tested on Linux, macOS, Windows, and WASM.
• Flexible distribution - Available via PyPI, npm, and Docker Hub.
• Permissive licensing - MIT-licensed core (libraries, packages, build tools), with AGPLv3 covering docs, example apps, and CI/config - see below for details.

Multi-Language Support

Language	Package Info

Community Links

Quick Start

C / C++

This process is too detailed to put in a README.md file, so please see our documentation:

• Documentation
• Documentation

[!TIP] You can install the library from our GitHub releases:

• C
• C++

JavaScript

For more detailed information on installing this package, please refer to our documentation:

CDN

<!-- IMPORTANT: this is browser-only -->
<script src="https://cdn.jsdelivr.net/npm/img2num@0.2.0/dist/browser/img2num.js"></script>

Package Manager

Install Img2Num from npm

npm install img2num

Import the Img2Num package

import { imageToSvg } from "img2num";

Python

For more detailed information on installing this package, please refer to our documentation:

Install Img2Num using pip

pip install img2num

Import Img2Num

from img2num import image_to_svg

License

The library is MIT-licensed

Prior to the refactor in #250, the entire project was licensed under AGPLv3. The core library was relicensed to MIT to make it easier to embed in commercial and closed-source projects, while documentation, example apps, and CI/config retained AGPLv3 to discourage unattributed reuse of project infrastructure that isn't part of the redistributable library itself.

Subdirectories retain their own licenses:

• docs/
• example-apps/react-js/
• .github/

Can't find something?

If you need something, see our documentation.

If you can't find it, feel free to open an issue to request assistance with finding or creating what you need.

Maintainers

[!NOTE]

Maintainers wanted

We’re looking for new maintainers. Read more here.

Contributors & Credits

Thanks to all of our contributors - your impact on this project has been greatly appreciated!