Img2Num FAQ

Find answers to common questions about Img2Num, including what it is, raster-to-SVG image vectorization, installation, supported languages, usage, troubleshooting, and contributing.

General​

What is Img2Num?​

Img2Num is an open-source raster-to-SVG vectorization library. It converts raster images such as PNG and JPEG files into clean, scalable SVG graphics made from flat color regions.

Unlike many image vectorization libraries that primarily target synthetic or computer-generated images, Img2Num has first-class support for natural images captured with a camera.

The core library is written in C++ and provides official bindings for C, Python, and JavaScript/WebAssembly, allowing Img2Num to be used in native applications, scripts, servers, Node.js, and web browsers.

What is raster-to-SVG vectorization?​

Raster-to-SVG vectorization is the process of converting a pixel-based raster image into a vector image made from scalable mathematical shapes called paths.

How does Img2Num vectorize an image?​

A raster image consists of pixels, while an SVG consists of scalable vector paths.

Img2Num converts raster images by:

1. Quantizing image colors into a smaller palette using k-means clustering.
2. Tracing the boundaries of color regions using Suzuki–Abe contour tracing.
3. Smoothing the resulting contours using Savitzky–Golay filtering.
4. Generating clean SVG paths from the processed regions.

The resulting SVG can scale to different sizes without pixelation and can often be significantly smaller than the original raster image.

Is Img2Num free and open source?​

Yes, Img2Num is free and open source.

What license is Img2Num under?​

What happened to the color-by-number app?​

Img2Num originally started as a browser-based color-by-number application. Early in development, it became clear that the underlying image-processing engine was the more reusable part of the project. The project therefore evolved into a general-purpose image vectorization library that can be embedded into other applications.

Some older documentation, blog posts, and screenshots still reference the original app. If you find something that is misleading, you can open an issue on GitHub.

The color-by-number app still exists as an example application demonstrating the library. You can find it in the Img2Num React.js example app along with other Img2Num example applications.

Who maintains Img2Num, and how can I support the project?​

Img2Num is maintained by Ryan Millard with co-maintainers Alex Krasner and Prachi Gupta. You can support the project by starring the repository, reporting bugs, contributing pull requests, or sponsoring on GitHub.

Installation & Package Selection​

Which languages and platforms does Img2Num support?​

• C: A stable C ABI wrapper around the core library.
• C++: The core library, consumable via CMake.
• Python: Installable with pip install img2num, with prebuilt wheels for major platforms and full type stubs (.pyi + py.typed).
• JavaScript/TypeScript: Installable with npm install img2num; the package uses WebAssembly and can run in browsers and Node.js.

Which package should I use for my project?​

• Websites or Web Apps: Use the npm package which runs entirely client-side and does not require a server.
• Scripts, Data Pipelines or Research: Use the Python package.
• Native Applications: Use the C++ core or C bindings for ABI stability or binding Img2Num from another language.

How do I install the Python package? Which Python versions and platforms are supported?​

pip install img2num

For more information about Img2Num and Python, see the library on PyPI and in our documentation.

Prebuilt Python wheels are currently published for the following platforms:

As of v0.3.0, wheels are not published for Linux aarch64, Intel (x86_64) macOS, Windows ARM64, PyPy, or CPython 3.14. On those platforms pip will fall back to building from source.

How do I install the npm package? Which Node versions are supported?​

npm install img2num

The package ships multiple build formats and the correct one is selected automatically via the package's exports map:

• Browser ESM: for bundlers (Vite, webpack, etc.) and <script type="module">
• IIFE / UMD: for <script> tags
• Node ESM and CJS: both import and require() work in Node

Are prebuilt binaries available?​

Prebuilt artifacts are published for every release:

• Python: Wheels are published on PyPI.
• JavaScript: The package is published on npm.
• C/C++: Archives are available through GitHub Releases.

You only need to build Img2Num from source for development or when using an unsupported platform.

Usage​

How do I convert an image to SVG with Img2Num?​

For a minimal working example, see the example apps and choose the one most relevant to your language or environment.

For JavaScript, there are also ready-to-run sandboxes:

• Node CommonJS
• Node ESM
• IIFE Browser
• UMD Browser
• Browser ESM

What image formats does Img2Num support?​

Img2Num supports raster images conforming to the RGBA format, with channel values in the range [0,255]. For guidance on preparing and validating image inputs for Img2Num functions, see the Img2Num documentation.

Which JavaScript build should I import?​

The npm package's exports map automatically selects the appropriate build when you import or require("img2num").

You only need to select a specific build when loading Img2Num through a plain <script> tag.
In that case, use the IIFE or UMD bundle.

See the Img2Num JavaScript documentation for the CDN snippet and more details.

Is the Img2Num JavaScript API synchronous or asynchronous?​

The processing API is technically asynchronous because of its WebAssembly calls, but it blocks the main thread while waiting for the actual vectorization call to complete. You therefore do not need to manage workers or promises around the vectorization call itself.

For more background on this behavior, see the Img2Num v0.3–0.4 changes blog post.

How do I enable or disable Img2Num logging?​

The native builds use a named spdlog logger.

When building Img2Num from source, set the CMake cache variable to control the log level:

cmake -DIMG2NUM_LOG_LEVEL=OFF

The available log levels are:

