swcgeom 0.18.3__py3-none-any.whl → 0.19.0__py3-none-any.whl

swcgeom/images/contrast.py

@@ -15,12 +15,10 @@
 
 """The contrast of an image.
 
-Notes
------
-This is expremental code, and the API is subject to change.
+NOTE: This is expremental code, and the API is subject to change.
 """
 
-from typing import Optional, overload
+from typing import overload
 
 import numpy as np
 import numpy.typing as npt
@@ -34,13 +32,11 @@ Array3D = npt.NDArray[np.float32]
 def contrast_std(image: Array3D) -> float:
     """Get the std contrast of an image stack.
 
-    Parameters
-    ----------
-    imgs : ndarray
+    Args:
+        imgs: ndarray
 
-    Returns
-    -------
-    contrast : float
+    Returns:
+        contrast
     """
     ...
 
@@ -49,21 +45,17 @@ def contrast_std(image: Array3D) -> float:
 def contrast_std(image: Array3D, contrast: float) -> Array3D:
     """Adjust the contrast of an image stack.
 
-    Parameters
-    ----------
-    imgs : ndarray
-    constrast : float
-        The contrast adjustment factor. 1.0 leaves the image unchanged.
+    Args:
+        imgs: ndarray
+        contrast: The contrast adjustment factor. 1.0 leaves the image unchanged.
 
-    Returns
-    -------
-    imgs : ndarray
-        The adjusted image.
+    Returns:
+        imgs: The adjusted image.
     """
     ...
 
 
-def contrast_std(image: Array3D, contrast: Optional[float] = None):
+def contrast_std(image: Array3D, contrast: float | None = None):
     if contrast is None:
         return np.std(image).item()
     else:
@@ -73,15 +65,9 @@ def contrast_std(image: Array3D, contrast: Optional[float] = None):
 def contrast_michelson(image: Array3D) -> float:
     """Get the Michelson contrast of an image stack.
 
-    Parameters
-    ----------
-    imgs : ndarray
-
-    Returns
-    -------
-    contrast : float
+    Returns:
+        contrast: float
     """
-
     vmax = np.max(image)
     vmin = np.min(image)
     return ((vmax - vmin) / (vmax + vmin)).item()
@@ -90,33 +76,23 @@ def contrast_michelson(image: Array3D) -> float:
 def contrast_rms(imgs: npt.NDArray[np.float32]) -> float:
     """Get the RMS contrast of an image stack.
 
-    Parameters
-    ----------
-    imgs : ndarray
-
-    Returns
-    -------
-    contrast : float
+    Returns:
+        contrast
     """
-
     return np.sqrt(np.mean(imgs**2)).item()
 
 
 def contrast_weber(imgs: Array3D, mask: npt.NDArray[np.bool_]) -> float:
     """Get the Weber contrast of an image stack.
 
-    Parameters
-    ----------
-    imgs : ndarray
-    mask : ndarray of bool
-        The mask to segment the foreground and background. 1 for
-        foreground, 0 for background.
+    Args:
+        imgs: ndarray
+        mask: The mask to segment the foreground and background.
+            1 for foreground, 0 for background.
 
-    Returns
-    -------
-    contrast : float
+    Returns:
+        contrast
     """
-
     l_foreground = np.mean(imgs, where=mask)
     l_background = np.mean(imgs, where=np.logical_not(mask))
     return ((l_foreground - l_background) / l_background).item()

swcgeom/images/folder.py

@@ -20,7 +20,7 @@ import os
 import re
 from collections.abc import Callable, Iterable
 from dataclasses import dataclass
-from typing import Generic, Literal, Optional, TypeVar, overload
+from typing import Generic, Literal, TypeVar, overload
 
 import numpy as np
 import numpy.typing as npt
@@ -41,13 +41,21 @@ class ImageStackFolderBase(Generic[ScalarType, T]):
     files: list[str]
     transform: Transform[npt.NDArray[ScalarType], T]
 
-    # fmt: off
     @overload
-    def __init__(self, files: Iterable[str], *, dtype: None = ..., transform: Optional[Transform[npt.NDArray[np.float32], T]] = None) -> None: ...
+    def __init__(
+        self,
+        files: Iterable[str],
+        *,
+        transform: Transform[npt.NDArray[np.float32], T] | None = ...,
+    ) -> None: ...
     @overload
