unravel.core.img_io module#

This module contains functions for loading and saving 3D images.

Main Functions:#

  • load_3D_img: Load a 3D image from a .czi, .nii.gz, or .tif series and return the ndarray.

  • save_3D_img: Save a 3D image as a .nii.gz, .tif series, .h5, or .zarr file.

Helper Functions:#

  • extract_resolution

  • load_image_metadata_from_txt

  • save_metadata_to_file

  • metadata

  • return_3D_img

unravel.core.img_io.return_3D_img(ndarray, return_metadata=False, return_res=False, xy_res=None, z_res=None, x_dim=None, y_dim=None, z_dim=None)[source]#

Return the 3D image ndarray and optionally resolutions (xy_res, z_res) or metadata (xy_res, z_res, x_dim, y_dim, z_dim).

Parameters:

  • ndarray (ndarray) – The 3D image array.

  • return_metadata (bool, optional) – Whether to return metadata. Default is False.

  • return_res (bool, optional) – Whether to return resolutions. Default is False.

  • xy_res (float, optional) – The resolution in the xy-plane.

  • z_res (float, optional) – The resolution in the z-plane.

  • x_dim (int, optional) – The size of the image in the x-dimension.

  • y_dim (int, optional) – The size of the image in the y-dimension.

  • z_dim (int, optional) – The size of the image in the z-dimension.

Returns:

  • ndarray – The 3D image array.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

  • tuple, optional – If return_metadata is True, returns (ndarray, xy_res, z_res, x_dim, y_dim, z_dim).

unravel.core.img_io.metadata(file_path, ndarray, return_res=False, return_metadata=False, xy_res=None, z_res=None, save_metadata=None)[source]#

Extract and handle metadata, including saving to a file if requested.

Parameters:

  • file_path (str) – The path to the image file.

  • ndarray (ndarray) – The 3D image array.

  • return_res (bool, optional) – Whether to return resolutions. Default is False.

  • return_metadata (bool, optional) – Whether to return metadata. Default is False.

  • xy_res (float, optional) – The resolution in the xy-plane.

  • z_res (float, optional) – The resolution in the z-plane.

  • save_metadata (str, optional) – Path to save metadata file. Default is None.

Returns:

Returns (xy_res, z_res, x_dim, y_dim, z_dim).

Return type:

tuple

unravel.core.img_io.extract_resolution(img_path)[source]#

Extract resolution from image metadata.

Parameters:

img_path (str) – The path to the image file.

Returns:

Returns (xy_res, z_res) in microns.

Return type:

tuple

unravel.core.img_io.load_czi(czi_path, channel=0, desired_axis_order='xyz', return_res=False, return_metadata=False, save_metadata=None, xy_res=None, z_res=None)[source]#

Load a .czi image and return the ndarray.

Parameters:

  • czi_path (str) – The path to the .czi file.

  • channel (int, optional) – The channel to load. Default is 0.

  • desired_axis_order (str, optional) – The desired order of the image axes. Default is ‘xyz’.

  • return_res (bool, optional) – Whether to return resolutions. Default is False.

  • return_metadata (bool, optional) – Whether to return metadata. Default is False.

  • save_metadata (str, optional) – Path to save metadata file. Default is None.

  • xy_res (float, optional) – The resolution in the xy-plane.

  • z_res (float, optional) – The resolution in the z-plane.

Returns:

  • ndarray – The loaded 3D image array.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

  • tuple, optional – If return_metadata is True, returns (ndarray, xy_res, z_res, x_dim, y_dim, z_dim).

unravel.core.img_io.load_tifs(tif_dir_path, desired_axis_order='xyz', return_res=False, return_metadata=False, save_metadata=None, xy_res=None, z_res=None, parallel_loading=True)[source]#

Load a series of .tif images and return the ndarray.

Parameters:

  • tif_dir_path (str) – The path to the directory containing the .tif files.

  • desired_axis_order (str, optional) – The desired order of the image axes. Default is ‘xyz’.

  • return_res (bool, optional) – Whether to return resolutions. Default is False.

  • return_metadata (bool, optional) – Whether to return metadata. Default is False.

  • save_metadata (str, optional) – Path to save metadata file. Default is None.

  • xy_res (float, optional) – The resolution in the xy-plane.

  • z_res (float, optional) – The resolution in the z-plane.

  • parallel_loading (bool, optional) – Whether to load images in parallel. Default is True.

Returns:

  • ndarray – The loaded 3D image array.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

  • tuple, optional – If return_metadata is True, returns (ndarray, xy_res, z_res, x_dim, y_dim, z_dim).

