Upload data with the CLI

You need an approved contributor account, a configured API URL and a valid login. Platform-managed uploads use signed upload URLs; you do not need personal AWS credentials for them.

Choose the workflow based on what you have:

Upload raw data for worker conversion

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

The upload command inspects recognised images and asks you to confirm physical voxel sizes and orientation. Confirmation queues conversion; a worker must run before the converted volume is available.

For a TIFF with known spacing:

brainmaps upload file scan.tif \
  --species 1 --voxel-size 2,2,5 --orientation ras

Voxel sizes are X,Y,Z in micrometres, even when the stored array order is Z,Y,X. Orientation describes the anatomical direction of increasing X,Y,Z. Use the values from your acquisition, not these example values. --yes accepts inferred metadata, so review the header before using it.

Automation caveat: upload file --json returns after upload and does not perform the interactive confirmation. Finish the review on the website or call the API’s confirm-metadata action before expecting a conversion job.

Convert and upload immediately

brainmaps upload image scan.tif \
  --species 1 --voxel-size 2,2,5 --levels 5

This runs conversion locally, then uploads the precomputed dataset. It accepts NIfTI, TIFF/OME-TIFF, TIFF slice folders, Zarr/OME-Zarr and existing precomputed data. Large volumes need sufficient local memory and disk space.

Channel and intensity limitations

The current TIFF/Zarr-to-precomputed path produces a single-channel volume: it selects the first channel, time point and sample axis where present. This affects upload image and the corresponding worker conversion. It is not a way to preserve a multichannel acquisition.

The image conversion path preserves uint16 intensities; other numeric types may be rescaled to the uint16 range. Keep the original data for quantitative analysis, and check output dtype and values before treating a converted volume as raw measurements.

For existing multichannel OME-Zarr, upload the directory unchanged:

brainmaps upload folder /path/to/brain.ome.zarr --species 1

The folder path preserves the stored arrays and metadata. Accurate display still depends on valid multiscale paths, axis names, physical scales and channel metadata. Upload success alone does not establish that those metadata are correct.

Label volumes

brainmaps upload image labels.tif \
  --species 1 --voxel-size 2,2,5 \
  --segmentation --labels labels.csv

A label table can be CSV or JSON and supplies IDs, names and optional colours/acronyms. --transcriptomic implies segmentation and marks the layer as transcriptomic. It does not import a gene-expression matrix or add a gene browser.

Convert without uploading

brainmaps convert nifti scan.nii.gz --out ./precomputed --levels 5
brainmaps convert tiff-precomputed scan.tif --voxel-size 2,2,5 --out ./precomputed
brainmaps convert zarr-precomputed brain.ome.zarr --out ./precomputed
brainmaps upload folder ./precomputed --species 1

These conversion commands have the channel/value limits described above. convert tiff-to-zarr, convert tiff-to-omezarr and convert validate-omezarr are also available; use each command’s --help for its input layout. Validate the resulting axes, channel count, units and physical scales before publishing.

Bring your own storage

brainmaps s3 configure configures a separate S3-compatible destination. Use brainmaps s3 preflight to check it before a large upload. The --cloud-prefix upload option uses this configured destination and requires its credentials.

Supported overrides are BRAINMAPS_S3_BUCKET, BRAINMAPS_S3_REGION, BRAINMAPS_S3_ACCESS_KEY_ID, BRAINMAPS_S3_SECRET_ACCESS_KEY, BRAINMAPS_S3_ENDPOINT_URL and BRAINMAPS_S3_PUBLIC_BASE_URL. Do not include credentials in shared commands or documentation. Browser streaming requires readable dataset URLs and suitable CORS headers.

Finish the catalogue entry

An upload is not automatically a complete brain record. Use Uploads → Finish setup on the website or create a brain from its upload UUID. Associate the correct species and, if relevant, atlas. Association alone does not align coordinates.