Exporting to the BioImage Model Zoo

The BioImage Model Zoo (BMZ) is a community-driven repository of pretrained models for bioimage analysis. Exporting a CAREamics model to the BMZ format produces a self-contained .zip archive that can be shared, uploaded to the Zoo, and consumed by other tools such as Fiji, Ilastik and deepImageJ.

This tutorial assumes you already have a trained CAREamist. See Saving and exporting models for a shorter overview.

A minimal export

The export_to_bmz method requires, at a minimum, a destination archive, a model name, an example input array and some metadata describing the model and the data it was trained on.

careamist.export_to_bmz(
    path_to_archive="my_model.zip",
    friendly_model_name="my_n2v_model",
    input_array=input_array,  # (1)!
    authors=[{"name": "Jane Doe"}],
    general_description="A Noise2Void model trained with CAREamics.",
    data_description="Fluorescence microscopy images of cells.",
)

1. The input array must have the same axes as recorded in the CAREamist configuration (for example YX for a 2D model). CAREamics runs it through the model to generate the example output stored in the archive.

path_to_archive must end with .zip. The friendly_model_name is the name used in the BMZ specification and on the website, and may only contain letters, numbers, dashes, underscores and parentheses.

Describing the authors

Authors are provided as a list of dictionaries. Only name is required; affiliation, email, github_user and orcid are all optional, but are recommended when publishing to the Zoo.

authors = [
    {
        "name": "Harry Potter",
        "affiliation": "Hogwarts",
        "github_user": "theboywholived",
        "orcid": "0000-0002-1825-0097",  # (1)!
    },
    {"name": "Albus Dumbledore", "affiliation": "Hogwarts"},
]

1. The ORCID must be a valid ORCID identifier, it is validated on export.

A complete export

Two further optional arguments let you control how the model is presented:

• covers: paths to cover images shown on the model's Zoo page. If omitted, CAREamics generates a cover from the example input and output.
• channel_names: names for the model's channels.

careamist.export_to_bmz(
    path_to_archive=path_to_archive,
    friendly_model_name="my_n2v_model",
    input_array=input_array,
    authors=authors,
    general_description="A Noise2Void model trained with CAREamics.",
    data_description="Fluorescence microscopy images of cells.",
    covers=[root / "cover.png"],  # (1)!
    channel_names=["nucleus"],  # (2)!
)

1. Cover images displayed on the BioImage Model Zoo website.
2. One name per channel.

What is in the archive?

The generated .zip bundles everything needed to reproduce and run the model:

• the model weights (as a PyTorch state dict),
• the CAREamics configuration (careamics.yaml),
• example input and output arrays,
• an environment file, a README and cover image(s),
• the BMZ model description (rdf.yaml).

Model validation

Before writing the archive, CAREamics validates the model description by running test_model from bioimageio.core, which runs the example input through the exported weights and checks the output against the stored example. If this test fails, export_to_bmz raises a ValueError and no archive is written. A passing export prints Model description test passed.

Loading a model back

A model exported to BMZ can be loaded back into CAREamics with load_from_bmz, which returns the configuration and the Lightning module. The path may also be an HTTP URL pointing to a downloadable archive.

config, model = load_from_bmz(path_to_archive)