Skip to content

contract

contract #

The driver contract, as the library speaks it: stage images in, run, read outputs back.

  1. Stage. stage_images re-encodes every image as images/<staged_name>.jpg under the workspace, its longest side at most max_dimension; the staged size is the size every output comes back at. staged_name is the one naming rule: zero-padded, so a driver listing the directory in lexicographic order sees the array's order.
  2. Run. run_driver runs the model's driver in the GPU interpreter with --images, --weights (a cgr.depth.snapshot) and --output, plus --multiview when the images are posed together.
  3. Read. read_depths turns each <staged_name>.npy and <staged_name>_conf.npy into a RelativeDepth; read_cameras and read_points read the multi-view extras, cameras.json and points.npy/colors.npy.

Camera dataclass #

One posed image as a multi-view driver reports it: OpenCV, at the staged size.

Source code in capturegraph-recipes/capturegraph_recipes/depth/inference/contract.py
@dataclass(frozen=True)
class Camera:
    """One posed image as a multi-view driver reports it: OpenCV, at the staged size."""

    camera_to_world: np.ndarray
    focal_x: float
    focal_y: float
    center_x: float
    center_y: float
    width: int
    height: int

read_cameras(output) #

The cameras a multi-view driver wrote, one per staged image in order.

Source code in capturegraph-recipes/capturegraph_recipes/depth/inference/contract.py
def read_cameras(output: Path) -> list[Camera]:
    """The cameras a multi-view driver wrote, one per staged image in order."""
    return [
        Camera(
            camera_to_world=np.asarray(entry["camera_to_world"], dtype=np.float64).reshape(4, 4),
            focal_x=float(entry["focal_x"]),
            focal_y=float(entry["focal_y"]),
            center_x=float(entry["center_x"]),
            center_y=float(entry["center_y"]),
            width=int(entry["width"]),
            height=int(entry["height"]),
        )
        for entry in json.loads((output / "cameras.json").read_text())
    ]

read_depths(output, count) #

The driver's depth and confidence planes for count images as RelativeDepth values.

Source code in capturegraph-recipes/capturegraph_recipes/depth/inference/contract.py
def read_depths(output: Path, count: int) -> cg.Array[RelativeDepth]:
    """The driver's depth and confidence planes for ``count`` images as ``RelativeDepth`` values."""
    depths = []
    for index in range(count):
        stem = output / staged_name(index)
        depths.append(
            RelativeDepth.of_arrays(
                np.load(f"{stem}.npy").astype(np.float32),
                np.load(f"{stem}_conf.npy").astype(np.float32),
            )
        )
    return cg.Array[RelativeDepth](depths)

read_points(output) #

The points a multi-view driver wrote as (positions, colors).

Source code in capturegraph-recipes/capturegraph_recipes/depth/inference/contract.py
def read_points(output: Path) -> tuple[np.ndarray, np.ndarray]:
    """The points a multi-view driver wrote as ``(positions, colors)``."""
    return (
        np.load(output / "points.npy").astype(np.float32).reshape(-1, 3),
        np.load(output / "colors.npy").astype(np.uint8).reshape(-1, 3),
    )

run_driver(work, driver, weights, *, multiview) #

Run driver over the staged images with weights; the output directory.

Source code in capturegraph-recipes/capturegraph_recipes/depth/inference/contract.py
def run_driver(
    work: cg.ManagedDir,
    driver: Path,
    weights: cg.ManagedDir,
    *,
    multiview: bool,
) -> Path:
    """Run ``driver`` over the staged images with ``weights``; the output directory."""
    output = work / OUTPUT
    output.mkdir()
    gpu_run(
        work,
        driver,
        [
            "--images",
            work / IMAGES,
            "--weights",
            weights,
            "--output",
            output,
            *(["--multiview"] if multiview else []),
        ],
    )
    return output

stage_images(images, work, max_dimension) #

Re-encode images as images/<staged_name>.jpg under work.

A side longer than max_dimension is shrunk to it, aspect kept.

Returns:

Type Description
list[tuple[int, int]]

Each image's stored (width, height), the size a camera solved at

list[tuple[int, int]]

the staged size is re-expressed at.

Source code in capturegraph-recipes/capturegraph_recipes/depth/inference/contract.py
def stage_images(
    images: cg.Array[cg.Image],
    work: cg.ManagedDir,
    max_dimension: int,
) -> list[tuple[int, int]]:
    """Re-encode ``images`` as ``images/<staged_name>.jpg`` under ``work``.

    A side longer than ``max_dimension`` is shrunk to it, aspect kept.

    Returns:
        Each image's stored ``(width, height)``, the size a camera solved at
        the staged size is re-expressed at.
    """
    directory = work / IMAGES
    directory.mkdir()
    sizes: list[tuple[int, int]] = []
    for index, image in enumerate(images):
        picture = image.pil().convert("RGB")
        sizes.append(picture.size)
        if max(picture.size) > max_dimension:
            picture = ImageOps.contain(picture, (max_dimension, max_dimension))
        picture.save(directory / f"{staged_name(index)}.jpg", quality=JPEG_QUALITY)
    return sizes

staged_name(index) #

The file stem of the image at index in a staged directory; sorts like the array.

Source code in capturegraph-recipes/capturegraph_recipes/depth/inference/contract.py
def staged_name(index: int) -> str:
    """The file stem of the image at ``index`` in a staged directory; sorts like the array."""
    return f"{index:05d}"