Skip to content

Input/Output

All the input/output operations are handled by the plantseg.io module. This module provides functions to read and write data in different formats. The supported formats are tiff, h5, and zarr, jpeg, png.

Reading

plantseg.io.smart_load(path, key=None, info_only=False, default=load_tiff) -> Union[tuple, tuple[np.ndarray, tuple]]

Load a dataset from a file and returns some meta info about it. The loader is chosen based on the file extension. Supported formats are: tiff, h5, zarr, and PIL images. If the format is not supported, a default loader can be provided (default: load_tiff).

Parameters:

  • path (str) –

    path to the file to load.

  • key (str, default: None ) –

    key of the dataset to load (if h5).

  • info_only (bool, default: False ) –

    if true will return a tuple with infos such as voxel resolution, units and shape.

  • default (callable, default: load_tiff ) –

    default loader if the type is not understood.

Returns:

  • stack ( ndarray ) –

    numpy array with the image data.

  • infos ( tuple ) –

    tuple with the voxel size, shape, metadata and voxel size unit (if info_only is True).

Examples:

>>> data, infos = smart_load('path/to/file.tif')
>>> data, infos = smart_load('path/to/file.h5', key='raw')
Source code in plantseg/io/io.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def smart_load(path, key=None, info_only=False, default=load_tiff) -> Union[tuple, tuple[np.ndarray, tuple]]:
    """
    Load a dataset from a file and returns some meta info about it. The loader is chosen based on the file extension.
    Supported formats are: tiff, h5, zarr, and PIL images.
    If the format is not supported, a default loader can be provided (default: load_tiff).

    Args:
        path (str): path to the file to load.
        key (str): key of the dataset to load (if h5).
        info_only (bool): if true will return a tuple with infos such as voxel resolution, units and shape.
        default (callable): default loader if the type is not understood.

    Returns:
        stack (np.ndarray): numpy array with the image data.
        infos (tuple): tuple with the voxel size, shape, metadata and voxel size unit (if info_only is True).

    Examples:
        >>> data, infos = smart_load('path/to/file.tif')
        >>> data, infos = smart_load('path/to/file.h5', key='raw')

    """
    _, ext = os.path.splitext(path)
    if ext in H5_EXTENSIONS:
        return load_h5(path, key, info_only=info_only)

    elif ext in TIFF_EXTENSIONS:
        return load_tiff(path, info_only=info_only)

    elif ext in PIL_EXTENSIONS:
        return load_pill(path, info_only=info_only)

    elif ext in ZARR_EXTENSIONS:
        return load_zarr(path, key, info_only=info_only)

    else:
        print(f"No default found for {ext}, reverting to default loader")
        return default(path)

Writing

plantseg.io.create_tiff(path: str, stack: np.ndarray, voxel_size: tuple[float, float, float], voxel_size_unit: str = 'um') -> None

Create a tiff file from a numpy array

Parameters:

  • path (str) –

    path of the new file

  • stack (ndarray) –

    numpy array to save as tiff

  • voxel_size (list or tuple) –

    tuple of the voxel size

  • voxel_size_unit (str, default: 'um' ) –

    units of the voxel size

Source code in plantseg/io/tiff.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def create_tiff(
    path: str,
    stack: np.ndarray,
    voxel_size: tuple[float, float, float],
    voxel_size_unit: str = 'um',
) -> None:
    """
    Create a tiff file from a numpy array

    Args:
        path (str): path of the new file
        stack (np.ndarray): numpy array to save as tiff
        voxel_size (list or tuple): tuple of the voxel size
        voxel_size_unit (str): units of the voxel size

    """
    # taken from: https://pypi.org/project/tifffile docs
    z, y, x = stack.shape
    stack = stack.reshape(1, z, 1, y, x, 1)  # dimensions in TZCYXS order
    spacing, y, x = voxel_size
    resolution = (1.0 / x, 1.0 / y)
    # Save output results as tiff
    tifffile.imwrite(
        path,
        data=stack,
        dtype=stack.dtype,
        imagej=True,
        resolution=resolution,
        metadata={'axes': 'TZCYXS', 'spacing': spacing, 'unit': voxel_size_unit},
        compression='zlib',
    )

plantseg.io.create_h5(path: str, stack: np.ndarray, key: str, voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), mode: str = 'a') -> None

Create a dataset inside a h5 file from a numpy array.

Parameters:

  • path (str) –

    file path.

  • stack (ndarray) –

    numpy array to save as dataset in the h5 file.

  • key (str) –

    key of the dataset in the h5 file.

  • voxel_size (tuple[float, float, float], default: (1.0, 1.0, 1.0) ) –

    voxel size in micrometers.

  • mode (str, default: 'a' ) –

    mode to open the h5 file ['w', 'a'].

