parq_blockmodel.blockmodel.ParquetBlockModel

class parq_blockmodel.blockmodel.ParquetBlockModel(blockmodel_path, name=None, geometry=None, schema=None, engine_initializer=None)

A class to represent a regular Parquet block model.

Canonical on-disk representation:

We treat .pbm files as ParquetBlockModel containers:

• The extension must be .pbm.

• The content is a Parquet table with embedded geometry metadata under the "parq-blockmodel" key, describing a regular parq_blockmodel.geometry.RegularGeometry grid.

The geometry is ijk-first: logical indices (i, j, k) enumerate the dense grid, and centroid coordinates (x, y, z) are derived from those indices plus geometry (corner, block size, axis orientation). In non-rotated models the grid axes align with the global X, Y, Z directions; in rotated models they do not.

Parquet storage order follows NumPy C-order with respect to ijk: i varies fastest, then j, then k. This aligns with numpy.ravel(order="C") and how RegularGeometry computes row indices. For xyz-defined, non-rotated models this corresponds to an increasing lexicographic ordering in (x, y, z), but callers should treat ijk + geometry as the canonical view.

blockmodel_path

Path to the canonical .pbm file backing this block model.

Type:

Path

name

The name of the block model, derived from the file name.

Type:

str

geometry

Geometry of the block model, loaded from Parquet metadata or inferred from centroid columns.

Type:

RegularGeometry

__init__(blockmodel_path, name=None, geometry=None, schema=None, engine_initializer=None)

Initialize a ParquetBlockModel.

Parameters:

• blockmodel_path (Path) – Path to the .pbm file.

• name (Optional[str]) – Optional name; defaults to file stem.

• geometry (Optional[RegularGeometry]) – Optional RegularGeometry; loaded from metadata if not provided.

• schema (Union[Path, DataFrameSchema, None]) – Optional pandera DataFrameSchema or path to YAML schema.

• engine_initializer (Optional[Callable]) – Optional callable that configures the df-eval Engine for custom lookups/functions. Signature: Callable[[Engine], Engine]. Called before applying calculated column operations.

Methods

__init__(blockmodel_path[, name, geometry, ...])	Initialize a ParquetBlockModel.
compress([level, policy])	Rewrite the backing file with archive compression.
configure_engine(initializer)	Register custom lookups and functions with the df-eval Engine.
create_demo_block_model(filename, **demo_kwargs)	Convenience helper used in tests to write a demo Parquet file and wrap it as a ParquetBlockModel.
create_heatmap_from_threshold(attribute, ...)	Create a 2D heatmap from a 3D block model at a specified attribute threshold.
create_report([columns, columns_per_batch, ...])	Create a ydata-profiling report for the block model.
create_toy_blockmodel(filename[, shape, ...])	Create a synthetic toy block model.
downsample(new_block_size, aggregation_config)	Downsample the block model to a coarser grid with specified aggregation methods for each attribute. This function supports downsampling of both categorical and numeric attributes. :type new_block_size: :param new_block_size: tuple of floats (dx, dy, dz) for the new block size. :type aggregation_config: :param aggregation_config: dict mapping attribute names to aggregation methods. Use basis for weighted_mean configurations.
ensure_spatial()	Ensure canonical spatial columns exist; recompute when missing.
ensure_world_id()	Ensure world_id exists; recompute when missing.
evaluate_surface(surface, *, column)	Evaluate a Surface and persist the resulting values into a column.
flag_polygon(polygon, *, column[, ...])	Evaluate a PolygonField and persist a new flag/domain column.
flag_solid(solid, *, column[, inside_value, ...])	Evaluate a MeshSolid and persist a new flag/domain column.
from_dataframe(dataframe, filename[, ...])	Create a ParquetBlockModel from a pandas DataFrame.
from_geometry(geometry, path[, name, ...])	Create a ParquetBlockModel from a geometry only.
from_parquet(parquet_path[, columns, ...])	Create a ParquetBlockModel from a source Parquet file.
plot(scalar[, grid_type, frame, threshold, ...])	Plot the block model using PyVista.
plot_heatmap(attribute, threshold[, axis, title])	Create a 2D heatmap plotly figure from a 3D block model at a specified attribute threshold.
read([columns, index, dense, include_calculated])	Read the Parquet file and return a DataFrame.
recompute_spatial()	Recompute and persist canonical spatial columns (x, y, z, i, j, k).
recompute_world_id()	Recompute and persist world_id from current spatial columns and encoding metadata.
rename(new_pbm_filepath[, ...])	Rename the underlying .pbm file and refresh path-bound caches.
to_dense_parquet(filepath[, chunk_size, ...])	Export the block model as a dense xyz-indexed Parquet file.
to_glb(output_path[, attributes, ...])	Export the block model as a GLB (glTF 2.0 binary) mesh.
to_ply(output_path[, attributes, ...])	Export the block model as a PLY (Polygon File Format) mesh.
to_pyvista([grid_type, attributes, frame])
triangulate([attributes, surface_only, sparse])	Generate a triangulated mesh from the block model.
upsample(new_block_size[, upsample_config, ...])	Upsample the block model to a finer grid with specified methods for each attribute. This function supports upsampling of both categorical and numeric attributes. :type new_block_size: :param new_block_size: tuple of floats (dx, dy, dz) for the new block size. :type upsample_config: :param upsample_config: dict mapping attribute names to upsampling methods (linear, nearest, mode, parent). :type interpolation_config: :param interpolation_config: deprecated alias of upsample_config.
validate([schema, sample_chunks])	Validate the block model data against a pandera schema.
validate_sparse()
validate_special_columns([sample_size])	Validate consistency of special columns against geometry and encoding metadata.
validate_xyz_parquet(parquet_path[, ...])	Validate xyz-defined Parquet input and return inferred geometry.
write(dataframe, *[, merge, index_columns, ...])	Persist data to the backing .pbm file.

