README.md

---
title: FlashImgs
emoji: 💠
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: "6.16.0"
python_version: "3.12.12"
app_file: app.py
suggested_hardware: zero-a10g
fullWidth: true
pinned: false
license: agpl-3.0
short_description: Adaptive 2D Gaussian splat fitting for images (ZeroGPU).
tags:
  - gaussian-splatting
  - 2d-gaussian-splatting
  - image-representation
  - gradio
  - zerogpu
  - computer-vision
---

# FlashImgs — 2D Gaussian Splatting for Images

Fit any image as a set of **2D Gaussians** in seconds, preview the
reconstruction and a 3D Gaussian-splat point cloud, and export files for
standard splat viewers. This Space is a [Gradio](https://www.gradio.app/)
wrapper around the [FlashImgs](https://github.com/OpsiClear/flashimgs) adaptive
fitter, running on **[ZeroGPU](https://huggingface.co/docs/hub/spaces-zerogpu)**.
It does **not** use the gaussifier feedforward sampler, AOTI, or TensorRT path.

## Hardware (ZeroGPU)

The GPU-bound fit is wrapped with `@spaces.GPU`, so the Space requests a
ZeroGPU (NVIDIA RTX Pro 6000 Blackwell, `sm_120`) slice only while a fit runs
and releases it immediately after.

To host this on ZeroGPU you need **ZeroGPU enabled on the account** that owns the
Space (a **PRO** subscription for a personal account, or a Team/Enterprise plan
for an organization), then select **ZeroGPU** in *Settings → Hardware*. The
`@spaces.GPU` decorator is a no-op off ZeroGPU, so the Space also runs unchanged
on a standard GPU tier.

## How to use

1. Upload an image (PNG/WebP alpha is honored automatically as a fit mask).
2. Adjust the **Fit** settings (max side, gaussian budget, steps, loss) if needed.
3. Click **Fit**.
4. Inspect the **3DGS** point-cloud preview and the **Image** reconstruction.
5. Tweak the **PLY** export controls (opacity, scale, thickness, Y axis) — the
   3D preview updates live — then download the files.

### Masks

- Embedded PNG/WebP alpha masks are used automatically to fit only the subject.
- With **Treat image border as mask border** enabled, opaque/RGB images use the
  image frame as the mask boundary.

## Outputs

- Reconstruction preview plus PSNR / SSIM and timing metrics.
- `.splat2d` file compatible with the FlashImgs web viewer.
- Edited planar **3DGS `.ply`** for standard splat viewers. The `factor_rgb`
  opacity scale, mask-edge scale clamp, thickness, and Y-axis controls update
  the preview while you adjust them; the downloadable PLY is always the latest
  edited file.

## How the build works

ZeroGPU Spaces use the Gradio SDK and install from `requirements.txt` with no
build-time CUDA toolchain, so FlashImgs and its CUDA backends cannot be compiled
on the Space. Instead, prebuilt wheels are vendored under [`wheels/`](wheels):

- `flashimgs` (pure Python, built from commit `11d4d3b` + local working-tree changes)
- `fussim` and `simple_sum_backend` — CUDA extensions compiled for
  **CPython 3.12**, **torch 2.11.0+cu130 (CUDA 13.0)**, and **Blackwell `sm_120`**

ZeroGPU pre-installs **torch 2.11.0 for CUDA 13.0**, so the wheels are built for
cu130 and `requirements.txt` pins bare `torch==2.11.0` / `torchvision==0.26.0`
(both resolve to the cu130 builds — a cu128 torchvision triggers
`operator torchvision::nms does not exist`). `python_version: 3.12.12` is set in
the front matter above, and `cfgs/default.yaml` is included at the Space root
because FlashImgs resolves its default config relative to the working directory.

To rebuild the wheels for a new FlashImgs revision (or a different torch / CUDA
arch), build `fussim` and `simple_sum_backend` from the FlashImgs source with
`TORCH_CUDA_ARCH_LIST=12.0+PTX` and `CUDA_HOME` pointing at the matching toolkit,
against the target torch, and rebuild the `flashimgs` wheel with full package
discovery.

## License

The wrapper code in this repository (`app.py`, configuration) is released under
the **GNU Affero General Public License v3.0** (AGPL-3.0) — see [`LICENSE`](LICENSE)
and [`NOTICE`](NOTICE). Because AGPL-3.0 is a network-copyleft license, anyone who
runs a modified version of this wrapper as a network service must offer its users
the modified source.

The vendored **FlashImgs** wheels (`flashimgs`, `simple_sum_backend`, and the
OpsiClear `fussim` fork) are a separate work under the **OpsiClear Restrictive
License** (non-commercial use only). The AGPL-3.0 license of this wrapper does
not extend to the FlashImgs engine; running the deployed app is subject to the
FlashImgs terms.