cellmap_flow.models.bioimage_catalog

The BioImage Model Zoo’s models, for the dashboard’s picker.

They come from bioimage.io’s artifact server (Hypha), whose listing holds each model’s whole description: its axes (so 2D or 3D, and any declared voxel size, without a fetch per model) and weights. The legacy collection.json index, which lags it (125 models to its 157 in October 2026), is the fallback when the server cannot be reached.

list_bioimage_models answers from a cache file under ~/.cellmap_flow/bioimage once there is one, so opening the Models tab does not download the zoo’s index each time; refresh_bioimage_models fetches it again; cached_bioimage_models reads the cache alone, never fetching. They give {"fetched": <ISO time>, "models": [...]}, the index’s models in its order, each as normalise gives it. A failed fetch raises ZooIndexError, whose message says why, and leaves the cache as it was.

None of the zoo’s models declares the voxel size it was trained at, so the EM ones’ were looked up by hand, in bioimage_voxel_sizes.yaml beside this module: trained_at reads it, and each listed model carries its row as trained (None for a model not in it).

bioimage_entry is the model entry of a zoo model, and entry_voxel_size decides what voxel_size it carries, by the rule the model’s server applies (BioModelConfig._input_voxel_size): the one place the Models tab’s Submit and models.resolve decide it.

Attributes

`ZOO_INDEX_URL`
`HYPHA_ARTIFACTS`
`HYPHA_MODELS_URL`
`FETCH_TIMEOUT_S`
`BIOIMAGE_CACHE_DIR`
`BIOIMAGE_CACHE_FILE`
`CACHE_FORMAT`
`STALE_AFTER_S`
`ZOO_PAGE_URL`
`TRAINED_VOXEL_SIZES_FILE`

Exceptions

ZooIndexError

The zoo's index could not be fetched or read.

Classes

VoxelSizeChoice

What entry_voxel_size decided.

Functions