Attributes

INTRINSIC_VOLUME_COLUMN
PBM_METADATA_KEY
POSITION_COLUMNS
SPECIAL_COLUMN_DTYPES
SPECIAL_COLUMN_ORDER
available_attributes	Persisted + calculated attribute columns.
available_columns	Persisted + calculated columns that can be read from this model.
calculated_attributes	Calculated block-property columns classified as attributes.
calculated_columns	df-eval columns available for materialization (schema + intrinsic).
centroid_index	Get the centroid index of the block model as (x, y, z).
column_categorical_ordered
corner	Backward-compatible access to the local grid corner.
grid	Backward-compatible access to the canonical block model grid.
id_column
index_columns
is_sparse
origin	Backward-compatible access to the world-frame origin.
persisted_attributes	Persisted block-property columns (non-positional).
persisted_columns	Column names physically persisted in the backing parquet.
position_columns	Persisted positional/identity columns present on disk.
schema_service	Lazy-initialized schema service (recreated if schema or engine changes).
sparsity
spatial_columns
world_id_column

property available_attributes: list[str]

Persisted + calculated attribute columns.

property available_columns: list[str]

Persisted + calculated columns that can be read from this model.

property calculated_attributes: list[str]

Calculated block-property columns classified as attributes.

property calculated_columns: list[str]

df-eval columns available for materialization (schema + intrinsic).

property centroid_index: MultiIndex

Get the centroid index of the block model as (x, y, z).

This index is built from the centroid columns x, y, z stored in the underlying .pbm Parquet file. It is primarily a backwards-compatibility view for xyz-first workflows which treat world-space centroids as the primary index.

Canonical ordering is defined by the C-order ijk layout in RegularGeometry, not by lexicographic sorting of (x, y, z). We therefore require this index to be unique but do not enforce global monotonicity in xyz.

Returns:

The MultiIndex representing centroid coordinates (x, y, z).

Return type:

pd.MultiIndex

compress(level=5, policy=None)

Rewrite the backing file with archive compression.

Return type:

ParquetBlockModel

configure_engine(initializer)

Register custom lookups and functions with the df-eval Engine.

This method allows post-construction configuration of the df-eval Engine for custom lookups and functions used in calculated columns. Can be called before reading calculated columns.

Parameters:

initializer (Callable) – Callable that accepts an Engine, registers lookups/functions, and returns the configured Engine. Signature: Callable[[Engine], Engine].

Return type:

None

Examples

>>> def setup_engine(engine):
...     engine.register_lookup("rock_codes", lookup_df)
...     engine.register_function("convert_units", converter_fn)
...     return engine
>>> pbm.configure_engine(setup_engine)
>>> result = pbm.read(columns=["rock_name", "converted_value"])

property corner: tuple[float, float, float] | list[float]

