ffgs 0.1.0.dev0__py3-none-any.whl

ffgs/models/tokengs/processing.py

@@ -0,0 +1,339 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Modified by the libgs contributors, 2026: the evaluation-time data path of
+# https://github.com/nv-tlabs/TokenGS (b16269c) as an ffgs `Processor` --
+# `ImageTransform` and `ray_condition` from tokengs/utils/data.py, camera
+# normalisation and input normalisation from tokengs/data/provider.py (`Provider.
+# _preprocess`), render settings from tokengs/rendering/gs.py and tokengs/options.py.
+# Training-only branches (flips, margins, timestamps, depth-based scaling) removed.
+
+"""TokenGS pre / post-processing: the author's evaluation data path.
+
+Per sample, as `tokengs/data/provider.py` does at evaluation:
+
+1. crop the largest centred region with the aspect ratio of `image_shape`, then
+   resize it to `image_shape` (torchvision bilinear, antialiased). The intrinsics
+   follow the upstream arithmetic exactly, including its half-pixel offset on odd
+   crop margins (the pixels are cropped at the rounded offset, K is shifted by the
+   exact one);
+2. cameras relative to the first input view (`"first_cam"`) or to the mean input
+   camera (`"mean_cam"`), translations times `scene_scale`;
+3. model input: ImageNet-normalised images and per-pixel Plücker rays.
+
+The Gaussians come out in that frame (`GSOutput.to_world()` maps them to the
+caller's world); colours are RGB (no SH). Rendering uses the upstream background and near / far
+planes. `crop_mode="pad"` / `"none"` replace step 1 with the ffgs rules.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+
+import torch
+import torch.nn.functional as F
+import torchvision.transforms.functional as TF
+
+from ...geometry import ModelFrame, anchored_frame
+from ...image import fit_images, fit_intrinsics, rescale
+from ...processor import ImageFitConfig, Prepared, Processor
+from ...types import Cameras, Gaussians, Views
+
+IMAGENET_MEAN = (0.485, 0.456, 0.406)
+IMAGENET_STD = (0.229, 0.224, 0.225)
+CAMERA_NORMALIZATIONS = ("first_cam", "mean_cam")
+_AUTOCAST = {"bfloat16": torch.bfloat16, "float16": torch.float16}
+
+
+@dataclass
+class TokenGSProcessorConfig(ImageFitConfig):
+    image_shape: list[int] = field(default_factory=lambda: [256, 448])
+    resize_mode: str = "bilinear"
+    # "first_cam": poses relative to the first input view; "mean_cam": to the mean
+    # input camera (the 2026.6 latent-bottleneck models).
+    camera_normalization: str = "first_cam"
+    scene_scale: float = 0.15
+    # The input view count the checkpoint was trained for. Other counts run (the
+    # number of Gaussians does not depend on it) but warn. None: any.
+    num_input_views: int | None = None
+    image_mean: list[float] = field(default_factory=lambda: list(IMAGENET_MEAN))
+    image_std: list[float] = field(default_factory=lambda: list(IMAGENET_STD))
+    # Render settings of the upstream renderer, in model-frame units.
+    znear: float = 0.025
+    zfar: float = 125.0
+    background: list[float] = field(default_factory=lambda: [0.5, 0.5, 0.5])
+    # Autocast dtype of the model on CUDA ("bfloat16", as upstream evaluates, or
+    # "float16"); None runs in fp32.
+    autocast: str | None = "bfloat16"
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if self.camera_normalization not in CAMERA_NORMALIZATIONS:
+            raise ValueError(
+                f"camera_normalization must be one of {CAMERA_NORMALIZATIONS}"
+            )
+        if self.autocast is not None and self.autocast not in _AUTOCAST:
+            raise ValueError(f"autocast must be None or one of {sorted(_AUTOCAST)}")
+
+
+class TokenGSProcessor(Processor):
+    config_cls = TokenGSProcessorConfig
+
+    def preprocess(
+        self, views: Views, device: torch.device, scene_scale: float | None = None
+    ) -> Prepared:
+        # TokenGS is conditioned on the input cameras (Plücker rays).
+        views.require("c2w", "intrinsics", by="TokenGS")
+        cfg = self.config
+        num_views = views.images.shape[1]
+        if cfg.num_input_views is not None and num_views != cfg.num_input_views:
+            warnings.warn(
+                f"this TokenGS checkpoint was trained for {cfg.num_input_views} "
+                f"input views, got {num_views}",
+                stacklevel=3,
+            )
+        scale = cfg.scene_scale if scene_scale is None else scene_scale
+        frame = self.frame(views.c2w, scale)
+        images, k = self.fit_pixel_views(views)
+        c2w = frame.c2w_to_model(views.c2w.float())
+        h, w = images.shape[-2:]
+        plucker = torch.stack(
+            [
+                ray_condition(k[i : i + 1], c2w[i : i + 1], h, w)[0]
+                for i in range(len(k))
+            ]
+        )
+        normalized = torch.stack(
+            [TF.normalize(x, cfg.image_mean, cfg.image_std) for x in images]
+        )
+        model_input = {"images": normalized.to(device), "plucker": plucker.to(device)}
+        return Prepared(model_input, frame)
+
+    def frame(self, c2w: torch.Tensor, scale: float) -> ModelFrame:
+        """The model frame of input views c2w [B, V, 4, 4]."""
+        if self.config.camera_normalization == "first_cam":
+            return anchored_frame(c2w, scale)
+        anchor = torch.stack([mean_camera(x.float()) for x in c2w])
+        return ModelFrame(anchor_c2w=anchor, scale=float(scale))
+
+    def postprocess(self, model_output: torch.Tensor) -> Gaussians:
+        g = model_output.float()
+        return Gaussians(
+            means=g[..., 0:3],
+            opacities=g[..., 3],
+            scales=g[..., 4:7],
+            quats=g[..., 7:11],
+            colors=g[..., 11:14],
+            sh_degree=None,
+        )
+
+    def render_planes(self, frame: ModelFrame) -> tuple[float, float]:
+        return self.config.znear / frame.scale, self.config.zfar / frame.scale
+
+    @property
+    def background(self) -> tuple[float, float, float]:
+        return tuple(self.config.background)
+
+    @property
+    def autocast_dtype(self) -> torch.dtype | None:
+        return None if self.config.autocast is None else _AUTOCAST[self.config.autocast]
+
+    # --- fitting inputs ---------------------------------------------------------
+
+    def fit_pixel_views(
+        self, views: Views, image_shape: list[int] | None = None
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        """Images [B, V, 3, h, w] and pixel intrinsics [B, V, 4] (fx, fy, cx, cy)
+        at `image_shape` (default: the model's), by the config's `crop_mode`."""
+        views.require("intrinsics", by="TokenGS")
+        cfg = self.config
+        shape = tuple(image_shape or cfg.image_shape)
+        src_h, src_w = views.image_shape
+        if views.normalized_intrinsics:
+            k = _pixel_k(views.intrinsics.float(), (src_h, src_w))
+        else:
+            k = _flat_k(views.intrinsics.float())
+        images, ks = [], []
+        for img, ki in zip(views.images, k):
+            if cfg.crop_mode == "crop":
+                img, ki = crop_and_resize(img, ki, shape, self._resize)
+            else:
+                img, kn = fit_images(
+                    img,
+                    _normalized_k(ki, (src_h, src_w)),
+                    shape,
+                    resize_mode=cfg.resize_mode,
+                    crop_mode=cfg.crop_mode,
+                    resize=self.resize,
+                    pad_value=cfg.pad_value,
+                )
+                ki = _pixel_k(kn, shape)
+            images.append(img)
+            ks.append(ki)
+        return torch.stack(images), torch.stack(ks)
+
+    def fit_views(self, views: Views, image_shape: list[int] | None = None) -> Views:
+        images, k = self.fit_pixel_views(views, image_shape)
+        return Views(
+            images,
+            _normalized_k(k, tuple(images.shape[-2:])),
+            views.c2w,
+            normalized_intrinsics=True,
+        )
+
+    def fit_cameras(
+        self, cameras: Cameras, image_shape: list[int] | None = None
+    ) -> Cameras:
+        cfg = self.config
+        shape = tuple(image_shape or cfg.image_shape)
+        if cfg.crop_mode != "crop":
+            k = fit_intrinsics(
+                cameras.normalized_k, cameras.image_shape, shape, cfg.crop_mode
+            )
+            return Cameras(cameras.c2w, k, shape, normalized_intrinsics=True)
+        if cameras.normalized_intrinsics:
+            k = _pixel_k(cameras.intrinsics.float(), cameras.image_shape)
+        else:
+            k = _flat_k(cameras.intrinsics.float())
+        k = crop_and_resize_intrinsics(k, cameras.image_shape, shape)
+        return Cameras(
+            cameras.c2w, _normalized_k(k, shape), shape, normalized_intrinsics=True
+        )
+
+    def _resize(self, images: torch.Tensor, shape: tuple[int, int]) -> torch.Tensor:
+        if self.resize is not None:
+            return self.resize(images, shape)
+        return rescale(images, shape, self.config.resize_mode)
+
+
+def crop_region(
+    image_shape: tuple[int, int], shape: tuple[int, int]
+) -> tuple[int, int]:
+    """(h, w) of the largest centred crop of `image_shape` with the aspect ratio
+    of `shape` (upstream `ImageTransform` with `max_crop=True`)."""
+    ori_h, ori_w = image_shape
+    crop_ratio = min(ori_h / shape[0], ori_w / shape[1])
+    return int(shape[0] * crop_ratio), int(shape[1] * crop_ratio)
+
+
+def crop_and_resize_intrinsics(
+    intrinsics: torch.Tensor, image_shape: tuple[int, int], shape: tuple[int, int]
+) -> torch.Tensor:
+    """Pixel intrinsics [..., 4] (fx, fy, cx, cy) through `crop_and_resize`."""
+    ori_h, ori_w = image_shape
+    new_h, new_w = crop_region(image_shape, shape)
+    # u,v convention: shift relative to original (un-cropped) raster
+    shift = ((new_w - ori_w) / 2, (new_h - ori_h) / 2)
+    scale = (shape[1] / new_w, shape[0] / new_h)
+    return torch.stack(
+        [
+            intrinsics[..., 0] * scale[0],
+            intrinsics[..., 1] * scale[1],
+            (intrinsics[..., 2] + shift[0]) * scale[0],
+            (intrinsics[..., 3] + shift[1]) * scale[1],
+        ],
+        dim=-1,
+    )
+
+
+def crop_and_resize(
+    images: torch.Tensor,
+    intrinsics: torch.Tensor,
+    shape: tuple[int, int],
+    resize=None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Centre-crop [V, 3, H, W] images to the aspect ratio of `shape`, resize to
+    `shape` (default: torchvision bilinear, antialiased), and map the pixel
+    intrinsics [V, 4] alike."""
+    image_shape = tuple(images.shape[-2:])
+    images = TF.center_crop(images, list(crop_region(image_shape, shape)))
+    if resize is None:
+        images = TF.resize(
+            images, list(shape), TF.InterpolationMode.BILINEAR, antialias=True
+        )
+    else:
+        images = resize(images, tuple(shape))
+    return images, crop_and_resize_intrinsics(intrinsics, image_shape, shape)
+
+
+def mean_camera(c2w: torch.Tensor) -> torch.Tensor:
+    """The mean camera [4, 4] of input views c2w [V, 4, 4]: mean position, mean
+    forward / down axes orthonormalised (upstream `_normalize_camera_mean_cam`)."""
+    position_avg = c2w[:, :3, 3].mean(0)  # (3,)
+    forward_avg = c2w[:, :3, 2].mean(0)  # (3,)
+    down_avg = c2w[:, :3, 1].mean(0)  # (3,)
+    # gram-schmidt process
+    forward_avg = F.normalize(forward_avg, dim=0)
+    down_avg = F.normalize(down_avg - down_avg.dot(forward_avg) * forward_avg, dim=0)
+    right_avg = torch.linalg.cross(down_avg, forward_avg)
+    pos_avg = torch.stack([right_avg, down_avg, forward_avg, position_avg], dim=1)
+    bottom = torch.tensor([[0, 0, 0, 1]], device=pos_avg.device).float()
+    return torch.cat([pos_avg, bottom], dim=0)  # (4, 4)
+
+
+def ray_condition(K: torch.Tensor, c2w: torch.Tensor, H: int, W: int) -> torch.Tensor:
+    """Plücker rays (o x d, d) [V, 6, H, W] through pixel centres, for pixel
+    intrinsics K [1, V, 4] and model-frame c2w [1, V, 4, 4]."""
+    B, V = K.shape[:2]
+    j, i = torch.meshgrid(
+        torch.linspace(0, H - 1, H, device=K.device, dtype=K.dtype),
+        torch.linspace(0, W - 1, W, device=K.device, dtype=K.dtype),
+        indexing="ij",
+    )
+    i = i.reshape([1, 1, H * W]).expand([B, V, H * W]) + 0.5
+    j = j.reshape([1, 1, H * W]).expand([B, V, H * W]) + 0.5
+
+    fx, fy, cx, cy = K.chunk(4, dim=-1)
+    zs = torch.ones_like(i)
+    xs = (i - cx) / fx * zs
+    ys = (j - cy) / fy * zs
+    zs = zs.expand_as(ys)
+
+    directions = torch.stack((xs, ys, zs), dim=-1)
+    directions = directions / directions.norm(dim=-1, keepdim=True)
+
+    rays_d = directions @ c2w[..., :3, :3].transpose(-1, -2)
+    rays_o = c2w[..., :3, 3]
+    rays_o = rays_o[..., None, :].expand_as(rays_d)
+
+    rays_dxo = torch.cross(rays_o, rays_d, dim=-1)
+    plucker = torch.cat([rays_dxo, rays_d], dim=-1)
+    return plucker.reshape(B, V, H, W, 6).permute(0, 1, 4, 2, 3).contiguous()
+
+
+def _flat_k(k: torch.Tensor) -> torch.Tensor:
+    """3x3 K [..., 3, 3] -> [..., 4] (fx, fy, cx, cy)."""
+    return torch.stack((k[..., 0, 0], k[..., 1, 1], k[..., 0, 2], k[..., 1, 2]), -1)
+
+
+def _pixel_k(k: torch.Tensor, image_shape: tuple[int, int]) -> torch.Tensor:
+    """Normalised 3x3 K -> pixel [..., 4] (fx, fy, cx, cy)."""
+    h, w = image_shape
+    return torch.stack(
+        (k[..., 0, 0] * w, k[..., 1, 1] * h, k[..., 0, 2] * w, k[..., 1, 2] * h), -1
+    )
+
+
+def _normalized_k(k: torch.Tensor, image_shape: tuple[int, int]) -> torch.Tensor:
+    """Pixel [..., 4] (fx, fy, cx, cy) -> normalised 3x3 K."""
+    h, w = image_shape
+    out = torch.zeros(*k.shape[:-1], 3, 3, dtype=k.dtype, device=k.device)
+    out[..., 0, 0] = k[..., 0] / w
+    out[..., 1, 1] = k[..., 1] / h
+    out[..., 0, 2] = k[..., 2] / w
+    out[..., 1, 2] = k[..., 3] / h
+    out[..., 2, 2] = 1.0
+    return out

ffgs/pipeline.py

@@ -0,0 +1,341 @@
+"""`GSPipeline`: posed images in, Gaussians out, for any registered model."""
+
+from __future__ import annotations
+
+import json
+from contextlib import nullcontext
+from dataclasses import dataclass, replace
+from itertools import chain
+from pathlib import Path
+from typing import Any
+
+import torch
+from torch import nn
+
+from . import dynamic, zoo
+from . import render as render_mod
+from .geometry import ModelFrame
+from .processor import PROCESSOR_CONFIG_NAME, Processor, read_json
+from .registry import ModelSpec, get_model_spec, spec_for_model
+from .types import Cameras, Gaussians, Views
+
+CONFIG_NAME = "config.json"
+# Options of `huggingface_hub` downloads that `from_pretrained` passes through.
+HUB_KWARGS = frozenset(
+    {
+        "revision",
+        "subfolder",
+        "cache_dir",
+        "token",
+        "force_download",
+        "local_files_only",
+    }
+)
+# What `subfolder=` fetches from a Hub repo: a saved pipeline and its code.
+_PIPELINE_FILES = (
+    CONFIG_NAME,
+    "model.safetensors",
+    "pytorch_model.bin",
+    PROCESSOR_CONFIG_NAME,
+    "*.py",
+)
+
+
+SPACES = ("model", "world")
+
+
+@dataclass
+class GSOutput:
+    """Predicted Gaussians, the model frame they were predicted in, and the input
+    cameras when the model predicts them.
+
+    `gaussians` (and `cameras`) are in `space`: `"model"`, the model's own frame,
+    as `pipe(views)` returns them (what the model's official code produces); or
+    `"world"`, the frame of the input c2w, after `to_world()`. `frame` is the
+    model frame either way; it is None when the model predicts its cameras and the
+    views had no poses, and then there is no world frame to go to.
+    """
+
+    gaussians: Gaussians
+    frame: ModelFrame | None
+    space: str = "model"
+    # Predicted input cameras (normalised K for the model's input images).
+    cameras: Cameras | None = None
+
+    def __post_init__(self) -> None:
+        if self.space not in SPACES:
+            raise ValueError(f"space must be one of {SPACES}, got {self.space!r}")
+        if self.space == "world" and self.frame is None:
+            raise ValueError("world-frame output needs the frame it came from")
+
+    def to_world(self) -> GSOutput:
+        """The same output with fp32 Gaussians (and cameras) in the world frame of
+        the input c2w (unchanged if already there). Rejects input c2w whose rotation
+        is not proper (non-orthonormal or a reflection), and outputs without a
+        frame (a model that predicts its cameras, run without poses)."""
+        if self.space == "world":
+            return self
+        if self.frame is None:
+            raise ValueError(
+                "this output has no world frame: the model predicts its own "
+                "cameras and the views had no poses (c2w). Its Gaussians and "
+                "`cameras` are in the model's frame; give Views c2w to place them "
+                "in yours"
+            )
+        to_world = self.frame.model_to_world()
+        gaussians = to_world.apply(self.gaussians.to(dtype=torch.float32))
+        cameras = self.cameras
+        if cameras is not None:
+            cameras = to_world.apply_cameras(replace(cameras, c2w=cameras.c2w.float()))
+        return GSOutput(gaussians, self.frame, space="world", cameras=cameras)
+
+
+class GSPipeline:
+    """Load with `from_pretrained`, call on `Views`, render at `Cameras`.
+
+    >>> pipe = GSPipeline.from_pretrained("path/or/repo-id", device="cuda")
+    >>> out = pipe(Views(images, intrinsics, c2w))  # Gaussians in the model frame
+    >>> images = pipe.render(out, Cameras(c2w_new, intrinsics_new, (h, w)))["images"]
+    >>> out.to_world().gaussians.save_ply("scene.ply")  # in the frame of c2w
+    """
+
+    def __init__(
+        self, model: nn.Module, processor: Processor, model_type: str | None = None
+    ) -> None:
+        self.model = model.eval()
+        self.processor = processor
+        self.model_type = model_type or spec_for_model(model).model_type
+
+    # --- loading / saving -------------------------------------------------------
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        pretrained: str | Path,
+        *,
+        model_type: str | None = None,
+        device: torch.device | str | None = None,
+        processor_overrides: dict[str, Any] | None = None,
+        trust_remote_code: bool = False,
+        **hub_kwargs: Any,
+    ) -> GSPipeline:
+        """`pretrained`: a directory written by `save_pretrained`, a model zoo
+        name (`"<family>/<variant>"`, see `ffgs.zoo.list_models()`), or a Hub
+        repo id — tried in that order. A zoo family name is reserved: it is
+        never read as a Hub repo owner.
+
+        `model_type` overrides the one in config.json (for directories exported
+        before it was recorded). It resolves to a registered or built-in model,
+        then an installed `ffgs.models` plugin, then — only with
+        `trust_remote_code=True` — the code the repo lists under
+        config.json:auto_map (see `ffgs.registry`). Pin `revision=` when trusting
+        Hub code.
+
+        `hub_kwargs` (`revision`, `subfolder`, `cache_dir`, `token`,
+        `force_download`, `local_files_only`) apply to every file fetched from the
+        Hub: config, weights, processor config and code. `subfolder` selects a
+        variant saved in a subdirectory of a repo (or of a local directory). A zoo
+        entry pins its own revision and file, so it takes neither.
+        """
+        unknown = set(hub_kwargs) - HUB_KWARGS
+        if unknown:
+            raise TypeError(
+                f"unexpected arguments {sorted(unknown)}; Hub options are "
+                f"{sorted(HUB_KWARGS)}"
+            )
+        name = zoo.resolve(pretrained)
+        if name is not None:
+            return cls._from_zoo(
+                name, model_type, device, processor_overrides, **hub_kwargs
+            )
+        subfolder = hub_kwargs.pop("subfolder", None)
+        if subfolder:
+            pretrained = _fetch_subfolder(pretrained, subfolder, **hub_kwargs)
+        config = None
+        if model_type is None:
+            config = read_json(pretrained, CONFIG_NAME, **hub_kwargs)
+            model_type = config.get("model_type")
+            if model_type is None:
+                raise ValueError(
+                    f"{CONFIG_NAME} of {pretrained} has no model_type; pass "
+                    "model_type= or re-export with GSPipeline.save_pretrained"
+                )
+        spec = _resolve_spec(
+            model_type, pretrained, config, trust_remote_code, **hub_kwargs
+        )
+        model = spec.model_cls.from_pretrained(str(pretrained), **hub_kwargs)
+        processor = spec.processor_cls.from_pretrained(pretrained, **hub_kwargs)
+        if processor_overrides:
+            processor = spec.processor_cls(processor.config, **processor_overrides)
+        pipe = cls(model, processor, model_type)
+        return pipe.to(device) if device is not None else pipe
+
+    @classmethod
+    def _from_zoo(
+        cls,
+        name: str,
+        model_type: str | None,
+        device: torch.device | str | None,
+        processor_overrides: dict[str, Any] | None,
+        **hub_kwargs: Any,
+    ) -> GSPipeline:
+        entry = zoo.get_entry(name)
+        pinned = sorted({"revision", "subfolder"} & set(hub_kwargs))
+        if pinned:
+            raise TypeError(
+                f"{name} is a zoo entry pinned to {entry.weights.repo}/"
+                f"{entry.weights.file}@{entry.weights.revision}; {pinned} do not "
+                "apply to it"
+            )
+        if model_type is not None and model_type != entry.model_type:
+            raise ValueError(
+                f"zoo entry {name} is a {entry.model_type!r} model, not "
+                f"{model_type!r}"
+            )
+        spec = get_model_spec(entry.model_type)
+        model = spec.model_cls(**entry.model)
+        state_dict = zoo.load_state_dict(entry, spec, **hub_kwargs)
+        try:
+            model.load_state_dict(state_dict, strict=True)
+        except RuntimeError as err:
+            raise RuntimeError(
+                f"zoo entry {name}: weights do not fit {spec.model_cls.__name__} "
+                f"(check the entry's model config and the model_type's "
+                f"convert_state_dict): {err}"
+            ) from None
+        processor = spec.processor_cls.from_dict(
+            entry.processor, source=f"zoo entry {name}: processor"
+        )
+        if processor_overrides:
+            processor = spec.processor_cls(processor.config, **processor_overrides)
+        pipe = cls(model, processor, entry.model_type)
+        return pipe.to(device) if device is not None else pipe
+
+    def save_pretrained(
+        self, save_directory: str | Path, *, include_code: bool = False, **kwargs: Any
+    ) -> Path:
+        """Weights + config.json (with model_type) + processor_config.json; for a
+        model loaded from repo code, that code too (+ config.json:auto_map).
+
+        `include_code=True` also ships the code of an installed model: the package
+        holding the model and processor classes is copied in and listed under
+        config.json:auto_map, so the directory loads with `trust_remote_code=True`
+        where that package is not installed (see `ffgs.dynamic.export_code`)."""
+        save_directory = Path(save_directory)
+        model_cls, processor_cls = type(self.model), type(self.processor)
+        # Code first: a package that cannot be shipped fails before any write.
+        auto_map = dynamic.save_code(model_cls, processor_cls, save_directory)
+        if auto_map is None and include_code:
+            auto_map = dynamic.export_code(model_cls, processor_cls, save_directory)
+        self.model.save_pretrained(save_directory, **kwargs)
+        config_path = save_directory / CONFIG_NAME
+        config = json.loads(config_path.read_text()) if config_path.is_file() else {}
+        config["model_type"] = self.model_type
+        if auto_map is not None:
+            config["auto_map"] = auto_map
+        config_path.write_text(json.dumps(config, indent=2, sort_keys=True) + "\n")
+        self.processor.save_pretrained(save_directory)
+        return save_directory
+
+    def to(self, device: torch.device | str) -> GSPipeline:
+        self.model.to(device)
+        return self
+
+    @property
+    def device(self) -> torch.device:
+        """Where the model is: its first parameter or buffer, else the CPU."""
+        tensor = next(chain(self.model.parameters(), self.model.buffers()), None)
+        return torch.device("cpu") if tensor is None else tensor.device
+
+    # --- inference --------------------------------------------------------------
+
+    def autocast(self):
+        dtype = self.processor.autocast_dtype
+        if dtype is None or self.device.type != "cuda":
+            return nullcontext()
+        return torch.autocast(device_type="cuda", dtype=dtype)
+
+    @torch.no_grad()
+    def __call__(self, views: Views, **options: Any) -> GSOutput:
+        """Predict Gaussians from `views`, in the model frame (`out.to_world()` for
+        the frame of `views.c2w`). Models that predict cameras run without c2w,
+        and with c2w fit their frame to them (`out.frame.residuals`). `options`
+        go to the processor (e.g. `scene_scale=`)."""
+        with torch.autocast(device_type=self.device.type, enabled=False):
+            prepared = self.processor.preprocess(views, self.device, **options)
+        with self.autocast():
+            raw = self.model(prepared.model_input)
+        gaussians = self.processor.postprocess(raw)
+        cameras = self.processor.predicted_cameras(raw)
+        frame = self.processor.output_frame(views, prepared, cameras)
+        return GSOutput(gaussians, frame, cameras=cameras)
+
+    @torch.no_grad()
+    def render(
+        self,
+        output: GSOutput,
+        cameras: Cameras,
+        **kwargs: Any,
+    ) -> dict[str, torch.Tensor]:
+        """Render `output` at `cameras`, given in the world frame of the input c2w
+        whichever `space` the Gaussians are in: for model-frame Gaussians the
+        cameras and the processor's near / far planes are taken into the model
+        frame first. Without a frame (no input poses) there is no world: `cameras`
+        are in the model's frame, like `output.cameras`. The background and other
+        render settings are the processor's (`render_settings`) unless given."""
+        near, far = self.processor.render_planes(output.frame)
+        if output.space == "model" and output.frame is not None:
+            cameras = output.frame.cameras_to_model(cameras)
+            near, far = near * output.frame.scale, far * output.frame.scale
+        kwargs.setdefault("background", self.processor.background)
+        for key, value in self.processor.render_settings.items():
+            kwargs.setdefault(key, value)
+        with torch.autocast(device_type=self.device.type, enabled=False):
+            return render_mod.render(
+                output.gaussians, cameras.to(self.device), near=near, far=far, **kwargs
+            )
+
+
+def _fetch_subfolder(pretrained: str | Path, subfolder: str, **hub_kwargs: Any) -> Path:
+    """A local directory holding `subfolder` of a directory or Hub repo."""
+    local = Path(pretrained)
+    if local.is_dir():
+        path = local / subfolder
+    else:
+        from huggingface_hub import snapshot_download
+
+        patterns = [f"{subfolder}/{name}" for name in _PIPELINE_FILES]
+        path = Path(
+            snapshot_download(str(pretrained), allow_patterns=patterns, **hub_kwargs)
+        )
+        path = path / subfolder
+    if not path.is_dir():
+        raise FileNotFoundError(f"{pretrained} has no subfolder {subfolder!r}")
+    return path
+
+
+def _resolve_spec(
+    model_type: str,
+    pretrained: str | Path,
+    config: dict | None,
+    trust_remote_code: bool,
+    **hub_kwargs: Any,
+) -> ModelSpec:
+    """Installed model first; repo code (config.json:auto_map) only if trusted."""
+    try:
+        return get_model_spec(model_type)
+    except KeyError:
+        if config is None:
+            config = read_json(pretrained, CONFIG_NAME, **hub_kwargs)
+        auto_map = config.get("auto_map")
+        if auto_map is None:
+            raise
+    if not trust_remote_code:
+        raise ValueError(
+            f"model_type {model_type!r} is not installed, and {pretrained} ships "
+            f"its own code for it ({CONFIG_NAME}:auto_map = {auto_map}). That code "
+            "would run on this machine: read it, then pass trust_remote_code=True "
+            "(with a pinned revision= for Hub repos). Or install a package that "
+            f"provides {model_type!r}."
+        )
+    return dynamic.spec_from_auto_map(model_type, auto_map, pretrained, **hub_kwargs)