Input and output

qim3d.io

qim3d.io.Downloader

Class for downloading large data files available on the QIM data repository.

Attributes:

Name	Type	Description
folder_name	str or PathLike	Folder class with the name of the folder in https://data.qim.dk/

Methods:

Name	Description
list_files	Prints the downloadable files from the QIM data repository.

Syntax for downloading and loading a file is qim3d.io.Downloader().{folder_name}.{file_name}(load_file=True)

Overview of available data

Below is a table of the available folders and files on the QIM data repository.

Folder name	File name	File size
Coal	CoalBrikett CoalBrikett_Zoom CoalBrikettZoom_DOWNSAMPLED	2.23 GB 3.72 GB 238 MB
Corals	Coral_1 Coral_2 Coral2_DOWNSAMPLED MexCoral	2.26 GB 2.38 GB 162 MB 2.23 GB
Cowry_Shell	Cowry_Shell Cowry_DOWNSAMPLED	1.82 GB 116 MB
Crab	HerrmitCrab OkinawaCrab	2.38 GB 1.86 GB
Deer_Mandible	Animal_Mandible DeerMandible_DOWNSAMPLED	2.79 GB 638 MB
Foam	Foam Foam_DOWNSAMPLED Foam_2 Foam_2_zoom	3.72 GB 238 MB 3.72 GB 3.72 GB
Hourglass	Hourglass Hourglass_4X_80kV_Air_9s_1_97um Hourglass_longexp_rerun	3.72 GB 1.83 GB 3.72 GB
Kiwi	Kiwi	2.86 GB
Loofah	Loofah Loofah_DOWNSAMPLED	2.23 GB 143 MB
Marine_Gastropods	MarineGatropod_1 MarineGastropod1_DOWNSAMPLED MarineGatropod_2 MarineGastropod2_DOWNSAMPLED	2.23 GB 143 MB 2.60 GB 166 MB
Mussel	ClosedMussel1 ClosedMussel1_DOWNSAMPLED	2.23 GB 143 MB
Oak_Branch	Oak_branch OakBranch_DOWNSAMPLED	2.38 GB 152 MB
Okinawa_Forams	Okinawa_Foram_1 Okinawa_Foram_2	1.84 GB 1.84 GB
Physalis	Physalis Physalis_DOWNSAMPLED	3.72 GB 238 MB
Raspberry	Raspberry2 Raspberry2_DOWNSAMPLED	2.97 GB 190 MB
Rope	FibreRope1 FibreRope1_DOWNSAMPLED	1.82 GB 686 MB
Sea_Urchin	SeaUrchin Cordatum_Shell Cordatum_Spine	2.60 GB 1.85 GB 183 MB
Snail	Escargot	2.60 GB
Sponge	Sponge	1.11 GB

Example

import qim3d

downloader = qim3d.io.Downloader()
downloader.list_files()
data = downloader.Cowry_Shell.Cowry_DOWNSAMPLED(load_file=True)

qim3d.viz.slicer_orthogonal(data, color_map="magma")

Source code in qim3d/io/_downloader.py

