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

swcgeom/utils/plotter_2d.py

@@ -15,8 +15,6 @@
 
 """2D Plotting utils."""
 
-from typing import Optional
-
 import matplotlib.pyplot as plt
 import numpy as np
 import numpy.typing as npt
@@ -43,18 +41,14 @@ def draw_lines(
 ) -> 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`.
+    Args:
+        ax: The plot 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 position.
+        **kwargs: Forwarded to `~matplotlib.collections.LineCollection`.
     """
-
     T = camera.MVP
     T = translate3d(*camera.position).dot(T)  # keep origin
 
@@ -113,8 +107,8 @@ def draw_circles(
     x: npt.NDArray,
     y: npt.NDArray,
     *,
-    y_min: Optional[float] = None,
-    y_max: Optional[float] = None,
+    y_min: float | None = None,
+    y_max: float | None = None,
     cmap: str | Colormap = "viridis",
 ) -> PatchCollection:
     """Draw a sequential of circles."""
@@ -140,7 +134,7 @@ def draw_circles(
 
 
 def get_fig_ax(
-    fig: Optional[Figure] = None, ax: Optional[Axes] = None
+    fig: Figure | None = None, ax: Axes | None = None
 ) -> tuple[Figure, Axes]:
     if fig is None and ax is not None:
         fig = ax.get_figure()

swcgeom/utils/plotter_3d.py

@@ -32,17 +32,15 @@ def draw_lines_3d(
 ):
     """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`.
+    Args:
+        ax: The plot 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: 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

@@ -48,21 +48,29 @@ class Camera:
     _look_at: Vec3f
     _up: Vec3f
 
-    # fmt: off
     @property
-    def position(self) -> Vec3f:    return self._position
+    def position(self) -> Vec3f:
+        return self._position
+
     @property
-    def look_at(self) -> Vec3f:     return self._look_at
+    def look_at(self) -> Vec3f:
+        return self._look_at
+
     @property
-    def up(self) -> Vec3f:          return self._up
+    def up(self) -> Vec3f:
+        return self._up
 
     @property
-    def MV(self) -> npt.NDArray[np.float32]:    raise NotImplementedError()
+    def MV(self) -> npt.NDArray[np.float32]:
+        raise NotImplementedError()
+
     @property
-    def P(self) -> npt.NDArray[np.float32]:     raise NotImplementedError()
+    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
+    def MVP(self) -> npt.NDArray[np.float32]:
+        return self.P.dot(self.MV)
 
 
 class SimpleCamera(Camera):

swcgeom/utils/sdf.py

@@ -17,10 +17,8 @@
 
 Refs: https://iquilezles.org/articles/distfunctions/
 
-Note
-----
-This module has been deprecated since v0.14.0, and will be removed in
-the future, use `sdflit` instead.
+NOTE: This module has been deprecated since v0.14.0, and will be removed in the future,
+use `sdflit` instead.
 """
 
 import warnings
@@ -60,15 +58,11 @@ class SDF(ABC):
     def distance(self, p: npt.NDArray[np.float32]) -> npt.NDArray[np.float32]:
         """Calculate signed distance.
 
-        Parmeters
-        ---------
-        p: ArrayLike
-            Hit point p of shape (N, 3).
+        Args:
+            p: Hit point p of shape (N, 3).
 
-        Returns
-        -------
-        distance : npt.NDArray[np.float32]
-            Distance array of shape (3,).
+        Returns:
+            distance: Distance array of shape (3,).
         """
         raise NotImplementedError()
 
@@ -84,11 +78,9 @@ class SDF(ABC):
     def is_in_bounding_box(self, p: npt.NDArray[np.float32]) -> npt.NDArray[np.bool_]:
         """Is p in bounding box.
 
-        Returns
-        -------
-        is_in : npt.NDArray[np.bool_]
-            Array of shape (N,), if bounding box is `None`, `True` will
-            be returned.
+        Returns:
+            is_in: Array of shape (N,).
+                If bounding box is `None`, `True` will be returned.
         """
 
         if self.bounding_box is None:
@@ -285,12 +277,9 @@ class SDFRoundCone(SDF):
     ) -> None:
         """SDF of round cone.
 
