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

swcgeom/core/tree_utils.py

@@ -1,9 +1,26 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
 """SWC util wrapper for tree."""
 
 import warnings
-from typing import Callable, Dict, Iterable, List, Optional, Tuple, TypeVar, overload
+from collections.abc import Callable, Iterable
+from typing import Optional, TypeVar, overload
 
 import numpy as np
+from typing_extensions import deprecated
 
 from swcgeom.core.swc import SWCLike
 from swcgeom.core.swc_utils import (
@@ -50,9 +67,9 @@ def sort_tree(tree: Tree) -> Tree:
 
 # fmt:off
 @overload
-def cut_tree(tree: Tree, *, enter: Callable[[Tree.Node, T | None], Tuple[T, bool]]) -> Tree: ...
+def cut_tree(tree: Tree, *, enter: Callable[[Tree.Node, T | None], tuple[T, bool]]) -> Tree: ...
 @overload
-def cut_tree(tree: Tree, *, leave: Callable[[Tree.Node, List[K]], Tuple[K, bool]]) -> Tree: ...
+def cut_tree(tree: Tree, *, leave: Callable[[Tree.Node, list[K]], tuple[K, bool]]) -> Tree: ...
 # fmt:on
 def cut_tree(tree: Tree, *, enter=None, leave=None):
     """Traverse and cut the tree.
@@ -60,11 +77,11 @@ def cut_tree(tree: Tree, *, enter=None, leave=None):
     Returning a `True` can delete the current node and its children.
     """
 
-    removals: List[int] = []
+    removals: list[int] = []
 
     if enter:
 
-        def _enter(n: Tree.Node, parent: Tuple[T, bool] | None) -> Tuple[T, bool]:
+        def _enter(n: Tree.Node, parent: tuple[T, bool] | None) -> tuple[T, bool]:
             if parent is not None and parent[1]:
                 removals.append(n.id)
                 return parent
@@ -79,7 +96,7 @@ def cut_tree(tree: Tree, *, enter=None, leave=None):
 
     elif leave:
 
-        def _leave(n: Tree.Node, children: List[K]) -> K:
+        def _leave(n: Tree.Node, children: list[K]) -> K:
             res, removal = leave(n, children)
             if removal:
                 removals.append(n.id)
@@ -94,24 +111,22 @@ def cut_tree(tree: Tree, *, enter=None, leave=None):
     return to_subtree(tree, removals)
 
 
-def to_sub_tree(swc_like: SWCLike, sub: Topology) -> Tuple[Tree, Dict[int, int]]:
+@deprecated("Use `to_subtree` instead")
+def to_sub_tree(swc_like: SWCLike, sub: Topology) -> tuple[Tree, dict[int, int]]:
     """Create subtree from origin tree.
 
     You can directly mark the node for removal, and we will remove it,
     but if the node you remove is not a leaf node, you need to use
     `propagate_remove` to remove all children.
 
+    .. deprecated:: 0.6.0
+        Use :meth:`to_subtree` instead.
+
     Returns
     -------
     tree : Tree
-    id_map : Dict[int, int]
+    id_map : dict[int, int]
     """
-    warnings.warn(
-        "`to_sub_tree` will be removed in v0.6.0, it is replaced by "
-        "`to_subtree` beacuse it is easy to use, and this will be "
-        "removed in next version",
-        DeprecationWarning,
-    )
 
     sub = propagate_removal(sub)
     (new_id, new_pid), id_map_arr = to_sub_topology(sub)
@@ -141,7 +156,7 @@ def to_subtree(
     swc_like : SWCLike
     removals : List of int
         A list of id of nodes to be removed.
-    out_mapping: List of int or Dict[int, int], optional
+    out_mapping: List of int or dict[int, int], optional
         Map new id to old id.
     """
 
@@ -166,7 +181,7 @@ def get_subtree(
     swc_like : SWCLike
     n : int
         Id of the root of the subtree.
-    out_mapping: List of int or Dict[int, int], optional
+    out_mapping: List of int or dict[int, int], optional
         Map new id to old id.
     """
 

swcgeom/core/tree_utils_impl.py

@@ -1,3 +1,18 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
 """SWC util wrapper for tree, split to avoid circle imports.
 
 Notes
@@ -5,7 +20,7 @@ Notes
 Do not import `Tree` and keep this file minimized.
 """
 
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Optional
 
 import numpy as np
 import numpy.typing as npt
@@ -15,8 +30,8 @@ from swcgeom.core.swc_utils import Topology, to_sub_topology, traverse
 
 __all__ = ["get_subtree_impl", "to_subtree_impl"]
 
-Mapping = Dict[int, int] | List[int]
-TreeArgs = Tuple[int, Dict[str, npt.NDArray[Any]], str, SWCNames]
+Mapping = dict[int, int] | list[int]
+TreeArgs = tuple[int, dict[str, npt.NDArray[Any]], str, SWCNames]
 
 
 def get_subtree_impl(

swcgeom/images/__init__.py

@@ -1,4 +1,19 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
 """Image Stack Related."""
 
-from swcgeom.images.folder import *
-from swcgeom.images.io import *
+from swcgeom.images.folder import *  # noqa: F403
+from swcgeom.images.io import *  # noqa: F403

swcgeom/images/augmentation.py

@@ -1,7 +1,27 @@
-"""Play augment in image stack."""
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Play augment in image stack.
+
+Notes
+-----
+This is expremental code, and the API is subject to change.
+"""
 
 import random
-from typing import List, Literal, Optional
+from typing import Literal, Optional
 
 import numpy as np
 import numpy.typing as npt
@@ -49,7 +69,7 @@ class Augmentation:
 
     def swapaxes(self, x, mode: Optional[Literal["xy", "xz", "yz"]] = None) -> NDArrf32:
         if mode is None:
-            modes: List[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
+            modes: list[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
             mode = modes[self.rand.randint(0, 2)]
 
         match mode:
@@ -64,7 +84,7 @@ class Augmentation:
 
     def flip(self, x, mode: Optional[Literal["xy", "xz", "yz"]] = None) -> NDArrf32:
         if mode is None:
-            modes: List[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
+            modes: list[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
             mode = modes[random.randint(0, 2)]
 
         match mode:

swcgeom/images/contrast.py

@@ -0,0 +1,122 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""The contrast of an image.
+
+Notes
+-----
+This is expremental code, and the API is subject to change.
+"""
+
+from typing import Optional, overload
+
+import numpy as np
+import numpy.typing as npt
+
+__all__ = ["contrast_std", "contrast_michelson", "contrast_rms", "contrast_weber"]
+
+Array3D = npt.NDArray[np.float32]
+
+
+@overload
+def contrast_std(image: Array3D) -> float:
+    """Get the std contrast of an image stack.
+
+    Parameters
+    ----------
+    imgs : ndarray
+
+    Returns
+    -------
+    contrast : float
+    """
+    ...
+
+
+@overload
+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.
+
+    Returns
+    -------
+    imgs : ndarray
+        The adjusted image.
+    """
+    ...
+
+
+def contrast_std(image: Array3D, contrast: Optional[float] = None):
+    if contrast is None:
+        return np.std(image).item()
+    else:
+        return np.clip(contrast * image, 0, 1)
+
+
+def contrast_michelson(image: Array3D) -> float:
+    """Get the Michelson contrast of an image stack.
+
+    Parameters
+    ----------
+    imgs : ndarray
+
+    Returns
+    -------
+    contrast : float
+    """
+
+    vmax = np.max(image)
+    vmin = np.min(image)
+    return ((vmax - vmin) / (vmax + vmin)).item()
+
+
+def contrast_rms(imgs: npt.NDArray[np.float32]) -> float:
+    """Get the RMS contrast of an image stack.
+
+    Parameters
+    ----------
+    imgs : ndarray
+
+    Returns
+    -------
+    contrast : float
+    """
+
+    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.
+
+    Returns
+    -------
+    contrast : float
+    """
+
+    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

@@ -1,41 +1,44 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
 """Image stack folder."""
 
+import math
 import os
 import re
-import warnings
-from abc import ABC, abstractmethod
-from typing import (
-    Callable,
-    Generic,
-    Iterable,
-    List,
-    Literal,
-    Optional,
-    Tuple,
-    TypeVar,
-    overload,
-)
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Generic, Literal, Optional, TypeVar, overload
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import Self
+from tqdm import tqdm
+from typing_extensions import Self, deprecated
 
 from swcgeom.images.io import ScalarType, read_imgs
 from swcgeom.transforms import Identity, Transform
 
-__all__ = [
-    "ImageStackFolder",
-    "LabeledImageStackFolder",
-    "PathImageStackFolder",
-]
+__all__ = ["ImageStackFolder", "LabeledImageStackFolder", "PathImageStackFolder"]
 
 T = TypeVar("T")
 
 
-class ImageStackFolderBase(Generic[ScalarType, T], ABC):
+class ImageStackFolderBase(Generic[ScalarType, T]):
     """Image stack folder base."""
 
-    files: List[str]
+    files: list[str]
     transform: Transform[npt.NDArray[ScalarType], T]
 
     # fmt: off
@@ -51,10 +54,6 @@ class ImageStackFolderBase(Generic[ScalarType, T], ABC):
         self.dtype = dtype or np.float32
         self.transform = transform or Identity()  # type: ignore
 
-    @abstractmethod
-    def __getitem__(self, key: str, /) -> T:
-        raise NotImplementedError()
-
     def __len__(self) -> int:
         return len(self.files)
 
@@ -67,7 +66,10 @@ class ImageStackFolderBase(Generic[ScalarType, T], ABC):
         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: Optional[str] = None) -> list[str]:
+        if not os.path.isdir(root):
+            raise NotADirectoryError(f"not a directory: {root}")
+
         is_valid = re.compile(pattern).match if pattern is not None else truthly
 
         fs = []
@@ -77,24 +79,78 @@ class ImageStackFolderBase(Generic[ScalarType, T], ABC):
         return fs
 
     @staticmethod
+    @deprecated("Use `~swcgeom.images.io.read_imgs(fname).get_full()` instead")
     def read_imgs(fname: str) -> npt.NDArray[np.float32]:
-        warnings.warn(
-            "`ImageStackFolderBase.read_imgs` serves as a "
-            "straightforward wrapper for `~swcgeom.images.io.read_imgs(fname).get_full()`. "
-            "However, as it is not utilized within our internal "
-            "processes, it is scheduled for removal in the "
-            "forthcoming version.",
-            DeprecationWarning,
-        )
+        """Read images.
+
+        .. deprecated:: 0.16.0
+            Use :meth:`~swcgeom.images.io.read_imgs(fname).get_full()` instead.
+        """
+
         return read_imgs(fname).get_full()
 
 
+@dataclass(frozen=True)
+class Statistics:
+    count: int = 0
+    minimum: float = math.nan
+    maximum: float = math.nan
+    mean: float = 0
+    variance: float = 0
+
+
 class ImageStackFolder(ImageStackFolderBase[ScalarType, T]):
     """Image stack folder."""
 
     def __getitem__(self, idx: int, /) -> T:
         return self._get(self.files[idx])
 
+    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
+
+        Notes
+        -----
+        We are asserting that the images are of the same shape.
+        """
+
+        vmin, vmax = math.inf, -math.inf
+        n, mean, M2 = 0, None, None
+
+        for idx in tqdm(range(len(self))) if verbose else range(len(self)):
+            imgs = self[idx] if transform else self._read(self.files[idx])
+
+            vmin = min(vmin, np.min(imgs))  # type: ignore
+            vmax = max(vmax, np.max(imgs))  # type: ignore
+            # Welford algorithm to calculate mean and variance
+            if mean is None:
+                mean = np.zeros_like(imgs)
+                M2 = np.zeros_like(imgs)
+
+            n += 1
+            delta = imgs - mean  # type: ignore
+            mean += delta / n
+            delta2 = imgs - mean
+            M2 += delta * delta2
+
+        if mean is None or M2 is None:  # n = 0
+            raise ValueError("empty folder")
+
+        variance = M2 / (n - 1) if n > 1 else np.zeros_like(mean)
+        return Statistics(
+            count=len(self),
+            maximum=vmax,
+            minimum=vmin,
+            mean=np.mean(mean).item(),
+            variance=np.mean(variance).item(),
+        )
+
     @classmethod
     def from_dir(cls, root: str, *, pattern: Optional[str] = None, **kwargs) -> Self:
         """
@@ -106,20 +162,21 @@ class ImageStackFolder(ImageStackFolderBase[ScalarType, T]):
         **kwargs
             Pass to `cls.__init__`
         """
+
         return cls(cls.scan(root, pattern=pattern), **kwargs)
 
 
 class LabeledImageStackFolder(ImageStackFolderBase[ScalarType, T]):
     """Image stack folder with label."""
 
-    labels: List[int]
+    labels: list[int]
 
     def __init__(self, files: Iterable[str], labels: Iterable[int], **kwargs):
         super().__init__(files, **kwargs)
         self.labels = list(labels)
 
-    def __getitem__(self, idx: int) -> Tuple[npt.NDArray[np.float32], int]:
-        return self.read_imgs(self.files[idx]), self.labels[idx]
+    def __getitem__(self, idx: int) -> tuple[T, int]:
+        return self._get(self.files[idx]), self.labels[idx]
 
     @classmethod
     def from_dir(
@@ -140,7 +197,7 @@ class LabeledImageStackFolder(ImageStackFolderBase[ScalarType, T]):
         return cls(files, labels, **kwargs)
 
 
-class PathImageStackFolder(ImageStackFolder[ScalarType, T]):
+class PathImageStackFolder(ImageStackFolderBase[ScalarType, T]):
     """Image stack folder with relpath."""
 
     root: str
@@ -149,7 +206,7 @@ class PathImageStackFolder(ImageStackFolder[ScalarType, T]):
         super().__init__(files, **kwargs)
         self.root = root
 
-    def __getitem__(self, idx: int) -> Tuple[T, str]:
+    def __getitem__(self, idx: int) -> tuple[T, str]:
         relpath = os.path.relpath(self.files[idx], self.root)
         return self._get(self.files[idx]), relpath
 
@@ -164,6 +221,7 @@ class PathImageStackFolder(ImageStackFolder[ScalarType, T]):
         **kwargs
             Pass to `cls.__init__`
         """
+
         return cls(cls.scan(root, pattern=pattern), root=root, **kwargs)