class Downloader:

    """
    Class for downloading large data files available on the [QIM data repository](https://data.qim.dk/).

    Attributes:
        folder_name (str or os.PathLike): Folder class with the name of the folder in <https://data.qim.dk/>

    Methods:
        list_files(): Prints the downloadable files from the QIM data repository.

    Syntax for downloading and loading a file is `qim3d.io.Downloader().{folder_name}.{file_name}(load_file=True)`

    ??? info "Overview of available data"
        Below is a table of the available folders and files on the [QIM data repository](https://data.qim.dk/).

        Folder name         | File name                                                                                                          | File size
        ------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------
        `Coal`              | `CoalBrikett` <br> `CoalBrikett_Zoom` <br> `CoalBrikettZoom_DOWNSAMPLED`                                           | 2.23 GB <br> 3.72 GB <br> 238 MB
        `Corals`            | `Coral_1` <br> `Coral_2` <br> `Coral2_DOWNSAMPLED` <br> `MexCoral`                                                 | 2.26 GB <br> 2.38 GB <br> 162 MB <br> 2.23 GB
        `Cowry_Shell`       | `Cowry_Shell` <br> `Cowry_DOWNSAMPLED`                                                                             | 1.82 GB <br> 116 MB
        `Crab`              | `HerrmitCrab` <br> `OkinawaCrab`                                                                                   | 2.38 GB <br> 1.86 GB
        `Deer_Mandible`     | `Animal_Mandible` <br> `DeerMandible_DOWNSAMPLED` <br>                                                             | 2.79 GB <br> 638 MB
        `Foam`              | `Foam` <br> `Foam_DOWNSAMPLED` <br> `Foam_2` <br> `Foam_2_zoom`                                                    | 3.72 GB <br> 238 MB <br> 3.72 GB <br> 3.72 GB
        `Hourglass`         | `Hourglass` <br> `Hourglass_4X_80kV_Air_9s_1_97um` <br> `Hourglass_longexp_rerun`                                  | 3.72 GB <br> 1.83 GB <br> 3.72 GB
        `Kiwi`              | `Kiwi`                                                                                                             | 2.86 GB
        `Loofah`            | `Loofah` <br> `Loofah_DOWNSAMPLED`                                                                                 | 2.23 GB <br> 143 MB
        `Marine_Gastropods` | `MarineGatropod_1` <br> `MarineGastropod1_DOWNSAMPLED` <br> `MarineGatropod_2` <br> `MarineGastropod2_DOWNSAMPLED` | 2.23 GB <br> 143 MB <br> 2.60 GB <br> 166 MB
        `Mussel`            | `ClosedMussel1` <br> `ClosedMussel1_DOWNSAMPLED`                                                                   | 2.23 GB <br> 143 MB
        `Oak_Branch`        | `Oak_branch` <br> `OakBranch_DOWNSAMPLED`                                                                          | 2.38 GB <br> 152 MB
        `Okinawa_Forams`    | `Okinawa_Foram_1` <br> `Okinawa_Foram_2`                                                                           | 1.84 GB <br> 1.84 GB
        `Physalis`          | `Physalis` <br> `Physalis_DOWNSAMPLED`                                                                             | 3.72 GB <br> 238 MB
        `Raspberry`         | `Raspberry2` <br> `Raspberry2_DOWNSAMPLED`                                                                         | 2.97 GB <br> 190 MB
        `Rope`              | `FibreRope1` <br> `FibreRope1_DOWNSAMPLED`                                                                         | 1.82 GB <br> 686 MB
        `Sea_Urchin`        | `SeaUrchin` <br> `Cordatum_Shell` <br> `Cordatum_Spine`                                                            | 2.60 GB <br> 1.85 GB <br> 183 MB
        `Snail`             | `Escargot`                                                                                                         | 2.60 GB
        `Sponge`            | `Sponge`                                                                                                           | 1.11 GB

    Example:
        ```python
        import qim3d

        downloader = qim3d.io.Downloader()
        downloader.list_files()
        data = downloader.Cowry_Shell.Cowry_DOWNSAMPLED(load_file=True)

        qim3d.viz.slicer_orthogonal(data, color_map="magma")
        ```
        ![cowry shell](../../assets/screenshots/cowry_shell_slicer.gif)

    """

    def __init__(self):
        folders = _extract_names()
        for idx, folder in enumerate(folders):
            exec(f'self.{folder} = _Myfolder(folder)')

    def list_files(self):
        """Generate and print formatted folder, file, and size information."""

        url_dl = 'https://archive.compute.dtu.dk/download/public/projects/viscomp_data_repository'

        folders = _extract_names()

        for folder in folders:
            log.info(f'\n{ouf.boxtitle(folder, return_str=True)}')
            files = _extract_names(folder)

            for file in files:
                url = os.path.join(url_dl, folder, file).replace('\\', '/')
                file_size = _get_file_size(url)
                formatted_file = (
                    f"{file[:-len(file.split('.')[-1])-1].replace('%20', '_')}"
                )
                formatted_size = _format_file_size(file_size)
                path_string = f'{folder}.{formatted_file}'

                log.info(f'{path_string:<50}({formatted_size})')