Backward-compatible access to the local grid corner.

classmethod create_demo_block_model(filename, **demo_kwargs)

Convenience helper used in tests to write a demo Parquet file and wrap it as a ParquetBlockModel.

Parameters:

• filename (Path) – Target .parquet file to hold the raw demo data. The canonical blockmodel file will be written alongside it with a .pbm suffix via from_parquet().

• **demo_kwargs – Additional keyword arguments forwarded to parq_blockmodel.utils.demo_block_model.create_demo_blockmodel(), for example shape or block_size. This allows tests and examples to control the logical grid used for the demo model.

Return type:

ParquetBlockModel

create_heatmap_from_threshold(attribute, threshold, axis='z', return_array=False)

Create a 2D heatmap from a 3D block model at a specified attribute threshold.

Parameters:

• attribute (str) – The name of the attribute to threshold.

• threshold (float) – The threshold value for the attribute.

• axis (str) – The axis to view from (‘x’, ‘y’, or ‘z’). Defaults to ‘z’.

• return_array (bool) – If True, returns the heatmap as a NumPy array. Defaults to False.

Returns:

A 2D heatmap as a PyVista ImageData object or a NumPy array.

Return type:

Union[pv.ImageData, np.ndarray]

create_report(columns=None, columns_per_batch=10, show_progress=True, open_in_browser=False, report_path=None, write_html=True, memory_budget=None)

Create a ydata-profiling report for the block model. By default the generated HTML is saved beside the block model with a .html suffix, and the returned report object can be re-saved later.

Parameters:

• columns (Optional[list[str]]) – List of column names to include in the profile. If None, all columns are used.

• columns_per_batch (Optional[int]) – Number of columns to process in each profiling batch. Use None to profile all requested columns in one pass.

• show_progress (bool) – bool: If True, displays a progress bar during profiling.

• open_in_browser (bool) – bool: If True, opens the report in a web browser after generation.

• report_path (Union[str, Path, None]) – Optional output path for the HTML report.

• write_html (bool) – If True, save the report HTML before returning it.

• memory_budget (Union[int, float, str, None]) – Optional heuristic per-batch memory budget in bytes or as a string such as "512MB" or "2GiB". When provided, the method derives columns_per_batch automatically from Parquet column-chunk metadata. If the full selected column set fits within the budget estimate, profiling runs without column chunking.

Return type:

BlockModelReport

Returns

BlockModelReport: The generated report wrapper. Use BlockModelReport.save() to write it again.

classmethod create_toy_blockmodel(filename, shape=(3, 3, 3), block_size=(1, 1, 1), corner=(-0.5, -0.5, -0.5), axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0, deposit_bearing=20.0, deposit_dip=30.0, deposit_plunge=10.0, grade_name='grade', grade_min=50.0, grade_max=65.0, deposit_center=(10.0, 7.5, 5.0), deposit_radii=(8.0, 5.0, 3.0), noise_std=0.0, noise_rel=None, noise_seed=None)

Create a synthetic toy block model.

The toy model is generated on a regular ijk grid with the specified shape and block_size, anchored at corner in world coordinates. A simple ellipsoidal grade distribution is created in xyz space and stored under grade_name alongside any supporting attributes.

Parameters:

• filename (Path) – Path to the source .parquet file to hold the raw toy data. A canonical .pbm file will be written alongside it with the same stem.

• shape (tuple of int, default (3, 3, 3)) – Number of blocks along the logical ijk axes.

• block_size (tuple of float, default (1, 1, 1)) – Block dimensions along each logical axis.

• corner (tuple of float, default (-0.5, -0.5, -0.5)) – World‑space coordinates of the block with indices (i=0, j=0, k=0) lower corner.

• axis_azimuth (float, default 0.0) – Rotation angles defining orientation of the logical ijk axes relative to the world xyz frame. These are converted to an orthonormal basis (axis_u, axis_v, axis_w) used by RegularGeometry.

• axis_dip (float, default 0.0) – Rotation angles defining orientation of the logical ijk axes relative to the world xyz frame. These are converted to an orthonormal basis (axis_u, axis_v, axis_w) used by RegularGeometry.

• axis_plunge (float, default 0.0) – Rotation angles defining orientation of the logical ijk axes relative to the world xyz frame. These are converted to an orthonormal basis (axis_u, axis_v, axis_w) used by RegularGeometry.

