---
license: apache-2.0
base_model: TencentARC/FreeSplatter
pipeline_tag: image-to-3d
library_name: gguf
tags:
  - gguf
  - ggml
  - gaussian-splatting
  - 3d-reconstruction
  - free-splatter.cpp
  - pose-free
---

# free-splatter.cpp — GGUF weights

GGUF conversions of [TencentARC/FreeSplatter](https://github.com/TencentARC/FreeSplatter)
for **[free-splatter.cpp](https://github.com/localai-org/free-splatter.cpp)**, a small
C/C++ ([ggml](https://github.com/ggml-org/ggml)) inference engine that runs the
FreeSplatter neural-network front-half on CPU or a Vulkan GPU — **no camera poses,
no Python**.

Given N uncalibrated images it returns, **for every input pixel**, a 3D Gaussian
(position · spherical-harmonic colour · opacity · scale · rotation) that a
Gaussian-splatting viewer can render. The rasterizer and PnP pose solver are out
of scope — these weights cover the patch tokenizer → multi-view transformer →
per-pixel Gaussian head.

## Files

| file | variant | precision | size | notes |
|---|---|---|---|---|
| `freesplatter-scene-f16.gguf` | scene | f16 | ~596 MB | **recommended**; 2 overlapping views of a scene |
| `freesplatter-scene-f32.gguf` | scene | f32 | ~1.2 GB | full precision (reference / CPU) |
| `freesplatter-object-f16.gguf` | object | f16 | ~596 MB | 3–4 views around one object |

All variants share the same transformer backbone; they differ only in the head
config (`gaussian_channels`, `sh_residual`, `use_2dgs`) and what they were trained
on. The GGUF carries those as `free-splatter.*` KV metadata, so the engine
configures itself from the file.

## Usage

```sh
# build the engine (see the repo README), then:
free_splatter-cli --device vulkan --splat scene.splat \
  freesplatter-scene-f16.gguf view1.jpg view2.jpg
```

Each view is center-cropped and resized to 512×512. The output `.splat` (antimatter15
format) opens in the bundled WebGL viewer or any Gaussian-splatting viewer; pass
`--out result.f32` instead for the raw `[N, 512, 512, gaussian_channels]` float32
Gaussian tensor. There is also a drop-photos-in-the-browser web app and a
multi-scene demo-video renderer — see the project repo.

## How these were made

Converted with [`scripts/convert.py`](https://github.com/localai-org/free-splatter.cpp/blob/master/scripts/convert.py)
directly from the upstream FreeSplatter `.safetensors` checkpoints (needs only
`torch` + `safetensors` + `gguf`). The converter maps the `transformer.*` weights
of pieces 1–3 and fails loudly on any unmapped or missing tensor — no weight is
silently dropped.

## License & attribution

Apache-2.0. These are derivative weights of
[TencentARC/FreeSplatter](https://github.com/TencentARC/FreeSplatter) (Apache-2.0);
all credit for the model goes to the FreeSplatter authors. The GGUF packaging and
the inference engine are part of free-splatter.cpp.