Logo # 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**. ![Status](https://img.shields.io/badge/status-active_development-brightgreen?logo=github) [![Deploy to GitHub Pages](https://github.com/Ryan-Millard/Img2Num/actions/workflows/deploy.yml/badge.svg)](https://github.com/Ryan-Millard/Img2Num/actions/workflows/deploy.yml) [![Multi-Language Release Generation](https://github.com/Ryan-Millard/Img2Num/actions/workflows/release.yml/badge.svg)](https://github.com/Ryan-Millard/Img2Num/actions/workflows/release.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Ryan-Millard/Img2Num/blob/main/LICENSE) [![Contributors](https://img.shields.io/github/contributors/Ryan-Millard/Img2Num)](https://github.com/Ryan-Millard/Img2Num/graphs/contributors) [![Stars](https://img.shields.io/github/stars/Ryan-Millard/Img2Num?style=social)](https://github.com/Ryan-Millard/Img2Num) [![Docker Pulls](https://img.shields.io/docker/pulls/ryanmillard/img2num-dev)](https://hub.docker.com/repository/docker/ryanmillard/img2num-dev/general) [![Open in Codespaces](https://img.shields.io/badge/-Open%20in%20Codespaces-black?logo=github)](https://codespaces.new/Ryan-Millard/Img2Num) [![Docs](https://img.shields.io/badge/docs-full-blue?logo=gitbook&logoColor=white)](https://ryan-millard.github.io/Img2Num/docs/) [![Changelog](https://img.shields.io/badge/changelog-full-orange?logo=git&logoColor=white)](https://ryan-millard.github.io/Img2Num/changelog/) ## Contents
- [Before vs After](#before-vs-after) - [Why Img2Num?](#why-img2num) - [Features](#features) - [Multi-Language Support](#multi-language-support) - [Community Links](#community-links) - [Supported Runtimes](#supported-runtimes) - [Installation](#installation) - [Browser Usage (CDN)](#browser-usage-cdn) - [Quick Start](#quick-start) - [API Reference](#api-reference) - [Navigating WebAssembly](#navigating-webassembly) - [Examples](#examples)
## Before vs After | Input (Original Raster) | Output (SVG) | |----------|------------------| | Original input raster image (Aerial view of mountains) | Final output SVG image (Aerial view of mountains) | | Original input raster image (A garden in Margate, South Africa) | Final output SVG image (A garden in Margate, South Africa) | | Original input raster image (A ring on a woman's hand) | Final output SVG image (A ring on a woman's hand) | ### What are you waiting for? Try our [image to color-by-number demo](https://ryan-millard.github.io/Img2Num/example-apps/react-js/)!
> [!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](https://potrace.sourceforge.net/) or [imagetracerjs](https://github.com/jankovicsandras/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](https://dawn.googlesource.com/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**](#multi-language-support) - 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 - **WebAssembly-powered** - The native C++ core is compiled to WebAssembly (WASM) for high-performance execution in browsers. - **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](https://dawn.googlesource.com/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](#license) for details. ## Multi-Language Support | Language | Package Info | |-----------:|:------------| | | [![Docs](https://img.shields.io/badge/docs-C-A8B9CC?logo=gitbook&logoColor=white)](https://ryan-millard.github.io/Img2Num/docs/c/) [![C Changelog](https://img.shields.io/badge/changelog-C-A8B9CC?logo=c)](https://ryan-millard.github.io/Img2Num/changelog/c/) | | | [![Docs](https://img.shields.io/badge/docs-C++-00599C?logo=gitbook&logoColor=white)](https://ryan-millard.github.io/Img2Num/docs/cpp/) [![C++ Changelog](https://img.shields.io/badge/changelog-C%2B%2B-00599C?logo=c%2B%2B&logoColor=white)](https://ryan-millard.github.io/Img2Num/changelog/cpp/) | | | [![npm](https://img.shields.io/npm/v/img2num?logo=npm)](https://www.npmjs.com/package/img2num) ![Downloads](https://img.shields.io/npm/dm/img2num?logo=npm) [![Docs](https://img.shields.io/badge/docs-JavaScript-F7DF1E?logo=gitbook&logoColor=white)](https://ryan-millard.github.io/Img2Num/docs/js/) [![JavaScript Changelog](https://img.shields.io/badge/changelog-JavaScript-F7DF1E?logo=javascript)](https://ryan-millard.github.io/Img2Num/changelog/js/) | | | ![PyPI](https://img.shields.io/pypi/v/img2num?logo=pypi) [![PyPI Downloads](https://img.shields.io/pypi/dm/img2num?logo=pypi)](https://pypi.org/project/img2num/) [![Supported Versions](https://img.shields.io/pypi/pyversions/img2num?logo=python)](https://pypi.org/project/img2num/) [![Docs](https://img.shields.io/badge/docs-Python-3776AB?logo=gitbook&logoColor=white)](https://ryan-millard.github.io/Img2Num/docs/py/) [![Python Changelog](https://img.shields.io/badge/changelog-Python-3776AB?logo=python)](https://ryan-millard.github.io/Img2Num/changelog/py/) | ## Community Links [![Changelog](https://img.shields.io/badge/Changelog-Full-orange?logo=git&logoColor=white)](https://ryan-millard.github.io/Img2Num/changelog/) [![Contributing](https://img.shields.io/badge/Contributing-Guide-blue?logo=github)](https://github.com/Ryan-Millard/Img2Num/blob/main/CONTRIBUTING.md) [![Issues](https://img.shields.io/badge/Issues-Available-brightgreen?logo=github)](https://github.com/Ryan-Millard/Img2Num/issues/views/1151) [![Good First Issues](https://img.shields.io/badge/Good%20First%20Issues-Welcome-6cc644?logo=github)](https://github.com/Ryan-Millard/Img2Num/issues/views/1155) [![Blog](https://img.shields.io/badge/Blog-Updates-ff6f00?logo=githubpages)](https://ryan-millard.github.io/Img2Num/blog/) [![GitHub Discussions](https://img.shields.io/badge/discussions-join_the_chat-4c1?logo=github)](https://github.com/Ryan-Millard/Img2Num/discussions) ## Supported Runtimes ![Browsers](https://img.shields.io/badge/Browsers-Modern_Browsers-4CAF50?logo=googlechrome&logoColor=white) ![Node.js](https://img.shields.io/badge/Node.js-%3E%3D14-339933?logo=nodedotjs&logoColor=white) > [!CAUTION] > This package currently supports **ESM only.** [#483](https://github.com/Ryan-Millard/Img2Num/issues/483) tracks this fix. ## Installation ```bash npm install img2num ``` ```bash pnpm add img2num ``` ```bash yarn add img2num ``` ```bash bun add img2num ``` ## Browser Usage (CDN) > [!IMPORTANT] > This approach only works in Browsers. ### jsDelivr CDN [![jsDelivr](https://img.shields.io/badge/CDN-jsDelivr-ff5627?logo=jsdelivr&logoColor=white)](https://www.jsdelivr.com/package/npm/img2num) ```html ``` ### unpkg CDN [![unpkg](https://img.shields.io/badge/CDN-unpkg-red?logo=npm&logoColor=white)](https://app.unpkg.com/img2num@0.2.0) ```html ``` ## Quick Start ### All-in-one (recommended) ```js import { imageToUint8ClampedArray, imageToSvg } from "img2num"; // Browsers: const { pixels, width, height } = await imageToUint8ClampedArray(file); // Node.js equivalent: // const { data, info } = await sharp(imagePath).ensureAlpha().raw().toBuffer({ resolveWithObject: true }); // const { width, height } = info; const { svg } = await imageToSvg({ pixels, width, height }); ``` > [!NOTE] > `imageToUint8ClampedArray` uses browser APIs (`Image`, `canvas`) and is only available in browser environments. In Node.js, use a library like [`sharp`](https://www.npmjs.com/package/sharp) to decode images to a `Uint8ClampedArray` in RGBA format before passing to the WASM functions. ## API Reference All WebAssembly-backed functions are `async` and return Promises. For full details see the [JavaScript API reference](https://ryan-millard.github.io/Img2Num/docs/js/api/). --- ## Navigating WebAssembly This package ships a `.wasm` binary and a worker file. The library automatically selects the correct worker implementation for your runtime — browser Web Workers or Node.js `worker_threads`. Some bundlers need extra configuration to handle `.wasm` assets correctly: - **Vite** — add to `vite.config.js`: ```js assetsInclude: ["**/*.wasm"] ``` - **Webpack 5** — enable `asyncWebAssembly: true` in `experiments`. - **Other bundlers** — if you run into issues, please [open an issue](https://github.com/Ryan-Millard/Img2Num/issues) so we can document the solution and help others facing the same problem. We actively welcome contributions to this section — if you've configured a bundler not listed here, please open a PR to add it to our [documentation](https://ryan-millard.github.io/Img2Num/docs/). ## Examples - **React** color-by-number website: [`example-apps/react-js`](https://github.com/Ryan-Millard/Img2Num/tree/main/example-apps/react-js) - **Node.js** console app: [`example-apps/console-js`](https://github.com/Ryan-Millard/Img2Num/tree/main/example-apps/console-js) Try the [live demo (`React example`)](https://ryan-millard.github.io/Img2Num/example-apps/react-js/). > **Have a cool idea or want to showcase a new environment?💡** > We welcome new [example apps](https://github.com/Ryan-Millard/Img2Num/tree/main/example-apps). ## License [MIT](https://github.com/Ryan-Millard/Img2Num/blob/main/LICENSE) © Ryan Millard ---

GitHub · Documentation · Changelog · Issues · Discussions · Blog

Contributors