Metadata-Version: 2.4
Name: parq-blockmodel
Version: 0.12.6
Summary: A Python package for efficient storage, manipulation, and analysis of mining block models using Parquet files.
Author-email: Greg Elphick <11791585+elphick@users.noreply.github.com>
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Requires-Dist: geopandas<2,>=1.1.1
Requires-Dist: numpy<2.1,>=1.25.2
Requires-Dist: parq-tools>=0.4.0
Requires-Dist: pyarrow>=16.0
Requires-Dist: pyvista>=0.44.2
Requires-Dist: scipy>=1.11
Provides-Extra: all
Requires-Dist: df-eval>=0.1.4; extra == 'all'
Requires-Dist: ezdxf>=1.3.0; extra == 'all'
Requires-Dist: imageio-ffmpeg<1,>=0.6.0; extra == 'all'
Requires-Dist: imageio<3,>=2.37.0; extra == 'all'
Requires-Dist: kaleido<2,>=1.1.0; extra == 'all'
Requires-Dist: pandera<0.21,>=0.19; extra == 'all'
Requires-Dist: plotly<7,>=6.1.1; extra == 'all'
Requires-Dist: plyfile>=1.0.0; extra == 'all'
Requires-Dist: rioxarray>=0.18.0; extra == 'all'
Requires-Dist: setuptools<81; extra == 'all'
Requires-Dist: tqdm>=4.67.1; extra == 'all'
Requires-Dist: trame-vtk<3,>=2.9.0; extra == 'all'
Requires-Dist: trame-vuetify<4,>=3.0.1; extra == 'all'
Requires-Dist: trame<4,>=3.10.2; extra == 'all'
Requires-Dist: ydata-profiling>=4.16.1; extra == 'all'
Provides-Extra: cad
Requires-Dist: ezdxf>=1.3.0; extra == 'cad'
Provides-Extra: mesh
Requires-Dist: plyfile>=1.0.0; extra == 'mesh'
Provides-Extra: profiling
Requires-Dist: setuptools<81; extra == 'profiling'
Requires-Dist: ydata-profiling>=4.16.1; extra == 'profiling'
Provides-Extra: progress
Requires-Dist: tqdm>=4.67.1; extra == 'progress'
Provides-Extra: schema
Requires-Dist: df-eval>=0.2.1; extra == 'schema'
Requires-Dist: pandera<0.21,>=0.19; extra == 'schema'
Provides-Extra: temporal
Requires-Dist: imageio-ffmpeg<1,>=0.6.0; extra == 'temporal'
Requires-Dist: imageio<3,>=2.37.0; extra == 'temporal'
Requires-Dist: rioxarray>=0.18.0; extra == 'temporal'
Provides-Extra: viz
Requires-Dist: kaleido<2,>=1.1.0; extra == 'viz'
Requires-Dist: plotly<7,>=6.1.1; extra == 'viz'
Requires-Dist: trame-vtk<3,>=2.9.0; extra == 'viz'
Requires-Dist: trame-vuetify<4,>=3.0.1; extra == 'viz'
Requires-Dist: trame<4,>=3.10.2; extra == 'viz'
Description-Content-Type: text/markdown

<h1 style="display: inline-flex; align-items: center; gap: 0.4rem; margin: 0;">
  <img src="https://raw.githubusercontent.com/elphick/parq-blockmodel/main/docs/_static/branding/parq-blockmodel.svg" alt="parq-blockmodel logo" width="72" style="display: block; margin-top: 20px;" />
  <span>parq-blockmodel</span>
</h1>

[![Run Tests](https://github.com/Elphick/parq-blockmodel/actions/workflows/build_and_test.yml/badge.svg?branch=main)](https://github.com/Elphick/parq-blockmodel/actions/workflows/build_and_test.yml)
[![PyPI](https://img.shields.io/pypi/v/parq-blockmodel?logo=python&logoColor=white)](https://pypi.org/project/parq-blockmodel/)
![Coverage](https://raw.githubusercontent.com/elphick/parq-blockmodel/main/docs/_static/badges/coverage.svg)
[![Python Versions](https://img.shields.io/pypi/pyversions/parq-blockmodel)](https://pypi.org/project/parq-blockmodel/)
[![License](https://img.shields.io/github/license/Elphick/parq-blockmodel?cacheSeconds=86400)](https://pypi.org/project/parq-blockmodel/)
[![Publish Docs](https://github.com/Elphick/parq-blockmodel/actions/workflows/docs_to_gh_pages.yml/badge.svg?branch=main)](https://github.com/Elphick/parq-blockmodel/actions/workflows/docs_to_gh_pages.yml)
[![Open Issues](https://img.shields.io/github/issues/Elphick/parq-blockmodel?cacheSeconds=86400)](https://github.com/Elphick/parq-blockmodel/issues)
[![Open PRs](https://img.shields.io/github/issues-pr/Elphick/parq-blockmodel?cacheSeconds=86400)](https://github.com/Elphick/parq-blockmodel/pulls)

## 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:

```bash
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:

```bash
pip install "parq-blockmodel[schema]"
```

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

```bash
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:

```python
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](https://parq-blockmodel.readthedocs.io/en/stable/user_guide/07_calculated_attributes.html)
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.

```python
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](https://parq-blockmodel.readthedocs.io/en/stable/user_guide/08_polygon_flagging.html) for 2D XY regions.
* [Surface encoding](https://parq-blockmodel.readthedocs.io/en/stable/user_guide/09_surface_encoding.html) for 2.5D elevation surfaces (`z = f(x, y)`).
* [Solid flagging](https://parq-blockmodel.readthedocs.io/en/stable/user_guide/10_solid_flagging.html) for closed 3D volumes.