-    def __init__(self, files: Iterable[str], *, dtype: ScalarType, transform: Optional[Transform[npt.NDArray[ScalarType], T]] = None) -> None: ...
-    # fmt: on
-
+    def __init__(
+        self,
+        files: Iterable[str],
+        *,
+        dtype: ScalarType,
+        transform: Transform[npt.NDArray[ScalarType], T] | None = ...,
+    ) -> None: ...
     def __init__(self, files: Iterable[str], *, dtype=None, transform=None) -> None:
         super().__init__()
         self.files = list(files)
@@ -66,7 +74,7 @@ class ImageStackFolderBase(Generic[ScalarType, T]):
         return read_imgs(fname, dtype=self.dtype).get_full()  # type: ignore
 
     @staticmethod
-    def scan(root: str, *, pattern: Optional[str] = None) -> list[str]:
+    def scan(root: str, *, pattern: str | None = None) -> list[str]:
         if not os.path.isdir(root):
             raise NotADirectoryError(f"not a directory: {root}")
 
@@ -108,16 +116,12 @@ class ImageStackFolder(ImageStackFolderBase[ScalarType, T]):
     def stat(self, *, transform: bool = False, verbose: bool = False) -> Statistics:
         """Statistics of folder.
 
-        Parameters
-        ----------
-        transform : bool, default to False
-            Apply transform to the images. If True, you need to make
-            sure the transformed data is a ndarray.
-        verbose : bool, optional
+        NOTE: We are asserting that the images are of the same shape.
 
-        Notes
-        -----
-        We are asserting that the images are of the same shape.
+        Args:
+            transform: Apply transform to the images.
+                If True, you need to make sure the transformed data is a ndarray.
+            verbose: Show progress bar.
         """
 
         vmin, vmax = math.inf, -math.inf
@@ -134,7 +138,7 @@ class ImageStackFolder(ImageStackFolderBase[ScalarType, T]):
                 M2 = np.zeros_like(imgs)
 
             n += 1
-            delta = imgs - mean  # type: ignore
+            delta = imgs - mean
             mean += delta / n
             delta2 = imgs - mean
             M2 += delta * delta2
@@ -152,15 +156,12 @@ class ImageStackFolder(ImageStackFolderBase[ScalarType, T]):
         )
 
     @classmethod
-    def from_dir(cls, root: str, *, pattern: Optional[str] = None, **kwargs) -> Self:
+    def from_dir(cls, root: str, *, pattern: str | None = None, **kwargs) -> Self:
         """
-        Parameters
-        ----------
-        root : str
-        pattern : str, optional
-            Filter files by pattern.
-        **kwargs
-            Pass to `cls.__init__`
+        Args:
+            root: str
+            pattern: Filter files by pattern.
+            **kwargs: Pass to `cls.__init__`
         """
 
         return cls(cls.scan(root, pattern=pattern), **kwargs)
@@ -184,7 +185,7 @@ class LabeledImageStackFolder(ImageStackFolderBase[ScalarType, T]):
         root: str,
         label: int | Callable[[str], int],
         *,
-        pattern: Optional[str] = None,
+        pattern: str | None = None,
         **kwargs,
     ) -> Self:
         files = cls.scan(root, pattern=pattern)
@@ -211,15 +212,12 @@ class PathImageStackFolder(ImageStackFolderBase[ScalarType, T]):
         return self._get(self.files[idx]), relpath
 
     @classmethod
-    def from_dir(cls, root: str, *, pattern: Optional[str] = None, **kwargs) -> Self:
+    def from_dir(cls, root: str, *, pattern: str | None = None, **kwargs) -> Self:
         """
-        Parameters
-        ----------
-        root : str
-        pattern : str, optional
-            Filter files by pattern.
-        **kwargs
-            Pass to `cls.__init__`
+        Args:
+            root: str
+            pattern: Filter files by pattern.
+            **kwargs: Pass to `cls.__init__`
         """
 
         return cls(cls.scan(root, pattern=pattern), root=root, **kwargs)

swcgeom/images/io.py

@@ -21,7 +21,7 @@ import warnings
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Iterable
 from functools import cache, lru_cache
