parq_blockmodel.geometry.RegularGeometry

parq_blockmodel.geometry.RegularGeometry#

class parq_blockmodel.geometry.RegularGeometry(local=None, world=None, schema_version='1.0', world_id_encoding=None, corner=None, block_size=None, shape=None, axis_u=None, axis_v=None, axis_w=None, srs=None)[source]#

Dense, metadata-defined block model geometry (C-order canonical).

This class describes all block model geometry in parq-blockmodel. It does not store x, y, z or i, j, k per block. All coordinates are derived from metadata + implicit row ordering.

local#

The local lattice geometry (corner, block_size, shape, C-order).

Type:

LocalGeometry

world#

The world embedding with origin, axes, and CRS.

Type:

WorldFrame

schema_version#

Version of the metadata schema. Default: “1.0”

Type:

str

world_id_encoding#

Encoding for world IDs.

Type:

dict, optional

Note

Internal Storage Ordering (C-order canonical)

parq-blockmodel uses NumPy C-order as its canonical definition of block ordering:

  • i varies fastest

  • j varies next

  • k varies slowest

  • r = i + ni * (j + nj * k)

This matches:

  • Parquet row-oriented storage naturally

  • NumPy operations (ravel, reshape)

  • Efficient dense arrays

  • Our metadata-based geometry model

This does NOT match lexicographic MultiIndex sorting (.sort_index([“x”, “y”, “z”])) which yields x slowest, z fastest. MultiIndex lexicographic sorting must NOT define canonical storage.

F-order is NOT used (even though OMF/VTK are sometimes described this way). PyVista accepts C-order 1D arrays perfectly fine.

Canonical = C-order. Do not switch to F-order.

__init__(local=None, world=None, schema_version='1.0', world_id_encoding=None, corner=None, block_size=None, shape=None, axis_u=None, axis_v=None, axis_w=None, srs=None)[source]#

Initialize RegularGeometry.

Can be called with either: 1. New style: RegularGeometry(local=…, world=…) 2. Old style: RegularGeometry(corner=…, block_size=…, shape=…, axis_u=…) 3. Or mix default parameters with keyword overrides

Methods

__init__([local, world, schema_version, ...])

Initialize RegularGeometry.

create([corner, block_size, shape, axis_u, ...])

Convenience factory for creating RegularGeometry with keyword arguments.

from_attrs(attrs[, key])

Reconstruct geometry from a DataFrame.attrs-style mapping.

from_metadata(meta)

Reconstruct geometry from stored metadata.

from_multi_index(index[, axis_azimuth, ...])

Infer geometry from an xyz centroid MultiIndex.

from_parquet(filepath[, axis_azimuth, ...])

Reconstruct geometry from a Parquet file.

from_parquet_metadata(metadata[, key])

Reconstruct geometry from Parquet file metadata.

ijk_from_row_index(rows)

Convert row index/indices into (i, j, k) using C‑order.

ijk_from_xyz(x, y, z[, tol])

Map world-space centroid coordinates to integer logical ijk indices.

row_index_from_ijk(i, j, k)

Convert (i, j, k) into row index using C‑order.

row_index_from_xyz(x, y, z[, tol])

Map world-space centroid coordinates directly to C-order row indices.

to_dataframe()

Backward-compatible alias for to_dataframe_xyz().

to_dataframe_xyz()

Return a DataFrame of XYZ centroids for export/inspection.

to_metadata_dict()

Serialize geometry metadata for Parquet storage.

to_multi_index_ijk()

Export (i, j, k) indices as a MultiIndex in C‑order.

to_multi_index_xyz()

Return XYZ centroid coordinates as a MultiIndex.

to_pyvista(*[, frame])

Return a pyvista.ImageData representing the dense grid.

xyz_from_ijk(i, j, k)

Convert logical indices to world-space centroid coordinates.

xyz_from_row_index(rows)

Convert C-order row index/indices to world-space centroid coordinates.

Attributes

axis_u

Backward-compatible access to U-axis.

axis_v

Backward-compatible access to V-axis.

axis_w

Backward-compatible access to W-axis.

block_size

Backward-compatible access to local-axis block spacing (dx, dy, dz).

centroid_x

centroid_y

centroid_z

corner

Backward-compatible access to local corner.

extents

Return the axis-aligned bounding box (xmin, xmax, ymin, ymax, zmin, zmax).

is_rotated

Return True if axes differ from the identity orientation.

origin

Backward-compatible access to world origin.

schema_version

shape

Backward-compatible access to grid shape.

srs

Backward-compatible access to spatial reference system.

world_id_encoding

local

world

property axis_u: tuple[float, float, float] | list[float] | ndarray[Any, dtype[floating]]#

Backward-compatible access to U-axis.

property axis_v: tuple[float, float, float] | list[float] | ndarray[Any, dtype[floating]]#

Backward-compatible access to V-axis.

property axis_w: tuple[float, float, float] | list[float] | ndarray[Any, dtype[floating]]#

Backward-compatible access to W-axis.

property block_size: tuple[float, float, float]#

Backward-compatible access to local-axis block spacing (dx, dy, dz).

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

Backward-compatible access to local corner.

classmethod create(corner=(0.0, 0.0, 0.0), block_size=(1.0, 1.0, 1.0), shape=(1, 1, 1), axis_u=(1.0, 0.0, 0.0), axis_v=(0.0, 1.0, 0.0), axis_w=(0.0, 0.0, 1.0), srs=None)[source]#

Convenience factory for creating RegularGeometry with keyword arguments.

This is the recommended way to construct geometries when you have individual parameters rather than pre-built LocalGeometry and WorldFrame.

