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

swcgeom/utils/numpy_helper.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.
+
+
 """Numpy related utils."""
 
 from contextlib import contextmanager
@@ -11,7 +26,7 @@ __all__ = ["padding1d", "numpy_err"]
 
 def padding1d(
     n: int,
-    v: npt.NDArray | None,
+    v: npt.ArrayLike | None,
     padding_value: Any = 0,
     dtype: npt.DTypeLike | None = None,
 ) -> npt.NDArray:
@@ -31,9 +46,19 @@ def padding1d(
         x will used, otherwise defaults to `~numpy.float32`.
     """
 
-    dtype = dtype or (v is not None and v.dtype) or np.float32
-    v = np.zeros(n, dtype=dtype) if v is None else v
-    v = v.astype(dtype) if v.dtype != dtype else v
+    if not isinstance(v, np.ndarray):
+        dtype = dtype or np.float32
+        if v is not None:
+            v = np.array(v, dtype=dtype)
+        else:
+            v = np.zeros(n, dtype=dtype)
+
+    if dtype is None:
+        dtype = v.dtype
+
+    if v.dtype != dtype:
+        v = v.astype(dtype)
+
     assert v.ndim == 1
 
     if v.shape[0] >= n:

swcgeom/utils/plotter_2d.py

@@ -0,0 +1,151 @@
+# 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.
+
+
+"""2D Plotting utils."""
+
+from typing import Optional
+
+import matplotlib.pyplot as plt
+import numpy as np
+import numpy.typing as npt
+from matplotlib import cm
+from matplotlib.axes import Axes
+from matplotlib.collections import LineCollection, PatchCollection
+from matplotlib.colors import Colormap, Normalize
+from matplotlib.figure import Figure
+from matplotlib.patches import Circle
+
+from swcgeom.utils.renderer import Camera
+from swcgeom.utils.transforms import to_homogeneous, translate3d
+
+__all__ = ["draw_lines", "draw_direction_indicator", "draw_circles", "get_fig_ax"]
+
+
+def draw_lines(
+    ax: Axes,
+    lines: npt.NDArray[np.floating],
+    camera: Camera,
+    joinstyle="round",
+    capstyle="round",
+    **kwargs,
+) -> LineCollection:
+    """Draw lines.
+
+    Parameters
+    ----------
+    ax : ~matplotlib.axes.Axes
+    lines : A collection of coords of lines
+        Excepting a ndarray of shape (N, 2, 3), the axis-2 holds two points,
+        and the axis-3 holds the coordinates (x, y, z).
+    camera : Camera
+        Camera position.
+    **kwargs : dict[str, Unknown]
+        Forwarded to `~matplotlib.collections.LineCollection`.
+    """
+
+    T = camera.MVP
+    T = translate3d(*camera.position).dot(T)  # keep origin
+
+    starts, ends = lines[:, 0], lines[:, 1]
+    starts, ends = to_homogeneous(starts, 1), to_homogeneous(ends, 1)
+    starts, ends = np.dot(T, starts.T).T[:, 0:2], np.dot(T, ends.T).T[:, 0:2]
+
+    edges = np.stack([starts, ends], axis=1)
+    collection = LineCollection(edges, joinstyle=joinstyle, capstyle=capstyle, **kwargs)  # type: ignore
+    return ax.add_collection(collection)  # type: ignore
+
+
+def draw_direction_indicator(
+    ax: Axes, camera: Camera, loc: tuple[float, float]
+) -> None:
+    x, y = loc
+    direction = camera.MV.dot(
+        [
+            [1, 0, 0, 1],
+            [0, 1, 0, 1],
+            [0, 0, 1, 1],
+            [0, 0, 0, 1],
+        ]
+    )
+
+    arrow_length, text_offset = 0.05, 0.05  # TODO: may still overlap
+    text_colors = [["x", "red"], ["y", "green"], ["z", "blue"]]
+    for (dx, dy, dz, _), (text, color) in zip(direction, text_colors):
+        if 1 - abs(dz) < 1e-5:
+            continue
+
+        ax.arrow(
+            x,
+            y,
+            arrow_length * dx,
+            arrow_length * dy,
+            head_length=0.02,
+            head_width=0.01,
+            color=color,
+            transform=ax.transAxes,
+        )
+
+        ax.text(
+            x + (arrow_length + text_offset) * dx,
+            y + (arrow_length + text_offset) * dy,
+            text,
+            color=color,
+            transform=ax.transAxes,
+            horizontalalignment="center",
+            verticalalignment="center",
+        )
+
+
+def draw_circles(
+    ax: Axes,
+    x: npt.NDArray,
+    y: npt.NDArray,
+    *,
+    y_min: Optional[float] = None,
+    y_max: Optional[float] = None,
+    cmap: str | Colormap = "viridis",
+) -> PatchCollection:
+    """Draw a sequential of circles."""
+
+    y_min = y.min() if y_min is None else y_min
+    y_max = y.max() if y_max is None else y_max
+    norm = Normalize(y_min, y_max)
+
+    color_map = cmap if isinstance(cmap, Colormap) else cm.get_cmap(name=cmap)
+    colors = color_map(norm(y))
+
+    circles = [
+        Circle((0, 0), xi, color=color) for xi, color in reversed(list(zip(x, colors)))
+    ]
+    patches = PatchCollection(circles, match_original=True)
+    patches.set_cmap(color_map)
+    patches.set_norm(norm)
+    patches: PatchCollection = ax.add_collection(patches)  # type: ignore
+
+    ax.set_aspect(1)
+    ax.autoscale()
+    return patches
+
+
+def get_fig_ax(
+    fig: Optional[Figure] = None, ax: Optional[Axes] = None
+) -> tuple[Figure, Axes]:
+    if fig is None and ax is not None:
+        fig = ax.get_figure()
+        assert fig is not None, "expecting a figure from the axes"
+
+    fig = fig or plt.gcf()
+    ax = ax or plt.gca()
+    return fig, ax

swcgeom/utils/plotter_3d.py

@@ -0,0 +1,48 @@
+# 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.
+
+
+"""3D Plotting utils."""
+
+import numpy as np
+import numpy.typing as npt
+from mpl_toolkits.mplot3d import Axes3D
+from mpl_toolkits.mplot3d.art3d import Line3DCollection
+
+__all__ = ["draw_lines_3d"]
+
+
+def draw_lines_3d(
+    ax: Axes3D,
+    lines: npt.NDArray[np.floating],
+    joinstyle="round",
+    capstyle="round",
+    **kwargs,
+):
+    """Draw lines.
+
+    Parameters
+    ----------
+    ax : ~matplotlib.axes.Axes
+    lines : A collection of coords of lines
+        Excepting a ndarray of shape (N, 2, 3), the axis-2 holds two points,
+        and the axis-3 holds the coordinates (x, y, z).
+    **kwargs : dict[str, Unknown]
+        Forwarded to `~mpl_toolkits.mplot3d.art3d.Line3DCollection`.
+    """
+
+    line_collection = Line3DCollection(
+        lines, joinstyle=joinstyle, capstyle=capstyle, **kwargs
+    )  # type: ignore
+    return ax.add_collection3d(line_collection)

swcgeom/utils/renderer.py

@@ -1,40 +1,38 @@
+# 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.
+
+
 """Rendering related utils."""
 
 from functools import cached_property
-from typing import Dict, Literal, Optional, Tuple, cast
+from typing import Literal, cast
 
-import matplotlib.pyplot as plt
 import numpy as np
 import numpy.typing as npt
-from matplotlib import cm
-from matplotlib.axes import Axes
-from matplotlib.collections import LineCollection, PatchCollection
-from matplotlib.colors import Colormap, Normalize
-from matplotlib.figure import Figure
-from matplotlib.patches import Circle
 from typing_extensions import Self
 
 from swcgeom.utils.transforms import (
     Vec3f,
     model_view_transformation,
     orthographic_projection_simple,
-    to_homogeneous,
-    translate3d,
 )
 
-__all__ = [
-    "CameraOptions",
-    "SimpleCamera",
-    "palette",
-    "draw_lines",
-    "draw_direction_indicator",
-    "draw_circles",
-    "get_fig_ax",
-]
-
-CameraOption = Vec3f | Tuple[Vec3f, Vec3f] | Tuple[Vec3f, Vec3f, Vec3f]
+__all__ = ["CameraOptions", "Camera", "SimpleCamera", "palette"]
+
+CameraOption = Vec3f | tuple[Vec3f, Vec3f] | tuple[Vec3f, Vec3f, Vec3f]
 CameraPreset = Literal["xy", "yz", "zx", "yx", "zy", "xz"]
-CameraPresets: Dict[CameraPreset, Tuple[Vec3f, Vec3f, Vec3f]] = {
+CameraPresets: dict[CameraPreset, tuple[Vec3f, Vec3f, Vec3f]] = {
     "xy": ((0.0, 0.0, 0.0), (+0.0, +0.0, -1.0), (+0.0, +1.0, +0.0)),
     "yz": ((0.0, 0.0, 0.0), (-1.0, +0.0, +0.0), (+0.0, +0.0, +1.0)),
     "zx": ((0.0, 0.0, 0.0), (+0.0, -1.0, +0.0), (+1.0, +0.0, +0.0)),
@@ -45,13 +43,35 @@ CameraPresets: Dict[CameraPreset, Tuple[Vec3f, Vec3f, Vec3f]] = {
 CameraOptions = CameraOption | CameraPreset
 
 
-class SimpleCamera:
+class Camera:
+    _position: Vec3f
+    _look_at: Vec3f
+    _up: Vec3f
+
+    # fmt: off
+    @property
+    def position(self) -> Vec3f:    return self._position
+    @property
+    def look_at(self) -> Vec3f:     return self._look_at
+    @property
+    def up(self) -> Vec3f:          return self._up
+
+    @property
+    def MV(self) -> npt.NDArray[np.float32]:    raise NotImplementedError()
+    @property
+    def P(self) -> npt.NDArray[np.float32]:     raise NotImplementedError()
+    @property
+    def MVP(self) -> npt.NDArray[np.float32]:   return self.P.dot(self.MV)
+    # fmt: on
+
+
+class SimpleCamera(Camera):
     """Simplest camera."""
 
     def __init__(self, position: Vec3f, look_at: Vec3f, up: Vec3f):
-        self.position = position
-        self.look_at = look_at
-        self.up = up
+        self._position = position
+        self._look_at = look_at
+        self._up = up
 
     @cached_property
     def MV(self) -> npt.NDArray[np.float32]:  # pylint: disable=invalid-name
@@ -61,10 +81,6 @@ class SimpleCamera:
     def P(self) -> npt.NDArray[np.float32]:  # pylint: disable=invalid-name
         return orthographic_projection_simple()
 
-    @cached_property
-    def MVP(self) -> npt.NDArray[np.float32]:  # pylint: disable=invalid-name
-        return self.P.dot(self.MV)
-
     @classmethod
     def from_options(cls, camera: CameraOptions) -> Self:
         if isinstance(camera, str):
@@ -76,7 +92,7 @@ class SimpleCamera:
         if isinstance(camera[0], tuple):
             return cls((0, 0, 0), cast(Vec3f, camera), (0, 1, 0))
 
-        return cls(*cast(Tuple[Vec3f, Vec3f, Vec3f], camera))
+        return cls(*cast(tuple[Vec3f, Vec3f, Vec3f], camera))
 
 
 class Palette:
@@ -84,8 +100,8 @@ class Palette:
 
     # pylint: disable=too-few-public-methods
 
-    default: Dict[int, str]
-    vaa3d: Dict[int, str]
+    default: dict[int, str]
+    vaa3d: dict[int, str]
 
     def __init__(self):
         default = [
@@ -130,115 +146,3 @@ class Palette:
 
 
 palette = Palette()
-
-
-def draw_lines(
-    ax: Axes, lines: npt.NDArray[np.floating], camera: SimpleCamera, **kwargs
-) -> LineCollection:
-    """Draw lines.
-
-    Parameters
-    ----------
-    ax : ~matplotlib.axes.Axes
-    lines : A collection of coords of lines
-        Excepting a ndarray of shape (N, 2, 3), the axis-2 holds two points,
-        and the axis-3 holds the coordinates (x, y, z).
-    camera : Camera
-        Camera position.
-    **kwargs : dict[str, Unknown]
-        Forwarded to `~matplotlib.collections.LineCollection`.
-    """
-
-    T = camera.MVP
-    T = translate3d(*camera.position).dot(T)  # keep origin
-
-    starts, ends = lines[:, 0], lines[:, 1]
-    starts, ends = to_homogeneous(starts, 1), to_homogeneous(ends, 1)
-    starts, ends = np.dot(T, starts.T).T[:, 0:2], np.dot(T, ends.T).T[:, 0:2]
-
-    edges = np.stack([starts, ends], axis=1)
-    return ax.add_collection(LineCollection(edges, **kwargs))  # type: ignore
-
-
-def draw_direction_indicator(
-    ax: Axes, camera: SimpleCamera, loc: Tuple[float, float]
-) -> None:
-    x, y = loc
-    direction = camera.MV.dot(
-        [
-            [1, 0, 0, 1],
-            [0, 1, 0, 1],
-            [0, 0, 1, 1],
-            [0, 0, 0, 1],
-        ]
-    )
-
-    arrow_length, text_offset = 0.05, 0.05  # TODO: may still overlap
-    text_colors = [["x", "red"], ["y", "green"], ["z", "blue"]]
-    for (dx, dy, dz, _), (text, color) in zip(direction, text_colors):
-        if 1 - abs(dz) < 1e-5:
-            continue
-
-        ax.arrow(
-            x,
-            y,
-            arrow_length * dx,
-            arrow_length * dy,
-            head_length=0.02,
-            head_width=0.01,
-            color=color,
-            transform=ax.transAxes,
-        )
-
-        ax.text(
-            x + (arrow_length + text_offset) * dx,
-            y + (arrow_length + text_offset) * dy,
-            text,
-            color=color,
-            transform=ax.transAxes,
-            horizontalalignment="center",
-            verticalalignment="center",
-        )
-
-
-def draw_circles(
-    ax: Axes,
-    x: npt.NDArray,
-    y: npt.NDArray,
-    *,
-    y_min: Optional[float] = None,
-    y_max: Optional[float] = None,
-    cmap: str | Colormap = "viridis",
-) -> PatchCollection:
-    """Draw a sequential of circles."""
-
-    y_min = y.min() if y_min is None else y_min
-    y_max = y.max() if y_max is None else y_max
-    norm = Normalize(y_min, y_max)
-
-    color_map = cmap if isinstance(cmap, Colormap) else cm.get_cmap(name=cmap)
-    colors = color_map(norm(y))
-
-    circles = [
-        Circle((0, 0), xi, color=color) for xi, color in reversed(list(zip(x, colors)))
-    ]
-    patches = PatchCollection(circles, match_original=True)
-    patches.set_cmap(color_map)
-    patches.set_norm(norm)
-    patches: PatchCollection = ax.add_collection(patches)  # type: ignore
-
-    ax.set_aspect(1)
-    ax.autoscale()
-    return patches
-
-
-def get_fig_ax(
-    fig: Figure | None = None, ax: Axes | None = None
-) -> Tuple[Figure, Axes]:
-    if fig is None:
-        fig = plt.gcf() if ax is None else ax.get_figure()
-
-    if ax is None:
-        ax = fig.gca()
-
-    return fig, ax

swcgeom/utils/sdf.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.
+
+
 """Signed distance functions.
 
 Refs: https://iquilezles.org/articles/distfunctions/
@@ -10,10 +25,11 @@ the future, use `sdflit` instead.
 
 import warnings
 from abc import ABC, abstractmethod
-from typing import Iterable, Tuple
+from collections.abc import Iterable
 
 import numpy as np
 import numpy.typing as npt
+from typing_extensions import deprecated
 
 from swcgeom.utils.solid_geometry import project_vector_on_plane
 
@@ -29,7 +45,7 @@ __all__ = [
 ]
 
 # Axis-aligned bounding box, tuple of array of shape (3,)
-AABB = Tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]
+AABB = tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]
 
 
 class SDF(ABC):