-from typing import Any, Generic, Literal, Optional, TypeVar, cast, overload
+from typing import Any, Generic, Literal, TypeVar, cast, overload
 
 import nrrd
 import numpy as np
@@ -39,10 +39,10 @@ RE_TERAFLY_ROOT = re.compile(r"^RES\((\d+)x(\d+)x(\d+)\)$")
 RE_TERAFLY_NAME = re.compile(r"^\d+(_\d+)?(_\d+)?")
 
 UINT_MAX = {
-    np.dtype(np.uint8): (2**8) - 1,  # type: ignore
-    np.dtype(np.uint16): (2**16) - 1,  # type: ignore
-    np.dtype(np.uint32): (2**32) - 1,  # type: ignore
-    np.dtype(np.uint64): (2**64) - 1,  # type: ignore
+    np.dtype(np.uint8): (2**8) - 1,
+    np.dtype(np.uint16): (2**16) - 1,
+    np.dtype(np.uint32): (2**32) - 1,
+    np.dtype(np.uint64): (2**64) - 1,
 }
 
 AXES_ORDER = {
@@ -83,19 +83,15 @@ class ImageStack(ABC, Generic[ScalarType]):
     def __getitem__(self, key):
         """Get pixel/patch of image stack.
 
-        Returns
-        -------
-        value : ndarray of f32
-            NDArray which shape depends on key. If key is tuple of ints,
+        Returns:
+            value: NDArray which shape depends on key. If key is tuple of ints,
         """
         raise NotImplementedError()
 
     def get_full(self) -> npt.NDArray[ScalarType]:
         """Get full image stack.
 
-        Notes
-        -----
-        this will load the full image stack into memory.
+        NOTE: this will load the full image stack into memory.
         """
         return self[:, :, :, :]
 
@@ -104,29 +100,20 @@ class ImageStack(ABC, Generic[ScalarType]):
         raise NotImplementedError()
 
 
-# fmt:off
 @overload
 def read_imgs(fname: str, *, dtype: ScalarType, **kwargs) -> ImageStack[ScalarType]: ...
 @overload
-def read_imgs(fname: str, *, dtype: None =..., **kwargs) -> ImageStack[np.float32]: ...
-# fmt:on
-
-
+def read_imgs(fname: str, *, dtype: None = ..., **kwargs) -> ImageStack[np.float32]: ...
 def read_imgs(fname: str, **kwargs):  # type: ignore
     """Read image stack.
 
-    Parameters
-    ----------
-    fname : str
-        The path of image stack.
-    dtype : np.dtype, default to `np.float32`
-        Casting data to specified dtype. If integer and float
-        conversions occur, they will be scaled (assuming floats are
-        between 0 and 1).
-    **kwargs : dict[str, Any]
-        Forwarding to the corresponding reader.
+    Args:
+        fname: The path of image stack.
+        dtype: Casting data to specified dtype.
+            If integer and float conversions occur, they will be scaled (assuming floats
+            are between 0 and 1). Default to `np.float32`.
+        **kwargs: Forwarding to the corresponding reader.
     """
-
     kwargs.setdefault("dtype", np.float32)
     if not os.path.exists(fname):
         raise ValueError(f"image stack not exists: {fname}")
@@ -155,27 +142,22 @@ def save_tiff(
     data: npt.NDArray | ImageStack,
     fname: str,
     *,
-    dtype: Optional[np.unsignedinteger | np.floating] = None,
+    dtype: np.unsignedinteger | np.floating | None = None,
     compression: str | Literal[False] = "zlib",
     **kwargs,
 ) -> None:
     """Save image stack as tiff.
 
-    Parameters
-    ----------
-    data : array
-        The image stack.
-    fname : str
-    dtype : np.dtype, optional
-        Casting data to specified dtype. If integer and float
-        conversions occur, they will be scaled (assuming floats are
-        between 0 and 1).
-    compression : str | False, default `zlib`
-        Compression algorithm, forwarding to `tifffile.imwrite`. If no
-        algorithnm is specify specified, we will use the zlib algorithm
-        with compression level 6 by default.
-    **kwargs : dict[str, Any]
-        Forwarding to `tifffile.imwrite`
+    Args:
+        data: The image stack.
+        fname: str
+        dtype: Casting data to specified dtype.
+            If integer and float conversions occur, they will be scaled (assuming
+            floats are between 0 and 1).
+        compression: Compression algorithm, forwarding to `tifffile.imwrite`.
+            If no algorithnm is specify specified, we will use the zlib algorithm with
+            compression level 6 by default.
+        **kwargs: Forwarding to `tifffile.imwrite`
     """
     if isinstance(data, ImageStack):
         data = data.get_full()  # TODO: avoid load full imgs to memory
@@ -191,11 +173,11 @@ def save_tiff(
         if np.issubdtype(data.dtype, np.floating) and np.issubdtype(
             dtype, np.unsignedinteger
         ):
-            scaler_factor = UINT_MAX[np.dtype(dtype)]  # type: ignore
+            scaler_factor = UINT_MAX[np.dtype(dtype)]
         elif np.issubdtype(data.dtype, np.unsignedinteger) and np.issubdtype(
             dtype, np.floating
         ):
-            scaler_factor = 1 / UINT_MAX[np.dtype(data.dtype)]  # type: ignore
+            scaler_factor = 1 / UINT_MAX[np.dtype(data.dtype)]
         else:
             scaler_factor = 1
 
@@ -218,7 +200,7 @@ class NDArrayImageStack(ImageStack[ScalarType]):
     """NDArray image stack."""
 
     def __init__(
-        self, imgs: npt.NDArray[Any], *, dtype: Optional[ScalarType] = None
+        self, imgs: npt.NDArray[Any], *, dtype: ScalarType | None = None
     ) -> None:
         super().__init__()
 
@@ -231,13 +213,13 @@ class NDArrayImageStack(ImageStack[ScalarType]):
             if np.issubdtype(dtype, np.floating) and np.issubdtype(
                 dtype_raw, np.unsignedinteger
             ):
-                sclar_factor = 1.0 / UINT_MAX[dtype_raw]
-                imgs = sclar_factor * imgs.astype(dtype)
+                scalar_factor = 1.0 / UINT_MAX[dtype_raw]
+                imgs = scalar_factor * imgs.astype(dtype)
             elif np.issubdtype(dtype, np.unsignedinteger) and np.issubdtype(
                 dtype_raw, np.floating
             ):
-                sclar_factor = UINT_MAX[dtype]  # type: ignore
-                imgs *= (sclar_factor * imgs).astype(dtype)
+                scalar_factor = UINT_MAX[dtype]
+                imgs *= (scalar_factor * imgs).astype(dtype)
             else:
                 imgs = imgs.astype(dtype)
 
@@ -284,27 +266,23 @@ class NrrdImageStack(NDArrayImageStack[ScalarType]):
 class V3dImageStack(NDArrayImageStack[ScalarType]):
     """v3d image stack."""
 
-    def __init__(
-        self, fname: str, loader: Raw | PBD, *, dtype: ScalarType, **kwargs
-    ) -> None:
-        r = loader()
+    def __init_subclass__(cls, loader: Raw | PBD) -> None:
+        super().__init_subclass__()
+        cls._loader = loader
+
+    def __init__(self, fname: str, *, dtype: ScalarType, **kwargs) -> None:
+        r = self._loader()
         imgs = r.load(fname)
         super().__init__(imgs, dtype=dtype, **kwargs)
 
 
-class V3drawImageStack(V3dImageStack[ScalarType]):
+class V3drawImageStack(V3dImageStack[ScalarType], loader=Raw):
     """v3draw image stack."""
 
-    def __init__(self, fname: str, *, dtype: ScalarType, **kwargs) -> None:
-        super().__init__(fname, loader=Raw, dtype=dtype, **kwargs)
-
 
-class V3dpbdImageStack(V3dImageStack[ScalarType]):
+class V3dpbdImageStack(V3dImageStack[ScalarType], loader=PBD):
     """v3dpbd image stack."""
 
-    def __init__(self, fname: str, *, dtype: ScalarType, **kwargs) -> None:
-        super().__init__(fname, loader=PBD, dtype=dtype, **kwargs)
-
 
 class TeraflyImageStack(ImageStack[ScalarType]):
     """TeraFly image stack.
@@ -312,21 +290,17 @@ class TeraflyImageStack(ImageStack[ScalarType]):
     TeraFly is a terabytes of multidimensional volumetric images file
     format as described in [1]_.
 
-    References
-    ----------
-    .. [1] Bria, Alessandro, Giulio Iannello, Leonardo Onofri, and
-       Hanchuan Peng. “TeraFly: Real-Time Three-Dimensional
-       Visualization and Annotation of Terabytes of Multidimensional
-       Volumetric Images.” Nature Methods 13,
-       no. 3 (March 2016): 192-94. https://doi.org/10.1038/nmeth.3767.
-
-    Notes
-    -----
-    Terafly and Vaa3d use a especial right-handed coordinate system
+    NOTE: Terafly and Vaa3d use a especial right-handed coordinate system
     (with origin point in the left-top and z-axis points front), but we
-    flip y-axis to makes it a left-handed coordinate system (with orgin
+    flip y-axis to makes it a left-handed coordinate system (with origin
     point in the left-bottom and z-axis points front). If you need to
     use its coordinate system, remember to FLIP Y-AXIS BACK.
+
+    References:
+    .. [1] Bria, Alessandro, Giulio Iannello, Leonardo Onofri, and Hanchuan Peng.
+       “TeraFly: Real-Time Three-Dimensional Visualization and Annotation of Terabytes
+       of Multidimensional Volumetric Images.” Nature Methods 13, no. 3 (March 2016):
+       192-94. https://doi.org/10.1038/nmeth.3767.
     """
 
     _listdir: Callable[[str], list[str]]
@@ -336,17 +310,13 @@ class TeraflyImageStack(ImageStack[ScalarType]):
         self, root: str, *, dtype: ScalarType, lru_maxsize: int | None = 128
     ) -> None:
         r"""
-        Parameters
-        ----------
-        root : str
-            The root of terafly which contains directories named as
-            `RES(YxXxZ)`.
-        dtype : np.dtype
-        lru_maxsize : int or None, default to 128
-            Forwarding to `functools.lru_cache`. A decompressed array
-            size of (256, 256, 256, 1), which is the typical size of
-            terafly image stack, takes about 256 * 256 * 256 * 1 *
-            4B = 64MB. A cache size of 128 requires about 8GB memeory.
+        Args:
+            root: The root of terafly which contains directories named as `RES(YxXxZ)`.
+            dtype: np.dtype
+            lru_maxsize: Forwarding to `functools.lru_cache`.
+                A decompressed array size of (256, 256, 256, 1), which is the typical
+                size of terafly image stack, takes about 256 * 256 * 256 * 1 * 4B = 64MB.
+                A cache size of 128 requires about 8GB memory.
         """
 
         super().__init__()
@@ -372,11 +342,8 @@ class TeraflyImageStack(ImageStack[ScalarType]):
     def __getitem__(self, key):
         """Get images in max resolution.
 
-        Examples
-        --------
-        ```python
-        imgs[0, 0, 0, 0]            # get value
-        imgs[0:64, 0:64, 0:64, :]   # get patch
+        >>> imgs[0, 0, 0, 0]  # get value # doctest: +SKIP
+        >>> imgs[0:64, 0:64, 0:64, :]  # get patch # doctest: +SKIP
         ```
         """
         if not isinstance(key, tuple):
@@ -399,9 +366,8 @@ class TeraflyImageStack(ImageStack[ScalarType]):
     ) -> npt.NDArray[ScalarType]:
         """Get patch of image stack.
 
-        Returns
-        -------
-        patch : array of shape (X, Y, Z, C)
+        Returns:
+            patch: array of shape (X, Y, Z, C)
         """
         if isinstance(strides, int):
             strides = (strides, strides, strides)
