brain_deer.surface.resources

On-demand atlas / surface resource registry, downloader, and local cache.

Surface Studio needs standard neuroimaging resources (template surfaces, cortical parcellations, subcortical segmentations, tract atlases). Rather than bundling hundreds of megabytes, we describe each resource in a registry and fetch it once into a local cache on first use, verifying an optional SHA-256.

Design notes:

  • Pure stdlib (urllib) downloader; no pooch/requests dependency.

  • Cache dir: $BRAIN_DEER_SURFACE_CACHE or ~/.braindeer/surface_cache.

  • Resources with url=None are user-supplied placeholders listed in the catalogue; fetch raises until the user provides the file (honest offline catalogue without unverifiable URLs).

  • Extra resources can be registered at runtime via register_resource() or from a JSON file via load_registry_file().

Exceptions

ResourceUnavailableError

Raised when a resource cannot be fetched (no URL, offline, or download failed).

Classes

Resource

A downloadable (or user-supplied) resource entry.

Functions

cache_dir(→ str)

Return the local resource cache directory (created only when create).

register_resource(→ None)

Add or replace a resource in the in-memory registry.

load_registry_file(→ int)

Load extra resources from a JSON manifest (list of resource dicts).

get_available_resources(→ list[dict])

List catalogue entries as plain dicts (JSON-friendly for UI/AI/commands).

local_path(→ str)

Absolute path where a resource is (or would be) cached.

fetch(→ str)

Download (if needed) a resource and return its local cache path.

Module Contents

class brain_deer.surface.resources.Resource

A downloadable (or user-supplied) resource entry.

brain_deer.surface.resources.cache_dir(*, create: bool = False) → str

Return the local resource cache directory (created only when create).

Checking whether a resource is cached must not have the side effect of creating directories (and must not fail in sandboxed/read-only environments), so creation is opt-in and only used by fetch().

brain_deer.surface.resources.register_resource(resource: Resource, *, overwrite: bool = True) → None

Add or replace a resource in the in-memory registry.

brain_deer.surface.resources.load_registry_file(path: str, *, overwrite: bool = True) → int

Load extra resources from a JSON manifest (list of resource dicts).

Returns the number of resources added. Unknown keys are ignored.

brain_deer.surface.resources.get_available_resources(kind: str | None = None, category: str | None = None) → list[dict]

List catalogue entries as plain dicts (JSON-friendly for UI/AI/commands).

brain_deer.surface.resources.local_path(resource_id: str) → str

Absolute path where a resource is (or would be) cached.

brain_deer.surface.resources.fetch(resource_id: str, *, force: bool = False, progress: Callable[[int, int], None] | None = None, timeout: float = 60.0) → str

Download (if needed) a resource and return its local cache path.

  • Returns immediately if already cached and force is False.

  • Raises ResourceUnavailableError for user-supplied entries (url=None).

  • Verifies SHA-256 when the registry provides one.

exception brain_deer.surface.resources.ResourceUnavailableError

Bases: RuntimeError

Raised when a resource cannot be fetched (no URL, offline, or download failed).