unravel.core.img_io.load_3D_tif(tif_path, desired_axis_order='xyz', return_res=False, return_metadata=False, save_metadata=None, xy_res=None, z_res=None)[source]#

Load a 3D .ome.tif or .tif image and return the ndarray.

Parameters:

  • tif_path (str) – The path to the .ome.tif file.

  • desired_axis_order (str, optional) – The desired order of the image axes. Default is ‘xyz’.

  • return_res (bool, optional) – Whether to return resolutions (works for .ome.tif). Default is False.

Returns:

  • ndarray – The loaded 3D image array.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

unravel.core.img_io.nii_path_or_nii(nii)[source]#

Helper function to load a NIfTI image if it’s a path. Returns the NIfTI image object.

Parameters:#

niistr, Path, or nib.Nifti1Image

Path to the NIfTI image file or a Nifti1Image object.

Returns:#

nib.Nifti1Image

The NIfTI image object.

unravel.core.img_io.nii_to_ndarray(nii)[source]#

Load a NIfTI image and return as a 3D ndarray.

Parameters:#

niistr, Path, or nib.Nifti1Image

Path to the NIfTI image file or a Nifti1Image object.

Returns:#

ndarrayndarray

The 3D image array.

unravel.core.img_io.load_nii(nii_path, desired_axis_order='xyz', return_res=False, return_metadata=False, save_metadata=None, xy_res=None, z_res=None)[source]#

Load a .nii.gz image and return the ndarray.

Parameters:

  • nii_path (str) – The path to the .nii.gz file.

  • desired_axis_order (str, optional) – The desired order of the image axes. Default is ‘xyz’.

  • return_res (bool, optional) – Whether to return resolutions. Default is False.

  • return_metadata (bool, optional) – Whether to return metadata. Default is False.

  • save_metadata (str, optional) – Path to save metadata file. Default is None.

  • xy_res (float, optional) – The resolution in the xy-plane (use if res is not specified in the metadata).

  • z_res (float, optional) – The resolution in the z-plane.

Returns:

  • ndarray – The loaded 3D image array.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

  • tuple, optional – If return_metadata is True, returns (ndarray, xy_res, z_res, x_dim, y_dim, z_dim).

Notes

  • If xy_res and z_res are provided, they will be used instead of the values from the metadata.

unravel.core.img_io.load_nii_subset(nii_path, xmin, xmax, ymin, ymax, zmin, zmax)[source]#

Load a spatial subset of a .nii.gz file and return an ndarray.

Parameters:

  • nii_path (str) – The path to the .nii.gz file.

  • xmin (int) – The spatial coordinates defining the subset.

  • xmax (int) – The spatial coordinates defining the subset.

  • ymin (int) – The spatial coordinates defining the subset.

  • ymax (int) – The spatial coordinates defining the subset.

  • zmin (int) – The spatial coordinates defining the subset.

  • zmax (int) – The spatial coordinates defining the subset.

Returns:

The loaded subset of the 3D image.

Return type:

ndarray

unravel.core.img_io.load_h5(hdf5_path, desired_axis_order='xyz', return_res=False, return_metadata=False, save_metadata=None, xy_res=None, z_res=None)[source]#

Load full resolution image from an HDF5 file (.h5) and return the ndarray.

Parameters:

  • hdf5_path (str) – The path to the .h5 file.

  • desired_axis_order (str, optional) – The desired order of the image axes. Default is ‘xyz’.

  • return_res (bool, optional) – Whether to return resolutions. Default is False.

  • return_metadata (bool, optional) – Whether to return metadata. Default is False.

  • save_metadata (str, optional) – Path to save metadata file. Default is None.

  • xy_res (float, optional) – The resolution in the xy-plane.

  • z_res (float, optional) – The resolution in the z-plane.

Returns:

  • ndarray – The loaded 3D image array.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

  • tuple, optional – If return_metadata is True, returns (ndarray, xy_res, z_res, x_dim, y_dim, z_dim).

unravel.core.img_io.load_zarr(zarr_path, channel=0, desired_axis_order='xyz', return_res=False, return_metadata=False, save_metadata=None, xy_res=None, z_res=None, level=None, verbose=False)[source]#

Load a channel and level of a Zarr image, optionally returning voxel resolution.

