parq-blockmodel

Overview

A Python package for efficient storage, manipulation, and analysis of mining block models using Parquet files. parq-blockmodel provides tools for reading, writing, indexing, and transforming large-scale block model datasets, leveraging the performance of Apache Arrow and Parquet for scalable geoscience data workflows.

Installation

Install the base package from PyPI:

pip install parq-blockmodel

Install the optional schema validation support when you want to validate block model attributes with Pandera schemas or load schema definitions from YAML:

pip install "parq-blockmodel[schema]"

Install the visualization extras when you want to use the Trame viewer:

pip install "parq-blockmodel[viz]"

Schema validation

ParquetBlockModel accepts an optional schema= argument on its main constructors. You can pass either a Pandera DataFrameSchema object or a path to a YAML schema file, then validate the resulting model in chunks:

from pathlib import Path

from parq_blockmodel import ParquetBlockModel

pbm = ParquetBlockModel.from_parquet(
    Path("path/to/blockmodel.parquet"),
    schema=Path("schemas/blockmodel.schema.yaml"),
)

pbm.validate()
pbm.validate(sample_chunks=1)  # quick spot-check for large models

See the User Guide for detailed documentation on calculated attributes, including custom lookups and functions.

Visualization

The block-model plotting path now delegates through parq_blockmodel.visualization, which keeps the rendering logic isolated from ParquetBlockModel itself.

from parq_blockmodel import ParquetBlockModel
from parq_blockmodel.visualization import BlockModelTrameApp, TrameBlockModelPlotEngine

pbm = ParquetBlockModel.from_parquet("orebody.parquet")
plotter = pbm.plot(scalar="grade", z_up_lock=True, z_up_hotkey="z")

# Optional terrain context for the PyVista engine:
# - elevation_raster adds a DEM surface
# - imagery_raster textures the DEM when both rasters align
plotter = pbm.plot(
    scalar="grade",
    elevation_raster="dem.tif",
    imagery_raster="imagery.tif",
)

trame_app_from_plot = pbm.plot(
    scalar="grade",
    engine=TrameBlockModelPlotEngine(),
    z_up_lock=True,
    z_up_hotkey="z",
)

app = BlockModelTrameApp(pbm, scalar="grade", z_up_lock=True, z_up_hotkey="z")

With z_up_lock=True, hold z for turntable-style orbit (yaw/pitch, no roll) with camera up aligned to +Z.

Geometry operations

parq-blockmodel supports three geometry flagging workflows:

• Polygon flagging for 2D XY regions.
• Surface encoding for 2.5D elevation surfaces (z = f(x, y)).
• Solid flagging for closed 3D volumes.