Source code in plantseg/io/h5.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def create_h5(
    path: str,
    stack: np.ndarray,
    key: str,
    voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0),
    mode: str = 'a',
) -> None:
    """
    Create a dataset inside a h5 file from a numpy array.

    Args:
        path (str): file path.
        stack (np.ndarray): numpy array to save as dataset in the h5 file.
        key (str): key of the dataset in the h5 file.
        voxel_size (tuple[float, float, float]: voxel size in micrometers.
        mode (str): mode to open the h5 file ['w', 'a'].

    """

    with h5py.File(path, mode) as f:
        if key in f:
            del f[key]
        f.create_dataset(key, data=stack, compression='gzip')
        # save voxel_size
        f[key].attrs['element_size_um'] = voxel_size

plantseg.io.create_zarr(path: str, stack: np.ndarray, key: str, voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), mode: str = 'a') -> None

Create a Zarr array from a NumPy array.

Parameters:

  • path (str) –

    The file path to the Zarr file.

  • stack (ndarray) –

    The NumPy array to save as a dataset.

  • key (str) –

    The internal key of the desired dataset.

  • voxel_size (tuple[float, float, float], default: (1.0, 1.0, 1.0) ) –

    The voxel size in micrometers.

  • mode (str, default: 'a' ) –

    The mode to open the Zarr file ['w', 'a'].

Source code in plantseg/io/zarr.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def create_zarr(
    path: str,
    stack: np.ndarray,
    key: str,
    voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0),
    mode: str = 'a',
) -> None:
    """
    Create a Zarr array from a NumPy array.

    Args:
        path (str): The file path to the Zarr file.
        stack (np.ndarray): The NumPy array to save as a dataset.
        key (str): The internal key of the desired dataset.
        voxel_size (tuple[float, float, float]): The voxel size in micrometers.
        mode (str): The mode to open the Zarr file ['w', 'a'].

    """
    zarr_file = zarr.open_group(path, mode)
    zarr_file.create_dataset(key, data=stack, compression='gzip', overwrite=True)
    zarr_file[key].attrs['element_size_um'] = voxel_size

Utilities

plantseg.io.load_shape(path: str, key: str = None) -> tuple[int, ...]

Load only the stack shape from a file using the smart loader.

Parameters:

  • path (str) –

    path to the file to load.

  • key (str, default: None ) –

    key of the dataset to load (if h5 or zarr).

Returns:

  • tuple[int, ...] –

    shape (tuple[int, ...]) shape of the image stack.

Examples:

>>> shape = load_shape('path/to/file.tif')
>>> print(shape)
(10, 512, 512)
Source code in plantseg/io/io.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def load_shape(path: str, key: str = None) -> tuple[int, ...]:
    """
    Load only the stack shape from a file using the smart loader.

    Args:
        path (str): path to the file to load.
        key (str): key of the dataset to load (if h5 or zarr).

    Returns:
        shape (tuple[int, ...]) shape of the image stack.

    Examples:
        >>> shape = load_shape('path/to/file.tif')
        >>> print(shape)
        (10, 512, 512)
    """
    _, data_shape, _, _ = smart_load(path, key=key, info_only=True)
    return data_shape

Tiff Utilities

plantseg.io.tiff.read_tiff_voxel_size(file_path: str) -> tuple[tuple[float, float, float], str]

Returns the voxels size and the voxel units for imagej and ome style tiff (if absent returns [1, 1, 1], um)

Parameters:

  • file_path (str) –

    path to the tiff file

Returns:

Source code in plantseg/io/tiff.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def read_tiff_voxel_size(file_path: str) -> tuple[tuple[float, float, float], str]:
    """
    Returns the voxels size and the voxel units for imagej and ome style tiff (if absent returns [1, 1, 1], um)

    Args:
        file_path (str): path to the tiff file

    Returns:
        voxel size
        voxel size unit

    """
    with tifffile.TiffFile(file_path) as tiff:
        if tiff.imagej_metadata is not None:
            [z, y, x], voxel_size_unit = _read_imagej_meta(tiff)

        elif tiff.ome_metadata is not None:
            [z, y, x], voxel_size_unit = _read_ome_meta(tiff)

        else:
            # default voxel size
            warnings.warn('No metadata found. Reverting to default voxel size (1., 1., 1.) um')
            x, y, z = 1.0, 1.0, 1.0
            voxel_size_unit = 'um'

        return (z, y, x), voxel_size_unit

H5 Utilities

plantseg.io.h5.list_keys(path: str) -> list[str]

List all keys in a h5 file

Parameters:

  • path (str) –

    path to the h5 file

Returns:

  • keys ( list[str] ) –

    A list of keys in the h5 file.

