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

swcgeom/transforms/geometry.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 geometry operations."""
 
 import warnings
@@ -72,7 +87,7 @@ class RadiusReseter(Generic[T], Transform[T, T]):
         new_tree.ndata[new_tree.names.r] = r
         return new_tree
 
-    def extra_repr(self):
+    def extra_repr(self) -> str:
         return f"r={self.r:.4f}"
 
 
@@ -141,7 +156,7 @@ class Translate(Generic[T], AffineTransform[T]):
         super().__init__(translate3d(tx, ty, tz), **kwargs)
         self.tx, self.ty, self.tz = tx, ty, tz
 
-    def extra_repr(self):
+    def extra_repr(self) -> str:
         return f"tx={self.tx:.4f}, ty={self.ty:.4f}, tz={self.tz:.4f}"
 
     @classmethod
@@ -194,8 +209,8 @@ class Rotate(Generic[T], AffineTransform[T]):
         self.theta = theta
         self.center = center
 
-    def extra_repr(self):
-        return f"n={self.n}, theta={self.theta:.4f}, center={self.center}"  # TODO: imporve format of n
+    def extra_repr(self) -> str:
+        return f"n={self.n}, theta={self.theta:.4f}, center={self.center}"  # TODO: improve format of n
 
     @classmethod
     def transform(
@@ -216,7 +231,7 @@ class RotateX(Generic[T], AffineTransform[T]):
         super().__init__(rotate3d_x(theta), center=center, **kwargs)
         self.theta = theta
 
-    def extra_repr(self):
+    def extra_repr(self) -> str:
         return f"center={self.center}, theta={self.theta:.4f}"
 
     @classmethod
@@ -232,7 +247,7 @@ class RotateY(Generic[T], AffineTransform[T]):
         self.theta = theta
         self.center = center
 
-    def extra_repr(self):
+    def extra_repr(self) -> str:
         return f"theta={self.theta:.4f}, center={self.center}"
 
     @classmethod
@@ -248,7 +263,7 @@ class RotateZ(Generic[T], AffineTransform[T]):
         self.theta = theta
         self.center = center
 
-    def extra_repr(self):
+    def extra_repr(self) -> str:
         return f"theta={self.theta:.4f}, center={self.center}"
 
     @classmethod

swcgeom/transforms/image_preprocess.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.
+
+
 """Image stack pre-processing."""
 
 import numpy as np

swcgeom/transforms/image_stack.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.
+
+
 """Create image stack from morphology.
 
 Notes
@@ -12,7 +27,8 @@ pip install swcgeom[all]
 import os
 import re
 import time
-from typing import Iterable, List, Optional, Tuple
+from collections.abc import Iterable
+from typing import Optional
 
 import numpy as np
 import numpy.typing as npt
@@ -26,6 +42,7 @@ from sdflit import (
     SDFObject,
 )
 from tqdm import tqdm
+from typing_extensions import deprecated
 
 from swcgeom.core import Population, Tree
 from swcgeom.transforms.base import Transform
