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.
| Input (Original Raster) | Output (SVG) |
|---|---|
 |
 |
 |
 |
 |
 |
Try our image to color-by-number demo!
Important
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.
- 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.
| Language | Package Info |
|---|---|
 |
   |
 |
   |
 |
     |
 |
      |
This process is too detailed to put in a README.md file, so please see our documentation:
For more detailed information on installing this package, please refer to our documentation:
<!-- IMPORTANT: this is browser-only -->
<script src="https://cdn.jsdelivr.net/npm/img2num@0.2.0/dist/browser/img2num.js"></script>npm install img2numimport { imageToSvg } from "img2num";For more detailed information on installing this package, please refer to our documentation:
pip install img2numfrom img2num import image_to_svg
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:
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.
Thanks to all of our contributors - your impact on this project has been greatly appreciated!
