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_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_path (str) – The path to 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_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.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_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, desired_axis_order='xyz')[source]#

Load a .zarr image and return the ndarray.

Parameters:

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

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

Returns:

The loaded 3D image array.

Return type:

ndarray

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)[source]#

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

Parameters:

  • img_path (str) – The path to the image 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.

  • 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, ndarray_axis_order='xyz')[source]#

Save an ndarray as a series of .tif images.

Parameters:

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

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

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

Return type:

None

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

Save an ndarray to a .zarr file.

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’.

Return type:

None

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, ndarray_axis_order='xyz', xy_res=1000, z_res=1000, data_type=<class 'numpy.float32'>, reference_img=None)[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.

  • 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.

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).

On this page
Show Source