ffgs 0.1.0.dev0__tar.gz → 0.1.0.dev1__tar.gz

{ffgs-0.1.0.dev0 → ffgs-0.1.0.dev1}/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.5
 Name: ffgs
-Version: 0.1.0.dev0
+Version: 0.1.0.dev1
 Summary: Standard inference for feed-forward 3D Gaussian Splatting models
 Project-URL: Repository, https://github.com/libgs/ffgs
 Author: libgs contributors
 License-Expression: Apache-2.0 AND MIT AND CC-BY-NC-4.0 AND CC-BY-NC-SA-4.0
 License-File: LICENSE
 License-File: src/ffgs/models/anysplat/LICENSE
+License-File: src/ffgs/models/c3g/LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10
+Requires-Dist: einops>=0.8.2
 Requires-Dist: huggingface-hub>=0.23
 Requires-Dist: numpy
 Requires-Dist: pillow
@@ -62,12 +64,13 @@ python examples/infer_nerfstudio_scene.py <scene> --model <family>/<variant> \
     --images-dir <scene>/images_4 --out out
 ```
 
-Models that predict their own cameras also run on images alone. There is no world
-frame then: the Gaussians and the predicted input cameras are both in the model's
-frame, and renders take cameras in that frame (see [Conventions](#conventions)):
+Models that do not need poses (`camera_input` "optional" or "none") also run on
+images alone. There is no world frame then: the Gaussians, and the input cameras
+for models that predict them, are in the model's frame, and renders take cameras
+in that frame (see [Conventions](#conventions)):
 
 ```python
-pipe = GSPipeline.from_pretrained("<family>/<variant>", device="cuda")  # a pose-free model
+pipe = GSPipeline.from_pretrained("<family>/<variant>", device="cuda")  # e.g. anysplat/default
 out = pipe(Views(images))                    # no intrinsics, no c2w: out.frame is None
 out.gaussians.save_ply("scene.ply")          # in the model's frame
 renders = pipe.render(out, out.cameras)["images"]  # the inputs, at the predicted cameras
@@ -96,7 +99,7 @@ Check the license of a model before use: some are for non-commercial use only.
 | | |
 |---|---|
 | images | float in [0, 1] (uint8 accepted), `[V, 3, H, W]` or `[B, V, 3, H, W]`, any resolution |
-| c2w | camera-to-world, OpenCV axes (x right, y down, z forward); optional for models that predict their own cameras |
+| c2w | camera-to-world, OpenCV axes (x right, y down, z forward); optional unless the model requires them (`camera_input="required"`) |
 | intrinsics | pixel K for the image size given, or normalised K with `normalized_intrinsics=True`; optional like c2w |
 | output | `GSOutput`: `Gaussians` (means, scales, wxyz quats, opacities, SH or RGB colours) in the model's frame, that frame (or `None`), and the input cameras the model predicted (or `None`) |
 