`normalise`(raw) → dict	One index entry as the picker shows it.
`normalise_artifact`(artifact) → Optional[dict]	One Hypha artifact as the picker shows it: `normalise`'s fields from
`trained_at`(model) → Optional[dict]	What `bioimage_voxel_sizes.yaml` says the model (an entry, or its
`list_bioimage_models`() → dict	The zoo's models, from the cache when there is a current one, with
`cached_bioimage_models`() → Optional[dict]	`list_bioimage_models`'s answer from the cache alone: None when
`refresh_bioimage_models`() → dict	Fetch the zoo's index again, and cache it.
`find_bioimage_model`(key) → Optional[dict]	The cached model whose id, nickname or key is `key`, or None.
`declared_voxel_size`(entry) → Optional[list]	The voxel size (nm, z y x) the model's description declares, None when it declares none.
`bioimage_entry`(model[, voxel_size, name]) → dict	The model entry of the zoo model `model` (an id or nickname
`entry_voxel_size`(model[, given, listed, online]) → VoxelSizeChoice	The `voxel_size` a zoo model's entry gets, by the rule its server

Module Contents

cellmap_flow.models.bioimage_catalog.ZOO_INDEX_URL = 'https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/collection.json'

cellmap_flow.models.bioimage_catalog.HYPHA_ARTIFACTS = 'https://hypha.aicell.io/bioimage-io/artifacts'

cellmap_flow.models.bioimage_catalog.HYPHA_MODELS_URL = ''

cellmap_flow.models.bioimage_catalog.FETCH_TIMEOUT_S = 30

cellmap_flow.models.bioimage_catalog.BIOIMAGE_CACHE_DIR

cellmap_flow.models.bioimage_catalog.BIOIMAGE_CACHE_FILE

cellmap_flow.models.bioimage_catalog.CACHE_FORMAT = 2

cellmap_flow.models.bioimage_catalog.STALE_AFTER_S = 3600

cellmap_flow.models.bioimage_catalog.ZOO_PAGE_URL = 'https://bioimage.io/#/artifacts/{}'

exception cellmap_flow.models.bioimage_catalog.ZooIndexError: The zoo’s index could not be fetched or read.

cellmap_flow.models.bioimage_catalog.normalise(raw: dict) → dict

One index entry as the picker shows it.

id is the index’s (a Zenodo DOI for older models, the nickname for newer ones), nickname the animal name (“affable-shark”) or None, and key the one to load it by, the nickname when there is one. dims is “2d”, “3d” or None; em whether its tags, name or description say electron microscopy; weight_formats short names (“pytorch”, “onnx”).

cellmap_flow.models.bioimage_catalog.normalise_artifact(artifact: dict) → dict | None: One Hypha artifact as the picker shows it: normalise’s fields from its description, with 2D/3D and the declared voxel size from its input’s axes. None for an artifact with no description.

cellmap_flow.models.bioimage_catalog.TRAINED_VOXEL_SIZES_FILE

cellmap_flow.models.bioimage_catalog.trained_at(model) → dict | None: What bioimage_voxel_sizes.yaml says the model (an entry, or its nickname) was trained at: {“voxel_size” (absent when trained across resolutions), “trained_on”, “confidence”, “source”, “note”?}, or None.

cellmap_flow.models.bioimage_catalog.list_bioimage_models() → dict

The zoo’s models, from the cache when there is a current one, with stale saying whether it is older than STALE_AFTER_S.

A cache in an older format is fetched again; when that fails it is still read, as a list that is older is better than none.

cellmap_flow.models.bioimage_catalog.cached_bioimage_models() → dict | None: list_bioimage_models’s answer from the cache alone: None when nothing is cached in this format, rather than fetching the index. The Finetune tab’s ranking lists the zoo’s models so (routes/finetune/rank_routes.py): its list must not wait on bioimage.io, and the Models tab’s BioImage Zoo list, once opened, has cached them.

cellmap_flow.models.bioimage_catalog.refresh_bioimage_models() → dict: Fetch the zoo’s index again, and cache it.

cellmap_flow.models.bioimage_catalog.find_bioimage_model(key: str) → dict | None

The cached model whose id, nickname or key is key, or None.

Only the cache is read: the Models tab’s submit must not wait on the network, and a model the tab listed is in it.

cellmap_flow.models.bioimage_catalog.declared_voxel_size(entry: dict) → list | None

The voxel size (nm, z y x) the model’s description declares, None when it declares none.

Read from its RDF (rdf_source) with a plain fetch, so the dashboard, which has no bioimageio.core, can refuse a blank voxel size at Submit: the server would otherwise refuse it after its job started, out of sight. Remembered per model. Raises ZooIndexError when the description cannot be read, which the caller treats as “don’t know”.

cellmap_flow.models.bioimage_catalog.bioimage_entry(model: str, voxel_size=None, name: str | None = None) → dict: The model entry of the zoo model model (an id or nickname bioimageio.core loads, or a description’s path or URL), at voxel_size (nm, z y x; None leaves it to the model’s server, see entry_voxel_size) and called name.

class cellmap_flow.models.bioimage_catalog.VoxelSizeChoice

What entry_voxel_size decided.

voxel_size is what the entry gets, None to leave it to the model’s server; source says why: “given”, “declared” (the description declares one, which the server reads), “trained” (cellmap-flow’s table says what it was trained at), “none” (it declares none, and the table does not know it: its server would refuse it), “unread” (listed, but its description could not be read) or “unlisted” (not in the cached listing). declared and trained are what was found.

voxel_size: list | None

source: str

declared: list | None

trained: dict | None

cellmap_flow.models.bioimage_catalog.entry_voxel_size(model: str, given=None, *, listed: dict | None = None, online: bool = True) → VoxelSizeChoice

The voxel_size a zoo model’s entry gets, by the rule its server applies (BioModelConfig._input_voxel_size: the one given, else the description’s, else the one it was trained at, else a refusal), with what the launcher can see of it.

given is what the user typed, if anything. listed is the model’s entry in the zoo’s listing (find_bioimage_model), when it is in it: its description’s declared voxel size is read from the listing, or fetched when the listing lacks it and online. A declared voxel size is left to the server to read. The one it was trained at is written into the entry, so the server need not find the table’s row by another key.