geolatent.core.mesh_builder#

Prediction-mesh construction for decision-surface rendering.

The central abstraction is MeshBuilder, which:

  1. Creates a regular 3-D grid spanning the convex region of the projected data with a configurable padding margin.

  2. Maps each grid vertex back to the original feature space via the PCA inverse transform stored in a fitted DimensionalityProjector.

  3. Queries the model for predicted class labels and, when available, class probabilities at every grid vertex.

  4. Returns a PredictionMesh bundle consumed by the rendering layer.

Notes

  • Grid size scales as resolution³. At resolution=30 this yields 27 000 points; at resolution=50 it yields 125 000. For most scikit-learn estimators the inference time remains well below 2 s for resolution ≤ 40.

  • Batched inference (batch_size parameter) is available to control memory pressure for large neural networks or kernel SVMs.

  • Detection of regression vs. classification is heuristic: if the model output is floating-point with more than 20 unique values we treat it as a regression target and render a continuous scalar field rather than class volumes.

Classes#

PredictionMesh

Outputs of a decision-surface prediction sweep over a 3-D grid.

MeshBuilder

Constructs prediction meshes for 3-D decision-surface rendering.

Module Contents#

class geolatent.core.mesh_builder.PredictionMesh[source]#

Outputs of a decision-surface prediction sweep over a 3-D grid.

x#

Flattened x-coordinates of the grid vertices in projected space.

Type:

np.ndarray of shape (resolution**3,)

y#

Flattened y-coordinates.

Type:

np.ndarray of shape (resolution**3,)

z#

Flattened z-coordinates.

Type:

np.ndarray of shape (resolution**3,)

predictions#

Predicted class index (integer) or regression target at each vertex.

Type:

np.ndarray of shape (resolution**3,)

probabilities#

Per-class probability at each vertex; None when the model does not expose predict_proba.

Type:

np.ndarray of shape (resolution**3, n_classes) or None

grid_shape#

Logical shape (resolution, resolution, resolution) of the 3-D grid.

Type:

tuple of 3 ints

n_classes#

Number of unique predicted class labels (meaningful only for classifiers).

Type:

int

unique_classes#

Sorted array of unique class labels found in predictions.

Type:

np.ndarray

bounds#

Per-axis bounding box: [[xmin, xmax], [ymin, ymax], [zmin, zmax]].

Type:

np.ndarray of shape (3, 2)

is_regression#

True when the model output is treated as a continuous regression value.

Type:

bool

x: numpy.ndarray#
y: numpy.ndarray#
z: numpy.ndarray#
predictions: numpy.ndarray#
probabilities: numpy.ndarray | None#
grid_shape: Tuple[int, int, int]#
n_classes: int#
unique_classes: numpy.ndarray#
bounds: numpy.ndarray#
is_regression: bool = False#
class geolatent.core.mesh_builder.MeshBuilder(resolution: int = 30, padding_fraction: float = 0.12, batch_size: int | None = None)[source]#

Constructs prediction meshes for 3-D decision-surface rendering.

Parameters:

  • resolution (int) – Number of grid points per spatial dimension. Total vertex count equals resolution³. Default 30 provides smooth surfaces for most models with sub-second inference time.

  • padding_fraction (float) – Fractional extension applied beyond the data bounding box on each axis. A value of 0.12 extends the grid by 12 % of the data range on every side, preventing clipping at the edges of the scatter cloud.

  • batch_size (int or None) – Maximum number of points passed to the model in a single predict call. None infers all points at once. Set to e.g. 4096 for memory-constrained models.

Examples

>>> from geolatent.core.mesh_builder import MeshBuilder
>>> builder = MeshBuilder(resolution=25)
>>> mesh = builder.build_prediction_mesh(clf, projector, X_3d)
>>> mesh.probabilities.shape
(15625, 2)
resolution = 30#
padding_fraction = 0.12#
batch_size = None#
build_prediction_mesh(model: object, projector: geolatent.core.projector.DimensionalityProjector, X_proj: numpy.ndarray) → PredictionMesh[source]#

Build a prediction mesh for model over the region spanned by X_proj.

Parameters:

  • model (sklearn-compatible estimator) – Must implement at least predict(X).

  • projector (DimensionalityProjector) – Fitted projector that supports inverse_transform (i.e., PCA).

  • X_proj (np.ndarray of shape (n_samples, 3)) – Training data in projected 3-D space, used to define the bounding box.

Returns:

mesh

Return type:

PredictionMesh

Raises:

ValueError – If projector does not support inverse_transform.