• deposit_bearing (float) – Orientation of the synthetic deposit in degrees.

• deposit_dip (float) – Orientation of the synthetic deposit in degrees.

• deposit_plunge (float) – Orientation of the synthetic deposit in degrees.

• grade_name (str, default "grade") – Name of the column storing the simulated grade values.

• grade_min (float) – Minimum and maximum grade values for the toy distribution.

• grade_max (float) – Minimum and maximum grade values for the toy distribution.

• deposit_center (tuple of float) – Center of the ellipsoidal deposit in world xyz coordinates.

• deposit_radii (tuple of float) – Semi‑axes of the deposit ellipsoid in world units.

• noise_std (float, default 0.0) – Absolute standard deviation of Gaussian noise added to grades.

• noise_rel (float, optional) – Relative standard deviation expressed as a fraction of (grade_max - grade_min). Mutually exclusive with noise_std.

• noise_seed (int, optional) – Seed used for reproducible Gaussian noise.

Returns:

A ParquetBlockModel backed by a canonical .pbm file with the generated toy data and geometry metadata.

Return type:

ParquetBlockModel

Notes

For rotated geometries (non‑zero rotation angles), xyz centroids will appear rotated in world coordinates relative to the ijk axes of the grid. Geometry validation is skipped in this case to avoid imposing axis‑aligned assumptions on the rotated layout.

downsample(new_block_size, aggregation_config)

Downsample the block model to a coarser grid with specified aggregation methods for each attribute. This function supports downsampling of both categorical and numeric attributes. :type new_block_size: :param new_block_size: tuple of floats (dx, dy, dz) for the new block size. :type aggregation_config: :param aggregation_config: dict mapping attribute names to aggregation methods.

Use basis for weighted_mean configurations.

Example

aggregation_config = {

‘grade’: {‘method’: ‘weighted_mean’, ‘basis’: ‘dry_mass’}, ‘density’: {‘method’: ‘weighted_mean’, ‘basis’: ‘volume’}, ‘dry_mass’: {‘method’: ‘sum’}, ‘volume’: {‘method’: ‘sum’}, ‘rock_type’: {‘method’: ‘mode’}

}

Returns:

A new ParquetBlockModel instance with the downsampled grid.

Return type:

ParquetBlockModel

ensure_spatial()

Ensure canonical spatial columns exist; recompute when missing.

Return type:

None

ensure_world_id()

Ensure world_id exists; recompute when missing.

Return type:

None

evaluate_surface(surface, *, column)

Evaluate a Surface and persist the resulting values into a column.

Return type:

ndarray

flag_polygon(polygon, *, column, inside_value=None, outside_value=<NA>, as_categorical=None)

Evaluate a PolygonField and persist a new flag/domain column.

Returns the dense boolean inside/outside mask aligned to geometry C-order.

Return type:

ndarray

flag_solid(solid, *, column, inside_value=None, outside_value=<NA>, as_categorical=None)

Evaluate a MeshSolid and persist a new flag/domain column.

Returns the dense boolean inside/outside mask aligned to geometry C-order.

Return type:

ndarray

classmethod from_dataframe(dataframe, filename, geometry=None, name=None, overwrite=False, axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0, chunk_size=1000000, schema=None, engine_initializer=None, compression='fast')

Create a ParquetBlockModel from a pandas DataFrame.

This constructor is oriented towards xyz-indexed DataFrames, where the index is a centroid MultiIndex with levels ("x", "y", "z") in world coordinates.

The DataFrame is written to a sibling .pbm file (replacing the .parquet suffix of filename) with embedded RegularGeometry metadata. Geometry is either supplied explicitly or inferred from the xyz centroids via RegularGeometry.from_multi_index().

Parameters:

• dataframe (pandas.DataFrame) – Block model data indexed by centroid coordinates with dataframe.index.names == ["x", "y", "z"].

• filename (Path) – Path to the source .parquet file which will be used as the basis for the sibling .pbm container.

• geometry (RegularGeometry, optional) – Geometry of the logical ijk grid. If omitted, it is inferred from the centroid MultiIndex, using the optional rotation angles to define the ijk axis orientation.

• name (str, optional) – Optional name for the resulting ParquetBlockModel. Defaults to filename.stem.

• overwrite (bool, default False) – If True, allows overwriting an existing .pbm file at the derived path.

• axis_azimuth (float, default 0.0) – Optional rotation angle used when inferring geometry from the xyz centroids. Defines the orientation of the logical ijk axes relative to the world coordinate frame.

• axis_dip (float, default 0.0) – Optional rotation angle. See axis_azimuth.

• axis_plunge (float, default 0.0) – Optional rotation angle. See axis_azimuth.

• chunk_size (int, default 1_000_000) – Batch size for writing Parquet data.

• schema (DataFrameSchema or Path, optional) – Optional pandera schema used to validate and coerce the DataFrame before writing. Accepts a DataFrameSchema object or a Path to a YAML schema file. When provided the schema is also stored on the resulting instance (self.schema).

Returns:

A block model backed by the newly written .pbm file.

Return type:

ParquetBlockModel

Note

New ijk-first workflows are encouraged to construct a RegularGeometry explicitly and use ParquetBlockModel.from_geometry() or ParquetBlockModel.from_parquet(). This helper remains for backwards compatibility with xyz-indexed DataFrames.

classmethod from_geometry(geometry, path, name=None, schema=None, engine_initializer=None, compression='fast')

Create a ParquetBlockModel from a geometry only.

This constructor materialises a dense ijk grid defined by a RegularGeometry into a Parquet file with xyz centroid columns but no additional attributes. It is useful for creating an empty block model skeleton that can be joined with external attribute data.

Parameters:

• geometry (RegularGeometry) – Geometry of the logical ijk grid.

• path (Path) – Path to the target .pbm file. The file will contain a row for every ijk block with derived xyz centroid columns and embedded geometry metadata.

• name (str, optional) – Optional name for the resulting ParquetBlockModel.

• schema (DataFrameSchema or Path, optional) – Optional pandera schema stored on the resulting instance (self.schema). Accepts a DataFrameSchema object or a Path to a YAML schema file.

Returns:

A block model with geometry defined but no attribute columns.

Return type:

ParquetBlockModel

classmethod from_parquet(parquet_path, columns=None, overwrite=False, axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0, chunk_size=1000000, schema=None, engine_initializer=None, compression='fast')

Create a ParquetBlockModel from a source Parquet file.

This helper promotes a source .parquet file (typically xyz-centric) into a canonical .pbm container with embedded RegularGeometry metadata.

The input Parquet is expected to contain centroid columns x, y, z describing block centroids in world coordinates. RegularGeometry is reconstructed from those centroids and/or any existing "parq-blockmodel" metadata via RegularGeometry.from_parquet(). Geometry becomes the authoritative description of the dense ijk grid; xyz centroids are treated as a derived view.

Parameters:

• parquet_path (Path) – Path to the source Parquet file. If the suffix is .pbm and overwrite is False, a ValueError is raised to avoid mutating an existing canonical container.

• columns (list[str], optional) – Optional subset of columns to copy from the source file into the resulting .pbm file. If None, all columns are copied.

• overwrite (bool, default False) – If True, allows overwriting an existing .pbm file at the target location.

• axis_azimuth (float, default 0.0) – Optional rotation angle used by RegularGeometry.from_parquet() to define the orientation of the logical ijk axes in world coordinates when inferring geometry. In the common case geometry is read directly from existing metadata and this parameter is 0.

• axis_dip (float, default 0.0) – Optional rotation angle. See axis_azimuth.

• axis_plunge (float, default 0.0) – Optional rotation angle. See axis_azimuth.

• chunk_size (int, default 1_000_000) – Batch size for reading Parquet data.

• schema (DataFrameSchema or Path, optional) – Optional pandera schema used to validate and coerce each chunk during the canonical write. Accepts a DataFrameSchema object or a Path to a YAML schema file. When provided the schema is also stored on the resulting instance (self.schema).

Returns:

A block model backed by a newly written .pbm file

located alongside parquet_path.

Return type:

ParquetBlockModel

property grid: RegularGeometry

Backward-compatible access to the canonical block model grid.

property origin: tuple[float, float, float] | list[float]

Backward-compatible access to the world-frame origin.

property persisted_attributes: list[str]

Persisted block-property columns (non-positional).

property persisted_columns: list[str]

Column names physically persisted in the backing parquet.

