Skip to content

Packaging an extension#

Three of CaptureGraph's Python packages carry the extension points, in a strict downward order — capturegraph (cg), capturegraph_ui (cgui) and capturegraph_recipes (cgr) — and everything a study adds plugs into an extension point the core package defines: a type (a value with an on-disk form), a component (something a page draws), a log sink, or a recipe (a cached analysis function over the scratch). Extending CaptureGraph lays out that taxonomy; this page covers the package that ships the other three. An extension is a uv workspace member that depends on the core package — and on the ui package if it ships components — and adds types, recipes, viewers and package data. capturegraph-recipes, the recipes package, is the template; this page is its layout, with the reasons.

The layout#

Path Holds
pyproject.toml The member's metadata, dependencies and wheel contents — the next section.
capturegraph_recipes/__init__.py The cgr surface: every type at the root, one name per recipe family, SplatViewer, and the GPU boundary's GPU, GPU_PYTHON_ENV, gpu_python and gpu_run.
types/compositions/, types/geometry/, types/reconstruction/ The vocabulary the package adds, one type per file, grouped by what a type is: the Struct compositions (posed_image.py, reconstruction.py, multiview.py), the geometry files (splat.py, relative_depth.py), the reconstruction arrays (keypoints.py, pairs.py, matches.py, tracks.py, observations.py).
sfm/, depth/, splats/, scheduling/ One folder per recipe family — the recipes that share a subject: structure from motion, learned depth, 3D Gaussian splats, capture scheduling — each __init__ aggregating its leaves, themselves in stage folders (sfm/correspondence/, depth/models/, splats/training/, scheduling/distance/, …).
depth/models/drivers/ The built-in GPU drivers, shipped in the wheel.
splats/viewer.py SplatViewer, beside the family whose result it draws.
splats/_vendor/ VERSIONS, and gsplat/ — its JavaScript and LICENSE.
gpu.py The GPU interpreter boundary: gpu_python, gpu_run, GPU_PYTHON_ENV and GPU.
tests/ The suite, kept out of the wheel.

The folders document the model: one theme per folder, one object per file, and the tree mirrors the conceptual hierarchy. A type belongs to no recipe in particular, so types/ groups by what a type is rather than by the recipe that produces it; a viewer sits beside what produces the value it draws.

gpu.py is the one place the package touches a GPU. A driver is a standalone script — torch, numpy and PIL, never capturegraph — that gpu_run runs by path in a separate interpreter, the one the CG_GPU_PYTHON environment variable names (GPU_PYTHON_ENV is that variable's name, and gpu_python finds the interpreter), so the package's own environment never imports torch. The interpreter runs with -P, so the driver's own folder is not on sys.path: a driver may be named after the package it imports (depth_anything_3.py imports the installed depth_anything_3), and it never imports a script beside it. GPU names the resource every GPU-bound recipe locks, as cg.lock("gpu"). The depth drivers ship under depth/models/drivers/, the splat trainer under splats/training/; the arguments a depth driver takes and the files it writes back are the driver contract (Learned depth).

pyproject.toml#

The member's file, with the dependency list shortened:

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=61.0", "wheel"]

[project]
name = "capturegraph-recipes"
version = "0.1.0"
description = "Reconstruction and scheduling recipes for CaptureGraph, …"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
  "capturegraph-lib",
  "capturegraph-ui",
  "numpy>=2.5.1",
  "scipy>=1.18.0",
  # … opencv-python-headless, Pillow, huggingface-hub, pandas, shapely,
  # meteostat, astral, openmeteo-requests, requests-cache, retry-requests,
  # each with a lower bound
]

[dependency-groups]
dev = ["pytest>=9.1.1", "setuptools>=80.9.0"]

[tool.uv.sources]
capturegraph-lib = { workspace = true }
capturegraph-ui = { workspace = true }

[tool.setuptools.packages.find]
include = ["capturegraph_recipes*"]
where = ["."]

[tool.setuptools.package-data]
"capturegraph_recipes.splats" = ["_vendor/*", "_vendor/*/*"]

[tool.pytest.ini_options]
testpaths = ["tests"]

