type annotations fixes

Author: gabe-rbo

CITATION.cff

@@ -5,7 +5,7 @@ authors:
     given-names: "Gabriel"
     email: "gabriel.ribeiro@dcc.ufmg.br"
 title: "pySurgery: Computational Surgery Theory in Python"
-version: 2.2.1
+version: 2.2.2
 date-released: 01-05-2026
 url: "https://github.com/gabe-rbo/pysurgery"
 repository-code: "https://github.com/gabe-rbo/pysurgery"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pysurgery"
-version = "2.2.1"
+version = "2.2.2"
 description = "A high-performance Python library for Computational Surgery Theory."
 dependencies = [
     "numpy>=2.4.4",
@@ -83,7 +83,7 @@ python_files = ["test_*.py"]
 "*" = ["*.jl", "*.yaml", "*.json"]
 
 [tool.bumpversion]
-current_version = "2.2.1"
+current_version = "2.2.2"
 commit = true
 tag = true
 

pysurgery/__init__.py

@@ -316,7 +316,7 @@
 
 from . import integrations
 
-__version__ = "2.2.1"
+__version__ = "2.2.2"
 
 def __getattr__(name):
     if name == "JuliaBridge":

pysurgery/bridge/surgery_backend.jl

@@ -3498,11 +3498,11 @@ Returns (R, B_aligned, disparity).
 function orthogonal_procrustes(A::AbstractMatrix{Float64}, B::AbstractMatrix{Float64})
     M = transpose(B) * A
     F = svd(M)
-    R = F.U * transpose(F.Vt)
+    R = F.U * F.Vt
     if det(R) < 0
         U = copy(F.U)
         U[:, end] .*= -1
-        R = U * transpose(F.Vt)
+        R = U * F.Vt
     end
     B_aligned = B * R
     disparity = norm(A - B_aligned)

pysurgery/geometry/embedding.py

@@ -32,7 +32,9 @@
 
 from dataclasses import dataclass, field
 from functools import lru_cache
-from typing import Optional, Sequence
+from typing import Optional, Sequence, Union, TYPE_CHECKING
+if TYPE_CHECKING:
+    from .point_cloud import PointCloud
 
 import numpy as np
 from scipy.spatial import cKDTree
@@ -327,7 +329,7 @@ def __post_init__(self) -> None:
     def from_source(
         cls,
         source: object,
-        coordinates: Optional[np.ndarray] = None,
+        coordinates: Optional[Union[np.ndarray, "PointCloud"]] = None,
         *,
         projection_matrix: Optional[np.ndarray] = None,
         source_name: Optional[str] = None,
@@ -553,7 +555,7 @@ def to_legacy_dict(self) -> dict[str, object]:
 
 def analyze_embedding(
     source: object,
-    coordinates: Optional[np.ndarray] = None,
+    coordinates: Optional[Union[np.ndarray, "PointCloud"]] = None,
     *,
     target_dimension: Optional[int] = None,
     allow_projection: bool = False,
@@ -973,7 +975,7 @@ def detect_self_intersections(
 
 
 def project_coordinates(
-    points: np.ndarray,
+    points: np.ndarray | PointCloud,
     target_dimension: int,
     *,
     method: str = "pca",
@@ -1062,7 +1064,7 @@ def project_coordinates(
     raise ValueError("Unknown projection method: {!r}".format(method))
 
 
-def jitter_coordinates(points: np.ndarray, *, scale: float = 1e-8, random_state: int = 0) -> np.ndarray:
+def jitter_coordinates(points: np.ndarray | PointCloud, *, scale: float = 1e-8, random_state: int = 0) -> np.ndarray:
     """Apply a deterministic small jitter for transversality-style retries.
 
     Args:
@@ -1159,7 +1161,7 @@ def _coerce_source_complex(source: object) -> tuple[SimplicialComplex, list[int]
     )
 
 
-def _coerce_coordinates(source: object, *, coordinates: Optional[np.ndarray] = None) -> np.ndarray:
+def _coerce_coordinates(source: object, *, coordinates: Optional[Union[np.ndarray, "PointCloud"]] = None) -> np.ndarray:
     """Coerce various source types and optional input into a coordinate array.
 
     Args:

pysurgery/geometry/intrinsic_dimension.py

@@ -22,7 +22,9 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Optional, Sequence
+from typing import Optional, Sequence, Union, TYPE_CHECKING
+if TYPE_CHECKING:
+    from .point_cloud import PointCloud
 
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Field
@@ -164,8 +166,8 @@ class _NeighborhoodCache:
 
 
 def _coerce_point_cloud(
-    data: np.ndarray | SimplicialComplex | object,
-    coordinates: Optional[np.ndarray] = None,
+    data: np.ndarray | PointCloud | SimplicialComplex | object,
+    coordinates: Optional[np.ndarray | PointCloud] = None,
 ) -> np.ndarray:
     """Coerce a point-cloud-like input to a dense float array.
 
@@ -185,7 +187,8 @@ def _coerce_point_cloud(
         TypeError: If the input type is not supported.
         ValueError: If the dimensions or sample size are invalid.
     """
-    if isinstance(data, np.ndarray):
+    from .point_cloud import PointCloud
+    if isinstance(data, (np.ndarray, PointCloud)):
         points = np.asarray(data, dtype=np.float64)
     elif coordinates is not None:
         points = np.asarray(coordinates, dtype=np.float64)
@@ -204,7 +207,7 @@ def _coerce_point_cloud(
 
 
 def _compute_knn_cache(
-    points: Optional[np.ndarray],
+    points: Optional[np.ndarray | PointCloud],
     *,
     k: int,
     distance_matrix: Optional[np.ndarray] = None,
@@ -373,10 +376,10 @@ def _aggregate_method_result(
 
 
 def levina_bickel_mle(
-    data: np.ndarray | SimplicialComplex | object,
+    data: np.ndarray | PointCloud | SimplicialComplex | object,
     k: int = 10,
     *,
-    coordinates: Optional[np.ndarray] = None,
+    coordinates: Optional[np.ndarray | PointCloud] = None,
     distance_matrix: Optional[np.ndarray] = None,
 ) -> IntrinsicDimensionMethodResult:
     """Estimate intrinsic dimension with the Levina--Bickel MLE.
@@ -440,9 +443,9 @@ def levina_bickel_mle(
 
 
 def twonn(
-    data: np.ndarray | SimplicialComplex | object,
+    data: np.ndarray | PointCloud | SimplicialComplex | object,
     *,
-    coordinates: Optional[np.ndarray] = None,
+    coordinates: Optional[np.ndarray | PointCloud] = None,
     distance_matrix: Optional[np.ndarray] = None,
 ) -> IntrinsicDimensionMethodResult:
     """Estimate intrinsic dimension using the TwoNN method.
@@ -525,10 +528,10 @@ def twonn(
 
 
 def local_pca_tangent_space_dimension(
-    data: np.ndarray | SimplicialComplex | object,
+    data: np.ndarray | PointCloud | SimplicialComplex | object,
     k: int = 12,
     *,
-    coordinates: Optional[np.ndarray] = None,
+    coordinates: Optional[np.ndarray | PointCloud] = None,
     distance_matrix: Optional[np.ndarray] = None,
     variance_threshold: float = 0.9,
     max_dimension: Optional[int] = None,
@@ -710,10 +713,10 @@ def exact_intrinsic_dimension(
 
 
 def estimate_intrinsic_dimension(
-    data: np.ndarray | SimplicialComplex | object,
+    data: np.ndarray | PointCloud | SimplicialComplex | object,
     k: int = 10,
     *,
-    coordinates: Optional[np.ndarray] = None,
+    coordinates: Optional[np.ndarray | PointCloud] = None,
     distance_matrix: Optional[np.ndarray] = None,
     methods: Sequence[str] = ("mle", "twonn", "pca"),
     variance_threshold: float = 0.9,

pysurgery/geometry/metrics.py

@@ -18,10 +18,12 @@
 
 import numpy as np
 import scipy.spatial.distance as dist
-from typing import Tuple, Optional
+from typing import Tuple, Optional, Union, TYPE_CHECKING
+if TYPE_CHECKING:
+    from .point_cloud import PointCloud
 from ..bridge.julia_bridge import julia_engine
 
-def orthogonal_procrustes(A: np.ndarray, B: np.ndarray, backend: str = "auto") -> Tuple[np.ndarray, np.ndarray, float]:
+def orthogonal_procrustes(A: Union[np.ndarray, "PointCloud"], B: Union[np.ndarray, "PointCloud"], backend: str = "auto") -> Tuple[np.ndarray, np.ndarray, float]:
     """Find the optimal orthogonal transformation to align two point clouds.
 
     What is Being Computed?:
@@ -55,6 +57,8 @@ def orthogonal_procrustes(A: np.ndarray, B: np.ndarray, backend: str = "auto") -
     Example:
         R, aligned, err = orthogonal_procrustes(A, B)
     """
+    A = np.asarray(A)
+    B = np.asarray(B)
     # Normalize backend
     backend_norm = str(backend).lower().strip()
     use_julia = (backend_norm == "julia") or (backend_norm == "auto" and julia_engine.available)
@@ -77,7 +81,7 @@ def orthogonal_procrustes(A: np.ndarray, B: np.ndarray, backend: str = "auto") -
     disparity = float(np.linalg.norm(A - B_aligned))
     return R, B_aligned, disparity
 
-def compute_distance_matrix(data: np.ndarray, metric: str = "euclidean", backend: str = "auto") -> np.ndarray:
+def compute_distance_matrix(data: Union[np.ndarray, "PointCloud"], metric: str = "euclidean", backend: str = "auto") -> np.ndarray:
     """Computes pairwise distance matrix using the optimal implementation.
 
     What is Being Computed?:
@@ -112,6 +116,7 @@ def compute_distance_matrix(data: np.ndarray, metric: str = "euclidean", backend
     Example:
         dist_mat = compute_distance_matrix(cloud, metric='euclidean')
     """
+    data = np.asarray(data)
     # Normalize backend
     backend_norm = str(backend).lower().strip()
     use_julia = (backend_norm == "julia") or (backend_norm == "auto" and julia_engine.available)
@@ -137,7 +142,7 @@ def compute_distance_matrix(data: np.ndarray, metric: str = "euclidean", backend
     else:
         raise ValueError(f"Unsupported metric: {metric}")
 
-def frechet_distance(curve_a: np.ndarray, curve_b: np.ndarray, backend: str = "auto") -> float:
+def frechet_distance(curve_a: Union[np.ndarray, "PointCloud"], curve_b: Union[np.ndarray, "PointCloud"], backend: str = "auto") -> float:
     """Computes the Discrete Fréchet distance between two ordered point sequences.
 
     What is Being Computed?:
@@ -169,6 +174,8 @@ def frechet_distance(curve_a: np.ndarray, curve_b: np.ndarray, backend: str = "a
     Example:
         dist = frechet_distance(path1, path2)
     """
+    curve_a = np.asarray(curve_a)
+    curve_b = np.asarray(curve_b)
     # Normalize backend
     backend_norm = str(backend).lower().strip()
     use_julia = (backend_norm == "julia") or (backend_norm == "auto" and julia_engine.available)
@@ -246,6 +253,12 @@ def gromov_wasserstein_distance(
     Example:
         gw = gromov_wasserstein_distance(D1, D2, epsilon=0.05)
     """
+    dist_matrix_A = np.asarray(dist_matrix_A)
+    dist_matrix_B = np.asarray(dist_matrix_B)
+    if p is not None:
+        p = np.asarray(p)
+    if q is not None:
+        q = np.asarray(q)
     # Normalize backend
     backend_norm = str(backend).lower().strip()
     use_julia = (backend_norm == "julia") or (backend_norm == "auto" and julia_engine.available)
@@ -303,7 +316,7 @@ def gromov_wasserstein_distance(
     gw_dist = max(0.0, term1 + term2 - term3)
     return float(np.sqrt(gw_dist))
 
-def farthest_point_sampling(points: np.ndarray, n_samples: int, initial_idx: int = 0) -> np.ndarray:
+def farthest_point_sampling(points: Union[np.ndarray, "PointCloud"], n_samples: int, initial_idx: int = 0) -> np.ndarray:
     """Subsample a point cloud by greedily picking points that maximize distance to the current set.
 
     What is Being Computed?:

pysurgery/topology/complexes.py

@@ -14,6 +14,7 @@
     from pysurgery.topology.fundamental_polyhedron import FundamentalPolyhedron
     from pysurgery.manifolds.handle_decompositions import HandleDecomposition
     from pysurgery.algebra.exact_sequences import ExactSequence
+    from pysurgery.geometry.point_cloud import PointCloud
 
 from pysurgery.algebra.math_core import get_sparse_snf_diagonal
 from pysurgery.core.exceptions import NotAManifoldError
@@ -2453,7 +2454,7 @@ def clear_cache(self, namespace: str | None = None) -> None:
     @classmethod
     def from_vietoris_rips(
         cls,
-        points: np.ndarray,
+        points: Union[np.ndarray, "PointCloud"],
         epsilon: float,
         max_dimension: int,
         coefficient_ring: str = "Z",
@@ -2660,7 +2661,7 @@ def from_maximal_simplices(
     @classmethod
     def from_point_cloud_cknn(
         cls,
-        points: np.ndarray,
+        points: Union[np.ndarray, "PointCloud"],
         k: int = 5,
         delta: float = 1.0,
         max_dimension: int = 2,
@@ -2747,7 +2748,7 @@ def from_point_cloud_cknn(
     @classmethod
     def from_alpha_complex(
         cls,
-        points: np.ndarray,
+        points: Union[np.ndarray, "PointCloud"],
         alpha: float | None = None,
         *,
         max_alpha_square: Optional[float] = None,
@@ -2856,7 +2857,7 @@ def from_alpha_complex(
     @classmethod
     def from_crust_algorithm(
         cls,
-        points: np.ndarray,
+        points: Union[np.ndarray, "PointCloud"],
         coefficient_ring: str = "Z",
         backend: str = "auto",
     ) -> "SimplicialComplex":
@@ -2981,7 +2982,7 @@ def _from_delaunay_filtered(cls, points, value_fn, threshold, max_dimension, coe
     @classmethod
     def from_delaunay_rips(
         cls,
-        points: np.ndarray,
+        points: Union[np.ndarray, "PointCloud"],
         threshold: float | None = None,
         max_dimension: int = 2,
         *,
@@ -3015,7 +3016,7 @@ def from_delaunay_rips(
     @classmethod
     def from_delaunay_cech(
         cls,
-        points: np.ndarray,
+        points: Union[np.ndarray, "PointCloud"],
         threshold: float | None = None,
         max_dimension: int = 2,
         *,
@@ -3049,7 +3050,7 @@ def from_delaunay_cech(
     @classmethod
     def from_witness(
         cls,
-        points: np.ndarray,
+        points: Union[np.ndarray, "PointCloud"],
         n_landmarks: int,
         alpha: float | None = None,
         *,
@@ -3164,7 +3165,7 @@ def simplices_to_point_cloud(self) -> Dict[Tuple[int, ...], np.ndarray]:
         """Return the mapping from simplices to their point cloud coordinates."""
         return self._simplices_to_point_cloud
 
-    def _generate_point_cloud_mappings(self, points: np.ndarray) -> None:
+    def _generate_point_cloud_mappings(self, points: Union[np.ndarray, "PointCloud"]) -> None:
         """Generate mappings between point cloud indices/coordinates and simplices.
 
         Args: