Mesh Module

Mesh Module#

The parq_blockmodel.mesh module provides functionality to convert regular block models into triangulated surface geometry. This enables visualization, exchange with external tools, and scientific analysis.

Overview#

Key concepts:

  • PLY (Polygon File Format) is the canonical internal format for mesh storage. It supports lossless round-tripping of all geometry and attributes. PLY files are ASCII by default (readable) and can be binary (compact).

  • GLB (glTF 2.0 binary) is a derived format for external visualization. It supports optional textures and materials, and can be viewed in standard 3D viewers (Babylon.js, Three.js, etc.).

  • Mesh geometry is always generated from RegularGeometry metadata, ensuring consistency between block model and mesh representations.

  • Rotated geometries are handled transparently; world-space coordinates reflect the rotation via axis vectors.

  • Block attributes (grades, rock types, densities) are preserved as per-vertex and per-face properties in both PLY and GLB formats.

Coordinates and Units#

All mesh coordinates are in world space with units and CRS inherited from the underlying ParquetBlockModel.geometry.

For non-rotated models, world coordinates align with global X, Y, Z axes.

For rotated models, world coordinates are computed by transforming local block coordinates via the orthonormal basis (axis_u, axis_v, axis_w).

Right-handedness is guaranteed: the cross product of axis_u and axis_v yields axis_w.

Sparse vs. Dense Meshes#

Sparse meshes include only blocks that exist in the block model data. This is useful for geological block models where many cells are empty. When surface_only=True (default), only exterior faces are included, which is typically what you want for visualization.

Dense meshes include all blocks in the logical grid defined by geometry. Use this for models with no missing cells or for analysis that requires complete coverage.

Attribute Mapping#

When exporting with attributes:

  • Vertex attributes: Each vertex inherits attributes from its parent block. For sparse models, vertices on block boundaries may be shared; the attribute is taken from the block that defines the vertex.

  • Face attributes: Each face inherits attributes from its parent block.

  • Categorical attributes: String/category columns are stored as integer codes in PLY files, with a metadata mapping for recovery. In GLB, categorical attributes are converted to numeric codes for visualization.

  • NaN handling: Missing values are preserved as NaN in PLY. In GLB with texture attributes, NaN values are rendered as transparent.

API Reference#

Main methods on ParquetBlockModel:

  • triangulate(attributes=None, surface_only=True, sparse=None) → Internal mesh representation

  • to_ply(output_path, attributes=None, surface_only=True, sparse=None, binary=False) → Export to PLY format

  • to_glb(output_path, attributes=None, texture_attribute=None, colormap='viridis', surface_only=True, sparse=None) → Export to GLB format

Examples#

Basic export to PLY:

from pathlib import Path
from parq_blockmodel import ParquetBlockModel

pbm = ParquetBlockModel(Path("model.pbm"))

# Export to PLY (lossless, includes all attributes)
pbm.to_ply("model.ply", attributes=["grade", "density"])

Export to GLB with colored texture:

# Export to GLB with grades shown as colors
pbm.to_glb("model.glb", texture_attribute="grade", colormap="viridis")

Get internal mesh and inspect:

mesh = pbm.triangulate(attributes=["grade"])
print(f"Vertices: {mesh.n_vertices}, Faces: {mesh.n_faces}")
print(f"Attributes: {list(mesh.vertex_attributes.keys())}")
print(f"Metadata: {mesh.metadata}")

Handle sparse model with surface-only:

# For a sparse 3D model with ~10% fill, generate surface mesh
mesh = pbm.triangulate(surface_only=True, sparse=True)

Dense mesh from sparse model:

# Include all blocks in the logical grid (fills empty cells)
mesh = pbm.triangulate(sparse=False)

Scientific Workflow Notes#

This module is designed for scientific and mining workflows:

  • Units are explicit: All coordinates carry the units of the block model. Conversion (e.g., feet to meters) must be done at the block model level.

  • Lossless PLY round-tripping: PLY export preserves all geometry and attribute data. This allows reliable interchange with other tools.

  • No implicit encodings: Block semantics (rock types, domains) are not encoded implicitly in colors. Use explicit attribute columns instead.

  • Rotated geometry support: Rotations are fully supported and transparent to the user; the mesh reflects the rotated orientation in world space.

  • Sparse block models: The mesh module efficiently handles sparse models by generating only surfaces and boundaries, avoiding unnecessary empty space.

See Also#

“””