plot(scalar, grid_type='image', frame='world', threshold=True, show_edges=True, show_axes=True, enable_picking=False, picked_attributes=None, z_up_lock=False, z_up_hotkey='z', elevation_raster=None, imagery_raster=None, engine=None)

Plot the block model using PyVista.

Parameters:

• scalar (str) – The name of the scalar attribute to visualize.

• grid_type (Literal['image', 'structured', 'unstructured']) – The type of grid to use for plotting. Options are “image”, “structured”, or “unstructured”.

• frame (Literal['world', 'local']) – Coordinate frame for image grids. "world" applies geometry axis vectors; "local" uses axis-aligned local ijk orientation. Only supported for grid_type="image".

• threshold (bool) – The thresholding option for the mesh. If True, applies a threshold to the scalar values.

• show_edges (bool) – Show edges of the mesh.

• show_axes (bool) – Show the axes in the plot.

• enable_picking (bool) – If True, enables picking mode to interactively select cells in the plot.

• picked_attributes (Optional[list[str]]) – A list of attributes that will be returned in picking mode. If None, all attributes are returned.

• z_up_lock (bool) – If True, hold the configured hotkey during interaction to enforce +Z camera up direction.

• z_up_hotkey (str) – Single-letter hotkey used with z_up_lock. Defaults to "z".

• elevation_raster (Union[str, Path, None]) – Optional raster path used to build an elevation surface overlay in PyVista.

• imagery_raster (Union[str, Path, None]) – Optional raster path used as a texture for the elevation surface in PyVista.

Return type:

Any

Returns:

plot_heatmap(attribute, threshold, axis='z', title=None)

Create a 2D heatmap plotly figure from a 3D block model at a specified attribute threshold.

Parameters:

• attribute (str) – The name of the attribute to threshold.

• threshold (float) – The threshold value for the attribute.

• axis (str) – The axis to view from (‘x’, ‘y’, or ‘z’). Defaults to ‘z’.

• title (Optional[str]) – The title of the heatmap. If None, a default title is used.

Returns:

A Plotly figure containing the heatmap.

Return type:

go.Figure

property position_columns: list[str]

Persisted positional/identity columns present on disk.

read(columns=None, index='xyz', dense=False, include_calculated=False)

Read the Parquet file and return a DataFrame.

Notes

Current behaviour (for backwards compatibility):

• index="xyz" (the default) returns a DataFrame indexed by centroid coordinates (x, y, z). This matches the original design where xyz are treated as canonical.

• index="ijk" returns a DataFrame whose index is derived from RegularGeometry via to_ijk_multi_index.

Option B design (future change, not yet enforced):

• The canonical in-memory representation will become an (i, j, k) MultiIndex with attributes-only columns.

• xyz (centroid) coordinates will be treated as a derived view computed from (i, j, k) + geometry, exposed via a helper such as as_xyz() or via pandas accessors that read geometry from df.attrs["parq-blockmodel"].

• Plotting helpers (PyVista, Plotly) will consume ijk + geometry and compute xyz internally when needed, so they do not rely on xyz being persisted as data columns.

Until that refactor is complete, this method preserves the existing xyz-first semantics so that external callers continue to work.

Parameters:

• columns (Optional[list[str]]) – List of column names to read. If None, all columns are read.

• index (Literal['xyz', 'ijk', None]) – The index type to use for the DataFrame. Options are "xyz" for centroid coordinates, "ijk" for block indices, or None for no index.

• dense (bool) – If True, reads/reindexes to the full dense grid. If False, returns the sparse layout in the underlying file.

• include_calculated (bool) – If True, include available calculated columns (schema-defined and intrinsic) in the default no-argument read. Explicit column requests still behave as before.

Returns:

The DataFrame containing the block model data.

Return type:

pd.DataFrame

Notes

index="xyz" is preserved as the default for backwards compatibility with earlier versions of parq_blockmodel that treated centroid coordinates as canonical. New code is encouraged to pass index="ijk" explicitly and work in terms of logical grid indices plus geometry.

recompute_spatial()

Recompute and persist canonical spatial columns (x, y, z, i, j, k).

Return type:

None

recompute_world_id()

Recompute and persist world_id from current spatial columns and encoding metadata.

Return type:

None

rename(new_pbm_filepath, rename_to_new_pbm_stem=True)

Rename the underlying .pbm file and refresh path-bound caches.

Parameters:

• new_pbm_filepath (Path) – Target .pbm file path.

