SAD: Soft Anisotropic Diagrams

Code for the paper Soft Anisotropic Diagrams for Differentiable Image Representation, with Metal, WGPU, CUDA, PyTorch, and browser backends.

Project page: https://luckyiyi.github.io/SAD/

./run.sh /path/to/image.png
./run.sh /path/to/image.png --backend auto
./run.sh /path/to/image.png --backend metal
./run.sh /path/to/image.png --backend cuda
./run.sh /path/to/image.png --backend wgpu
./run.sh /path/to/image.png --backend pytorch --target-bpp 2.0

Backend options: auto, metal, wgpu, cuda, pytorch. Compatibility note: --backend webgpu is still accepted and maps to wgpu. Default training targets DEFAULT_TARGET_BPP=1.0 from training_config.json; pass --target-bpp to override it. Pass an image path explicitly; run.sh only uses test.png when that file exists at the repo root. Default training output is intentionally small: a reconstruction PNG and a *_sites.txt file. Metal can also write debug cells and tau heatmaps with --include-debug-mask.

run.sh is the preferred entry point on a new machine. It builds native backends automatically when sources changed and, if no usable backend is found, bootstraps Python backend dependencies through install.sh. Set SAD_NO_AUTO_INSTALL=1 to disable automatic Python package installs.

Manual install is still available:

./install.sh --backend auto

Or install a specific backend:

./install.sh --backend metal
./install.sh --backend cuda
./install.sh --backend wgpu
./install.sh --backend pytorch

Notes:

• Metal requires macOS + Xcode command line tools (xcode-select --install).
• ./build.sh and ./install.sh --backend metal build the Metal executable into build/metal/.
• CUDA requires a CUDA toolkit with nvcc on PATH and CMake 3.20+.
• WGPU (wgpu-py) installs Python deps from backends/webgpu_py/requirements.txt.
• PyTorch requires Python 3.9+, PyTorch, CMake 3.26+, and Metal or CUDA.

All backends support render-only mode from a saved *_sites.txt:

./run.sh --render /path/to/sites.txt --backend metal
./run.sh --render /path/to/sites.txt --backend cuda --width 1024 --height 1024
./run.sh --render /path/to/sites.txt --backend wgpu --width 1024 --height 1024
./run.sh --render /path/to/sites.txt --backend pytorch --width 1024 --height 1024

Metal also has a convenience script:

./render.sh results/foo_sites.txt --width 1024 --height 1024

Open backends/webgpu_js/index.html in a WebGPU-capable browser, load a *_sites.txt, and inspect the forward pass with render modes, optional site dots, and PNG export.

The hosted demo is available from the project page: https://luckyiyi.github.io/SAD/

Run the Table 4 Kodak evaluation from the repository root:

./reproduce_table4.sh

The script downloads the 24 Kodak images, trains them at 16.0 BPP using training_config.json, and reports the mean PSNR. Inputs, reconstructions, *_sites.txt files, and the summary are written to results/reproduction/table4/.

Each backend has its own README with setup, build, and usage details:

• backends/metal/README.md (Swift + Metal)
• backends/cuda/README.md (C++/CUDA)
• backends/pytorch/README.md (PyTorch MPS/CUDA extension)
• backends/webgpu_py/README.md (wgpu-py training)
• backends/webgpu_js/README.md (browser viewer, trainer, and demo)

See backends/README.md for an overview.