@@ -62,14 +79,14 @@ class ToImageStack(Transform[Tree, npt.NDArray[np.uint8]]):
         ONLY works for small image stacks, use :meth`transform_and_save`
         for big image stack.
         """
-        return np.stack(list(self.transfrom(x, verbose=False)), axis=0)
+        return np.stack(list(self.transform(x, verbose=False)), axis=0)
 
-    def transfrom(
+    def transform(
         self,
         x: Tree,
         verbose: bool = True,
         *,
-        ranges: Optional[Tuple[npt.ArrayLike, npt.ArrayLike]] = None,
+        ranges: Optional[tuple[npt.ArrayLike, npt.ArrayLike]] = None,
     ) -> Iterable[npt.NDArray[np.uint8]]:
         if verbose:
             print("To image stack: " + x.source)
@@ -101,10 +118,20 @@ class ToImageStack(Transform[Tree, npt.NDArray[np.uint8]]):
             frame = (255 * voxel[..., 0, 0]).astype(np.uint8)
             yield frame
 
+    @deprecated("Use transform instead")
+    def transfrom(
+        self,
+        x: Tree,
+        verbose: bool = True,
+        *,
+        ranges: Optional[tuple[npt.ArrayLike, npt.ArrayLike]] = None,
+    ) -> Iterable[npt.NDArray[np.uint8]]:
+        return self.transform(x, verbose, ranges=ranges)
+
     def transform_and_save(
         self, fname: str, x: Tree, verbose: bool = True, **kwargs
     ) -> None:
-        self.save_tif(fname, self.transfrom(x, verbose=verbose, **kwargs))
+        self.save_tif(fname, self.transform(x, verbose=verbose, **kwargs))
 
     def transform_population(
         self, population: Population | str, verbose: bool = True
@@ -124,7 +151,7 @@ class ToImageStack(Transform[Tree, npt.NDArray[np.uint8]]):
             if not os.path.isfile(tif):
                 self.transform_and_save(tif, tree, verbose=False)
 
-    def extra_repr(self):
+    def extra_repr(self) -> str:
         res = ",".join(f"{a:.4f}" for a in self.resolution)
         return f"resolution=({res})"
 
@@ -133,7 +160,7 @@ class ToImageStack(Transform[Tree, npt.NDArray[np.uint8]]):
         scene = ObjectsScene()
         scene.set_background((0, 0, 0))
 
-        def leave(n: Tree.Node, children: List[Tree.Node]) -> Tree.Node:
+        def leave(n: Tree.Node, children: list[Tree.Node]) -> Tree.Node:
             for c in children:
                 sdf = RoundCone(_tp3f(n.xyz()), _tp3f(c.xyz()), n.r, c.r).into()
                 scene.add_object(SDFObject(sdf, material).into())
@@ -175,7 +202,7 @@ class ToImageStack(Transform[Tree, npt.NDArray[np.uint8]]):
     def save_tif(
         fname: str,
         frames: Iterable[npt.NDArray[np.uint8]],
-        resolution: Tuple[float, float] = (1, 1),
+        resolution: tuple[float, float] = (1, 1),
     ) -> None:
         with tifffile.TiffWriter(fname) as tif:
             for frame in frames:
@@ -191,7 +218,7 @@ class ToImageStack(Transform[Tree, npt.NDArray[np.uint8]]):
                 )
 
 
-def _tp3f(x: npt.NDArray) -> Tuple[float, float, float]:
+def _tp3f(x: npt.NDArray) -> tuple[float, float, float]:
     """Convert to tuple of 3 floats."""
     assert len(x) == 3
     return (float(x[0]), float(x[1]), float(x[2]))

swcgeom/transforms/images.py

@@ -1,19 +1,36 @@
-"""Image stack related transform."""
+# 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.
+
 
-import warnings
-from typing import Tuple
+"""Image stack related transform."""
 
 import numpy as np
 import numpy.typing as npt
+from typing_extensions import deprecated
 
-from swcgeom.transforms.base import Transform
+from swcgeom.transforms.base import Identity, Transform
 
 __all__ = [
     "ImagesCenterCrop",
     "ImagesScale",
     "ImagesClip",
+    "ImagesFlip",
+    "ImagesFlipY",
     "ImagesNormalizer",
     "ImagesMeanVarianceAdjustment",
+    "ImagesScaleToUnitRange",
+    "ImagesHistogramEqualization",
     "Center",  # legacy
 ]
 
@@ -24,7 +41,7 @@ NDArrayf32 = npt.NDArray[np.float32]
 class ImagesCenterCrop(Transform[NDArrayf32, NDArrayf32]):
     """Get image stack center."""
 
-    def __init__(self, shape_out: int | Tuple[int, int, int]):
+    def __init__(self, shape_out: int | tuple[int, int, int]):
         super().__init__()
         self.shape_out = (
             shape_out
@@ -42,21 +59,14 @@ class ImagesCenterCrop(Transform[NDArrayf32, NDArrayf32]):
         return f"shape_out=({','.join(str(a) for a in self.shape_out)})"
 
 
+@deprecated("use `ImagesCenterCrop` instead", stacklevel=2)
 class Center(ImagesCenterCrop):
     """Get image stack center.
 