Parameters:

  • corner (Point, optional) – Local corner (u₀, v₀, w₀) of block (i=0, j=0, k=0). Defaults to (0, 0, 0).

  • block_size (BlockSize, optional) – Block dimensions (dx, dy, dz) along the local i/j/k (u/v/w) axes. Defaults to (1, 1, 1).

  • shape (Shape3D, optional) – Number of blocks (nᵢ, nⱼ, nₖ). Defaults to (1, 1, 1).

  • axis_u (Vector, optional) – Orthonormal U-axis for world embedding. Defaults to (1, 0, 0).

  • axis_v (Vector, optional) – Orthonormal V-axis for world embedding. Defaults to (0, 1, 0).

  • axis_w (Vector, optional) – Orthonormal W-axis for world embedding. Defaults to (0, 0, 1).

  • srs (str, optional) – Spatial reference system identifier.

Returns:

New geometry instance.

Return type:

RegularGeometry

property extents: tuple[float, float, float, float, float, float]#

Return the axis-aligned bounding box (xmin, xmax, ymin, ymax, zmin, zmax).

For unrotated geometries this is derived directly from corner, block_size, and shape. For rotated geometries, we conservatively compute extents from the centroid cloud.

classmethod from_attrs(attrs, key='parq-blockmodel')[source]#

Reconstruct geometry from a DataFrame.attrs-style mapping.

attrs[key] is expected to contain the dict produced by to_metadata_dict() (or a compatible future schema that from_metadata() can consume).

Return type:

RegularGeometry

classmethod from_metadata(meta)[source]#

Reconstruct geometry from stored metadata.

Return type:

RegularGeometry

classmethod from_multi_index(index, axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0)[source]#

Infer geometry from an xyz centroid MultiIndex.

Convenience constructor used by ParquetBlockModel.from_dataframe() when no explicit geometry is provided. The index must have levels ("x", "y", "z") in world coordinates.

Parameters:

  • index (pd.MultiIndex) – Centroid coordinates with names ["x", "y", "z"].

  • axis_azimuth (float) – Optional rotation angles (degrees) defining the orientation of the logical ijk axes in world space.

  • axis_dip (float) – Optional rotation angles (degrees) defining the orientation of the logical ijk axes in world space.

  • axis_plunge (float) – Optional rotation angles (degrees) defining the orientation of the logical ijk axes in world space.

Return type:

RegularGeometry

classmethod from_parquet(filepath, axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0, chunk_size=1000000)[source]#

Reconstruct geometry from a Parquet file.

Preferred path is to read geometry metadata from the Parquet key_value_metadata under the reserved key "parq-blockmodel". If that key is missing, fall back to centroid-based inference using x, y, z columns and provided rotation angles. :rtype: RegularGeometry

Todo

Consider efficiency gains by staying in numpy versus using python sets.

classmethod from_parquet_metadata(metadata, key='parq-blockmodel')[source]#

Reconstruct geometry from Parquet file metadata.

Parameters:

  • metadata (Any) – Either a pyarrow.parquet.FileMetaData instance or a mapping of key-value metadata (usually dict[str, str]).

  • key (str) – Metadata key under which the geometry payload is stored.

Returns:

The reconstructed geometry.

Return type:

RegularGeometry

Raises:

  • KeyError – If the key is not present in the provided metadata.

  • TypeError – If metadata is not a valid type.

  • ValueError – If the payload cannot be interpreted as valid geometry metadata.

ijk_from_row_index(rows)[source]#

Convert row index/indices into (i, j, k) using C‑order.

ijk_from_xyz(x, y, z, tol=1e-06)[source]#

Map world-space centroid coordinates to integer logical ijk indices.

Return type:

tuple[ndarray, ndarray, ndarray]

property is_rotated: bool#

Return True if axes differ from the identity orientation.

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

Backward-compatible access to world origin.

row_index_from_ijk(i, j, k)[source]#

Convert (i, j, k) into row index using C‑order.

row_index_from_xyz(x, y, z, tol=1e-06)[source]#

Map world-space centroid coordinates directly to C-order row indices.

Return type:

ndarray

property shape: tuple[int, int, int] | list[float]#

Backward-compatible access to grid shape.

property srs: str | None#

Backward-compatible access to spatial reference system.

to_dataframe()[source]#

Backward-compatible alias for to_dataframe_xyz().

Return type:

DataFrame

to_dataframe_xyz()[source]#

Return a DataFrame of XYZ centroids for export/inspection.

Return type:

DataFrame

to_metadata_dict()[source]#

Serialize geometry metadata for Parquet storage.

Return type:

dict

to_multi_index_ijk()[source]#

Export (i, j, k) indices as a MultiIndex in C‑order.

Return type:

MultiIndex

to_multi_index_xyz()[source]#

Return XYZ centroid coordinates as a MultiIndex. :rtype: MultiIndex

Note

This MultiIndex preserves C‑order row layout. If you want lexicographic (‘x slowest, z fastest’), sort it explicitly:

mi = geom.to_multi_index_xyz().sort_index()

to_pyvista(*, frame='world')[source]#

Return a pyvista.ImageData representing the dense grid.

Parameters:

frame (str, optional) – Coordinate frame used for the returned grid. - "world" (default): apply world orientation from axis_u/v/w. - "local": return axis-aligned local grid (no rotation).

Returns:

The grid representation.

Return type:

pyvista.ImageData

Note

In "world" mode, rotation is encoded using the ImageData direction matrix, so plotting reflects geometry orientation.

xyz_from_ijk(i, j, k)[source]#

Convert logical indices to world-space centroid coordinates.

Return type:

tuple[ndarray, ndarray, ndarray]

xyz_from_row_index(rows)[source]#

Convert C-order row index/indices to world-space centroid coordinates.

Return type:

tuple[ndarray, ndarray, ndarray]