-        Parmeters
-        ---------
-        a, b : ArrayLike
-            Coordinates of point A/B of shape (3,).
-        ra, rb : float
-            Radius of point A/B.
+        Args:
+            a, b: Coordinates of point A/B of shape (3,).
+            ra, rb: Radius of point A/B.
         """
 
         self.a = np.array(a, dtype=np.float32)

swcgeom/utils/solid_geometry.py

@@ -28,6 +28,15 @@ __all__ = [
 
 
 def find_unit_vector_on_plane(normal_vec3: npt.NDArray) -> npt.NDArray:
+    """Find a random unit vector on the plane defined by the normal vector.
+
+    >>> normal = np.array([0, 0, 1])
+    >>> u = find_unit_vector_on_plane(normal)
+    >>> np.allclose(np.dot(u, normal), 0)  # Should be perpendicular
+    True
+    >>> np.allclose(np.linalg.norm(u), 1)  # Should be unit length
+    True
+    """
     r = np.random.rand(3)
     r /= np.linalg.norm(r)
     while np.allclose(r, normal_vec3) or np.allclose(r, -normal_vec3):
@@ -45,6 +54,21 @@ def find_sphere_line_intersection(
     line_point_a: npt.NDArray,
     line_point_b: npt.NDArray,
 ) -> list[tuple[float, npt.NDArray[np.float64]]]:
+    """Find intersection points between a sphere and a line.
+
+    >>> center = np.array([0, 0, 0])
+    >>> radius = 1.0
+    >>> p1 = np.array([-2, 0, 0])
+    >>> p2 = np.array([2, 0, 0])
+    >>> intersections = find_sphere_line_intersection(center, radius, p1, p2)
+    >>> len(intersections)
+    2
+    >>> np.allclose(intersections[0][1], [-1, 0, 0])
+    True
+    >>> np.allclose(intersections[1][1], [1, 0, 0])
+    True
+    """
+
     A = np.array(line_point_a)
     B = np.array(line_point_b)
     C = np.array(sphere_center)
@@ -74,8 +98,20 @@ def find_sphere_line_intersection(
 
 
 def project_point_on_line(
-    point_a: npt.ArrayLike, direction_vector: npt.ArrayLike, point_p: npt.ArrayLike
+    point_a: npt.ArrayLike,
+    direction_vector: npt.ArrayLike,
+    point_p: npt.ArrayLike,
 ) -> npt.NDArray:
+    """Project a point onto a line defined by a point and direction vector.
+
+    >>> a = np.array([0, 0, 0])
+    >>> d = np.array([1, 0, 0])
+    >>> p = np.array([1, 1, 0])
+    >>> projection = project_point_on_line(a, d, p)
+    >>> np.allclose(projection, [1, 0, 0])
+    True
+    """
+
     A = np.array(point_a)
     n = np.array(direction_vector)
     P = np.array(point_p)
@@ -86,6 +122,14 @@ def project_point_on_line(
 
 
 def project_vector_on_vector(vec: npt.ArrayLike, target: npt.ArrayLike) -> npt.NDArray:
+    """Project one vector onto another.
+
+    >>> v = np.array([1, 1, 0])
+    >>> t = np.array([1, 0, 0])
+    >>> proj = project_vector_on_vector(v, t)
+    >>> np.allclose(proj, [1, 0, 0])
+    True
+    """
     v = np.array(vec)
     n = np.array(target)
 
@@ -95,8 +139,20 @@ def project_vector_on_vector(vec: npt.ArrayLike, target: npt.ArrayLike) -> npt.N
 
 
 def project_vector_on_plane(
-    vec: npt.ArrayLike, plane_normal_vec: npt.ArrayLike
+    vec: npt.ArrayLike,
+    plane_normal_vec: npt.ArrayLike,
 ) -> npt.NDArray:
+    """Project a vector onto a plane defined by its normal vector.
+
+    >>> v = np.array([1, 1, 1])
+    >>> n = np.array([0, 0, 1])
+    >>> proj = project_vector_on_plane(v, n)
+    >>> np.allclose(proj, [1, 1, 0])  # Z component removed
+    True
+    >>> np.allclose(np.dot(proj, n), 0)  # Should be perpendicular to normal
+    True
+    """
+
     v = np.array(vec)
     n = np.array(plane_normal_vec)
 

swcgeom/utils/transforms.py

@@ -36,26 +36,56 @@ Vec3f = tuple[float, float, float]
 
 
 def angle(a: npt.ArrayLike, b: npt.ArrayLike) -> float:
-    """Get the angle of vectors.
+    """Get the signed angle between two vectors.
 
-    Returns
-    -------
-    angle : float
-        Angle in radians.
+    The angle is positive if the rotation from a to b is counter-clockwise, and
+    negative if clockwise.
+
+    >>> angle([1, 0, 0], [1, 0, 0])  # identical
+    0.0
+    >>> angle([1, 0, 0], [0, 1, 0])  # 90 degrees counter-clockwise
+    1.5707963267948966
+    >>> angle([1, 0, 0], [0, -1, 0])  # 90 degrees clockwise
+    -1.5707963267948966
+
+    Returns:
+        angle: Angle in radians between -π and π.
     """