• rename_to_new_pbm_stem (bool, default True) – If True, update self.name to the new file stem.

Returns:

Self (mutated).

Return type:

ParquetBlockModel

Notes

This method only relocates the file on disk and refreshes internal caches. Any computed columns held in memory (not persisted to the original .pbm) will not be saved to the new location. Persist them first:

>>> pbm.write(df_with_new_columns).rename(Path("new_location.pbm"))

property schema_service: SchemaService

Lazy-initialized schema service (recreated if schema or engine changes).

Returns:

Stateful schema service bound to current geometry and schema.

Return type:

SchemaService

to_dense_parquet(filepath, chunk_size=100000, show_progress=False)

Export the block model as a dense xyz-indexed Parquet file.

The underlying .pbm may be sparse with respect to the dense ijk grid encoded by geometry. This helper iterates over the on‑disk data in chunks, reindexes each chunk to the full dense centroid MultiIndex geometry.to_multi_index_xyz() and writes the result to filepath.

Parameters:

• filepath (Path) – Target path for the exported Parquet file.

• chunk_size (int, default 100_000) – Number of rows to process per chunk when reading from the backing .pbm file.

• show_progress (bool, default False) – If True, display a progress bar while exporting.

Return type:

None

Notes

This export is primarily intended for interoperability with tools that expect a fully populated xyz grid. The canonical representation of the block model remains the .pbm file with embedded RegularGeometry metadata.

to_glb(output_path, attributes=None, texture_attribute=None, colormap='viridis', surface_only=True, sparse=None)

Export the block model as a GLB (glTF 2.0 binary) mesh.

GLB is a derived format for external visualization in 3D viewers. Optionally applies vertex colors based on a scalar attribute (e.g., grade, density). Geometry metadata is embedded in the glTF extras field for reference.

Parameters:

• output_path (str or Path) – Target GLB file path.

• attributes (list[str], optional) – Block attributes to include (stored in glTF extensions).

• texture_attribute (str, optional) – Attribute name to use for vertex coloring (e.g., “grade”). Must be numeric. If None, uses default gray material.

• colormap (str, default "viridis") – Matplotlib colormap name for mapping texture_attribute to colors. Examples: “viridis”, “plasma”, “coolwarm”, “Greys”.

• surface_only (bool, default True) – If True, export only exterior surface faces.

• sparse (bool, optional) – If True, export only existing blocks. If None, infer from model sparsity.

Returns:

The output file path (pathlib.Path).

Return type:

Path

Notes

GLB format is optimized for visualization and may lose some precision compared to PLY. For scientific workflows requiring lossless data preservation, prefer to_ply().

The texture_attribute is normalized to [0, 1] and mapped to the specified colormap. NaN values are rendered as transparent.

Examples

>>> pbm = ParquetBlockModel(Path("model.pbm"))
>>> pbm.to_glb("model.glb", texture_attribute="grade", colormap="viridis")

to_ply(output_path, attributes=None, surface_only=True, sparse=None, binary=False)

Export the block model as a PLY (Polygon File Format) mesh.

PLY is the canonical format for mesh storage, supporting lossless round-tripping of all geometry and attribute data. The output file includes: - Vertex coordinates in world space - Face connectivity (triangles) - Per-vertex and per-face attributes (grades, rock type, etc.) - Block logical indices (i, j, k) for traceability - Geometry metadata (corner, block_size, shape, axes, CRS)

Parameters:

• output_path (str or Path) – Target PLY file path.

• attributes (list[str], optional) – Block attributes to include. If None, only geometry is exported.

• surface_only (bool, default True) – If True, export only exterior surface faces.

• sparse (bool, optional) – If True, export only existing blocks. If None, infer from model sparsity.

• binary (bool, default False) – If True, write binary PLY (smaller file, less readable). If False, write ASCII PLY (larger, human-readable).

Returns:

The output file path (pathlib.Path).

Return type:

Path

Notes

Units and coordinate system are inherited from geometry. For rotated geometries, world-space coordinates reflect the rotation.

Examples

>>> pbm = ParquetBlockModel(Path("model.pbm"))
>>> pbm.to_ply("model.ply", attributes=["grade", "density"])

triangulate(attributes=None, surface_only=True, sparse=None)

Generate a triangulated mesh from the block model.