-    .. deprecated:: 0.5.0
+    .. deprecated:: 0.16.0
         Use :class:`ImagesCenterCrop` instead.
     """
 
-    def __init__(self, shape_out: int | Tuple[int, int, int]):
-        warnings.warn(
-            "`Center` is deprecated, use `ImagesCenterCrop` instead",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        super().__init__(shape_out)
-
 
 class ImagesScale(Transform[NDArrayf32, NDArrayf32]):
     def __init__(self, scaler: float) -> None:
@@ -66,6 +76,9 @@ class ImagesScale(Transform[NDArrayf32, NDArrayf32]):
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return self.scaler * x
 
+    def extra_repr(self) -> str:
+        return f"scaler={self.scaler}"
+
 
 class ImagesClip(Transform[NDArrayf32, NDArrayf32]):
     def __init__(self, vmin: float = 0, vmax: float = 1, /) -> None:
@@ -75,6 +88,41 @@ class ImagesClip(Transform[NDArrayf32, NDArrayf32]):
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return np.clip(x, self.vmin, self.vmax)
 
+    def extra_repr(self) -> str:
+        return f"vmin={self.vmin}, vmax={self.vmax}"
+
+
+class ImagesFlip(Transform[NDArrayf32, NDArrayf32]):
+    """Flip image stack along axis."""
+
+    def __init__(self, axis: int, /) -> None:
+        super().__init__()
+        self.axis = axis
+
+    def __call__(self, x: NDArrayf32) -> NDArrayf32:
+        return np.flip(x, axis=self.axis)
+
+    def extra_repr(self) -> str:
+        return f"axis={self.axis}"
+
+
+class ImagesFlipY(ImagesFlip):
+    """Flip image stack along Y-axis.
+
+    See Also
+    --------
+    ~.images.io.TeraflyImageStack:
+        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 point in the left-bottom and z-axis points front).
+        If you need to use its coordinate system, remember to FLIP
+        Y-AXIS BACK.
+    """
+
+    def __init__(self, axis: int = 1, /) -> None:
+        super().__init__(axis)  # (X, Y, Z, C)
+
 
 class ImagesNormalizer(Transform[NDArrayf32, NDArrayf32]):
     """Normalize image stack."""
@@ -100,3 +148,62 @@ class ImagesMeanVarianceAdjustment(Transform[NDArrayf32, NDArrayf32]):
 
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return (x - self.mean) / self.variance
+
+    def extra_repr(self) -> str:
+        return f"mean={self.mean}, variance={self.variance}"
+
+
+class ImagesScaleToUnitRange(Transform[NDArrayf32, NDArrayf32]):
+    """Scale image stack to unit range."""
+
+    def __init__(self, vmin: float, vmax: float, *, clip: bool = True) -> None:
+        """Scale image stack to unit range.
+
+        Parameters
+        ----------
+        vmin : float
+            Minimum value.
+        vmax : float
+            Maximum value.
+        clip : bool, default True
+            Clip values to [0, 1] to avoid numerical issues.
+        """
+
+        super().__init__()
+        self.vmin = vmin
+        self.vmax = vmax
+        self.diff = vmax - vmin
+        self.clip = clip
+        self.post = ImagesClip(0, 1) if self.clip else Identity()
+
+    def __call__(self, x: NDArrayf32) -> NDArrayf32:
+        return self.post((x - self.vmin) / self.diff)
+
+    def extra_repr(self) -> str:
+        return f"vmin={self.vmin}, vmax={self.vmax}, clip={self.clip}"
+
+
+class ImagesHistogramEqualization(Transform[NDArrayf32, NDArrayf32]):
+    """Image histogram equalization.
+
+    References
+    ----------
+    http://www.janeriksolem.net/histogram-equalization-with-python-and.html
+    """
+
+    def __init__(self, bins: int = 256) -> None:
+        super().__init__()
+        self.bins = bins
+
+    def __call__(self, x: NDArrayf32) -> NDArrayf32:
+        # get image histogram
+        hist, bin_edges = np.histogram(x.flatten(), self.bins, density=True)
+        cdf = hist.cumsum()  # cumulative distribution function
+        cdf = cdf / cdf[-1]  # normalize
+
+        # use linear interpolation of cdf to find new pixel values
+        equalized = np.interp(x.flatten(), bin_edges[:-1], cdf)
+        return equalized.reshape(x.shape).astype(np.float32)
+
+    def extra_repr(self) -> str:
+        return f"bins={self.bins}"

swcgeom/transforms/mst.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.
+
+
 """Minimum spanning tree."""
 
 import warnings

swcgeom/transforms/neurolucida_asc.py

@@ -1,12 +1,25 @@
+# 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.
+
+
 """Neurolucida related transformation."""
 
 import os
 import re
 from enum import Enum, auto
 from io import TextIOBase
-from typing import Any, List, NamedTuple, Optional, cast
-
-import numpy as np
+from typing import Any, NamedTuple, Optional, cast
 
 from swcgeom.core import Tree
 from swcgeom.core.swc_utils import SWCNames, SWCTypes, get_names, get_types
@@ -116,8 +129,8 @@ class ASTNode:
         self,
         type: ASTType,
         value: Any = None,
-        tokens: Optional[List["Token"]] = None,
-        children: Optional[List["ASTNode"]] = None,
+        tokens: Optional[list["Token"]] = None,
+        children: Optional[list["ASTNode"]] = None,
     ):
         self.type = type
         self.value = value
@@ -149,7 +162,7 @@ class ASTNode:
 
 
 class AST(ASTNode):
-    def __init__(self, children: Optional[List[ASTNode]] = None, source: str = ""):
+    def __init__(self, children: Optional[list[ASTNode]] = None, source: str = ""):
         super().__init__(ASTType.ROOT, children=children)
         self.source = source
 
@@ -423,7 +436,7 @@ class Lexer:
         return self
 
     def __next__(self) -> Token:
-        match (word := self._read_word()):
+        match word := self._read_word():
             case "":
                 raise StopIteration
 

swcgeom/transforms/path.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.
+
+
 """Transformation in path."""
 
 from swcgeom.core import Path, Tree, redirect_tree

swcgeom/transforms/population.py

@@ -1,6 +1,19 @@
-"""Transformation in population."""
+# 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.
+
 
-from typing import List
+"""Transformation in population."""
 
 from swcgeom.core import Population, Tree
 from swcgeom.transforms.base import Transform
@@ -16,7 +29,7 @@ class PopulationTransform(Transform[Population, Population]):
         self.transform = transform
 
     def __call__(self, population: Population) -> Population:
-        trees: List[Tree] = []
+        trees: list[Tree] = []
         for t in population:
             new_t = self.transform(t)
             if new_t.source == "":