Every heavy dependency lives here and nowhere beneath: the core package imports without SciPy, meteostat or Hugging Face Hub present. The list is the union of what the four families import — SciPy, OpenCV, Pillow and Hugging Face Hub for reconstruction (sfm, depth, splats), pandas and shapely for scheduling, and meteostat, Open-Meteo and astral for cgr.scheduling.forecast, which scores a capture by the weather and the sun's position.

The include pattern is the wheel's contents: capturegraph_recipes* ships the package tree — depth/models/drivers/ and the vendored JavaScript with it — and leaves tests out. The package-data globs carry the non-Python files, _vendor/* for VERSIONS and _vendor/*/* for gsplat's two. A packaging test in the suite pins both: the include pattern is exactly the package glob, and find_packages under it yields capturegraph_recipes.depth.models.drivers and nothing outside the package tree. The dev group holds what that test needs, pytest and setuptools.

Inside the workspace the member is registered in the root pyproject.toml — [tool.uv.workspace].members, [tool.uv.sources] and the root dependencies — and uv sync installs it editable. No CaptureGraph package is published (Installation), so a project outside the workspace adds the member from a clone as an editable path:

uv add --editable /path/to/CaptureGraph/capturegraph-recipes

uv reads the member's workspace sources, so the core and ui packages come along editable from the same clone.

The surface#

The root __init__ is the one import a user makes, and it re-exports every public name leaf by leaf — the four families, the GPU boundary, the viewer and the ten types:

from capturegraph_recipes import (
    depth as depth,
    scheduling as scheduling,
    sfm as sfm,
    splats as splats,
)
from capturegraph_recipes.gpu import (
    GPU as GPU,
    GPU_PYTHON_ENV as GPU_PYTHON_ENV,
    gpu_python as gpu_python,
    gpu_run as gpu_run,
)
from capturegraph_recipes.splats.viewer import (
    SplatViewer as SplatViewer,
)
from capturegraph_recipes.types.geometry.splat import (
    Splat as Splat,
)
# … one block per type: Keypoints, Matches, Multiview, Observations, Pairs,
# PosedImage, Reconstruction, RelativeDepth, Tracks

Inside the package, a module imports from leaf modules of its own package and from the packages beneath it through their public surfaces — import capturegraph as cg, import capturegraph_ui as cgui — never from a package above and never from another package's leaf. The order is what keeps the core the standard: it imports without the recipes' dependencies present, and a change to a recipe never touches the JSON the app executes. An upward import would make importing the core pull in SciPy and the rest, and every recipe change a change to the standard. The check is a grep of the source for the module name, capturegraph_recipes, in the core and ui packages, and it stays empty; a README that points a reader upward names the distribution, capturegraph-recipes, and is prose, not an import.

Tests#

The cg_scratch pytest fixture is shipped by the core package as a plugin, so a test in any package gets an isolated scratch by naming it: every new, every memoized call and every ImpureState for that test lands under tmp_path and is gone afterwards.

Three patterns cover the suite — the shapes tests take, not a checklist an extension must fill. A recipe test calls the recipe twice and asserts the second call is a hit. A type test round-trips a value and asserts on what loads back (Adding a type). A viewer test builds a page and reads the folder (Adding a component).

A GPU stage — cgr.depth.predict, cgr.depth.multiview, cgr.splats.train — is tested without torch by standing in for the interpreter. The test writes a small script that takes -P, the driver and its arguments, asserts what the stage promised to pass (the driver's name, the staged NNNNN.jpg files, --multiview only when asked) and writes back the files the driver contract promises, then points CG_GPU_PYTHON at it with monkeypatch.setenv(cgr.GPU_PYTHON_ENV, str(script)). The recipe under test runs unchanged, so the suite pins the contract from the library's side and never needs a GPU.

The reference#

The API reference is one generated page per module under docs/reference/<package>/, with a matching nested nav in zensical.toml; both are committed. The generator holds the list of packages it mirrors — add the member and its package name to it, then regenerate:

uv run python scripts/gen-api-reference.py          # rewrite pages and nav
uv run python scripts/gen-api-reference.py --check  # exit 1 if anything is stale

CI runs --check before building the site, so a stale reference fails the build: regenerate after adding, moving or removing any module.

Checking the package#

A finished member passes three checks: uv sync --all-packages from the repository root resolves it and installs its dev group, uv run pytest from its directory passes its suite, and uv run python scripts/gen-api-reference.py --check stays green.