geolatent.core.geometry#
Geometric utilities for geolatent.
Provides analytical geometry operations used to enrich decision-boundary visualisations with class-level structural overlays:
Confidence ellipsoids — parametric surfaces derived from the class- conditional covariance matrix, scaled to a chosen Mahalanobis-distance contour (analogous to a 1-σ / 2-σ region for a Gaussian assumption).
Class centroids — arithmetic means of class point clouds, rendered as star markers that anchor the viewer’s spatial reference frame.
Convex hull traces (optional, computationally cheap for n ≤ 1000) — rendered as transparent mesh surfaces that bound each class cluster.
All methods in GeometryUtils operate exclusively in the 3-D projected
space returned by DimensionalityProjector.
Classes#
Collection of geometric analysis and Plotly trace generators. |
Module Contents#
- class geolatent.core.geometry.GeometryUtils(config: geolatent.config.themes.VisualizationConfig)[source]#
Collection of geometric analysis and Plotly trace generators.
All methods accept the 3-D projected coordinate array X_proj and the label vector y, and return lists of fully configured Plotly traces that can be added directly to a
Scene3D.- Parameters:
config (VisualizationConfig) – Master configuration; colour palette and render settings are read here.
- config#
- compute_class_ellipsoids(X_proj: numpy.ndarray, y: numpy.ndarray, *, confidence: float = 0.9, n_grid: int = 40, class_names: Dict | None = None) List[plotly.graph_objects.Surface][source]#
Generate parametric ellipsoid traces for each class.
The ellipsoid is derived from the empirical covariance matrix of the class subset and scaled so that it encloses confidence percent of samples under a multivariate-Gaussian assumption.
- Parameters:
X_proj (np.ndarray of shape (n_samples, 3)) – Projected data coordinates.
y (np.ndarray of shape (n_samples,)) – Class label vector.
confidence (float) – Fraction of the distribution to enclose (e.g., 0.90 → 90 % region).
n_grid (int) – Resolution of the parametric ellipsoid surface mesh.
class_names (dict, optional) – Mapping from class label to display string.
- Returns:
traces
- Return type:
list of go.Surface
- compute_class_centroids(X_proj: numpy.ndarray, y: numpy.ndarray, *, class_names: Dict | None = None) plotly.graph_objects.Scatter3d[source]#
Build a single Scatter3d trace for all class centroids.
- Parameters:
X_proj (np.ndarray of shape (n_samples, 3))
y (np.ndarray of shape (n_samples,))
class_names (dict, optional)
- Returns:
trace – Star-shaped markers at the class-mean coordinates.
- Return type:
go.Scatter3d
- compute_convex_hull_traces(X_proj: numpy.ndarray, y: numpy.ndarray, *, class_names: Dict | None = None) List[plotly.graph_objects.Mesh3d][source]#
Generate convex-hull surface traces for each class cluster.