Geometric Fitting#
Fit elliptical rings or tori to three-dimensional clouds and compare trajectories with Procrustes disparity. Fits retain the input coordinate scale. Containment score and outside distance quantify geometric fit; they do not establish topological recovery.
Ring and Torus Fits#
- neuralfieldmanifold.geometry.fit_ring(points, *, config=None)[source]#
Fit a planar elliptical annulus to a three-dimensional point cloud.
- Parameters:
points (array_like, shape (n_points, 3)) – Finite coordinates with at least four points and nonzero extent along each coordinate.
config (FitConfig or None) – Compactness, hole, and angular homogeneity settings.
- Returns:
Center, orientation, inner and outer ellipse radii, fit measures, and optimizer status. Distances are in input coordinate units.
- Return type:
Notes
Uses PCA initialization and bounded robust least squares. Containment is measured in the fitted plane; MSE also includes normal offsets.
- neuralfieldmanifold.geometry.fit_torus(points, *, config=None)[source]#
Fit a thick elliptical torus to a three-dimensional point cloud.
- Parameters:
points (array_like, shape (n_points, 3)) – Finite coordinates with at least four points and nonzero extent along each coordinate.
config (FitConfig or None) – Compactness, hole, and angular homogeneity settings.
- Returns:
Center, orientation, major radii, tube radius, fit measures, and optimizer status. Distances are in input coordinate units.
- Return type:
Notes
Uses PCA initialization and bounded robust least squares. Score is the fraction of points contained within the fitted tube.
Settings and Results#
- class neuralfieldmanifold.geometry.FitConfig(regularization: float = 0.1, hole_ratio: float | None = None, angular_modes: int = 3)[source]#
Control the compactness and hole penalties in geometric fitting.
- Parameters:
regularization (float) – Nonnegative weight for compactness and hole penalties relative to point-containment residuals.
hole_ratio (float or None) – Hole constraint ratio, between zero and one. None selects 0.5 for a ring or 0.75 for a torus.
angular_modes (int) – Number of Fourier modes in the angular homogeneity penalty.
- class neuralfieldmanifold.geometry.GeometryFit(kind: str, center: ndarray, normal: ndarray, u_axis: ndarray, v_axis: ndarray, major_radii: tuple[float, float], tube_radius: float, inner_radii: tuple[float, float] | None, score: float, error: float, mse: float, r_squared: float, hole_quality: float, fraction_in_hole: float, success: bool, evaluations: int, optimizer_message: str)[source]#
Fitted geometry, residual measures, and optimizer diagnostics.
- kind#
Geometry type: ring or torus.
- Type:
str
- center#
Center in input coordinates.
- Type:
ndarray, shape (3,)
- normal, u_axis, v_axis
Fitted orientation vectors.
- Type:
ndarray, shape (3,)
- major_radii#
Ellipse radii along u_axis and v_axis.
- Type:
tuple of float
- tube_radius#
Torus tube radius, or half the mean annular width for a ring.
- Type:
float
- inner_radii#
Inner ellipse radii for a ring; None for a torus.
- Type:
tuple of float or None
- score#
Fraction of points contained in the fitted geometry.
- Type:
float
- error#
Mean outside distance, in input units.
- Type:
float
- mse#
Mean squared outside distance. For rings, includes normal offsets.
- Type:
float
- r_squared#
One minus the ratio of squared outside distances to total centered point-cloud variation. Ring outside distances are measured in-plane.
- Type:
float
- hole_quality#
Relative hole-size measure of the fitted geometry.
- Type:
float
- fraction_in_hole#
Fraction of points in the central hole.
- Type:
float
- success#
Whether the optimizer reported convergence.
- Type:
bool
- evaluations#
Number of optimizer function evaluations.
- Type:
int
- optimizer_message#
Optimizer termination message.
- Type:
str
Notes
Ring containment and mean error are measured in the fitted plane. Torus distances are three-dimensional.
- property features#
radii, fit quality, normal, and plane axes.
Order is R1, R2, tube radius, MSE, error, score, normal xyz, u-axis xyz, v-axis xyz. Orientation signs follow the fitted PCA frame; this function does not impose an additional sign convention.
- Type:
15 geometry features
Trajectory Comparison#
- neuralfieldmanifold.geometry.pairwise_disparity(signals, *, dimension, tau_samples, target_points=2000)[source]#
Compare delay embeddings of time-aligned signals using Procrustes analysis.
- Parameters:
signals (array_like, shape (n_signals, n_samples)) – At least two equal-length signals with corresponding time samples.
dimension (int) – Number of delay coordinates.
tau_samples (int) – Delay between coordinates, in samples.
target_points (int) – Approximate number of points per embedding. Subsampling uses stride max(1, n_points // target_points), so this is not a strict upper bound.
- Returns:
Pair indices, individual disparities, their mean, and population standard deviation.
- Return type: