Skip to content

loader

lacuna.assets.masks.loader

Brain mask loading.

Downloads (with SHA-256 verification) and caches a binary brain mask for a given coordinate space and resolution via pooch, then validates that the file is a binary mask on Lacuna's canonical grid for that space/resolution before use.

load_brain_mask(space, resolution, *, validate=True)

Load a binary brain mask for space/resolution, caching on first use.

Anatomically identical spaces (e.g. MNI152NLin2009[abc]Asym) are normalized to their canonical form before lookup.

Parameters:

Name Type Description Default
space str

Coordinate space identifier (e.g. "MNI152NLin6Asym").

 required
resolution float

Voxel resolution in mm (1.0 or 2.0).

 required
validate bool

Verify the downloaded file is a binary 3D mask on the canonical grid.

 True

Returns:

Type Description
Path

Path to the locally cached brain mask (.nii.gz).

Raises:

Type Description
KeyError

If no mask is registered for the space/resolution.
FileNotFoundError

If the mask has no URL or the download fails.
ValueError

If validation fails.
Source code in src/lacuna/assets/masks/loader.py 
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def load_brain_mask(space: str, resolution: float, *, validate: bool = True) -> Path:
    """Load a binary brain mask for ``space``/``resolution``, caching on first use.

    Anatomically identical spaces (e.g. MNI152NLin2009[abc]Asym) are normalized to
    their canonical form before lookup.

    Parameters
    ----------
    space : str
        Coordinate space identifier (e.g. "MNI152NLin6Asym").
    resolution : float
        Voxel resolution in mm (1.0 or 2.0).
    validate : bool, default True
        Verify the downloaded file is a binary 3D mask on the canonical grid.

    Returns
    -------
    Path
        Path to the locally cached brain mask (.nii.gz).

    Raises
    ------
    KeyError
        If no mask is registered for the space/resolution.
    FileNotFoundError
        If the mask has no URL or the download fails.
    ValueError
        If validation fails.
    """
    canonical_space = _canonicalize_space_variant(space)
    name = mask_name(canonical_space, float(resolution))
    metadata = BRAIN_MASK_REGISTRY.get(name)  # KeyError if unknown

    if not metadata.url:
        raise FileNotFoundError(f"Brain mask '{name}' has no download URL registered.")

    try:
        import pooch
    except ImportError as e:  # pragma: no cover - pooch is a hard dependency
        raise ImportError(
            "pooch is required to download brain masks. Install with: pip install pooch"
        ) from e

    from lacuna.utils.cache import get_cache_dir

    cache_dir = Path(get_cache_dir()) / "masks"
    logger.debug(f"Loading brain mask {name} from {metadata.url}")
    try:
        path = pooch.retrieve(
            url=metadata.url,
            known_hash=f"sha256:{metadata.sha256}" if metadata.sha256 else None,
            fname=f"{name}_desc-brain_mask.nii.gz",
            path=cache_dir,
            progressbar=True,
        )
    except Exception as e:
        raise FileNotFoundError(
            f"Failed to download brain mask '{name}' from {metadata.url}: {e}"
        ) from e

    path = Path(path)
    if validate:
        _validate_mask(path, canonical_space, float(resolution))
    return path