# ryan-millard/img2num architecture

> Architecture diagram of the GitHub repository ryan-millard/img2num, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryan-millard/img2num
- Repository: https://github.com/ryan-millard/img2num

## Overview

Img2Num is a raster-to-SVG vectorizer designed especially for natural images. Its main workflow takes raster pixels through color reduction and contour processing, then emits layered SVG paths; users can reach the native core through C or Python bindings, or JavaScript through WebAssembly. The graph also preserves the documented GPU path. The README documents the core stages and language support; sampled source confirms the contour and WASM-client responsibilities, but does not expose the complete native call chain.

Main entry points: [`core/include/img2num.h`](https://github.com/ryan-millard/img2num/blob/main/core/include/img2num.h) (C++ API), [`core/src/internal/kmeans.cpp`](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/kmeans.cpp) (Color Quantization), [`bindings/c/src/cimg2num.cpp`](https://github.com/ryan-millard/img2num/blob/main/bindings/c/src/cimg2num.cpp) (C Binding), [`bindings/py/src/img2num_pybind.cpp`](https://github.com/ryan-millard/img2num/blob/main/bindings/py/src/img2num_pybind.cpp) (Python Binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Language Interfaces"]
  node_cpp_api["C++ API<br/>[img2num.h]"]
  node_c_binding["C Binding<br/>[cimg2num.cpp]"]
  node_python_binding["Python Binding<br/>[img2num_pybind.cpp]"]
  node_js_api["JavaScript API<br/>[index.js]"]
  node_wasm_client["WASM Client<br/>[wasmClient.js]"]
  node_wasm_bridge["WASM Bridge<br/>[wasm_wrapper.c]"]
end

subgraph group_core["Vectorization Core"]
  node_pixel_color["Color Model<br/>[cielab_impl.h]"]
  node_image_filter["Image Filtering"]
  node_quantization["Color Quantization<br/>[kmeans.cpp]"]
  node_contours["Contour Extraction<br/>[contours.cpp]"]
  node_simplification["Polygon Simplification"]
  node_svg_writer["SVG Generation<br/>[image_to_svg.cpp]"]
  node_labels_svg["Labeled SVG<br/>[labels_to_svg.cpp]"]
end

subgraph group_gpu["GPU Processing"]
  node_gpu_quantization["GPU Quantization<br/>[kmeans_gpu.cpp]"]
  node_gpu_runtime["WebGPU Runtime<br/>[gpu.h]"]
end

node_user(("Image User"))

node_user -->|"provides pixels"| node_cpp_api
node_user -->|"uses binding"| node_c_binding
node_user -->|"uses binding"| node_python_binding
node_user -->|"uses package"| node_js_api
node_js_api -.->|"invokes"| node_wasm_client
node_wasm_client -.->|"calls exports"| node_wasm_bridge
node_c_binding -.->|"forwards requests"| node_cpp_api
node_python_binding -.->|"forwards requests"| node_cpp_api
node_wasm_bridge -.->|"forwards requests"| node_cpp_api
node_cpp_api -.->|"filters image"| node_image_filter
node_cpp_api -->|"reduces colors"| node_quantization
node_quantization -.->|"uses color model"| node_pixel_color
node_quantization -.->|"accelerates with"| node_gpu_quantization
node_gpu_quantization -.->|"uses WebGPU"| node_gpu_runtime
node_cpp_api -->|"extracts contours"| node_contours
node_contours -->|"simplifies paths"| node_simplification
node_cpp_api -->|"writes SVG"| node_svg_writer
node_cpp_api -->|"writes labeled SVG"| node_labels_svg

click node_cpp_api "https://github.com/ryan-millard/img2num/blob/main/core/include/img2num.h"
click node_c_binding "https://github.com/ryan-millard/img2num/blob/main/bindings/c/src/cimg2num.cpp"
click node_python_binding "https://github.com/ryan-millard/img2num/blob/main/bindings/py/src/img2num_pybind.cpp"
click node_js_api "https://github.com/ryan-millard/img2num/blob/main/packages/js/src/index.js"
click node_wasm_client "https://github.com/ryan-millard/img2num/blob/main/packages/js/src/wasmClient.js"
click node_wasm_bridge "https://github.com/ryan-millard/img2num/blob/main/bindings/js/src/wasm_wrapper.c"
click node_pixel_color "https://github.com/ryan-millard/img2num/blob/main/core/include/internal/cielab_impl.h"
click node_image_filter "https://github.com/ryan-millard/img2num/blob/main/core/src/internal/bilateral_filter.cpp"
click node_quantization "https://github.com/ryan-millard/img2num/blob/main/core/src/internal/kmeans.cpp"
click node_gpu_quantization "https://github.com/ryan-millard/img2num/blob/main/core/src/internal/kmeans_gpu.cpp"
click node_gpu_runtime "https://github.com/ryan-millard/img2num/blob/main/core/include/internal/gpu.h"
click node_contours "https://github.com/ryan-millard/img2num/blob/main/core/src/internal/contours.cpp"
click node_simplification "https://github.com/ryan-millard/img2num/blob/main/core/src/internal/douglas_peucker.cpp"
click node_svg_writer "https://github.com/ryan-millard/img2num/blob/main/core/src/internal/image_to_svg.cpp"
click node_labels_svg "https://github.com/ryan-millard/img2num/blob/main/core/src/internal/labels_to_svg.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cpp_api,node_c_binding,node_python_binding,node_js_api,node_wasm_client,node_wasm_bridge,node_user toneBlue
class node_pixel_color,node_image_filter,node_quantization,node_contours,node_simplification,node_svg_writer,node_labels_svg toneAmber
class node_gpu_quantization,node_gpu_runtime toneMint
```

## Components

### Language Interfaces

- [C++ API](https://github.com/ryan-millard/img2num/blob/main/core/include/img2num.h): `core/include/img2num.h`
- [C Binding](https://github.com/ryan-millard/img2num/blob/main/bindings/c/src/cimg2num.cpp): `bindings/c/src/cimg2num.cpp`
- [Python Binding](https://github.com/ryan-millard/img2num/blob/main/bindings/py/src/img2num_pybind.cpp): `bindings/py/src/img2num_pybind.cpp`
- [JavaScript API](https://github.com/ryan-millard/img2num/blob/main/packages/js/src/index.js): `packages/js/src/index.js`
- [WASM Client](https://github.com/ryan-millard/img2num/blob/main/packages/js/src/wasmClient.js): `packages/js/src/wasmClient.js`
- [WASM Bridge](https://github.com/ryan-millard/img2num/blob/main/bindings/js/src/wasm_wrapper.c): `bindings/js/src/wasm_wrapper.c`

### Vectorization Core

- [Color Model](https://github.com/ryan-millard/img2num/blob/main/core/include/internal/cielab_impl.h): `core/include/internal/cielab_impl.h`
- [Image Filtering](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/bilateral_filter.cpp): `core/src/internal/bilateral_filter.cpp`
- [Color Quantization](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/kmeans.cpp): `core/src/internal/kmeans.cpp`
- [Contour Extraction](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/contours.cpp): `core/src/internal/contours.cpp`
- [Polygon Simplification](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/douglas_peucker.cpp): `core/src/internal/douglas_peucker.cpp`
- [SVG Generation](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/image_to_svg.cpp): `core/src/internal/image_to_svg.cpp`
- [Labeled SVG](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/labels_to_svg.cpp): `core/src/internal/labels_to_svg.cpp`

### GPU Processing

- [GPU Quantization](https://github.com/ryan-millard/img2num/blob/main/core/src/internal/kmeans_gpu.cpp): `core/src/internal/kmeans_gpu.cpp`
- [WebGPU Runtime](https://github.com/ryan-millard/img2num/blob/main/core/include/internal/gpu.h): `core/include/internal/gpu.h`

### Other components

- **Image User**

## Connections

- Image User → C++ API: provides pixels (evidence: `README.md`)
- Image User → C Binding: uses binding (evidence: `README.md`)
- Image User → Python Binding: uses binding (evidence: `README.md`)
- Image User → JavaScript API: uses package (evidence: `README.md`)
- JavaScript API → WASM Client: invokes
- WASM Client → WASM Bridge: calls exports
- C Binding → C++ API: forwards requests
- Python Binding → C++ API: forwards requests
- WASM Bridge → C++ API: forwards requests
- C++ API → Image Filtering: filters image
- C++ API → Color Quantization: reduces colors (evidence: `README.md`)
- Color Quantization → Color Model: uses color model
- Color Quantization → GPU Quantization: accelerates with
- GPU Quantization → WebGPU Runtime: uses WebGPU
- C++ API → Contour Extraction: extracts contours (evidence: `README.md`)
- Contour Extraction → Polygon Simplification: simplifies paths (evidence: `README.md`)
- C++ API → SVG Generation: writes SVG (evidence: `README.md`)
- C++ API → Labeled SVG: writes labeled SVG (evidence: `README.md`)
