update image_io docstrings

brainglobe · Mar 21, 2024 · 0e4e956 · 0e4e956
1 parent 4551e6e
commit 0e4e956
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 8 deletions.
diff --git a/brainglobe_utils/image_io/load.py b/brainglobe_utils/image_io/load.py
@@ -86,6 +86,15 @@ def load_any(
     -------
     np.ndarray
         The loaded brain.
+
+    Raises
+    ------
+    ImageIOLoadException
+        If there was an issue loading the image with image_io.
+
+    See Also
+    ------
+    image_io.utils.ImageIOLoadException
     """
     src_path = Path(src_path)
 
@@ -170,7 +179,8 @@ def load_img_stack(
     Parameters
     ----------
     stack_path : str or pathlib.Path
-        The path of the image to be loaded.
+        The path of the image to be loaded. Note that only 3D tiffs are
+        supported.
 
     x_scaling_factor : float
         The scaling of the brain along the x dimension (applied on loading
@@ -193,6 +203,11 @@ def load_img_stack(
     -------
     np.ndarray
         The loaded brain array.
+
+    Raises
+    ------
+    ImageIOLoadException
+        If attempt to load a 2D tiff.
     """
     stack_path = Path(stack_path)
     logging.debug(f"Loading: {stack_path}")
@@ -221,7 +236,6 @@ def load_img_stack(
         logging.debug("Converting downsampled stack to array")
         stack = np.array(downsampled_stack)
 
-    # stack = np.rollaxis(stack, 0, 3)
     if z_scaling_factor != 1:
         logging.debug("Downsampling stack in Z")
         stack = scale_z(stack, z_scaling_factor)
@@ -281,7 +295,8 @@ def load_from_folder(
     Parameters
     ----------
     src_folder : str or pathlib.Path
-        The source folder containing tiff files.
+        The source folder containing tiff files. Note that this folder must
+        contain at least 2 tiffs, and all tiff images must have the same shape.
 
     x_scaling_factor : float, optional
         The scaling of the brain along the x dimension (applied on loading
@@ -313,6 +328,12 @@ def load_from_folder(
     -------
     np.ndarray
         The loaded and scaled brain.
+
+    Raises
+    ------
+    ImageIOLoadException
+        If attempt to load a directory containing only a single tiff, or a
+        sequence of tiffs that have different shapes.
     """
     paths = get_sorted_file_paths(src_folder, file_extension=file_extension)
 
@@ -345,7 +366,8 @@ def load_img_sequence(
     ----------
     img_sequence_file_path : str or pathlib.Path
         The path to the file containing the ordered list of image paths (one
-        per line).
+        per line). Note that this file must contain at least 2 paths, and all
+        referenced images must have the same shape.
 
     x_scaling_factor : float, optional
         The scaling of the brain along the x dimension (applied on loading
@@ -377,6 +399,12 @@ def load_img_sequence(
     -------
     np.ndarray
         The loaded and scaled brain.
+
+    Raises
+    ------
+    ImageIOLoadException
+        If attempt to load a txt file containing only a single path, or a
+        sequence of paths that load images with different shapes.
     """
     img_sequence_file_path = Path(img_sequence_file_path)
     with open(img_sequence_file_path, "r") as in_file:
@@ -411,7 +439,8 @@ def load_image_series(
     Parameters
     ----------
     paths : list of str or list of pathlib.Path
-        Ordered list of image paths.
+        Ordered list of image paths. Must contain at least 2 paths, and all
+        referenced images must have the same shape.
 
     x_scaling_factor : float, optional
         The scaling of the brain along the x dimension (applied on loading
@@ -439,6 +468,12 @@ def load_image_series(
     -------
     np.ndarray
         The loaded and scaled brain.
+
+    Raises
+    ------
+    ImageIOLoadException
+        If attempt to load a single path, or a sequence of paths that load
+        images with different shapes.
     """
     # Throw an error if there's only one image to load - should be an image
     # series, so at least 2 paths.
@@ -481,7 +516,8 @@ def threaded_load_from_sequence(
     Parameters
     ----------
     paths_sequence : list of str or list of pathlib.Path
-        The sorted list of the planes paths on the filesystem.
+        The sorted list of the planes paths on the filesystem. All planes
+        must have the same shape.
 
     x_scaling_factor : float, optional
         The scaling of the brain along the x dimension (applied on loading
@@ -503,6 +539,11 @@ def threaded_load_from_sequence(
     -------
     np.ndarray
         The loaded and scaled brain.
+
+    Raises
+    ------
+    ImageIOLoadException
+        If attempt to load a sequence of images with different shapes.
     """
     stacks = []
     n_processes = get_num_processes(min_free_cpu_cores=n_free_cpus)
@@ -560,7 +601,8 @@ def load_from_paths_sequence(
     Parameters
     ----------
     paths_sequence : list of str or list of pathlib.Path
-        The sorted list of the planes paths on the filesystem.
+        The sorted list of the planes paths on the filesystem. All planes
+        must have the same shape.
 
     x_scaling_factor : float, optional
         The scaling of the brain along the x dimension (applied on loading
@@ -579,6 +621,11 @@ def load_from_paths_sequence(
     -------
     np.ndarray
         The loaded and scaled brain.
+
+    Raises
+    ------
+    ImageIOLoadException
+        If attempt to load a sequence of images with different shapes.
     """
     for i, p in enumerate(
         tqdm(paths_sequence, desc="Loading images", unit="plane")

diff --git a/brainglobe_utils/image_io/utils.py b/brainglobe_utils/image_io/utils.py
@@ -70,7 +70,7 @@ def check_mem(img_byte_size, n_imgs):
 
     Raises
     ------
-    BrainLoadException
+    ImageIOLoadException
         If not enough memory is available.
     """
     total_size = img_byte_size * n_imgs