# deadsix27/waifu2x-converter-cpp architecture

> Architecture diagram of the GitHub repository deadsix27/waifu2x-converter-cpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deadsix27/waifu2x-converter-cpp
- Repository: https://github.com/deadsix27/waifu2x-converter-cpp

## Overview

1. **Repository purpose**
   - This is a command-line image conversion tool: a C++ reimplementation of waifu2x’s converter path for **noise reduction and image scaling**.
   - The core architecture is a **pipeline**: parse CLI options → load image(s) and model metadata → run conversion through a selected backend → write the output image.

2. **Top-level layering**
   - The code is split into a small number of clear layers:
     - **CLI / app entrypoint** in `src/main.cpp` and `src/w2xconv.cpp`
     - **conversion orchestration** in `src/convertRoutine.cpp`
     - **image/model/runtime support** in `src/common.*`, `src/Env.*`, `src/modelHandler.*`, `src/Buffer.*`
     - **backend implementations** for CPU SIMD, CUDA, and OpenCL
     - **platform wrappers** for Windows in `w32-apps/`
   - This is not a service-oriented repo; it is a single native executable with pluggable compute backends.

3. **Command-line and configuration boundary**
   - Argument parsing is handled with the vendored **TCLAP** headers in `include/tclap/`.
   - JSON-based model definitions are parsed with vendored **picojson** in `include/picojson.h`.
   - The README and file layout suggest the executable takes user options for things like denoise level, scaling factor, backend choice, and output behavior, then passes those into the conversion pipeline.

4. **Core conversion flow**
   - `src/convertRoutine.cpp` is the main orchestration point for processing an image through waifu2x-style conversion.
   - It likely coordinates:
     - image loading and preprocessing
     - tile/chunk handling for large images
     - model selection
     - backend execution
     - postprocessing and output assembly
   - `src/Buffer.*` and `src/cvwrap.*` likely serve as the bridge between OpenCV image objects and the internal tensor/buffer representation used by the neural model code.

5. **Model subsystem**
   - `models_rgb/` contains JSON model descriptors such as:
     - `noise0_model.json` through `noise3_model.json`
     - `scale2.0x_model.json`
   - These are the runtime model assets the converter loads to decide whether it is doing denoising or 2x scaling.
   - The README says the converter supports **vgg models only**, so model handling is likely constrained to one model family rather than arbitrary architectures.

6. **Backend execution model**
   - The repo has multiple compute backends under `src/modelHandler_*`:
     - `modelHandler_CUDA.cpp/.cu`
     - `modelHandler_OpenCL.cpp/.cl`
     - CPU/SIMD variants: `sse`, `avx`, `fma`, `neon`, `altivec`
   - `src/modelHandler.cpp/.hpp` appears to be the backend-agnostic dispatch layer that chooses an implementation based on platform and compile-time support.
   - `src/modelHandler_simd.hpp` plus the `*_unroll*.hpp` files indicate a hand-optimized CPU inference path for convolution-heavy work.

7. **Platform and hardware specialization**
   - The architecture is explicitly split by hardware capability:
     - **CUDA** for NVIDIA GPUs
     - **OpenCL** for broader GPU support
     - **SIMD CPU paths** for x86 and ARM families
   - `src/compiler.h`, `src/sec.hpp`, and `src/tchar.h` suggest portability glue for compiler/platform differences.
   - This means the “model execution” boundary is the key abstraction point in the repo.

8. **Concurrency and execution control**
   - `src/threadPool.*` indicates the conversion pipeline uses background worker threads rather than a single-threaded loop.
   - The thread pool likely feeds tiled image work units to the chosen backend and helps overlap preprocessing, inference, and recomposition.
   - `src/Env.*` likely stores runtime state such as backend availability, device selection, memory limits, and other process-wide settings.

9. **OpenCV as I/O and image-processing dependency**
   - The README states OpenCV is a required dependency, and `src/cvwrap.*` suggests a wrapper around OpenCV operations.
   - OpenCV is probably responsible for:
     - reading input images
     - color conversion / resizing support
     - intermediate image handling
     - writing output images
   - That makes OpenCV the main external dependency at the data boundary, while the waifu2x-specific logic stays inside the repo.

10. **Command-line application packaging**
   - `CMakeLists.txt` is the main cross-platform build entrypoint.
   - `BUILDING.md`, `dist.sh`, and `.github/workflows/w2x-runner.yml` show the project is built and packaged as a native binary for Linux, Windows, and related targets.
   - `w32-apps/` contains Windows-specific launchers, resource files, installer/uninstaller scripts, and bench/test utilities, which are separate from the core conversion engine.

11. **Legacy and reference material**
   - `old_files/` contains older implementation and documentation artifacts, including Lua/NOCUDA code and historical docs.
   - These are not part of the main runtime architecture; they serve as reference material and historical context for how the converter evolved.
   - `FORK_CHANGES.md` is also useful as a maintenance boundary marker for changes relative to upstream/fork history.

