backends

navis.transforms.backends.BackendMixin

Gives a transform a .backend property.

self._backend holds only what the user explicitly asked for (None means "follow the config"). The effective backend is resolved lazily, on access.

That laziness is load-bearing: template packages such as flybrains build all their transforms at import time, i.e. long before a user gets a chance to touch navis.config. If we snapshotted the backend in __init__, setting navis.config.default_transform_backend after import flybrains would silently have no effect.

Subclasses whose fastcore implementation is not the CMTK/elastix one override _fallback_backend and _fastcore_available.

Source code in navis/transforms/backends.py

class BackendMixin:
    """Gives a transform a `.backend` property.

    `self._backend` holds only what the user explicitly asked for (`None` means
    "follow the config"). The effective backend is resolved lazily, on access.

    That laziness is load-bearing: template packages such as `flybrains` build
    all their transforms at import time, i.e. long before a user gets a chance
    to touch `navis.config`. If we snapshotted the backend in `__init__`,
    setting `navis.config.default_transform_backend` after `import flybrains`
    would silently have no effect.

    Subclasses whose fastcore implementation is not the CMTK/elastix one
    override `_fallback_backend` and `_fastcore_available`.

    """

    _backend = None

    #: What this transform calls its non-fastcore implementation.
    _fallback_backend = "binary"

    #: Predicate deciding whether fastcore can serve this transform.
    _fastcore_available = staticmethod(fastcore_transforms_available)

    @property
    def backend(self) -> str:
        """The backend this transform will actually use."""
        return resolve_backend(
            self._backend,
            available=self._fastcore_available,
            fallback=self._fallback_backend,
        )

backend: str property

The backend this transform will actually use.

navis.transforms.backends.elastix_is_invertible cached

Whether this elastix transform can be inverted.

Uses fastcore's header-only probe, which is ~10x cheaper than parsing the file - it does not read the B-spline coefficients. That matters because this is asked of every registered transform whenever the bridging graph is built.

Source code in navis/transforms/backends.py

@functools.lru_cache(maxsize=256)
def elastix_is_invertible(path: str) -> bool:
    """Whether this elastix transform can be inverted.

    Uses fastcore's header-only probe, which is ~10x cheaper than parsing the
    file - it does not read the B-spline coefficients. That matters because this
    is asked of every registered transform whenever the bridging graph is built.

    """
    from .. import utils

    return bool(utils.fastcore.probe_elastix_invertible(path))

navis.transforms.backends.fastcore_landmarks_available

Whether the installed navis-fastcore can do the landmark transforms.

Probed separately from fastcore_transforms_available - and for the same reason it probes classes rather than a version - because the two arrived in different fastcore releases. An install can have one and not the other.

Source code in navis/transforms/backends.py

def fastcore_landmarks_available() -> bool:
    """Whether the installed navis-fastcore can do the landmark transforms.

    Probed separately from `fastcore_transforms_available` - and for the same
    reason it probes classes rather than a version - because the two arrived in
    different fastcore releases. An install can have one and not the other.

    """
    from .. import utils

    fc = utils.fastcore
    return fc is not None and hasattr(fc, "TpsTransform") and hasattr(fc, "MlsTransform")

navis.transforms.backends.fastcore_transforms_available

Whether the installed navis-fastcore can do CMTK/elastix transforms.

We probe for the classes rather than comparing fastcore.__version__: the latter is derived from the install metadata and is unreliable (notably in editable installs, where it can lag the actual build by several versions).

Source code in navis/transforms/backends.py

def fastcore_transforms_available() -> bool:
    """Whether the installed navis-fastcore can do CMTK/elastix transforms.

    We probe for the classes rather than comparing `fastcore.__version__`: the
    latter is derived from the install metadata and is unreliable (notably in
    editable installs, where it can lag the actual build by several versions).

    """
    # NB: must go through the module (rather than `from ..utils import fastcore`)
    # so tests can monkeypatch `navis.utils.fastcore = None`.
    from .. import utils

    fc = utils.fastcore
    return (
        fc is not None
        and hasattr(fc, "ElastixTransform")
        and hasattr(fc, "CmtkRegistration")
    )

navis.transforms.backends.get_cmtk_reg cached

Get a (cached) fastcore CmtkRegistration for these files.

Source code in navis/transforms/backends.py

@functools.lru_cache(maxsize=64)
def get_cmtk_reg(paths: tuple):
    """Get a (cached) fastcore CmtkRegistration for these files."""
    from .. import utils

    return utils.fastcore.CmtkRegistration(list(paths))

navis.transforms.backends.get_elastix_transform cached

Get a (cached) fastcore ElastixTransform for this file.

Source code in navis/transforms/backends.py

@functools.lru_cache(maxsize=64)
def get_elastix_transform(path: str):
    """Get a (cached) fastcore ElastixTransform for this file."""
    from .. import utils

    return utils.fastcore.ElastixTransform(path)

navis.transforms.backends.resolve_backend

Resolve a backend request to either "fastcore" or fallback.

PARAMETER	DESCRIPTION
requested	`None` defers to `navis.config.default_transform_backend`. "binary" and "python" both mean "do not use fastcore"; which of the two comes back is decided by `fallback`, not by the request. TYPE: auto | fastcore | binary | python | None DEFAULT: None
available	Predicate deciding whether fastcore can serve this transform. Defaults to the CMTK/elastix probe. TYPE: callable DEFAULT: None
fallback	What to return when fastcore is not used. TYPE: str DEFAULT: 'binary'

Source code in navis/transforms/backends.py

def resolve_backend(requested=None, available=None, fallback="binary") -> str:
    """Resolve a backend request to either "fastcore" or `fallback`.

    Parameters
    ----------
    requested : "auto" | "fastcore" | "binary" | "python" | None
                `None` defers to `navis.config.default_transform_backend`.
                "binary" and "python" both mean "do not use fastcore"; which of
                the two comes back is decided by `fallback`, not by the request.
    available : callable, optional
                Predicate deciding whether fastcore can serve this transform.
                Defaults to the CMTK/elastix probe.
    fallback :  str
                What to return when fastcore is not used.

    """
    if requested is None:
        requested = getattr(config, "default_transform_backend", "auto")

    if requested not in BACKENDS:
        raise ValueError(
            f'Unknown transform backend "{requested}". Must be one of {BACKENDS}.'
        )

    if available is None:
        available = fastcore_transforms_available

    if requested in FALLBACK_BACKENDS:
        return fallback

    if requested == "fastcore":
        if not available():
            raise ValueError(
                'Transform backend "fastcore" was requested but navis-fastcore is '
                "either not installed or too old to provide this transform. "
                "Try `pip install -U navis-fastcore`."
            )
        return "fastcore"

    # "auto": use fastcore if we can, else fall back
    return "fastcore" if available() else fallback