geolatent.rendering#

Rendering sub-package for geolatent.

Contains the dark-scientific scene manager, decision-surface renderer, and data-overlay generator.

Submodules#

Classes#

DataOverlay

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

Scene3D

Stateful 3-D Plotly figure builder with dark-scientific theming.

DecisionSurfaceRenderer

Renders decision surfaces from a PredictionMesh.

Package Contents#

class geolatent.rendering.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

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

Stateful 3-D Plotly figure builder with dark-scientific theming.

Parameters:

config (VisualizationConfig) – Master configuration; theme colours, render sizes, and camera settings are all read from here.

Examples

>>> scene = Scene3D(DARK_SCIENTIFIC)
>>> scene.add_trace(some_trace).add_trace(another_trace)
>>> fig = scene.render()
>>> fig.show()
config#
add_trace(trace: plotly.graph_objects.BaseTraceType) → Scene3D[source]#

Add a single Plotly trace.

Parameters:

trace (go.BaseTraceType)

Return type:

self

add_traces(traces: Sequence[plotly.graph_objects.BaseTraceType]) → Scene3D[source]#

Add multiple Plotly traces at once.

Parameters:

traces (sequence of go.BaseTraceType)

Return type:

self

set_title(title: str) → Scene3D[source]#

Set the figure title.

Parameters:

title (str)

Return type:

self

set_axis_labels(labels: List[str]) → Scene3D[source]#

Override the three axis labels.

Parameters:

labels (list of 3 str)

Return type:

self

add_variance_annotation(explained_variance_ratio: object) → Scene3D[source]#

Append a cumulative explained-variance annotation.

Parameters:

explained_variance_ratio (array-like of shape (3,)) – Per-component explained-variance ratios from PCA.

Return type:

self

add_text_annotation(text: str, *, x: float = 0.99, y: float = 0.99) → Scene3D[source]#

Add a free-form text annotation in paper coordinates.

Parameters:

  • text (str) – HTML-formatted annotation text.

  • x (float) – Paper-coordinate position (0–1).

  • y (float) – Paper-coordinate position (0–1).

Return type:

self

render() → plotly.graph_objects.Figure[source]#

Apply the dark-scientific layout and return the completed figure.

Returns:

fig – A fully configured Plotly figure ready for fig.show() or fig.write_html().

Return type:

go.Figure

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

Renders decision surfaces from a PredictionMesh.

Parameters:

config (VisualizationConfig) – Master configuration; colour palette and surface opacity are read here.

Examples

>>> renderer = DecisionSurfaceRenderer(DARK_SCIENTIFIC)
>>> traces = renderer.render(mesh)
>>> for t in traces:
...     scene.add_trace(t)
config#
render(mesh: geolatent.core.mesh_builder.PredictionMesh, *, class_names: Dict | None = None, show_confidence: bool = True) → List[plotly.graph_objects.BaseTraceType][source]#

Auto-select and execute the most appropriate rendering strategy.

Parameters:

  • mesh (PredictionMesh) – Pre-computed prediction mesh from MeshBuilder.

  • class_names (dict, optional) – Mapping from class label to display string.

  • show_confidence (bool) – When True and mesh.probabilities is available, render nested confidence isosurfaces in addition to the boundary shell.

Returns:

traces

Return type:

list of Plotly traces

render_probability_isosurfaces(mesh: geolatent.core.mesh_builder.PredictionMesh, *, class_names: Dict | None = None, show_confidence: bool = True, boundary_threshold: float = 0.5, confidence_thresholds: List[float] | None = None) → List[plotly.graph_objects.Isosurface][source]#

Render probability isosurfaces for each class.

For each class c, the decision boundary surface (P(class=c) = 0.5) is rendered as a translucent shell. When show_confidence is True, additional shells at higher probability thresholds convey confidence depth.

Parameters:

  • mesh (PredictionMesh) – Must have probabilities populated.

  • class_names (dict, optional)

  • show_confidence (bool)

  • boundary_threshold (float) – Primary isosurface probability value (default 0.50).

  • confidence_thresholds (list of float, optional) – Additional isosurface levels drawn inside the boundary shell. Defaults to [0.70, 0.85] when show_confidence is True.

Returns:

traces

Return type:

list of go.Isosurface

render_class_volumes(mesh: geolatent.core.mesh_builder.PredictionMesh, *, class_names: Dict | None = None) → List[plotly.graph_objects.BaseTraceType][source]#

Render a per-class volume for models without predict_proba.

Maps predicted class indices onto a discrete colour scale and renders the full volumetric class partition as a transparent go.Volume. To give class boundaries a clear visual edge, one go.Isosurface per class boundary is additionally rendered.

Parameters:
Returns:

traces

Return type:

list of Plotly traces

render_regression_field(mesh: geolatent.core.mesh_builder.PredictionMesh) → List[plotly.graph_objects.Volume][source]#

Render a continuous regression prediction field as a volumetric trace.

Parameters:

mesh (PredictionMesh) – A mesh whose is_regression flag is True.

Returns:

traces

Return type:

list of go.Volume