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 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.