viewer._bundle_io — binary bundle helpers

tempura/viewer/_bundle_io.py holds the small shared helpers for writing the binary viewer bundles. It has no physics — just the array-serialization conventions that the device and potential exporters agree on.

Conventions

Arrays are written row-major and little-endian: float32 for height fields and potentials, uint16 for masks and footprints. array_ref(...) builds the JSON descriptor (relative path, dtype, shape, row-major flag) that the metadata files reference, and safe_file_stem(...) turns a gate or layer name into a filesystem-safe stem. Keeping these in one place ensures the on-disk layout stays consistent across both exporters.

API

_bundle_io

Shared helpers for writing binary viewer bundles.

array_ref(path, shape, *, dtype)

Build a JSON reference for a binary array file.

Source code in tempura/viewer/_bundle_io.py

def array_ref(path: Path, shape: tuple[int, ...], *, dtype: str) -> dict[str, object]:
    """Build a JSON reference for a binary array file."""
    return {
        "path": str(Path("arrays") / path.name),
        "dtype": dtype,
        "shape": list(shape),
        "row_major": True,
    }

safe_file_stem(name)

Return a filesystem-safe file stem.

Source code in tempura/viewer/_bundle_io.py

def safe_file_stem(name: str) -> str:
    """Return a filesystem-safe file stem."""
    stem = re.sub(r"[^0-9A-Za-z._-]+", "_", name.strip())
    return stem or "layer"

write_float32_array(path, arr)

Write an array as row-major little-endian float32.

Source code in tempura/viewer/_bundle_io.py

def write_float32_array(path: Path, arr: np.ndarray) -> None:
    """Write an array as row-major little-endian float32."""
    np.ascontiguousarray(arr, dtype="<f4").tofile(path)

write_uint16_array(path, arr)

Write an array as row-major little-endian uint16.

Source code in tempura/viewer/_bundle_io.py

def write_uint16_array(path: Path, arr: np.ndarray) -> None:
    """Write an array as row-major little-endian uint16."""
    np.ascontiguousarray(arr, dtype="<u2").tofile(path)