Parameters:

  • zarr_path (str or Path) – Path to .zarr directory.

  • channel (int, optional) – Channel index to load (for 4D data). If None, loads all channels.

  • desired_axis_order (str, optional) – Desired output axis order (default: “xyz”).

  • return_res (bool, optional) – If True, returns voxel resolution in mm (xy_res, z_res) along with the image.

  • save_metadata (str, optional) – Path to save metadata file. Default is None.

  • xy_res (float, optional) – Resolution in the xy-plane (in microns). If None, will be extracted from metadata.

  • z_res (float, optional) – Resolution in the z-plane (in microns). If None, will be extracted from metadata.

  • level (str or int, optional) – Resolution level to load (default: highest).

  • verbose (bool) – Print debug output.

Returns:

  • ndarray – 3D numpy array from the zarr store, with shape (z, y, x) or (z, x, y) depending on desired_axis_order.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

  • tuple, optional – If return_metadata is True, returns (ndarray, xy_res, z_res, x_dim, y_dim, z_dim).

unravel.core.img_io.resolve_path(upstream_path, path_or_pattern, make_parents=True, is_file=True)[source]#

Returns full path or Path(upstream_path, path_or_pattern) and optionally creates parent directories.

Parameters:

  • upstream_path (str) – The base path.

  • path_or_pattern (str) – The relative path or glob pattern.

  • make_parents (bool, optional) – Whether to create parent directories if they don’t exist. Default is True.

  • is_file (bool, optional) – Whether the path is a file. Default is True.

Returns:

The resolved path or None if not found.

Return type:

Path or None

unravel.core.img_io.save_metadata_to_file(xy_res, z_res, x_dim, y_dim, z_dim, save_metadata='parameters/metadata.txt')[source]#

Save metadata to a text file.

Parameters:

  • xy_res (float) – The resolution in the xy-plane.

  • z_res (float) – The resolution in the z-plane.

  • x_dim (int) – The size of the image in the x-dimension.

  • y_dim (int) – The size of the image in the y-dimension.

  • z_dim (int) – The size of the image in the z-dimension.

  • save_metadata (str, optional) – Path to save metadata file. Default is ‘parameters/metadata.txt’.

unravel.core.img_io.load_image_metadata_from_txt(metadata='./parameters/metadata*')[source]#

Load metadata from a text file.

Parameters:

metadata (str, optional) – The path or pattern to the metadata file. Default is ‘./parameters/metadata*’.

Returns:

Returns (xy_res, z_res, x_dim, y_dim, z_dim) or (None, None, None, None, None) if file not found.

Return type:

tuple

unravel.core.img_io.load_3D_img(img_path, channel=0, desired_axis_order='xyz', return_res=False, return_metadata=False, xy_res=None, z_res=None, save_metadata=None, verbose=False)[source]#

Load a 3D image from various file formats and return the ndarray.

Parameters:

  • img_path (str) – The path to the image file (.czi, .ome.tif, .tif, .nii.gz, .h5, .zarr) or directory w/ 2D .ome.tif or .tif files.

  • channel (int, optional) – The channel to load. Default is 0.

  • desired_axis_order (str, optional) – The desired order of the image axes. Default is ‘xyz’.

  • return_res (bool, optional) – Whether to return resolutions. Default is False.

  • return_metadata (bool, optional) – Whether to return metadata. Default is False.

  • xy_res (float, optional) – The resolution in the xy-plane.

  • z_res (float, optional) – The resolution in the z-plane.

  • save_metadata (str, optional) – Path to save metadata file. Default is None.

Returns:

  • ndarray – The loaded 3D image array.

  • tuple, optional – If return_res is True, returns (ndarray, xy_res, z_res).

  • tuple, optional – If return_metadata is True, returns (ndarray, xy_res, z_res, x_dim, y_dim, z_dim).

unravel.core.img_io.save_as_nii(ndarray, output, xy_res=1000, z_res=1000, data_type=None, reference=None)[source]#

Save a numpy array as a .nii.gz image with the specified resolution and orientation, using a reference image if provided.

Parameters:

  • ndarray (ndarray) – The numpy array to save as a NIFTI image.

  • output (str or Path) – The file path to save the output image. ‘.nii.gz’ is appended if not present.

  • xy_res (float, optional) – XY-plane resolution in microns. Default is 1000.

  • z_res (float, optional) – Z-axis resolution in microns. Default is 1000.

  • data_type (data-type, optional) – Data type for the NIFTI image. Default is np.float32.

  • reference (str, Path, or nib.Nifti1Image, optional) – Either a path to a reference .nii.gz file or a Nifti1Image object to set orientation and resolution. If provided, xy_res and z_res are ignored. Default is None.