@@ -173,15 +189,15 @@ class SDFDifference(SDF):
         return flags
 
 
+@deprecated("Use `SDFUnion` instead")
 class SDFCompose(SDFUnion):
-    """Compose multiple SDFs."""
+    """Compose multiple SDFs.
+
+    .. deprecated:: 0.14.0
+        Use :cls:`SDFUnion` instead.
+    """
 
     def __init__(self, sdfs: Iterable[SDF]) -> None:
-        warnings.warn(
-            "`SDFCompose` has been replace by `SDFUnion` since v0.14.0, "
-            "and will be removed in next version",
-            DeprecationWarning,
-        )
         sdfs = list(sdfs)
         if len(sdfs) == 1:
             warnings.warn("compose only one SDF, use SDFCompose.compose instead")

swcgeom/utils/solid_geometry.py

@@ -1,6 +1,19 @@
-"""Solid Geometry."""
+# 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, Tuple
+"""Solid Geometry."""
 
 import numpy as np
 import numpy.typing as npt
@@ -31,7 +44,7 @@ def find_sphere_line_intersection(
     sphere_radius: float,
     line_point_a: npt.NDArray,
     line_point_b: npt.NDArray,
-) -> List[Tuple[float, npt.NDArray[np.float64]]]:
+) -> list[tuple[float, npt.NDArray[np.float64]]]:
     A = np.array(line_point_a)
     B = np.array(line_point_b)
     C = np.array(sphere_center)

swcgeom/utils/transforms.py

@@ -1,6 +1,19 @@
-"""3D geometry transformations."""
+# 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 Tuple
+"""3D geometry transformations."""
 
 import numpy as np
 import numpy.typing as npt
@@ -19,11 +32,11 @@ __all__ = [
     "orthographic_projection_simple",
 ]
 
-Vec3f = Tuple[float, float, float]
+Vec3f = tuple[float, float, float]
 
 
 def angle(a: npt.ArrayLike, b: npt.ArrayLike) -> float:
-    """Get the agnle of vectors.
+    """Get the angle of vectors.
 
     Returns
     -------