geoh5py - Python API for geoh5 file format

0.12.1 verified Sat May 09 auth: no python

geoh5py is a Python library providing a high-level interface to read, write, and manipulate geoh5, an open file format for geoscientific data. It supports various geoscience objects like points, curves, surfaces, grids, drillholes, and 3D block models. Version 0.12.1 supports Python >=3.10,<4.0, and is actively maintained by Mira Geoscience with regular releases (approx. monthly).

pip install geoh5py

Common errors

error AttributeError: module 'geoh5py' has no attribute 'Workspace' ↓

cause Attempting to import Workspace from top-level geoh5py instead of geoh5py.workspace.

fix

Use 'from geoh5py.workspace import Workspace'.

error FileNotFoundError: [Errno 2] No such file or directory: 'example.geoh5' ↓

cause When opening a workspace for reading, the file must exist. Creating with 'Workspace('new.geoh5')' requires write mode.

fix

For creation, ensure the file path is writable; for reading, check the file exists.

error OSError: Unable to open file (unable to open file: name = '...', errno = 13, error message = 'Permission denied', flags = 0, o_flags = 0) ↓

cause The file is locked by another process (e.g., geoh5 GUI).

fix

Close the geoh5 file in any other application before opening with geoh5py.

error ValueError: Data values length does not match number of vertices ↓

cause Adding data with mismatched array length relative to object vertices or cells.

fix

Ensure the length of data values equals the number of base elements (e.g., vertices for PointData).

Warnings

breaking Python 3.9 or earlier is not supported. Requires Python >=3.10. ↓

fix Upgrade Python to 3.10+ or use geoh5py 0.9.2 (last supporting Python 3.9).

deprecated The 'get_data' method on objects returns a dict with keys as data names; in older versions it returned lists. Relying on order may break. ↓

fix Always access data by name, e.g., obj.get_data('my_data'), not by index.

gotcha Workspace files must be closed properly (via .close() or context manager). Otherwise, data may be lost or file locked. ↓

fix Use 'with Workspace('file.geoh5') as workspace:' or call workspace.close() after operations.

gotcha Colour data in VisualParameters returns BGR order, not RGB. This can cause unexpected colour rendering. ↓

fix Manually convert BGR to RGB when using colour values.

Imports

Workspace

wrong

from geoh5py import Workspace

correct

from geoh5py.workspace import Workspace

Workspace is in the workspace module, not top-level.

PointData

wrong

from geoh5py import PointData

correct

from geoh5py.objects import PointData

Object types are in the objects module.

Grid2D
```
from geoh5py.objects import Grid2D
```

Quickstart

Creates a geoh5 workspace, adds a PointData object with vertices and a data attribute, then closes.

from geoh5py.workspace import Workspace

# Create a new workspace
workspace = Workspace('example.geoh5')

# Add a point data object
from geoh5py.objects import PointData
import numpy as np

pts = PointData.create(workspace,
                       vertices=np.array([[0,0,0],[1,0,0],[0,1,0]]))

# Add data to points
pts.add_data({'elevation': {'values': np.array([100,200,300])}})

# Close workspace
workspace.close()