@@ -421,10 +387,9 @@ class TeraflyImageStack(ImageStack[ScalarType]):
     def find_correspond_imgs(self, p, res_level=-1):
         """Find the image which contain this point.
 
-        Returns
-        -------
-        patch : array of shape (X, Y, Z, C)
-        patch_offset : (int, int, int)
+        Returns:
+            patch: array of shape (X, Y, Z, C)
+            patch_offset: (int, int, int)
         """
         p = np.array(p)
         self._check_params(res_level, p)
@@ -442,14 +407,10 @@ class TeraflyImageStack(ImageStack[ScalarType]):
     def get_resolutions(cls, root: str) -> tuple[list[Vec3i], list[str], list[Vec3i]]:
         """Get all resolutions.
 
-        Returns
-        -------
-        resolutions : List of (int, int, int)
-            Sequence of sorted resolutions (from small to large).
-        roots : list[str]
-            Sequence of root of resolutions respectively.
-        patch_sizes : List of (int, int, int)
-            Sequence of patch size of resolutions respectively.
+        Returns:
+            resolutions: Sequence of sorted resolutions (from small to large).
+            roots: Sequence of root of resolutions respectively.
+            patch_sizes: Sequence of patch size of resolutions respectively.
         """
 
         roots = list(cls.get_resolution_dirs(root))