Notes

  • The function will automatically create parent directories if they do not exist.

  • The affine transformation is constructed assuming RAS orientation if no reference is provided.

unravel.core.img_io.save_as_tifs(ndarray, tif_dir_out=None, ndarray_axis_order='xyz', parallel=True, max_workers=None, verbose=False)[source]#

Save an ndarray as a series of .tif images.

Parameters:

  • ndarray (ndarray) – The 3D image array to save.

  • tif_dir_out (str or Path) – The directory to save the .tif files.

  • ndarray_axis_order (str, optional) – The order of the ndarray axes. Default is ‘xyz’.

  • parallel (bool, optional) – Whether to save slices in parallel. Default is False.

  • max_workers (int or None, optional) – Number of threads to use for parallel saving. Defaults to os.cpu_count().

  • verbose (bool, optional) – How to print the output directory. Default is False.

Return type:

None

unravel.core.img_io.save_as_zarr(ndarray, output_path=None, ndarray_axis_order='xyz', xy_res=None, z_res=None, verbose=False)[source]#

Save a 3D ndarray to a .zarr file as well as OME-NGFF-compatible metadata.

Parameters:

  • ndarray (ndarray) – The 3D image array to save.

  • output_path (str) – The path to save the .zarr file.

  • ndarray_axis_order (str, optional) – The order of the ndarray axes. Default is ‘xyz’.

  • xy_res (float, optional) – The voxel size in the XY plane (in mm).

  • z_res (float, optional) – The voxel size in the Z direction (in mm).

unravel.core.img_io.save_as_h5(ndarray, output_path, ndarray_axis_order='xyz')[source]#

Save an ndarray to an HDF5 file (.h5).

Parameters:

  • ndarray (ndarray) – The 3D image array to save.

  • output_path (str) – The path to save the .h5 file.

  • ndarray_axis_order (str, optional) – The order of the ndarray axes. Default is ‘xyz’.

Return type:

None

unravel.core.img_io.save_3D_img(img, output_path=None, ndarray_axis_order='xyz', xy_res=1000, z_res=1000, data_type=<class 'numpy.float32'>, reference_img=None, verbose=False)[source]#

Save a 3D image in various formats.

Parameters:

  • img (ndarray) – The 3D image array to save.

  • output_path (str) – The path to save the image. The file extension determines the format: .nii.gz, .zarr, .h5, .tif, or a directory path for a TIFF series.

  • ndarray_axis_order (str, optional) – The order of the ndarray axes. Default is ‘xyz’.

  • xy_res (float, optional) – The x/y resolution in microns for a NIFTI image output. Default is 1000.

  • z_res (float, optional) – The z resolution in microns for a NIFTI image output. Default is 1000.

  • data_type (data-type, optional) – Data type for a NIFTI image output. Default is np.float32.

  • reference_img (str, Path, or a nib.Nifti1Image object, optional) – Either path to a .nii.gz file or a Nifti1Image object to set orientation and resolution. Default is None. If provided, xy_res and z_res are ignored.

  • verbose (bool, optional) – Print addtional infomation. Default is False.

unravel.core.img_io.zarr_level_to_tifs(zarr_path, output_dir, channel_map, resolution_level=None, xy_res=None, z_res=None)[source]#

Extracts a specified resolution level from a Zarr file and saves the specified channels as TIFF files.

Parameters:#

zarr_pathstr or Path

Path to the Zarr file.

output_dirstr or Path

Directory to save the output TIFF files. If None, defaults to “TIFFs/<sample_name>”.

resolution_levelstr

Resolution level to extract (e.g., “0”, “1”, …, “9”).

channel_mapdict

Mapping of output directory names to Zarr channel indices (e.g., {‘red’: 0, ‘green’: 1}).

xy_resfloat, optional

X/Y resolution in microns.

z_resfloat, optional

Z resolution in microns. Default is 100 µm for Genetic Tools Atlas data.

unravel.core.img_io.nii_voxel_size(nii, use_um=True)[source]#

Get the resolution (voxel size) of a NIfTI image.

Parameters:#

niistr, Path, or nib.Nifti1Image

Path to the NIfTI image file or a Nifti1Image object.

use_umbool, optional. Default is True.

If True, return the resolution in micrometers (um). If False, return the resolution in millimeters (mm).

Returns:#

restuple of float or float

If anisotropic, returns (x_res, y_res, z_res) in micrometers (um) or millimeters (mm). If isotropic, returns a single float value for the resolution in micrometers (um) or millimeters (mm).