• TRACE
• DEBUG
• INFO
• WARN
• ERROR
• CRITICAL
• OFF

Troubleshooting​

How do I fix WASM loading errors in Node.js?​

Symptom: You may encounter an error such as Error: Could not load WASM module.

Cause: The .wasm binary is not found relative to index.js.

Fix: Ensure build-wasm/index.wasm is present alongside index.js in the installed package:

ls node_modules/img2num/build-wasm/

If the WASM file is missing, reinstall Img2Num:

npm uninstall img2num
npm install img2num

What if the WASM file exists but still does not load?​

If the .wasm file exists but loading still fails, your bundler may need explicit *.wasm asset handling.

export default defineConfig({
  assetsInclude: ["**/*.wasm"],
});

If you encounter any problems, please open an issue so we can document the solution.

How do I fix ERR_REQUIRE_ESM or a CommonJS import error?​

Version 0.4.0 contained a regression in which the CJS build pulled in an ESM‑only dependency. This caused require("img2num") to fail in Node.js.

The issue was fixed in the following release, and v0.4.0 is deprecated on npm for this reason.
If your project is pinned to 0.4.0, remove the pin and upgrade.

Why does pip install img2num fail or try to compile from source?​

This usually means that pip could not find a prebuilt wheel matching your platform and Python version, so it fell back to the source distribution.

pip install -U pip

If your platform genuinely does not have a compatible prebuilt wheel, you can either install the required C++17 toolchain and CMake and build Img2Num from source, or open an issue on GitHub requesting support for your platform.

How can I improve noisy, missing, or inaccurate SVG output?​

The quality of the generated SVG depends heavily on the image‑processing parameters, and different problems require different adjustments:

• Speckled or noisy regions: Increase bilateral filtering, or try the CIE LAB filter variant. You can also reduce the color count.
• Missing details or merged shapes: Increase the color count or reduce filtering strength.
• Jagged edges or noisy paths: Increase contour smoothing, or raise min_area to filter out tiny contours. You can also increase sigma_spatial to smooth noise before clustering.
• Very small images: Icons and thumbnails may contain too few pixels for stable clustering. Try upscaling the image first or reducing the number of colors.

If the result appears blurry or over‑smoothed (loss of edge detail), reduce the spatial standard deviation (sigma_spatial).
If the result is too noisy or insufficiently smoothed, increase it.

Remember that bilateral filtering depends on both spatial and range parameters:

• sigma_spatial controls geometric smoothing
• sigma_range controls intensity similarity sensitivity

Both may need to be tuned per image depending on texture and noise levels.

If the output still looks incorrect after tuning these parameters, file a bug on GitHub and include the input image and the exact parameters used so the problem can be reproduced.

K-Means run slow in the browser, how can I speed it up?​

K-means can take seconds on large images. Try:

• Lowering num_colors
• Lowering max_iter
• Using a smaller source image for development

How can I fix Memory Errors (Out of Memory) when using Img2Num?​

The WASM heap is fixed at compile time. Very large images may exceed it. Consider:

• Downscaling the input image
• Splitting the image into tiles

How do I fix missing CIE LAB output in Img2Num?​

Make sure color_space = 0 (default). color_space = 1 uses sRGB which may produce different cluster boundaries.

How do I report an Img2Num bug?​

Open a GitHub issue and include:

• The Img2Num package and version (pip show img2num or npm ls img2num)
• Your operating system and browser, where applicable
• The input image, or a shareable equivalent that reproduces the problem
• The parameters used
• The complete error output
• A minimal reproduction, if possible

Contributing to Img2Num​

How do I build the project locally, and what toolchain do I need?​

See the Img2Num contributing guide for instructions on building the project locally and setting up the required development environment.

What commit message convention does Img2Num use?​

Img2Num uses Conventional Commits such as feat:, fix:, and docs:, together with component scopes. This convention is important because releases are fully automated using release‑please. Release automation reads commit messages to determine version bumps and generate changelogs for the project's four release components:

• Core
• C bindings
• JavaScript
• Python

A mislabeled commit can therefore result in an incorrect changelog entry or version bump.

The project usually catches these issues before a pull request is merged, so contributors do not need to master the convention immediately.
For more details, see Conventional Commits.

Where can I find good first issues for Img2Num?​

You can browse the Img2Num good first issues board. Before starting work on an issue, leave a comment to confirm that it is still relevant and has not already been taken.

How do I contribute to the docs site?​

The Img2Num documentation site img2num.dev is a Docusaurus application located in the docs/ folder. For most documentation changes, standard Markdown and MDX knowledge is enough. Every documentation page also has an "Edit this page" link that takes you directly to the corresponding file on GitHub.

Can I add a binding for another language?​

Yes. This is one of the purposes of the C bindings: they provide a stable C ABI that can serve as a foundation for additional language bindings such as Rust, Go, or Ruby.

If you want to add another language binding, open an issue first to discuss the proposed approach so that the implementation fits the project's release and CI setup.

The project does plan to support additional languages in the future, but would like the core library to stabilize first at v1.x to avoid frequent and costly refactors.

Img2Num Project​

Why is the mascot a hedgehog? 🦔​

The mascot is Joan, an African pygmy hedgehog and the project's original quality-assurance department. She belonged to the maintainer and lives on as the face of Img2Num.