12. **How data moves through the system**
   - At a high level, the flow is:
     - user invokes the CLI
     - options are parsed
     - model JSON is loaded from `models_rgb/`
     - image is read via OpenCV
     - work is split into buffers/tiles
     - `modelHandler` dispatches to the best available backend
     - processed tiles are recombined
     - final image is written out
   - The key architectural seams are between CLI/configuration, image buffering, model execution, and output I/O.

13. **What to draw in an architecture diagram**
   - The central box should be the **conversion engine**, with arrows in from:
     - CLI arguments
     - model JSON assets
     - input images
   - Inside the engine, show a dispatcher feeding one of several backends:
     - CPU SIMD
     - CUDA
     - OpenCL
   - Surround that with shared support components:
     - thread pool
     - OpenCV wrapper
     - runtime environment/config
   - Keep the Windows app layer and legacy files outside the main runtime path.

Main entry points: [`src/convertRoutine.cpp`](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/convertRoutine.cpp) (convertRoutine), [`src/w2xconv.cpp`](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/w2xconv.cpp) (w2xconv), [`src/modelHandler.cpp`](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler.cpp) (modelHandler), [`src/cvwrap.cpp`](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/cvwrap.cpp) (cvwrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI / App"]
  node_main(("main<br/>entrypoint<br/>[main.cpp]"))
  node_w2xconv["w2xconv<br/>cli facade<br/>[w2xconv.cpp]"]
end

subgraph group_group_core["Conversion Core"]
  node_convert_routine["convertRoutine<br/>pipeline orchestrator<br/>[convertRoutine.cpp]"]
  node_env["Env<br/>runtime state<br/>[Env.cpp]"]
  node_common["common<br/>shared utilities<br/>[common.cpp]"]
  node_buffer[("Buffer<br/>[Buffer.cpp]")]
  node_cvwrap["cvwrap<br/>opencv bridge<br/>[cvwrap.cpp]"]
  node_model_handler["modelHandler<br/>backend dispatcher<br/>[modelHandler.cpp]"]
  node_thread_pool["threadPool<br/>concurrency<br/>[threadPool.cpp]"]
end

subgraph group_group_backends["Compute Backends"]
  node_cuda_backend["CUDA<br/>gpu backend"]
  node_opencl_backend["OpenCL<br/>gpu backend"]
  node_simd_backend["SIMD CPU<br/>cpu backend"]
  node_simd_core["simd core<br/>vector kernels"]
end

subgraph group_group_assets["Assets / Dependencies"]
  node_tclap["TCLAP<br/>cli parser<br/>[CmdLine.h]"]
  node_picojson["picojson<br/>json parser<br/>[picojson.h]"]
  node_models_rgb[("models_rgb<br/>model assets<br/>[noise0_model.json]")]
  node_opencv["OpenCV<br/>external dependency"]
end

subgraph group_group_platform["Platform Layer"]
  node_w32_apps["w32-apps<br/>windows packaging"]
end

subgraph group_group_legacy["Legacy / Reference"]
  node_old_files["old_files<br/>legacy archive<br/>[README.md]"]
end

node_main -->|"starts"| node_w2xconv
node_w2xconv -->|"parses args"| node_tclap
node_w2xconv -->|"invokes"| node_convert_routine
node_convert_routine -->|"reads state"| node_env
node_convert_routine -->|"uses"| node_common
node_convert_routine -->|"tiles into"| node_buffer
node_convert_routine -->|"loads/saves"| node_cvwrap
node_convert_routine -->|"executes"| node_model_handler
node_convert_routine -->|"parallelizes"| node_thread_pool
node_convert_routine -->|"loads model"| node_models_rgb
node_convert_routine -->|"parses json"| node_picojson
node_cvwrap -->|"wraps"| node_opencv
node_model_handler -->|"dispatches to"| node_cuda_backend
node_model_handler -->|"dispatches to"| node_opencl_backend
node_model_handler -->|"dispatches to"| node_simd_backend
node_simd_backend -->|"shares kernels"| node_simd_core
node_w2xconv -.->|"packages with"| node_w32_apps
node_old_files -.->|"historical reference"| node_convert_routine

click node_main "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/main.cpp"
click node_w2xconv "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/w2xconv.cpp"
click node_convert_routine "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/convertRoutine.cpp"
click node_env "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/Env.cpp"
click node_common "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/common.cpp"
click node_buffer "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/Buffer.cpp"
click node_cvwrap "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/cvwrap.cpp"
click node_model_handler "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler.cpp"
click node_thread_pool "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/threadPool.cpp"
click node_cuda_backend "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_CUDA.cpp"
click node_opencl_backend "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_OpenCL.cpp"
click node_simd_backend "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_sse.cpp"
click node_simd_core "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_simd.hpp"
click node_tclap "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/include/tclap/CmdLine.h"
click node_picojson "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/include/picojson.h"
click node_models_rgb "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/models_rgb/noise0_model.json"
click node_w32_apps "https://github.com/deadsix27/waifu2x-converter-cpp/tree/master/w32-apps/Makefile"
click node_old_files "https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/old_files/README.md"

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_main,node_w2xconv toneBlue
class node_convert_routine,node_env,node_common,node_buffer,node_cvwrap,node_model_handler,node_thread_pool toneAmber
class node_cuda_backend,node_opencl_backend,node_simd_backend,node_simd_core toneMint
class node_tclap,node_picojson,node_models_rgb,node_opencv toneRose
class node_w32_apps toneIndigo
class node_old_files toneTeal
```

## Components

### CLI / App

Command-line entrypoint and option parsing

- [main](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/main.cpp): entrypoint · Program startup and dispatch · `src/main.cpp`
- [w2xconv](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/w2xconv.cpp): cli facade · Command-line interface and option wiring · `src/w2xconv.cpp`

### Conversion Core

Orchestration, buffering, runtime state, and image/model support

- [convertRoutine](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/convertRoutine.cpp): pipeline orchestrator · Coordinates image conversion from input to output · `src/convertRoutine.cpp`
- [Env](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/Env.cpp): runtime state · Process-wide settings and device/runtime selection · `src/Env.cpp`
- [common](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/common.cpp): shared utilities · Shared conversion helpers and constants · `src/common.cpp`
- [Buffer](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/Buffer.cpp): image buffer · Internal tensor/image buffer representation · `src/Buffer.cpp`
- [cvwrap](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/cvwrap.cpp): opencv bridge · Wrapper around OpenCV image operations · `src/cvwrap.cpp`
- [modelHandler](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler.cpp): backend dispatcher · Selects and drives the active compute backend · `src/modelHandler.cpp`
- [threadPool](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/threadPool.cpp): concurrency · Worker pool for tiled and background work · `src/threadPool.cpp`

### Compute Backends

CPU SIMD, CUDA, and OpenCL model execution paths

- [CUDA](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_CUDA.cpp): gpu backend · NVIDIA GPU inference path · `src/modelHandler_CUDA.cpp`
- [OpenCL](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_OpenCL.cpp): gpu backend · Portable GPU inference path · `src/modelHandler_OpenCL.cpp`
- [SIMD CPU](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_sse.cpp): cpu backend · Hand-optimized CPU inference paths · `src/modelHandler_sse.cpp`
- [simd core](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/src/modelHandler_simd.hpp): vector kernels · Shared unrolled SIMD kernels and helpers · `src/modelHandler_simd.hpp`

### Assets / Dependencies

Vendored parsers, model definitions, and image I/O dependency

- [TCLAP](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/include/tclap/CmdLine.h): cli parser · Vendored command-line parsing library · `include/tclap/CmdLine.h`
- [picojson](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/include/picojson.h): json parser · Vendored JSON parsing library for model descriptors · `include/picojson.h`
- [models_rgb](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/models_rgb/noise0_model.json): model assets · Runtime JSON model descriptors for denoise and scale modes · `models_rgb/noise0_model.json`
- **OpenCV**: external dependency · Image loading, resizing, color conversion, and saving

### Platform Layer

Windows-specific packaging and launch wrappers

- [w32-apps](https://github.com/deadsix27/waifu2x-converter-cpp/tree/master/w32-apps/Makefile): windows packaging · Windows launchers, resources, and installer utilities · `w32-apps/Makefile`

### Legacy / Reference

Historical source and documentation not on the main runtime path

- [old_files](https://github.com/deadsix27/waifu2x-converter-cpp/blob/master/old_files/README.md): legacy archive · Historical Lua-era implementation and documentation · `old_files/README.md`

## Connections

- main → w2xconv: starts · Program entry hands off to CLI application logic
- w2xconv → TCLAP: parses args · Command-line options are defined and parsed with TCLAP
- w2xconv → convertRoutine: invokes · CLI settings are forwarded into the conversion pipeline
- convertRoutine → Env: reads state · Uses runtime configuration and device selection
- convertRoutine → common: uses · Shared conversion helpers and constants
- convertRoutine → Buffer: tiles into · Image work is split into internal buffers and tiles
- convertRoutine → cvwrap: loads/saves · Image I/O and image operations go through OpenCV wrapper
- convertRoutine → modelHandler: executes · Orchestrates model inference through the dispatcher
- convertRoutine → threadPool: parallelizes · Background workers handle tiled conversion work
- convertRoutine → models_rgb: loads model · Model JSON descriptors are selected by denoise/scale mode
- convertRoutine → picojson: parses json · Model metadata is read through picojson
- cvwrap → OpenCV: wraps · OpenCV is the external image-processing boundary
- modelHandler → CUDA: dispatches to · Chooses CUDA when available and selected
- modelHandler → OpenCL: dispatches to · Chooses OpenCL when available and selected
- modelHandler → SIMD CPU: dispatches to · Chooses CPU SIMD paths on supported platforms
- SIMD CPU → simd core: shares kernels · SIMD variants reuse common unrolled kernel definitions
- w2xconv → w32-apps: packages with · Windows-specific wrappers and resources support distribution
- old_files → convertRoutine: historical reference · Legacy implementation documents the repo's earlier architecture