swcgeom 0.19.4__cp312-cp312-macosx_14_0_arm64.whl

swcgeom/utils/ellipse.py

@@ -0,0 +1,131 @@
+# SPDX-FileCopyrightText: 2022 - 2025 Zexin Yuan <pypi@yzx9.xyz>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Finds the Minimum Volume Enclosing Ellipsoid."""
+
+# pylint: disable=invalid-name
+
+from functools import cached_property
+
+import numpy as np
+import numpy.linalg as la
+import numpy.typing as npt
+
+__all__ = ["mvee"]
+
+
+class Ellipse:
+    """Ellipse wrapper."""
+
+    def __init__(
+        self, A: npt.NDArray[np.float64], centroid: npt.NDArray[np.float64]
+    ) -> None:
+        self.A = A
+        self.centroid = centroid
+
+    @property
+    def radii(self) -> tuple[float, float]:
+        # x, y radii.
+        _U, D, _V = self.svd
+        rx, ry = 1.0 / np.sqrt(D)
+        return rx, ry
+
+    @property
+    def a(self) -> float:
+        a, _b = self.axes
+        return a
+
+    @property
+    def b(self) -> float:
+        _a, b = self.axes
+        return b
+
+    @property
+    def axes(self) -> tuple[float, float]:
+        # Major and minor semi-axis of the ellipse.
+        rx, ry = self.radii
+        dx, dy = 2 * rx, 2 * ry
+        a, b = max(dx, dy), min(dx, dy)
+        return a, b
+
+    @property
+    def eccentricity(self) -> float:
+        a, b = self.axes
+        e = np.sqrt(a**2 - b**2) / a
+        return e
+
+    @property
+    def alpha(self) -> float:
+        # Orientation angle (with respect to the x axis counterclockwise).
+        _U, _D, V = self.svd
+        arcsin = -1.0 * np.rad2deg(np.arcsin(V[0][0]))
+        arccos = np.rad2deg(np.arccos(V[0][1]))
+        alpha = arccos if arcsin > 0.0 else -1.0 * arccos
+        return alpha
+
+    @cached_property
+    def svd(self):
+        # V is the rotation matrix that gives the orientation of the ellipsoid.
+        # https://en.wikipedia.org/wiki/Rotation_matrix
+        # http://mathworld.wolfram.com/RotationMatrix.html
+        U, D, V = la.svd(self.A)
+        return U, D, V
+
+
+def mvee(points: npt.NDArray[np.floating], tol: float = 1e-3) -> Ellipse:
+    """Finds the Minimum Volume Enclosing Ellipsoid.
+
+    >>> # Create a set of 2D points
+    >>> points = np.array([[0, 0], [1, 0], [0, 1], [1, 1]], dtype=np.float64)
+    >>> ellipse = mvee(points)
+
+    >>> # Check centroid is at center of points
+    >>> np.allclose(ellipse.centroid, [0.5, 0.5])
+    True
+
+    >>> # Check ellipse properties
+    >>> rx, ry = ellipse.radii
+    >>> np.allclose([rx, ry], [np.sqrt(2) / 2, np.sqrt(2) / 2], rtol=1e-5)
+    True
+
+    Reference:
+    1. http://stackoverflow.com/questions/14016898/port-matlab-bounding-ellipsoid-code-to-python
+    2. http://stackoverflow.com/questions/1768197/bounding-ellipse/1768440#1768440
+    3. https://minillinim.github.io/GroopM/dev_docs/groopm.ellipsoid-pysrc.html
+
+    Args:
+        points: Array of shape (N, d) where N is number of points and d is dimension
+        tol: Tolerance for convergence
+
+    Returns:
+        Ellipse: An Ellipse object containing the minimum volume enclosing ellipse
+    """
+
+    A, centroid = _mvee(points, tol=tol)
+    return Ellipse(A, centroid)
+
+
+def _mvee(
+    points: npt.NDArray[np.floating], tol: float = 1e-3
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    N, d = points.shape
+    Q = np.column_stack((points, np.ones(N))).T
+    err = tol + 1.0
+    u = np.ones(N) / N
+    while err > tol:
+        # assert u.sum() == 1 # invariant
+        X = np.dot(np.dot(Q, np.diag(u)), Q.T)
+        M = np.diag(np.dot(np.dot(Q.T, la.inv(X)), Q))
+        jdx = np.argmax(M)
+        step_size = (M[jdx] - d - 1.0) / ((d + 1) * (M[jdx] - 1.0))
+        new_u = (1 - step_size) * u
+        new_u[jdx] += step_size
+        err = la.norm(new_u - u)
+        u = new_u
+    c = np.dot(u, points)
+    A = (
+        la.inv(np.dot(np.dot(points.T, np.diag(u)), points) - np.multiply.outer(c, c))
+        / d
+    )
+    return A, c

swcgeom/utils/file.py

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: 2022 - 2025 Zexin Yuan <pypi@yzx9.xyz>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""File related utils.
+
+NOTE: If character coding is enabled, all denpendencies need to be installed, try:
+
+```sh
+pip install swcgeom[all]
+```
+"""
+
+import warnings
+from io import BytesIO, TextIOBase, TextIOWrapper
+from typing import Literal
+
+__all__ = ["FileReader", "PathOrIO"]
+
+PathOrIO = int | str | bytes | BytesIO | TextIOBase
+
+
+class FileReader:
+    def __init__(
+        self,
+        fname: PathOrIO,
+        *,
+        encoding: Literal["detect"] | str = "utf-8",
+        low_confidence: float = 0.9,
+        **kwargs,
+    ) -> None:
+        """Read file.
+
+        Args:
+            fname: PathOrIO
+            encoding: The name of the encoding used to decode the file.
+                If is `detect`, we will try to detect the character encoding.
+            low_confidence: The confidence threshold for character encoding detection.
+                Used for detect character endocing, raising warning when parsing with
+                low confidence.
+        """
+        # TODO: support StringIO
+        self.fname, self.fb, self.f = "", None, None
+        if isinstance(fname, TextIOBase):
+            self.f = fname
+            encoding = fname.encoding  # skip detect
+        elif isinstance(fname, BytesIO):
+            self.fb = fname
+        else:
+            self.fname = fname
+
+        if encoding == "detect":
+            encoding = detect_encoding(fname, low_confidence=low_confidence)
+        self.encoding = encoding
+        self.kwargs = kwargs
+
+    def __enter__(self) -> TextIOBase:
+        if isinstance(self.fb, BytesIO):
+            self.f = TextIOWrapper(self.fb, encoding=self.encoding)
+        elif self.f is None:
+            self.f = open(self.fname, "r", encoding=self.encoding, **self.kwargs)
+
+        return self.f
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        if self.f:
+            self.f.close()
+        return True
+
+
+def detect_encoding(fname: PathOrIO, *, low_confidence: float = 0.9) -> str:
+    import chardet
+
+    if isinstance(fname, TextIOBase):
+        return fname.encoding
+    elif isinstance(fname, BytesIO):
+        data = fname.read()
+        fname.seek(0, 0)
+    else:
+        with open(fname, "rb") as f:
+            data = f.read()
+
+    result = chardet.detect(data)
+    encoding = result["encoding"] or "utf-8"
+    if result["confidence"] < low_confidence:
+        warnings.warn(
+            f"parse as `{encoding}` with low confidence "
+            f"{result['confidence']} in `{fname}`"
+        )
+    return encoding