Creates a triangle mesh representation of the block model geometry, optionally including block attributes (grades, rock types, etc.) as vertex or face attributes.

Parameters:

• attributes (list[str], optional) – List of attribute columns to include in the mesh. If None, only geometry is included (no attributes). Attributes must be in self.attributes.

• surface_only (bool, default True) – If True, include only exterior surface faces. If False, include all interior faces as well. Useful for sparse models.

• sparse (bool, optional) – If True (or None and sparse model detected), include only blocks that exist in the data. If False, generate mesh for full dense grid.

Returns:

Triangle mesh with vertices, faces, and optional attributes.

Return type:

parq_blockmodel.mesh.TriangleMesh

Notes

The mesh uses right-handed coordinates in world space, with rotation applied via geometry axis vectors. Attributes are preserved as per-vertex or per-face properties. For sparse models, only surface faces are typically needed (surface_only=True).

Examples

>>> pbm = ParquetBlockModel(Path("model.pbm"))
>>> mesh = pbm.triangulate(attributes=["grade", "density"], surface_only=True)
>>> print(f"Mesh: {mesh.n_vertices} vertices, {mesh.n_faces} faces")

upsample(new_block_size, upsample_config=None, interpolation_config=None)

Upsample the block model to a finer grid with specified methods for each attribute. This function supports upsampling of both categorical and numeric attributes. :type new_block_size: :param new_block_size: tuple of floats (dx, dy, dz) for the new block size. :type upsample_config: :param upsample_config: dict mapping attribute names to upsampling methods

(linear, nearest, mode, parent).

Parameters:

interpolation_config – deprecated alias of upsample_config.

Example

upsample_config = {

‘grade’: ‘linear’, ‘density’: ‘linear’, ‘dry_mass’: ‘linear’, ‘volume’: ‘linear’, ‘rock_type’: ‘mode’

}

Returns:

A new ParquetBlockModel instance with the upsampled grid.

Return type:

ParquetBlockModel

validate(schema=None, sample_chunks=0)

Validate the block model data against a pandera schema.

Reads the backing .pbm file in chunks and validates each chunk against the supplied (or stored) schema.

Parameters:

• schema (Union[Path, DataFrameSchema, None]) – A pandera DataFrameSchema to validate against. When None (default) self.schema is used.

• sample_chunks (int) – Number of chunks to validate. 0 (default) validates every chunk; a positive integer limits validation to that many leading chunks, which is useful for quick spot-checks on large models.

Returns:

True when all validated chunks pass.

Return type:

bool

Raises:

• ValueError – If no schema is available (neither passed nor stored).

• pandera.errors.SchemaErrors – If any chunk fails validation (when pandera raises in lazy mode).

validate_special_columns(sample_size=1000)

Validate consistency of special columns against geometry and encoding metadata.

Returns False when any available positional representation disagrees with another (for example block_id vs ijk/xyz, or world_id vs xyz + world_id_encoding). sample_size controls validation sampling for large datasets (set 0 to validate all rows).

Return type:

bool

classmethod validate_xyz_parquet(parquet_path, axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0, chunk_size=1000000, tol=1e-06)

Validate xyz-defined Parquet input and return inferred geometry.

This is a backwards-compatible wrapper that delegates to ingest_utils.validate_xyz_parquet().

Return type:

RegularGeometry

write(dataframe, *, merge=False, index_columns=None, batch_size=1000000, allow_overwrite=True, show_progress=False, compression='fast', **pq_write_kwargs)

Persist data to the backing .pbm file.

Parameters:

• dataframe (pd.DataFrame) – Data to persist.

• merge (bool, default False) – If False, rewrite the file using only dataframe columns. If True, append columns from dataframe to existing parquet rows using key alignment (streamed via parq-tools).

• index_columns (list[str], optional) – Key columns used for merge alignment. Defaults to ["block_id"] when available, then ["i", "j", "k"], then ["x", "y", "z"].

• batch_size (int, default 1_000_000) – Streaming batch size used when merge=True.

• allow_overwrite (bool, default True) – Forwarded to merge helper.

• show_progress (bool, default False) – Forwarded to merge helper.

• compression (str or int, default "fast") – Active write compression policy. “fast”/0 maps to snappy; integers greater than zero map to zstd at that level.

• **pq_write_kwargs (object) – Extra args forwarded to parquet writer (merge mode).

Return type:

ParquetBlockModel