qim3d.io.Downloader.list_files

list_files()

Generate and print formatted folder, file, and size information.

Source code in qim3d/io/_downloader.py

def list_files(self):
    """Generate and print formatted folder, file, and size information."""

    url_dl = 'https://archive.compute.dtu.dk/download/public/projects/viscomp_data_repository'

    folders = _extract_names()

    for folder in folders:
        log.info(f'\n{ouf.boxtitle(folder, return_str=True)}')
        files = _extract_names(folder)

        for file in files:
            url = os.path.join(url_dl, folder, file).replace('\\', '/')
            file_size = _get_file_size(url)
            formatted_file = (
                f"{file[:-len(file.split('.')[-1])-1].replace('%20', '_')}"
            )
            formatted_size = _format_file_size(file_size)
            path_string = f'{folder}.{formatted_file}'

            log.info(f'{path_string:<50}({formatted_size})')

qim3d.io.load

load(path, virtual_stack=False, dataset_name=None, return_metadata=False, contains=None, force_load=False, dim_order=(2, 1, 0), progress_bar=False, display_memory_usage=False, **kwargs)

Load data from the specified file or directory.

Supported formats:

• Tiff (including file stacks)
• HDF5
• TXRM/TXM/XRM
• NIfTI
• PIL (including file stacks)
• VOL/VGI
• DICOM

Parameters:

Name	Type	Description	Default
path	str or PathLike	The path to the file or directory.	required
virtual_stack	bool	Specifies whether to use virtual stack when loading files. Default is False.	False
dataset_name	str	Specifies the name of the dataset to be loaded in case multiple dataset exist within the same file. Default is None (only for HDF5 files)	None
return_metadata	bool	Specifies whether to return metadata or not. Default is False (only for HDF5 and TXRM/TXM/XRM files)	False
contains	str	Specifies a part of the name that is common for the TIFF file stack to be loaded (only for TIFF stacks). Default is None.	None
force_load	bool	If the file size exceeds available memory, a MemoryError is raised. If force_load is True, the error is changed to warning and the loader tries to load it anyway. Default is False.	False
dim_order	tuple	The order of the dimensions in the volume for .vol files. Default is (2,1,0) which corresponds to (z,y,x)	(2, 1, 0)
progress_bar	bool	Displays tqdm progress bar. Useful for large files. So far works only for linux. Default is False.	False
display_memory_usage	bool	If true, prints used memory and available memory after loading file. Default is False.	False
**kwargs	Any	Additional keyword arguments supported by DataLoader: - virtual_stack (bool) - dataset_name (str) - return_metadata (bool) - contains (str) - force_load (bool) - dim_order (tuple)	{}

Returns:

Name	Type	Description
vol	(ndarray, memmap, Dataset, ArrayProxy or tuple)	The loaded volume If virtual_stack=True, returns numpy.memmap, h5py._hl.dataset.Dataset or nibabel.arrayproxy.ArrayProxy depending on file format If return_metadata=True and file format is either HDF5, NIfTI or TXRM/TXM/XRM, returns tuple (volume, metadata).

Raises:

Type	Description
MemoryError	if the given file size exceeds available memory

Example

import qim3d

vol = qim3d.io.load("path/to/image.tif", virtual_stack=True)

Source code in qim3d/io/_loading.py