@@ -497,13 +458,13 @@ class TeraflyImageStack(ImageStack[ScalarType]):
 
         res = self.res[res_level]
         for p in coords:
-            assert np.less(
-                [0, 0, 0], p
-            ).all(), f"indices ({p[0]}, {p[1]}, {p[2]}) out of range (0, 0, 0)"
+            assert np.less([0, 0, 0], p).all(), (
+                f"indices ({p[0]}, {p[1]}, {p[2]}) out of range (0, 0, 0)"
+            )
 
-            assert np.greater(
-                res, p
-            ).all(), f"indices ({p[0]}, {p[1]}, {p[2]}) out of range ({res[0]}, {res[1]}, {res[2]})"
+            assert np.greater(res, p).all(), (
+                f"indices ({p[0]}, {p[1]}, {p[2]}) out of range ({res[0]}, {res[1]}, {res[2]})"
+            )
 
     def _get_range(self, starts, ends, res_level, out):
         # pylint: disable=too-many-locals
@@ -529,13 +490,13 @@ class TeraflyImageStack(ImageStack[ScalarType]):
         if shape[1] > lens[1]:
             starts_y = starts + [0, lens[1], 0]
             ends_y = np.array([starts[0], ends[1], ends[2]])
-            ends_y += [min(shape[0], lens[0]), 0, 0]  # type: ignore
+            ends_y += [min(shape[0], lens[0]), 0, 0]
             self._get_range(starts_y, ends_y, res_level, out[:, lens[1] :, :])
 
         if shape[2] > lens[2]:
             starts_z = starts + [0, 0, lens[2]]
             ends_z = np.array([starts[0], starts[1], ends[2]])
