geolatent.rendering.overlays#

Data-point overlay rendering for geolatent.

DataOverlay is responsible for all trace types that are layered on top of decision surfaces: per-class scatter clouds, class-centroid markers, and optional confidence-ellipsoid surfaces.

Design rationale: each rendering method returns a list of independent Plotly traces rather than mutating an existing figure. This keeps the overlay layer stateless and trivially composable with scene objects produced by other modules.

Classes#

DataOverlay

Generates data-point and structural overlays for 3-D scenes.

Module Contents#

class geolatent.rendering.overlays.DataOverlay(config: geolatent.config.themes.VisualizationConfig)[source]#

Generates data-point and structural overlays for 3-D scenes.

Parameters:

config (VisualizationConfig) – Master configuration; colour palette, marker sizes, and opacity values are all sourced from here.

Examples

>>> overlay = DataOverlay(DARK_SCIENTIFIC)
>>> traces = overlay.render_scatter(X_3d, y)
>>> centroid = overlay.render_centroids(X_3d, y)
config#
render_scatter(X_proj: numpy.ndarray, y: numpy.ndarray, *, class_names: Dict | None = None, point_size_override: int | None = None, opacity_override: float | None = None) → List[plotly.graph_objects.Scatter3d][source]#

Render a per-class scatter trace for every unique class label.

One go.Scatter3d trace is produced per class, allowing Plotly’s interactive legend to toggle individual classes on and off.

Parameters:

  • X_proj (np.ndarray of shape (n_samples, 3)) – 3-D projected coordinates.

  • y (np.ndarray of shape (n_samples,)) – Class label vector.

  • class_names (dict, optional) – Mapping {label: display_string}.

  • point_size_override (int, optional) – Override config.render.marker_size.

  • opacity_override (float, optional) – Override config.render.scatter_opacity.

Returns:

traces – One trace per unique class, in sorted label order.

Return type:

list of go.Scatter3d

render_centroids(X_proj: numpy.ndarray, y: numpy.ndarray, *, class_names: Dict | None = None) → plotly.graph_objects.Scatter3d[source]#

Render diamond-shaped class-centroid markers.

Delegates to compute_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

Return type:

go.Scatter3d

render_ellipsoids(X_proj: numpy.ndarray, y: numpy.ndarray, *, confidence: float = 0.9, class_names: Dict | None = None) → List[plotly.graph_objects.Surface][source]#

Render parametric confidence-ellipsoid surfaces for each class.

Delegates to compute_class_ellipsoids().

Parameters:

  • X_proj (np.ndarray of shape (n_samples, 3))

  • y (np.ndarray of shape (n_samples,))

  • confidence (float) – Confidence level for the Mahalanobis-distance ellipsoid (default 0.90).

  • class_names (dict, optional)

Returns:

traces

Return type:

list of go.Surface

render_convex_hulls(X_proj: numpy.ndarray, y: numpy.ndarray, *, class_names: Dict | None = None) → List[plotly.graph_objects.Mesh3d][source]#

Render transparent convex-hull surfaces around each class cluster.

Delegates to compute_convex_hull_traces().

Parameters:

  • X_proj (np.ndarray of shape (n_samples, 3))

  • y (np.ndarray of shape (n_samples,))

  • class_names (dict, optional)

Returns:

traces

Return type:

list of go.Mesh3d

render_trajectory(waypoints: numpy.ndarray, *, name: str = 'Trajectory', color: str | None = None, line_width: int = 4, show_waypoints: bool = True) → List[plotly.graph_objects.BaseTraceType][source]#

Render an ordered sequence of waypoints as a 3-D polyline.

Useful for visualising gradient-descent trajectories, attention paths, or other sequential processes in the projected embedding space.

Parameters:

  • waypoints (np.ndarray of shape (n_steps, 3)) – Ordered sequence of 3-D positions.

  • name (str) – Legend label for the trajectory.

  • color (str, optional) – Line colour (hex). Defaults to the first class colour.

  • line_width (int) – Width of the line in pixels.

  • show_waypoints (bool) – Whether to overlay individual step markers.

Returns:

traces

Return type:

list of Plotly traces