def load(
    path: str | os.PathLike,
    virtual_stack: bool = False,
    dataset_name: bool = None,
    return_metadata: bool = False,
    contains: bool = None,
    force_load: bool = False,
    dim_order: tuple = (2, 1, 0),
    progress_bar: bool = False,
    display_memory_usage: bool = False,
    **kwargs,
) -> np.ndarray:
    """
    Load data from the specified file or directory.

    Supported formats:

    - `Tiff` (including file stacks)
    - `HDF5`
    - `TXRM`/`TXM`/`XRM`
    - `NIfTI`
    - `PIL` (including file stacks)
    - `VOL`/`VGI`
    - `DICOM`

    Args:
        path (str or os.PathLike): The path to the file or directory.
        virtual_stack (bool, optional): Specifies whether to use virtual
            stack when loading files. Default is False.
        dataset_name (str, optional): Specifies the name of the dataset to be loaded
            in case multiple dataset exist within the same file. Default is None (only for HDF5 files)
        return_metadata (bool, optional): Specifies whether to return metadata or not. Default is False (only for HDF5 and TXRM/TXM/XRM files)
        contains (str, optional): Specifies a part of the name that is common for the TIFF file stack to be loaded (only for TIFF stacks).
            Default is None.
        force_load (bool, optional): If the file size exceeds available memory, a MemoryError is raised.
            If force_load is True, the error is changed to warning and the loader tries to load it anyway. Default is False.
        dim_order (tuple, optional): The order of the dimensions in the volume for .vol files. Default is (2,1,0) which corresponds to (z,y,x)
        progress_bar (bool, optional): Displays tqdm progress bar. Useful for large files. So far works only for linux. Default is False.
        display_memory_usage (bool, optional): If true, prints used memory and available memory after loading file. Default is False.
        **kwargs (Any): Additional keyword arguments supported by `DataLoader`:
            - `virtual_stack` (bool)
            - `dataset_name` (str)
            - `return_metadata` (bool)
            - `contains` (str)
            - `force_load` (bool)
            - `dim_order` (tuple)

    Returns:
        vol (numpy.ndarray, numpy.memmap, h5py._hl.dataset.Dataset, nibabel.arrayproxy.ArrayProxy or tuple): The loaded volume

            If `virtual_stack=True`, returns `numpy.memmap`, `h5py._hl.dataset.Dataset` or `nibabel.arrayproxy.ArrayProxy` depending on file format
            If `return_metadata=True` and file format is either HDF5, NIfTI or TXRM/TXM/XRM, returns `tuple` (volume, metadata).

    Raises:
        MemoryError: if the given file size exceeds available memory

    Example:
        ```python
        import qim3d

        vol = qim3d.io.load("path/to/image.tif", virtual_stack=True)
        ```

    """

    loader = DataLoader(
        virtual_stack=virtual_stack,
        dataset_name=dataset_name,
        return_metadata=return_metadata,
        contains=contains,
        force_load=force_load,
        dim_order=dim_order,
        **kwargs,
    )

    if progress_bar and os.name == 'posix':
        with FileLoadingProgressBar(path):
            data = loader.load(path)
    else:
        data = loader.load(path)

    def log_memory_info(data):
        mem = Memory()
        log.info(
            'Volume using %s of memory\n',
            sizeof(data[0].nbytes if isinstance(data, tuple) else data.nbytes),
        )
        mem.report()

    if return_metadata and not isinstance(data, tuple):
        log.warning('The file format does not contain metadata')

    if not virtual_stack:
        if display_memory_usage:
            log_memory_info(data)
    else:
        # Only log if file type is not a np.ndarray, i.e., it is some kind of memmap object
        if not isinstance(
            type(data[0]) if isinstance(data, tuple) else type(data), np.ndarray
        ):
            log.info('Using virtual stack')
        else:
            log.warning('Virtual stack is not supported for this file format')
            if display_memory_usage:
                log_memory_info(data)

    return data

qim3d.io.save

save(path, data, replace=False, compression=False, basename=None, sliced_dim=0, chunk_shape='auto', **kwargs)

Save data to a specified file path.

Parameters:

Name	Type	Description	Default
path	str or PathLike	The path to save file to. File format is chosen based on the extension. Supported extensions are: '.tif', '.tiff', '.nii', '.nii.gz', '.h5', '.vol', '.vgi', '.dcm', '.DCM', '.zarr', '.jpeg', '.jpg', '.png'	required
data	ndarray	The data to be saved	required
replace	bool	Specifies if an existing file with identical path should be replaced. Default is False.	False
compression	bool	Specifies if the file should be saved with Deflate compression (lossless). Default is False.	False
basename	str	Specifies the basename for a TIFF stack saved as several files (only relevant for TIFF stacks). Default is None	None
sliced_dim	int	Specifies the dimension that is sliced in case a TIFF stack is saved as several files (only relevant for TIFF stacks). Default is 0, i.e., the first dimension.	0
**kwargs	Any	Additional keyword arguments to be passed to the DataSaver constructor	{}

Raises:

Type	Description
ValueError	If the provided path is an existing directory and self.basename is not provided OR If the file format is not supported OR If the provided path does not exist and self.basename is not provided OR If a file extension is not provided OR if a file with the specified path already exists and replace=False.

Example

import qim3d

# Generate synthetic blob
vol = qim3d.generate.noise_object(noise_scale = 0.015)

qim3d.io.save("blob.tif", vol, replace=True)

Volumes can also be saved with one file per slice:

import qim3d

# Generate synthetic blob
vol = qim3d.generate.noise_object(noise_scale = 0.015)

qim3d.io.save("slices", vol, basename="blob-slices", sliced_dim=0)

Source code in qim3d/io/_saving.py

def save(
    path: str | os.PathLike,
    data: np.ndarray,
    replace: bool = False,
    compression: bool = False,
    basename: bool = None,
    sliced_dim: int = 0,
    chunk_shape: str = 'auto',
    **kwargs,
) -> None:
    """
    Save data to a specified file path.

    Args:
        path (str or os.PathLike): The path to save file to. File format is chosen based on the extension.
            Supported extensions are: <em>'.tif', '.tiff', '.nii', '.nii.gz', '.h5', '.vol', '.vgi', '.dcm', '.DCM', '.zarr', '.jpeg', '.jpg', '.png'</em>
        data (numpy.ndarray): The data to be saved
        replace (bool, optional): Specifies if an existing file with identical path should be replaced.
            Default is False.
        compression (bool, optional): Specifies if the file should be saved with Deflate compression (lossless).
            Default is False.
        basename (str, optional): Specifies the basename for a TIFF stack saved as several files
            (only relevant for TIFF stacks). Default is None
        sliced_dim (int, optional): Specifies the dimension that is sliced in case a TIFF stack is saved
            as several files (only relevant for TIFF stacks). Default is 0, i.e., the first dimension.
        **kwargs (Any): Additional keyword arguments to be passed to the DataSaver constructor

    Raises:
        ValueError: If the provided path is an existing directory and self.basename is not provided <strong>OR</strong>
            If the file format is not supported <strong>OR</strong>
            If the provided path does not exist and self.basename is not provided <strong>OR</strong>
            If a file extension is not provided <strong>OR</strong>
            if a file with the specified path already exists and replace=False.

    Example:
        ```python
        import qim3d

        # Generate synthetic blob
        vol = qim3d.generate.noise_object(noise_scale = 0.015)

        qim3d.io.save("blob.tif", vol, replace=True)
        ```

        Volumes can also be saved with one file per slice:
        ```python
        import qim3d

        # Generate synthetic blob
        vol = qim3d.generate.noise_object(noise_scale = 0.015)

        qim3d.io.save("slices", vol, basename="blob-slices", sliced_dim=0)
        ```

    """

    DataSaver(
        replace=replace,
        compression=compression,
        basename=basename,
        sliced_dim=sliced_dim,
        chunk_shape=chunk_shape,
        **kwargs,
    ).save(path, data)

qim3d.io.export_ome_zarr

export_ome_zarr(path, data, chunk_size=256, downsample_rate=2, order=1, replace=False, method='scaleZYX', progress_bar=True, progress_bar_repeat_time='auto')

Export 3D image data to OME-Zarr format with pyramidal downsampling.

This function generates a multi-scale OME-Zarr representation of the input data, which is commonly used for large imaging datasets. The downsampled scales are calculated such that the smallest scale fits within the specified chunk_size.

Parameters:

Name	Type	Description	Default
path	str or PathLike	The directory where the OME-Zarr data will be stored.	required
data	ndarray or array	The 3D image data to be exported. Supports both NumPy and Dask arrays.	required
chunk_size	int	The size of the chunks for storing data. This affects both the original data and the downsampled scales. Defaults to 256.	256
downsample_rate	int	The factor by which to downsample the data for each scale. Must be greater than 1. Defaults to 2.	2
order	int	The interpolation order to use when downsampling. Defaults to 1 (linear). Use 0 for a faster nearest-neighbor interpolation.	1
replace	bool	Whether to replace the existing directory if it already exists. Defaults to False.	False
method	str	The method used for downsampling. If set to "dask", Dask arrays are used for chunking and downsampling. Defaults to "scaleZYX".	'scaleZYX'
progress_bar	bool	Whether to display a progress bar during export. Defaults to True.	True
progress_bar_repeat_time	str or int	The repeat interval (in seconds) for updating the progress bar. Defaults to "auto".	'auto'

Raises:

Type	Description
ValueError	If the directory already exists and replace is False.
ValueError	If downsample_rate is less than or equal to 1.

Example

import qim3d

downloader = qim3d.io.Downloader()
data = downloader.Snail.Escargot(load_file=True)

qim3d.io.export_ome_zarr("Escargot.zarr", data, chunk_size=100, downsample_rate=2)

Source code in qim3d/io/_ome_zarr.py

def export_ome_zarr(
    path: str | os.PathLike,
    data: np.ndarray | da.core.Array,
    chunk_size: int = 256,
    downsample_rate: int = 2,
    order: int = 1,
    replace: bool = False,
    method: str = 'scaleZYX',
    progress_bar: bool = True,
    progress_bar_repeat_time: str = 'auto',
) -> None:
    """
    Export 3D image data to OME-Zarr format with pyramidal downsampling.

    This function generates a multi-scale OME-Zarr representation of the input data, which is commonly used for large imaging datasets. The downsampled scales are calculated such that the smallest scale fits within the specified `chunk_size`.

    Args:
        path (str or os.PathLike): The directory where the OME-Zarr data will be stored.
        data (np.ndarray or dask.array): The 3D image data to be exported. Supports both NumPy and Dask arrays.
        chunk_size (int, optional): The size of the chunks for storing data. This affects both the original data and the downsampled scales. Defaults to 256.
        downsample_rate (int, optional): The factor by which to downsample the data for each scale. Must be greater than 1. Defaults to 2.
        order (int, optional): The interpolation order to use when downsampling. Defaults to 1 (linear). Use 0 for a faster nearest-neighbor interpolation.
        replace (bool, optional): Whether to replace the existing directory if it already exists. Defaults to False.
        method (str, optional): The method used for downsampling. If set to "dask", Dask arrays are used for chunking and downsampling. Defaults to "scaleZYX".
        progress_bar (bool, optional): Whether to display a progress bar during export. Defaults to True.
        progress_bar_repeat_time (str or int, optional): The repeat interval (in seconds) for updating the progress bar. Defaults to "auto".

    Raises:
        ValueError: If the directory already exists and `replace` is False.
        ValueError: If `downsample_rate` is less than or equal to 1.

    Example:
        ```python
        import qim3d

        downloader = qim3d.io.Downloader()
        data = downloader.Snail.Escargot(load_file=True)

        qim3d.io.export_ome_zarr("Escargot.zarr", data, chunk_size=100, downsample_rate=2)
        ```

    """

    # Check if directory exists
    if os.path.exists(path):
        if replace:
            shutil.rmtree(path)
        else:
            raise ValueError(
                f'Directory {path} already exists. Use replace=True to overwrite.'
            )

    # Check if downsample_rate is valid
    if downsample_rate <= 1:
        raise ValueError('Downsample rate must be greater than 1.')

    log.info(f'Exporting data to OME-Zarr format at {path}')

    # Get the number of scales
    min_dim = np.max(np.shape(data))
    nscales = math.ceil(math.log(min_dim / chunk_size) / math.log(downsample_rate))
    log.info(f'Number of scales: {nscales + 1}')

    # Create scaler
    scaler = OMEScaler(
        downscale=downsample_rate, max_layer=nscales, method=method, order=order
    )

    # write the image data
    os.mkdir(path)
    store = parse_url(path, mode='w').store
    root = zarr.group(store=store)

    # Check if we want to process using Dask
    if 'dask' in method and not isinstance(data, da.Array):
        log.info('\nConverting input data to Dask array')
        data = da.from_array(data, chunks=(chunk_size, chunk_size, chunk_size))
        log.info(f' - shape...: {data.shape}\n - chunks..: {data.chunksize}\n')

    elif 'dask' in method and isinstance(data, da.Array):
        log.info('\nInput data will be rechunked')
        data = data.rechunk((chunk_size, chunk_size, chunk_size))
        log.info(f' - shape...: {data.shape}\n - chunks..: {data.chunksize}\n')

    log.info('Calculating the multi-scale pyramid')

    # Generate multi-scale pyramid
    mip = scaler.func(data)

    log.info('Writing data to disk')
    kwargs = dict(
        pyramid=mip,
        group=root,
        fmt=CurrentFormat(),
        axes='zyx',
        name=None,
        compute=True,
        storage_options=dict(chunks=(chunk_size, chunk_size, chunk_size)),
    )
    if progress_bar:
        n_chunks = get_n_chunks(
            shapes=(scaled_data.shape for scaled_data in mip),
            dtypes=(scaled_data.dtype for scaled_data in mip),
        )
        with OmeZarrExportProgressBar(
            path=path, n_chunks=n_chunks, reapeat_time=progress_bar_repeat_time
        ):
            write_multiscale(**kwargs)
    else:
        write_multiscale(**kwargs)

    log.info('\nAll done!')

    return

qim3d.io.import_ome_zarr

import_ome_zarr(path, scale=0, load=True)

Import image data from an OME-Zarr file.

This function reads OME-Zarr formatted volumetric image data and returns the specified scale. The image data can be lazily loaded (as Dask arrays) or fully computed into memory.

Parameters:

Name	Type	Description	Default
path	str or PathLike	The file path to the OME-Zarr data.	required
scale	int or str	The scale level to load. If 'highest', loads the finest scale (scale 0). If 'lowest', loads the coarsest scale (last available scale). Defaults to 0.	0
load	bool	Whether to compute the selected scale into memory. If False, returns a lazy Dask array. Defaults to True.	True

Returns:

Name	Type	Description
vol	ndarray or Array	The requested image data, either as a NumPy array if load=True, or a Dask array if load=False.

Raises:

Type	Description
ValueError	If the requested scale does not exist in the data.

Example

import qim3d

data = qim3d.io.import_ome_zarr("Escargot.zarr", scale=0, load=True)

Source code in qim3d/io/_ome_zarr.py

def import_ome_zarr(
    path: str | os.PathLike, scale: int = 0, load: bool = True
) -> np.ndarray:
    """
    Import image data from an OME-Zarr file.

    This function reads OME-Zarr formatted volumetric image data and returns the specified scale.
    The image data can be lazily loaded (as Dask arrays) or fully computed into memory.

    Args:
        path (str or os.PathLike): The file path to the OME-Zarr data.
        scale (int or str, optional): The scale level to load.
            If 'highest', loads the finest scale (scale 0).
            If 'lowest', loads the coarsest scale (last available scale). Defaults to 0.
        load (bool, optional): Whether to compute the selected scale into memory.
            If False, returns a lazy Dask array. Defaults to True.

    Returns:
        vol (np.ndarray or dask.array.Array): The requested image data, either as a NumPy array if `load=True`, or a Dask array if `load=False`.

    Raises:
        ValueError: If the requested `scale` does not exist in the data.

    Example:
        ```python
        import qim3d

        data = qim3d.io.import_ome_zarr("Escargot.zarr", scale=0, load=True)

        ```

    """

    # read the image data
    # store = parse_url(path, mode="r").store

    reader = Reader(parse_url(path))
    nodes = list(reader())
    image_node = nodes[0]
    dask_data = image_node.data

    log.info(f'Data contains {len(dask_data)} scales:')
    for i in np.arange(len(dask_data)):
        log.info(f'- Scale {i}: {dask_data[i].shape}')

    if scale == 'highest':
        scale = 0

    if scale == 'lowest':
        scale = len(dask_data) - 1

    if scale >= len(dask_data):
        raise ValueError(
            f'Scale {scale} does not exist in the data. Please choose a scale between 0 and {len(dask_data)-1}.'
        )

    log.info(f'\nLoading scale {scale} with shape {dask_data[scale].shape}')

    if load:
        vol = dask_data[scale].compute()
    else:
        vol = dask_data[scale]

    return vol