Source code in plantseg/io/h5.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def list_keys(path: str) -> list[str]:
    """
    List all keys in a h5 file

    Args:
        path (str): path to the h5 file

    Returns:
        keys (list[str]): A list of keys in the h5 file.

    """

    def _recursive_find_keys(f, base='/'):
        _list_keys = []
        for key, dataset in f.items():
            if isinstance(dataset, h5py.Group):
                new_base = f"{base}{key}/"
                _list_keys += _recursive_find_keys(dataset, new_base)

            elif isinstance(dataset, h5py.Dataset):
                _list_keys.append(f'{base}{key}')
        return _list_keys

    with h5py.File(path, 'r') as h5_f:
        return _recursive_find_keys(h5_f)

plantseg.io.h5.del_h5_key(path: str, key: str, mode: str = 'a') -> None

helper function to delete a dataset from a h5file

Parameters:

  • path (str) –

    path to the h5file

  • key (str) –

    key of the dataset to delete

  • mode (str, default: 'a' ) –

    mode to open the h5 file ['r', 'r+']

Source code in plantseg/io/h5.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def del_h5_key(path: str, key: str, mode: str = 'a') -> None:
    """
    helper function to delete a dataset from a h5file

    Args:
        path (str): path to the h5file
        key (str): key of the dataset to delete
        mode (str): mode to open the h5 file ['r', 'r+']

    """
    with h5py.File(path, mode) as f:
        if key in f:
            del f[key]
            f.close()

plantseg.io.h5.rename_h5_key(path: str, old_key: str, new_key: str, mode='r+') -> None

Rename the 'old_key' dataset to 'new_key'

Parameters:

  • path (str) –

    path to the h5 file

  • old_key (str) –

    old key name

  • new_key (str) –

    new key name

  • mode (str, default: 'r+' ) –

    mode to open the h5 file ['r', 'r+']

Source code in plantseg/io/h5.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def rename_h5_key(path: str, old_key: str, new_key: str, mode='r+') -> None:
    """
    Rename the 'old_key' dataset to 'new_key'

    Args:
        path (str): path to the h5 file
        old_key (str): old key name
        new_key (str): new key name
        mode (str): mode to open the h5 file ['r', 'r+']

    """
    with h5py.File(path, mode) as f:
        if old_key in f:
            f[new_key] = f[old_key]
            del f[old_key]
            f.close()

Zarr Utilities

plantseg.io.zarr.list_keys(path: str) -> list[str]

List all keys in a Zarr file.

Parameters:

  • path (str) –

    The path to the Zarr file.

Returns:

  • keys ( list[str] ) –

    A list of keys in the Zarr file.

Source code in plantseg/io/zarr.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def list_keys(path: str) -> list[str]:
    """
    List all keys in a Zarr file.

    Args:
        path (str): The path to the Zarr file.

    Returns:
        keys (list[str]): A list of keys in the Zarr file.
    """

    def _recursive_find_keys(zarr_group: zarr.Group, base: Path = Path('')) -> list[str]:
        _list_keys = []
        for key, dataset in zarr_group.items():
            if isinstance(dataset, zarr.Group):
                new_base = base / key
                _list_keys.extend(_recursive_find_keys(dataset, new_base))
            elif isinstance(dataset, zarr.Array):
                _list_keys.append(str(base / key))
        return _list_keys

    zarr_file = zarr.open_group(path, 'r')
    return _recursive_find_keys(zarr_file)

plantseg.io.zarr.del_zarr_key(path: str, key: str, mode: str = 'a') -> None

Delete a dataset from a Zarr file.

Parameters:

  • path (str) –

    The path to the Zarr file.

  • key (str) –

    The internal key of the dataset to be deleted.

  • mode (str, default: 'a' ) –

    The mode to open the Zarr file ['w', 'a'].

Source code in plantseg/io/zarr.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
def del_zarr_key(path: str, key: str, mode: str = 'a') -> None:
    """
    Delete a dataset from a Zarr file.

    Args:
        path (str): The path to the Zarr file.
        key (str): The internal key of the dataset to be deleted.
        mode (str): The mode to open the Zarr file ['w', 'a'].

    """
    zarr_file = zarr.open_group(path, mode)
    if key in zarr_file:
        del zarr_file[key]

plantseg.io.zarr.rename_zarr_key(path: str, old_key: str, new_key: str, mode='r+') -> None

Rename a dataset in a Zarr file.

Parameters:

  • path (str) –

    The path to the Zarr file.

  • old_key (str) –

    The current key of the dataset.

  • new_key (str) –

    The new key for the dataset.

  • mode (str, default: 'r+' ) –

    The mode to open the Zarr file ['r+'].

Source code in plantseg/io/zarr.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
def rename_zarr_key(path: str, old_key: str, new_key: str, mode='r+') -> None:
    """
    Rename a dataset in a Zarr file.

    Args:
        path (str): The path to the Zarr file.
        old_key (str): The current key of the dataset.
        new_key (str): The new key for the dataset.
        mode (str): The mode to open the Zarr file ['r+'].

    """
    zarr_file = zarr.open_group(path, mode)
    if old_key in zarr_file:
        zarr_file[new_key] = zarr_file[old_key]
        del zarr_file[old_key]