-            ends_z += [min(shape[0], lens[0]), min(shape[1], lens[1]), 0]  # type: ignore
+            ends_z += [min(shape[0], lens[0]), min(shape[1], lens[1]), 0]
             self._get_range(starts_z, ends_z, res_level, out[:, :, lens[2] :])
 
     def _find_correspond_imgs(self, p, res_level):
@@ -580,14 +541,14 @@ class GrayImageStack:
     def __init__(self, imgs: ImageStack) -> None:
         self.imgs = imgs
 
-    # fmt: off
     @overload
     def __getitem__(self, key: Vec3i) -> np.float32: ...
     @overload
     def __getitem__(self, key: npt.NDArray[np.integer[Any]]) -> np.float32: ...
     @overload
-    def __getitem__(self, key: slice | tuple[slice, slice] | tuple[slice, slice, slice]) -> npt.NDArray[np.float32]: ...
-    # fmt: on
+    def __getitem__(
+        self, key: slice | tuple[slice, slice] | tuple[slice, slice, slice]
+    ) -> npt.NDArray[np.float32]: ...
     def __getitem__(self, key):
         """Get pixel/patch of image stack."""
         v = self[key]
@@ -601,14 +562,12 @@ class GrayImageStack:
             return v[:, 0]
         if v.ndim == 1:
             return v[0]
-        raise ValueError("unsupport key")
+        raise ValueError("unsupported key")
 
     def get_full(self) -> npt.NDArray[np.float32]:
         """Get full image stack.
 
-        Notes
-        -----
-        this will load the full image stack into memory.
+        NOTE: this will load the full image stack into memory.
         """
         return self.imgs.get_full()[:, :, :, 0]