qim3d.io.load_mesh

load_mesh(filename)

Load a mesh from a specific file. This function is based on the PyGEL3D library's loading function implementation.

Supported formats:

• X3D
• OBJ
• OFF
• PLY

Parameters:

Name	Type	Description	Default
filename	str or PathLike	The path to the file.	required

Returns:

Name	Type	Description
mesh	Manifold or None	A hmesh object containing the mesh data or None if loading failed.

Example

import qim3d

mesh = qim3d.io.load_mesh("path/to/mesh.obj")

Source code in qim3d/io/_loading.py

def load_mesh(filename: str) -> hmesh.Manifold:
    """
    Load a mesh from a specific file.
    This function is based on the [PyGEL3D library's loading function implementation](https://www2.compute.dtu.dk/projects/GEL/PyGEL/pygel3d/hmesh.html#load).

    Supported formats:

    - `X3D`
    - `OBJ`
    - `OFF`
    - `PLY`

    Args:
        filename (str or os.PathLike): The path to the file.

    Returns:
        mesh (hmesh.Manifold or None): A hmesh object containing the mesh data or None if loading failed.

    Example:
        ```python
        import qim3d

        mesh = qim3d.io.load_mesh("path/to/mesh.obj")
        ```

    """
    mesh = hmesh.load(filename)

    return mesh

qim3d.io.save_mesh

save_mesh(filename, mesh)

Save a mesh object to a specific file. This function is based on the PyGEL3D library's saving function implementation.

Parameters:

Name	Type	Description	Default
filename	str or PathLike	The path to save file to. File format is chosen based on the extension. Supported extensions are: '.x3d', '.obj', '.off'.	required
mesh	Manifold	A hmesh.Manifold object representing the mesh.	required

Example

import qim3d

synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
mesh = qim3d.mesh.from_volume(synthetic_blob)
qim3d.io.save_mesh("mesh.obj", mesh)

Source code in qim3d/io/_saving.py

def save_mesh(filename: str, mesh: hmesh.Manifold) -> None:
    """
    Save a mesh object to a specific file.
    This function is based on the [PyGEL3D library's saving function implementation](https://www2.compute.dtu.dk/projects/GEL/PyGEL/pygel3d/hmesh.html#save).


    Args:
        filename (str or os.PathLike): The path to save file to. File format is chosen based on the extension. Supported extensions are: '.x3d', '.obj', '.off'.
        mesh (pygel3d.hmesh.Manifold): A hmesh.Manifold object representing the mesh.

    Example:
        ```python
        import qim3d

        synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
        mesh = qim3d.mesh.from_volume(synthetic_blob)
        qim3d.io.save_mesh("mesh.obj", mesh)
        ```

    """
    # Export the mesh to the specified filename
    hmesh.save(filename, mesh)