Compute jobs and workers

The API coordinates jobs and records progress. A machine running the CLI performs the work. This can be a workstation, server or scheduled compute node; the platform queue does not by itself provide a running worker.

Upload, confirm, convert

brainmaps upload file scan.nii.gz --species 1
brainmaps worker run

The browser’s single-file upload follows the same sequence: upload bytes, inspect and confirm voxel metadata, then queue conversion. upload image is a separate path that converts immediately on the invoking machine.

The current TIFF/Zarr conversion selects the first channel/time/sample where present. Preserve multichannel OME-Zarr with upload folder when all channels are needed; see conversion limits.

Run and monitor

brainmaps worker run
brainmaps jobs list
brainmaps jobs get JOB_UUID
brainmaps jobs retry JOB_UUID
brainmaps jobs cancel JOB_UUID

worker run --once processes at most one available job and exits. Without it, the worker polls for more work. Keep the process running or supervise it through your compute environment if you need continuous processing.

Generic job claiming is scoped to the authenticated user’s own jobs. Staff can inspect other users’ jobs, but that does not make a worker claim all users’ work. Atlas build jobs use their own organiser permissions and queue.

The website’s Jobs page shows status and recorded progress/errors. A failed worker can lose its lease and allow retry; inspect the error and input metadata before manually retrying a failing conversion.

Supported jobs

worker run also handles atlas build jobs. Local registration is available through register run and related commands; it is not a generic queued job kind.

BrainGlobe export

As the atlas creator or one of its delegated administrators:

brainmaps atlas export-brainglobe RELEASE_UUID

The release must meet the export checks: built template/segmentation volumes and the structure hierarchy in segmentation metadata. Mesh-only catalogue entries are insufficient.

On the worker, install the BrainGlobe extra with Python 3.11 or later:

uv sync --python 3.11 --extra brainglobe
uv run brainmaps worker run

A successful export stores its link at exports.brainglobe.url in release metadata; the website exposes it as a BrainGlobe package download.

Jobs, ingest records, atlas builds and registration runs are separate API resources. ingest commands record and hand off an ingestion workflow; creating an ingest record does not automatically execute every processing step.