Skip to content

Getting Started

This guide helps you set up ZarrNii and get started with its basic functionality. By the end of this guide, you'll be able to read OME-Zarr and NIfTI datasets, perform basic transformations, and save your results.

Installation

ZarrNii requires Python 3.10 or later. Install it using Poetry, a modern dependency manager for Python.

1. Clone the Repository

If you're using the source code, clone the ZarrNii repository:

git clone https://github.com/yourusername/zarrnii.git
cd zarrnii

2. Install with Poetry

Run the following command to install the library and its dependencies:

poetry install

If you don't use Poetry, install ZarrNii and its dependencies using pip:

pip install zarrnii

Prerequisites

Before using ZarrNii, ensure you have: - OME-Zarr datasets: Multidimensional images in Zarr format. - NIfTI datasets: Neuroimaging data in .nii or .nii.gz format.

Basic Usage

1. Reading Data

You can load an OME-Zarr or NIfTI dataset into a ZarrNii object.

From OME-Zarr:

from zarrnii import ZarrNii

# Load OME-Zarr
znimg = ZarrNii.from_ome_zarr("path/to/dataset.ome.zarr")

print("Data shape:", znimg.darr.shape)
print("Affine matrix:\n", znimg.affine.matrix)

From NIfTI:

# Load NIfTI
znimg = ZarrNii.from_nifti("path/to/dataset.nii")

print("Data shape:", znimg.darr.shape)
print("Affine matrix:\n", znimg.affine.matrix)

2. Performing Transformations

ZarrNii supports various transformations, such as cropping, downsampling, and upsampling.

Cropping:

Crop a region from the dataset using voxel or RAS (real-world) coordinates:

cropped = znimg.crop_with_bounding_box((10, 10, 10), (50, 50, 50))
print("Cropped shape:", cropped.darr.shape)

Downsampling:

Reduce the resolution of your dataset:

downsampled = znimg.downsample(level=2)
print("Downsampled shape:", downsampled.darr.shape)

Upsampling:

Increase the resolution of your dataset:

upsampled = znimg.upsample(along_x=2, along_y=2, along_z=2)
print("Upsampled shape:", upsampled.darr.shape)

3. Saving Data

ZarrNii makes it easy to save your datasets in both OME-Zarr and NIfTI formats.

To NIfTI:

Save the dataset as a .nii file:

znimg.to_nifti("output_dataset.nii")

To OME-Zarr:

Save the dataset back to OME-Zarr format:

znimg.to_ome_zarr("output_dataset.ome.zarr")

Example Workflow

Here’s a full workflow from loading an OME-Zarr dataset to saving a downsampled version as NIfTI:

from zarrnii import ZarrNii

# Load an OME-Zarr dataset
znimg = ZarrNii.from_ome_zarr("path/to/dataset.ome.zarr")

# Perform transformations
cropped = znimg.crop_with_bounding_box((10, 10, 10), (100, 100, 100))
downsampled = cropped.downsample(level=2)

# Save the result as a NIfTI file
downsampled.to_nifti("downsampled_output.nii")

What’s Next?