-    a, b = np.array(a), np.array(b)
-    costheta = np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
-    theta = np.arccos(costheta)
-    return theta if np.cross(a, b) > 0 else -theta
 
+    a = np.asarray(a)
+    b = np.asarray(b)
 
-def scale3d(sx: float, sy: float, sz: float) -> npt.NDArray[np.float32]:
-    """Get the 3D scale transfomation matrix.
+    # Normalize vectors
+    a_norm = a / np.linalg.norm(a)
+    b_norm = b / np.linalg.norm(b)
+
+    # Calculate cosine of angle
+    cos_theta = np.dot(a_norm, b_norm)
+    cos_theta = np.clip(cos_theta, -1.0, 1.0)  # Ensure within valid range
+    theta = np.arccos(cos_theta)
+
+    # Determine sign using cross product
+    cross = np.cross(a_norm, b_norm)
+    sign = np.sign(cross[2])  # Use z-component for 3D
+    return float(sign * theta)
 
-    Returns
-    -------
-    T : np.NDArray
-        The homogeneous transfomation matrix, shape (4, 4).
+
+def scale3d(sx: float, sy: float, sz: float) -> npt.NDArray[np.float32]:
+    """Get the 3D scale transformation matrix.
+
+    >>> np.allclose(
+    ...     scale3d(2, 3, 4),
+    ...     [
+    ...         [2.0, 0.0, 0.0, 0.0],
+    ...         [0.0, 3.0, 0.0, 0.0],
+    ...         [0.0, 0.0, 4.0, 0.0],
+    ...         [0.0, 0.0, 0.0, 1.0],
+    ...     ],
+    ... )
+    True
+
+    Returns:
+        T: The homogeneous transformation matrix, shape (4, 4).
     """
     return np.array(
         [
@@ -69,12 +99,21 @@ def scale3d(sx: float, sy: float, sz: float) -> npt.NDArray[np.float32]:
 
 
 def translate3d(tx: float, ty: float, tz: float) -> npt.NDArray[np.float32]:
-    """Get the 3D translate transfomation matrix.
-
-    Returns
-    -------
-    T : np.NDArray
-        The homogeneous transfomation matrix, shape (4, 4).
+    """Get the 3D translate transformation matrix.
+
+    >>> np.allclose(
+    ...     translate3d(1, 2, 3),
+    ...     [
+    ...         [1.0, 0.0, 0.0, 1.0],
+    ...         [0.0, 1.0, 0.0, 2.0],
+    ...         [0.0, 0.0, 1.0, 3.0],
+    ...         [0.0, 0.0, 0.0, 1.0],
+    ...     ],
+    ... )
+    True
+
+    Returns:
+        T: The homogeneous transformation matrix, shape (4, 4).
     """
     return np.array(
         [
@@ -88,10 +127,10 @@ def translate3d(tx: float, ty: float, tz: float) -> npt.NDArray[np.float32]:
 
 
 def rotate3d(n: npt.ArrayLike, theta: float) -> npt.NDArray[np.float32]:
-    r"""Get the 3D rotation transfomation matrix.
+    r"""Get the 3D rotation transformation matrix.
 
-    Rotate v with axis n by an angle theta according to the right hand rule,
-    follow rodrigues' rotaion formula.
+    Rotate v with axis n by an angle theta according to the right hand rule, follow 
+    rodrigues' rotation formula.
 
     .. math::
 
@@ -105,17 +144,12 @@ def rotate3d(n: npt.ArrayLike, theta: float) -> npt.NDArray[np.float32]:
         -n_y & n_x & 0
         \end{pmatrix}
 
-    Parameters
-    ----------
-    n : ArrayLike
-        Rotation axis.
-    theta : float
-        Rotation angle in radians.
-
-    Returns
-    -------
-    T : np.NDArray
-        The homogeneous transfomation matrix, shape (4, 4).
+    Args: 
+        n: Rotation axis.
+        theta: Rotation angle in radians.
+
+    Returns:
+        T: The homogeneous transformation matrix, shape (4, 4).
     """
 
     n = np.array(n)
@@ -138,20 +172,28 @@ def rotate3d(n: npt.ArrayLike, theta: float) -> npt.NDArray[np.float32]:
 
 
 def rotate3d_x(theta: float) -> npt.NDArray[np.float32]:
-    """Get the 3D rotation transfomation matrix.
+    """Get the 3D rotation transformation matrix.
 
     Rotate 3D vector `v` with `x`-axis by an angle theta according to the right
     hand rule.
 
-    Parameters
-    ----------
-    theta : float
-        Rotation angle in radians.
-
-    Returns
-    -------
-    T : np.NDArray
-        The homogeneous transfomation matrix, shape (4, 4).
+    >>> np.allclose(
+    ...     rotate3d_x(np.pi / 2),  # 90 degree rotation
+    ...     [
+    ...         [+1.0, +0.0, +0.0, +0.0],
+    ...         [+0.0, +0.0, -1.0, +0.0],
+    ...         [+0.0, +1.0, +0.0, +0.0],
+    ...         [+0.0, +0.0, +0.0, +1.0],
+    ...     ],
+    ... )
+    True
+
+    Args:
+        theta: float
+            Rotation angle in radians.
+
+    Returns:
+        T: The homogeneous transformation matrix, shape (4, 4).
     """
 
     return np.array(
@@ -166,20 +208,27 @@ def rotate3d_x(theta: float) -> npt.NDArray[np.float32]:
 
 
 def rotate3d_y(theta: float) -> npt.NDArray[np.float32]:
-    """Get the 3D rotation transfomation matrix.
+    """Get the 3D rotation transformation matrix.
 
     Rotate 3D vector `v` with `y`-axis by an angle theta according to the right
     hand rule.
 
-    Parameters
-    ----------
-    theta : float
-        Rotation angle in radians.
-
-    Returns
-    -------
-    T : np.NDArray
-        The homogeneous transfomation matrix, shape (4, 4).
+    >>> np.allclose(
+    ...     rotate3d_y(np.pi / 2),  # 90 degree rotation
+    ...     [
+    ...         [+0.0, +0.0, +1.0, +0.0],
+    ...         [+0.0, +1.0, +0.0, +0.0],
+    ...         [-1.0, +0.0, +0.0, +0.0],
+    ...         [+0.0, +0.0, +0.0, +1.0],
+    ...     ],
+    ... )
+    True
+
+    Args:
+        theta: Rotation angle in radians.
+
+    Returns:
+        T: The homogeneous transformation matrix, shape (4, 4).
     """
     return np.array(
         [
@@ -193,20 +242,29 @@ def rotate3d_y(theta: float) -> npt.NDArray[np.float32]:
 
 
 def rotate3d_z(theta: float) -> npt.NDArray[np.float32]:
-    """Get the 3D rotation transfomation matrix.
-
-    Rotate 3D vector `v` with `z`-axis by an angle theta according to the right
-    hand rule.
-
-    Parameters
-    ----------
-    theta : float
-        Rotation angle in radians.
-
-    Returns
-    -------
-    T : np.NDArray
-        The homogeneous transfomation matrix, shape (4, 4).
+    """Get the 3D rotation transformation matrix.
+
+    Rotate 3D vector `v` with `z`-axis by an angle theta according to the right hand
+    rule.
+
+    >>> np.allclose(
+    ...     rotate3d_z(np.pi / 2),  # 90 degree rotation
+    ...     [
+    ...         [+0.0, -1.0, +0.0, +0.0],
+    ...         [+1.0, +0.0, +0.0, +0.0],
+    ...         [+0.0, +0.0, +1.0, +0.0],
+    ...         [+0.0, +0.0, +0.0, +1.0],
+    ...     ],
+    ... )
+    True
+
+    Args:
+        theta: float
+            Rotation angle in radians.
+
+    Returns:
+        T: np.NDArray
+            The homogeneous transformation matrix, shape (4, 4).
     """
     return np.array(
         [
@@ -222,17 +280,20 @@ def rotate3d_z(theta: float) -> npt.NDArray[np.float32]:
 def to_homogeneous(xyz: npt.ArrayLike, w: float) -> npt.NDArray[np.float32]:
     """Fill xyz to homogeneous coordinates.
 
-    Parameters
-    ----------
-    xyz : ArrayLike
-        Coordinate of shape (..., 3)
-    w : float
-        w of homogeneous coordinate, 1 for dot, 0 for vector.
-
-    Returns
-    -------
-    xyz4 : npt.NDArray[np.float32]
-        Array of shape (..., 4)
+    >>> np.allclose(to_homogeneous([1, 2, 3], 1), [1.0, 2.0, 3.0, 1.0])
+    True
+    >>> np.allclose(
+    ...     to_homogeneous([[1, 2, 3], [4, 5, 6]], 0),
+    ...     [[1.0, 2.0, 3.0, 0.0], [4.0, 5.0, 6.0, 0.0]],
+    ... )
+    True
+
+    Args:
+        xyz: Coordinate of shape (..., 3)
+        w: w of homogeneous coordinate, 1 for dot, 0 for vector.
+
+    Returns:
+        xyz4: Array of shape (..., 4)
     """
     xyz = np.array(xyz)
     if xyz.ndim == 1:
@@ -247,17 +308,12 @@ def to_homogeneous(xyz: npt.ArrayLike, w: float) -> npt.NDArray[np.float32]:
 def _to_homogeneous(xyz: npt.NDArray, w: float) -> npt.NDArray[np.float32]:
     """Fill xyz to homogeneous coordinates.
 
-    Parameters
-    ----------
-    xyz : npt.NDArray
-        Coordinate of shape (N, 3)
-    w : float
-        w of homogeneous coordinate, 1 for dot, 0 for vector.
-
-    Returns
-    -------
-    xyz4 : npt.NDArray[np.float32]
-        Array of shape (N, 4)
+    Args:
+        xyz: Coordinate of shape (N, 3)
+        w: w of homogeneous coordinate, 1 for dot, 0 for vector.
+
+    Returns:
+        xyz4: Array of shape (N, 4)
     """
     if xyz.shape[1] == 4:
         return xyz
@@ -273,14 +329,10 @@ def model_view_transformation(
 ) -> npt.NDArray[np.float32]:
     r"""Play model/view transformation.
 
-    Parameters
-    ----------
-    position: Tuple[float, float, float]
-        Camera position \vec{e}.
-    look_at: Tuple[float, float, float]
-        Camera look-at \vec{g}.
-    up: Tuple[float, float, float]
-        Camera up direction \vec{t}.
+    Args:
+        position: Camera position \vec{e}.
+        look_at: Camera look-at \vec{g}.
+        up: Camera up direction \vec{t}.
     """
 
     e = np.array(position, dtype=np.float32)
@@ -301,7 +353,19 @@ def model_view_transformation(
 
 
 def orthographic_projection_simple() -> npt.NDArray[np.float32]:
-    """Simple orthographic projection by drop z-axis"""
+    """Simple orthographic projection by drop z-axis
+
+    >>> np.allclose(
+    ...     orthographic_projection_simple(),
+    ...     [
+    ...         [1.0, 0.0, 0.0, 0.0],
+    ...         [0.0, 1.0, 0.0, 0.0],
+    ...         [0.0, 0.0, 0.0, 0.0],
+    ...         [0.0, 0.0, 0.0, 0.0],
+    ...     ],
+    ... )
+    True
+    """
     return np.array(
         [
             [1, 0, 0, 0],