@@ -220,16 +223,22 @@ pipe = GSPipeline.from_pretrained("owner/family-repo", subfolder="variant",
 ## Adding a model
 
 A model is a model class with `PyTorchModelHubMixin`, a `Processor` subclass
-(`preprocess`, returning the model input and its `ModelFrame`, or `None` when the
-model predicts its own cameras; `postprocess`, to model-frame `Gaussians`;
+(`preprocess`, returning the model input and its `ModelFrame`, or `None` without
+input poses or when the model predicts its own cameras; `postprocess`, to model-frame `Gaussians`;
 `render_planes`, near / far in world units, or in model units when the frame is
 `None`; for models that predict cameras, `predicted_cameras`, from the model output
 to model-frame `Cameras`, and `output_frame`, whose default fits the frame to the
 given c2w as above; optionally `background` and `render_settings`, the model's
 rasteriser settings such as `radius_clip`, `rasterize_mode` or `clamp`, which
-`pipe.render` uses unless the caller passes them) and a
-`ModelSpec(model_type, model_cls, processor_cls)`. `from_pretrained` resolves the
-`model_type` in `config.json` in this order:
+`pipe.render` uses unless the caller passes them; `camera_input`, whether the
+model is conditioned on the input cameras: `"required"` (the default, always),
+`"optional"` (when given) or `"none"` (never);
+for models trained on poses of a fixed scale, a `camera_spread` in the config, the
+mean distance of the input cameras to the first one in the training data) and a
+`ModelSpec(model_type, model_cls, processor_cls, display_name=...)`. Applications
+read `camera_input`, `camera_spread` and `display_name` to handle a new
+model without changes. `from_pretrained` resolves the `model_type` in
+`config.json` in this order:
 
 1. **In your code** — `ffgs.register_model(spec)` before loading (built-in models
    are registered the same way, on first use).
@@ -303,6 +312,13 @@ torch first (see `.github/workflows/ci.yml`). `tests/fixtures/reference.safetens
 holds frozen reference outputs of the default data path; change it only together
 with a deliberate change to that path.
 
+To release, set `version` in `pyproject.toml` (then `uv lock`), commit it as
+`chore: release X.Y.Z`, merge it into main and push the tag `vX.Y.Z` on that commit.
+`.github/workflows/release.yml` then runs CI, publishes to PyPI and creates the
+[GitHub release](https://github.com/libgs/ffgs/releases), whose notes are generated
+by [git-cliff](https://git-cliff.org/) from the conventional commits since the
+previous tag (`cliff.toml`; preview with `uvx git-cliff --unreleased`).
+
 ## License
 
 **The ffgs package as distributed is not entirely Apache-2.0: it includes code for
@@ -314,6 +330,8 @@ non-commercial use only.** Its license expression is
 - vendored model code under `src/ffgs/models/<family>/` keeps its upstream license.
   `src/ffgs/models/anysplat/` mixes MIT, Apache-2.0 and non-commercial
   (CC-BY-NC-4.0, CC-BY-NC-SA-4.0) files; its `LICENSE` lists the license per file;
+  `src/ffgs/models/c3g/` mixes MIT, Apache-2.0 and VGGT files kept with the
+  CC-BY-NC-4.0 text; its `LICENSE` describes which is which;
 - model weights are not part of the package and carry their own licenses.
 
 The code and weight licenses of each model are listed in

{ffgs-0.1.0.dev0 → ffgs-0.1.0.dev1}/README.md

@@ -40,12 +40,13 @@ python examples/infer_nerfstudio_scene.py <scene> --model <family>/<variant> \
     --images-dir <scene>/images_4 --out out
 ```
 
-Models that predict their own cameras also run on images alone. There is no world
-frame then: the Gaussians and the predicted input cameras are both in the model's
-frame, and renders take cameras in that frame (see [Conventions](#conventions)):
+Models that do not need poses (`camera_input` "optional" or "none") also run on
+images alone. There is no world frame then: the Gaussians, and the input cameras
+for models that predict them, are in the model's frame, and renders take cameras
+in that frame (see [Conventions](#conventions)):
 
 ```python
-pipe = GSPipeline.from_pretrained("<family>/<variant>", device="cuda")  # a pose-free model
+pipe = GSPipeline.from_pretrained("<family>/<variant>", device="cuda")  # e.g. anysplat/default
 out = pipe(Views(images))                    # no intrinsics, no c2w: out.frame is None
 out.gaussians.save_ply("scene.ply")          # in the model's frame
 renders = pipe.render(out, out.cameras)["images"]  # the inputs, at the predicted cameras
@@ -74,7 +75,7 @@ Check the license of a model before use: some are for non-commercial use only.
 | | |
 |---|---|
 | images | float in [0, 1] (uint8 accepted), `[V, 3, H, W]` or `[B, V, 3, H, W]`, any resolution |
-| c2w | camera-to-world, OpenCV axes (x right, y down, z forward); optional for models that predict their own cameras |
+| c2w | camera-to-world, OpenCV axes (x right, y down, z forward); optional unless the model requires them (`camera_input="required"`) |
 | intrinsics | pixel K for the image size given, or normalised K with `normalized_intrinsics=True`; optional like c2w |
 | output | `GSOutput`: `Gaussians` (means, scales, wxyz quats, opacities, SH or RGB colours) in the model's frame, that frame (or `None`), and the input cameras the model predicted (or `None`) |
 
@@ -198,16 +199,22 @@ pipe = GSPipeline.from_pretrained("owner/family-repo", subfolder="variant",
 ## Adding a model
 
 A model is a model class with `PyTorchModelHubMixin`, a `Processor` subclass
-(`preprocess`, returning the model input and its `ModelFrame`, or `None` when the
-model predicts its own cameras; `postprocess`, to model-frame `Gaussians`;
+(`preprocess`, returning the model input and its `ModelFrame`, or `None` without
+input poses or when the model predicts its own cameras; `postprocess`, to model-frame `Gaussians`;
 `render_planes`, near / far in world units, or in model units when the frame is
 `None`; for models that predict cameras, `predicted_cameras`, from the model output
 to model-frame `Cameras`, and `output_frame`, whose default fits the frame to the
 given c2w as above; optionally `background` and `render_settings`, the model's
 rasteriser settings such as `radius_clip`, `rasterize_mode` or `clamp`, which
-`pipe.render` uses unless the caller passes them) and a
-`ModelSpec(model_type, model_cls, processor_cls)`. `from_pretrained` resolves the
-`model_type` in `config.json` in this order:
+`pipe.render` uses unless the caller passes them; `camera_input`, whether the
+model is conditioned on the input cameras: `"required"` (the default, always),
+`"optional"` (when given) or `"none"` (never);
+for models trained on poses of a fixed scale, a `camera_spread` in the config, the
+mean distance of the input cameras to the first one in the training data) and a
+`ModelSpec(model_type, model_cls, processor_cls, display_name=...)`. Applications
+read `camera_input`, `camera_spread` and `display_name` to handle a new
+model without changes. `from_pretrained` resolves the `model_type` in
+`config.json` in this order:
 
 1. **In your code** — `ffgs.register_model(spec)` before loading (built-in models
    are registered the same way, on first use).
@@ -281,6 +288,13 @@ torch first (see `.github/workflows/ci.yml`). `tests/fixtures/reference.safetens
 holds frozen reference outputs of the default data path; change it only together
 with a deliberate change to that path.
 
+To release, set `version` in `pyproject.toml` (then `uv lock`), commit it as
+`chore: release X.Y.Z`, merge it into main and push the tag `vX.Y.Z` on that commit.
+`.github/workflows/release.yml` then runs CI, publishes to PyPI and creates the
+[GitHub release](https://github.com/libgs/ffgs/releases), whose notes are generated
+by [git-cliff](https://git-cliff.org/) from the conventional commits since the
+previous tag (`cliff.toml`; preview with `uvx git-cliff --unreleased`).
+
 ## License
 
 **The ffgs package as distributed is not entirely Apache-2.0: it includes code for
@@ -292,6 +306,8 @@ non-commercial use only.** Its license expression is
 - vendored model code under `src/ffgs/models/<family>/` keeps its upstream license.
   `src/ffgs/models/anysplat/` mixes MIT, Apache-2.0 and non-commercial
   (CC-BY-NC-4.0, CC-BY-NC-SA-4.0) files; its `LICENSE` lists the license per file;
+  `src/ffgs/models/c3g/` mixes MIT, Apache-2.0 and VGGT files kept with the
+  CC-BY-NC-4.0 text; its `LICENSE` describes which is which;
 - model weights are not part of the package and carry their own licenses.
 
 The code and weight licenses of each model are listed in

ffgs-0.1.0.dev1/docs/models/c3g.md

@@ -0,0 +1,89 @@
+# C3G
+
+C3G ([paper](https://arxiv.org/abs/2512.04021),
+[code](https://github.com/cvlab-kaist/C3G)) predicts a fixed budget of 2048
+Gaussians from unposed images: learnable query tokens decode the features of a
+VGGT aggregator. It predicts no cameras, and poses never enter the model: given
+c2w only fix the output frame (see [Conventions](../../README.md#conventions)).
+
+## Licenses
+
+The code is vendored from the official code (`src/ffgs/models/c3g/`, Gaussian
+inference only), each file under its own license: MIT (C3G), Apache-2.0 (DINOv2
+layers) and the VGGT files with upstream's root-license pointer, kept with the
+CC BY-NC 4.0 text. **The C3G model directory as a whole is for non-commercial
+use only**; see its [`LICENSE`](../../src/ffgs/models/c3g/LICENSE). The authors
+declare no license for the weights; they are fine-tuned from VGGT-1B, whose
+weights are CC BY-NC 4.0 (non-commercial). The zoo downloads them from the
+authors' repository; ffgs does not redistribute them.
+
+## Zoo entries
+
+| zoo name | model | input views | input size | weights |
+|---|---|---|---|---|
+| `c3g/default` | the released multiview Gaussian decoder: 2048 Gaussians, SH degree 0 | 2 or more | 224×224 | [honggyuAn/C3G](https://huggingface.co/honggyuAn/C3G) (`gaussian_decoder_multiview.ckpt`) |
+
+The checkpoint is the authors' Lightning checkpoint (4.6 GB, with the frozen
+DPT head it was trained with); the zoo pins its revision and SHA-256 and loads
+the encoder strictly. The 2-view checkpoint and the feature decoders (LSeg,
+DINOv2, DINOv3) are not in the zoo.
+
+## Usage
+
+Without poses there is no world frame and no cameras: the Gaussians are in the
+model's frame (the first camera at the origin, looking down +z), and renders take
+cameras in that frame:
+
+```python
+from ffgs import GSPipeline, Views
+
+pipe = GSPipeline.from_pretrained("c3g/default", device="cuda")
+out = pipe(Views(images))                    # out.frame and out.cameras are None
+out.gaussians.save_ply("scene.ply")          # in the model's frame
+```
+
+With poses the output is placed in their frame, as upstream normalises the scene:
+the first camera as the anchor and the distance between the first and last
+cameras as the unit (it must lie in [1e-3, 1e10]):
+
+```python
+out = pipe(Views(images, intrinsics, c2w))   # c2w do not change the prediction
+out.to_world().gaussians.save_ply("scene.ply")  # in the frame of c2w
+renders = pipe.render(out, target_cameras)["images"]  # cameras in that frame
+```
+
+The processor resizes with PIL Lanczos and centre-crops to 224×224, as upstream
+does. It renders as upstream: black background, no radius clip, no colour clamp.
+Upstream's renderer is scale-invariant (it rescales near / far and the scene);
+ffgs renders with gsplat at the nominal near / far 0.1 / 100, in the units of the
+given c2w (of the model frame without poses).
+
+## Results on RealEstate10K
+
+`c3g/default` and the official code (cvlab-kaist/C3G 40b2cc9: the encoder and its
+CUDA renderer, two context views, `test.align_pose=false`) on the same weights,
+the first three scenes of the authors' RE10K evaluation index, each rendered at
+its target cameras (normalised as upstream: first context camera, endpoint
+baseline). This checks that ffgs runs the model as upstream does; it does not
+reproduce the paper (no pose optimisation, three scenes).
+
+| scene | official vs ffgs renders, PSNR | official vs GT, PSNR | ffgs vs GT, PSNR |
+|---|---|---|---|
+| `000c3ab189999a83` | 38.6 / 37.8 / 37.6 | 16.35 / 16.39 / 16.31 | 16.37 / 16.37 / 16.29 |
+| `000db54a47bd43fe` | 37.0 / 35.5 / 35.2 | 21.45 / 20.76 / 20.24 | 21.49 / 20.83 / 20.31 |
+| `0017ce4c6a39d122` | 40.0 / 40.2 / 40.0 | 19.20 / 16.82 / 16.61 | 19.15 / 16.81 / 16.60 |
+
+- **Inputs**: the preprocessed context and target images are identical; the
+  normalised target cameras agree to 1e-7.
+- **Prediction**: on the CPU, the official encoder and ffgs give bit-identical
+  aggregator tokens and Gaussian parameters. On CUDA neither is reproducible:
+  run twice on the same input, the official model itself moves about 175 of the
+  2048 Gaussians by more than 1e-2, as many as official vs ffgs. The cause is the
+  head's attention: in fp32, `scaled_dot_product_attention` runs PyTorch's
+  memory-efficient kernel (`fmha_cutlassF_f32_aligned_64x128_rf_sm80`, measured on
+  an RTX PRO 6000 Blackwell with torch 2.7.1), whose output varies from run to run,
+  also under `torch.use_deterministic_algorithms(True)`; the second decoder layer
+  amplifies it. Every other op of the head is bit-reproducible, and so is the whole
+  head with the math backend. ffgs keeps upstream's default backend.
+- **Rendering**: the remaining render difference comes from that and from the
+  renderers (upstream's scale-invariant CUDA rasteriser vs gsplat).

{ffgs-0.1.0.dev0 → ffgs-0.1.0.dev1}/docs/models/index.md

@@ -3,10 +3,11 @@
 The models ffgs ships. Each has a page with its source, licenses, zoo entries,
 usage notes and results against the official code.
 
-| model | zoo names | poses | input views | input size | license (code / weights) | page |
+| model | zoo names | poses (`camera_input`) | input views | input size | license (code / weights) | page |
 |---|---|---|---|---|---|---|
 | TokenGS | `tokengs/*` | required | 2 / 4 / 6 | 256×256, 256×448 | Apache-2.0 / non-commercial | [tokengs.md](tokengs.md) |
-| AnySplat | `anysplat/default` | optional (predicts the cameras) | any | 448×448 | non-commercial / non-commercial | [anysplat.md](anysplat.md) |
+| AnySplat | `anysplat/default` | none (given poses only place the output) | any | 448×448 | non-commercial / non-commercial | [anysplat.md](anysplat.md) |
+| C3G | `c3g/default` | none (given poses only place the output) | 2 or more | 224×224 | non-commercial / non-commercial (undeclared, VGGT-derived) | [c3g.md](c3g.md) |
 
 `ffgs.zoo.list_models()` lists every zoo name; each zoo entry also records its
 source, pinned revision and license.

{ffgs-0.1.0.dev0 → ffgs-0.1.0.dev1}/pyproject.toml

@@ -1,12 +1,15 @@
 [project]
 name = "ffgs"
-version = "0.1.0.dev0"
+version = "0.1.0.dev1"
 description = "Standard inference for feed-forward 3D Gaussian Splatting models"
 readme = "README.md"
-# The AnySplat model (src/ffgs/models/anysplat/) includes non-commercial code: see
-# its LICENSE.
+# AnySplat and C3G include non-commercial components: see each model's LICENSE.
 license = "Apache-2.0 AND MIT AND CC-BY-NC-4.0 AND CC-BY-NC-SA-4.0"
-license-files = ["LICENSE", "src/ffgs/models/anysplat/LICENSE"]
+license-files = [
+    "LICENSE",
+    "src/ffgs/models/anysplat/LICENSE",
+    "src/ffgs/models/c3g/LICENSE",
+]
 authors = [{ name = "libgs contributors" }]
 requires-python = ">=3.10"
 classifiers = [
@@ -14,6 +17,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
+    "einops>=0.8.2",
     "huggingface_hub>=0.23",
     "numpy",
     "pillow",

{ffgs-0.1.0.dev0 → ffgs-0.1.0.dev1}/src/ffgs/models/anysplat/__init__.py

@@ -33,6 +33,7 @@ SPEC = register_model(
         model_cls=AnySplat,
         processor_cls=AnySplatProcessor,
         convert_state_dict=convert_state_dict,
+        display_name="AnySplat",
     )
 )
 

{ffgs-0.1.0.dev0 → ffgs-0.1.0.dev1}/src/ffgs/models/anysplat/processing.py

@@ -77,6 +77,7 @@ class AnySplatProcessorConfig(ImageFitConfig):
 
 class AnySplatProcessor(Processor):
     config_cls = AnySplatProcessorConfig
+    camera_input = "none"
 
     def preprocess(self, views: Views, device: torch.device) -> Prepared:
         images = self.fit_views(views).images