geoh5py.objects

geoh5py.objects.block_model

class geoh5py.objects.block_model.BlockModel(object_type: ObjectType, **kwargs)[source]

Bases: GridObject

Rectilinear 3D tensor mesh defined by three perpendicular axes. Each axis is divided into discrete intervals that define the cell dimensions. Nodal coordinates are determined relative to the origin and the sign of cell delimiters. Negative and positive cell delimiters are accepted to denote relative offsets from the origin.

property cell_delimiters
property centroids: ndarray | None

numpy.array, shape (n_cells, 3): Cell center locations in world coordinates.

centroids = [
    [x_1, y_1, z_1],
    ...,
    [x_N, y_N, z_N]
]
classmethod default_type_uid() → UUID[source]
Returns:

Default unique identifier

property n_cells: int | None

int: Total number of cells

property origin: ndarray

numpy.array of float, shape (3, ): Coordinates of the origin.

property rotation: float

float: Clockwise rotation angle (degree) about the vertical axis.

property shape: tuple | None

list of int, len (3, ): Number of cells along the u, v and z-axis

property u_cell_delimiters: ndarray | None

numpy.array of float: Nodal offsets along the u-axis relative to the origin.

property u_cells: ndarray | None

numpy.array of float, shape (shape [0], ): Cell size along the u-axis.

property v_cell_delimiters: ndarray | None

numpy.array of float: Nodal offsets along the v-axis relative to the origin.

property v_cells: ndarray | None

numpy.array of float, shape (shape [1], ): Cell size along the v-axis.

property z_cell_delimiters: ndarray | None

numpy.array of float: Nodal offsets along the z-axis relative to the origin (positive up).

property z_cells: ndarray | None

numpy.array of float, shape (shape [2], ): Cell size along the z-axis

geoh5py.objects.curve

class geoh5py.objects.curve.Curve(object_type: ObjectType, name='Curve', **kwargs)[source]

Bases: CellObject

Curve object defined by a series of line segments (cells) connecting vertices.

property cells: ndarray | None

numpy.ndarray of int, shape (*, 2): Array of indices defining segments connecting vertices. Defined based on parts if set by the user.

property current_line_id: UUID | None
classmethod default_type_uid() → UUID[source]
Returns:

Default unique identifier

property parts

numpy.array of int, shape (n_vertices, 2): Group identifiers for vertices connected by line segments as defined by the cells property. The definition of the cells property get modified by the setting of parts.

property unique_parts

list of int: Unique parts identifiers.

geoh5py.objects.drape_model

class geoh5py.objects.drape_model.DrapeModel(object_type: ObjectType, **kwargs)[source]

Bases: GridObject

Drape (curtain) model object made up of layers and prisms.

property centroids

numpy.array of float, shape (n_cells, 3): Cell center locations in world coordinates.

centroids = [
    [x_1, y_1, z_1],
    ...,
    [x_N, y_N, z_N]
]
classmethod default_type_uid() → UUID[source]

Default type uid.

property layers: ndarray | None

numpy.array, shape(, 3): Layers in the drape model with columns: X (prism index), K (depth index), elevation (cell bottom)). shape(, 3) organized into blocks representing each prism in the model.

layers = [
    [x_1, k_1, z_11],
    [x_1, k_2, z_12],
    ...
    [x_1, k_N, z_1N],
    .
    .
    .
    [x_M, k_1, z_M1],
    [x_M, k_2, z_M2],
    ...
    [x_M, k_N, z_MM]
]
property n_cells

int: Number of cells.

property prisms: ndarray | None

numpy.array, shape(*, 5) detailing the assembly of :obj: geoh5py.objects.drape_model.Drapemodel.layers within the trace of the drape model.

Columns: Easting, Northing, Elevation (top), layer index (first), layer count.

prisms = [
    [e_1, n_1, z_1, l_1, c_1],
    ...,
    [e_N, n_N, z_N, l_N, c_N]
]

geoh5py.objects.drillhole

class geoh5py.objects.drillhole.Drillhole(object_type: ObjectType, **kwargs)[source]

Bases: Points

Drillhole object class defined by

Warning

Not yet implemented.

add_data(data: dict, property_group: str | PropertyGroup | None = None, compression: int = 5, collocation_distance=None) → Data | list[Data][source]

Create Data specific to the drillhole object from dictionary of name and arguments. A keyword ‘depth’ or ‘from-to’ with corresponding depth values is expected in order to locate the data along the well path.

Parameters:

data – Dictionary of data to be added to the object, e.g.

data_dict = {
    "data_A": {
        'values', [v_1, v_2, ...],
        "from-to": numpy.ndarray,
        },
    "data_B": {
        'values', [v_1, v_2, ...],
        "depth": numpy.ndarray,
        },
}
Parameters:

  • property_group – Name or PropertyGroup used to group the data.

  • collocation_distance – Minimum collocation distance for matching

  • compression – Compression level for data.

Returns:

List of new Data objects.

add_vertices(xyz)[source]

Function to add vertices to the drillhole

property cells: ndarray | None

numpy.ndarray of int, shape (*, 2): Array of indices defining segments connecting vertices.

property collar

numpy.array of float, shape (3, ): Coordinates of the collar

property cost

float: Cost estimate of the drillhole

property default_collocation_distance

Minimum collocation distance for matching depth on merge

classmethod default_type_uid() → UUID[source]

Default entity type unique identifier

property depths: FloatData | None
desurvey(depths)[source]

Function to return x, y, z coordinates from depth.

property end_of_hole: float | None

End of drillhole in meters

property extent: ndarray | None

Geography bounding box of the object.

Returns:

shape(2, 3) Bounding box defined by the bottom South-West and top North-East coordinates.

format_survey_values(values: list | ndarray) → recarray[source]

Reformat the survey values as structured array with the right shape.

property from_

Depth data corresponding to the tops of the interval values.

property locations: ndarray | None

Lookup array of the well path in x, y, z coordinates.

mask_by_extent(extent: ndarray, inverse: bool = False) → ndarray | None[source]

Sub-class extension of mask_by_extent().

Uses the collar location only.

property planning: str

Status of the hole on of “Default”, “Ongoing”, “Planned”, “Completed” or “No status”

sort_depths()[source]

Read the ‘DEPTH’ data and sort all Data.values if needed

property surveys: ndarray

Coordinates of the surveys

property to_

Depth data corresponding to the bottoms of the interval values.

property trace: ndarray | None

numpy.array: Drillhole trace defining the path in 3D

property trace_depth: ndarray | None

numpy.array: Drillhole trace depth from top to bottom

validate_data(attributes: dict, property_group=None, collocation_distance=None) → tuple[source]

Validate input drillhole data attributes.

Parameters:

  • attributes – Dictionary of data attributes.

  • property_group – Input property group to validate against.

  • collocation_distance – Minimum collocation distance for matching.

validate_depth_data(depth: ndarray, values: ndarray, collocation_distance=0.0001) → ndarray[source]

Compare new and current depth values. Append new vertices if necessary and return an augmented values vector that matches the vertices indexing.

Parameters:

  • depth – Array of depth values.

  • values – Array of values.

  • collocation_distance – Minimum collocation distance for matching.

Returns:

Augmented values vector that matches the vertices indexing.

validate_interval_data(from_to: ndarray | list, values: ndarray, collocation_distance: float = 0.0001) → ndarray[source]

Compare new and current depth values, append new vertices if necessary and return an augmented values vector that matches the vertices indexing.

Parameters:

  • from_to – Array of from-to values.

  • values – Array of values.

  • collocation_distance – Minimum collocation distance for matching.

Returns:

Augmented values vector that matches the vertices indexing.

geoh5py.objects.drillhole.compute_deviation(surveys: ndarray) → ndarray[source]

Compute deviation distances from survey parameters.

Parameters:

surveys – Array of azimuth, dip and depth values.

geoh5py.objects.drillhole.deviation_x(azimuth, dip)[source]

Compute the easting deviation.

Parameters:

  • azimuth – Degree angle clockwise from North

  • dip – Degree angle positive down from horizontal

Return deviation:

Change in easting distance.

geoh5py.objects.drillhole.deviation_y(azimuth, dip)[source]

Compute the northing deviation.

Parameters:

  • azimuth – Degree angle clockwise from North

  • dip – Degree angle positive down from horizontal

Return deviation:

Change in northing distance.

geoh5py.objects.drillhole.deviation_z(_, dip)[source]

Compute the vertical deviation.

Parameters:

dip – Degree angle positive down from horizontal

Return deviation:

Change in vertical distance.

geoh5py.objects.geo_image

class geoh5py.objects.geo_image.GeoImage(object_type: ObjectType, **kwargs)[source]

Bases: ObjectBase

Image object class.

Warning

Not yet implemented.

property cells: ndarray | None

numpy.ndarray of int, shape (*, 2): Array of indices defining segments connecting vertices. Defined based on parts if set by the user.

copy(parent=None, copy_children: bool = True, clear_cache: bool = False, mask: ndarray | None = None, **kwargs)[source]

Function to copy an entity to a different parent entity.

Parameters:

  • parent – New parent for the copied object.

  • copy_children – Copy children entities.

  • clear_cache – Clear cache of data values.

  • mask – Array of indices to sub-sample the input entity.

  • kwargs – Additional keyword arguments.

copy_from_extent(extent: ndarray, parent=None, copy_children: bool = True, clear_cache: bool = False, inverse: bool = False, **kwargs) → GeoImage | None[source]

Sub-class extension of copy_from_extent().

classmethod default_type_uid() → UUID[source]

Default entity type unique identifier

property default_vertices

Assign the default vertices based on image pixel count

property dip: float

Calculated dip of the image in degrees from the vertices position. :return: the dip angle.

property extent: ndarray | None

Geography bounding box of the object.

Returns:

shape(2, 3) Bounding box defined by the bottom South-West and top North-East coordinates.

georeference(reference: ndarray | list, locations: ndarray | list)[source]

Georeference the image vertices (corners) based on input reference and corresponding world coordinates.

Parameters:

  • reference – Array of integers representing the reference used as reference points.

  • locations – Array of floats for the corresponding world coordinates for each input pixel.

Return vertices:

Corners (vertices) in world coordinates.

georeferencing_from_image()[source]

Georeferencing the GeoImage from the image.

georeferencing_from_tiff()[source]

Get the geographic information from the PIL Image to georeference it. Run the georeference() method of the object.

property image

Get the image as a PIL.Image object.

property image_data

Get the FilenameData entity holding the image.

property image_georeferenced: Image | None

Get the image as a georeferenced PIL.Image object.

mask_by_extent(extent: ndarray, inverse: bool = False) → ndarray | None[source]

Sub-class extension of mask_by_extent().

Uses the four corners of the image to determine overlap with the extent window.

property origin: np.array | None

The origin of the image. :return: an array of the origin of the image in x, y, z.

property rotation: float | None

The rotation of the image in degrees, counter-clockwise. :return: the rotation angle.

save_as(name: str, path: str | Path = '')[source]

Function to save the geoimage into an image file. It the name ends by ‘.tif’ or ‘.tiff’ and the tag is not None then the image is saved as georeferenced tiff image ; else, the image is save with PIL.Image’s save function. :param name: the name to give to the image. :param path: the path of the file of the image, default: ‘’.

set_tag_from_vertices()[source]

If tag is None, set the basic tag values based on vertices in order to export as a georeferenced .tiff. WARNING: this function must be used after georeference().

property tag: dict | None

Georeferencing information of a tiff image stored in the header. :return: a dictionary containing the PIL.Image.tag information.

to_grid2d(mode: str | None = None, **grid2d_kwargs) → Grid2D[source]

Create a geoh5py :obj:geoh5py.objects.grid2d.Grid2D from the geoimage in the same workspace.

Parameters:

  • mode – The output image mode, defaults to the incoming image.mode. If “GRAY” convert the image to grayscale.

  • grid2d_kwargs – Keyword arguments to pass to the geoh5py.objects.grid2d.Grid2D constructor.

Returns:

the new created geoh5py.objects.grid2d.Grid2D.

property vertices: ndarray | None

vertices: Defines the four corners of the geo_image

geoh5py.objects.grid2d

class geoh5py.objects.grid2d.Grid2D(object_type: ObjectType, **kwargs)[source]

Bases: GridObject

Rectilinear 2D grid of uniform cell size. The grid can be oriented in 3D space through horizontal rotation and dip parameters. Nodal coordinates are determined relative to the origin and the sign of cell delimiters.

property cell_center_u: ndarray | None

numpy.array of float, shape(u_count, ): Cell center local coordinate along the u-axis.

property cell_center_v: ndarray | None

numpy.array of float shape(u_count, ): The cell center local coordinate along the v-axis.

property centroids: ndarray | None

numpy.array of float, shape (n_cells, 3): Cell center locations in world coordinates.

centroids = [
    [x_1, y_1, z_1],
    ...,
    [x_N, y_N, z_N]
]
copy_from_extent(extent: ndarray, parent=None, copy_children: bool = True, clear_cache: bool = False, inverse: bool = False, **kwargs) → Grid2D | None[source]

Sub-class extension of copy_from_extent().

classmethod default_type_uid() → UUID[source]
Returns:

Default unique identifier

property dip: float

float: Dip angle from horizontal (positive down) in degrees.

property n_cells: int | None

int: Total number of cells.

property origin: ndarray

numpy.array of float, shape (3, ): Coordinates of the origin.

property rotation: float

float: Clockwise rotation angle (degree) about the vertical axis.

property shape: tuple | None

list of int, len (2, ): Number of cells along the u and v-axis.

to_geoimage(keys: list | str, mode: str | None = None, **geoimage_kwargs) → GeoImage[source]

Create a :obj:geoh5py.objects.geo_image.GeoImage object from the current Grid2D.

Parameters:

  • keys – the list of the data name to pass as band in the image. Warning: The len of the list can only be 1, 3, 4 (Pillow restrictions).

  • mode – The mode of the image. One of ‘GRAY’, ‘RGB’, ‘RGBA’ or ‘CMYK’.

Returns:

a new georeferenced geoh5py.objects.geo_image.GeoImage.

property u_cell_size: float | None

np.ndarray: Cell size along the u-axis.

property u_count: int | None

int: Number of cells along u-axis

property v_cell_size: float | None

np.ndarray: Cell size along the v-axis

property v_count: int | None

int: Number of cells along v-axis

property vertical: bool | None

bool: Set the grid to be vertical.

geoh5py.objects.integrator

class geoh5py.objects.integrator.IntegratorPoints(object_type: ObjectType, **kwargs)[source]

Bases: Points

INTEGRATOR Points object. Sub-class of geoh5py.objects.points.Points.

classmethod default_type_uid() → UUID[source]

Default entity type unique identifier

class geoh5py.objects.integrator.NeighbourhoodSurface(object_type: ObjectType, **kwargs)[source]

Bases: Surface

Points object made up of vertices.

classmethod default_type_uid() → UUID[source]

Default type uid.

geoh5py.objects.label

class geoh5py.objects.label.Label(object_type: ObjectType, **kwargs)[source]

Bases: ObjectBase

Label object for annotation in viewport.

Warning

Not yet implemented.

copy(parent=None, copy_children: bool = True, clear_cache: bool = False, mask: ndarray | None = None, **kwargs)[source]

Function to copy an entity to a different parent entity.

Parameters:

  • parent – Target parent to copy the entity under. Copied to current parent if None.

  • copy_children – (Optional) Create copies of all children entities along with it.

  • clear_cache – Clear array attributes after copy.

  • mask – (Optional) Indices of vertices to copy.

  • kwargs – Additional keyword arguments.

Returns:

New copy of the input entity.

classmethod default_type_uid() → UUID[source]

Default entity type unique identifier

property extent

Geography bounding box of the object.

mask_by_extent(extent: ndarray, inverse: bool = False) → None[source]

Sub-class extension of mask_by_extent().

geoh5py.objects.notype_object

class geoh5py.objects.notype_object.NoTypeObject(object_type: ObjectType, **kwargs)[source]

Bases: ObjectBase

Generic Data object without a registered type

copy(parent=None, copy_children: bool = True, clear_cache: bool = False, mask: ndarray | None = None, **kwargs)[source]

Function to copy an entity to a different parent entity.

Parameters:

  • parent – Target parent to copy the entity under. Copied to current parent if None.

  • copy_children – (Optional) Create copies of all children entities along with it.

  • clear_cache – Clear array attributes after copy.

  • mask – Array of indices to sub-sample the input entity.

  • kwargs – Additional keyword arguments.

Returns:

New copy of the input entity.

classmethod default_type_uid() → UUID[source]

Default entity type unique identifier

property extent

Geography bounding box of the object.

mask_by_extent(extent: ndarray, inverse: bool = False) → None[source]

Sub-class extension of mask_by_extent().

geoh5py.objects.object_base

class geoh5py.objects.object_base.ObjectBase(object_type: ObjectType, **kwargs)[source]

Bases: EntityContainer

Object base class.

add_children(children: list[Entity | PropertyGroup])[source]
Parameters:

children – Add a list of entities as children

add_comment(comment: str, author: str | None = None)[source]

Add text comment to an object.

Parameters:

  • comment – Text to be added as comment.

  • author – Name of author or defaults to contributors.

add_data(data: dict, property_group: str | PropertyGroup | None = None, compression: int = 5) → Data | list[Data][source]

Create Data from dictionary of name and arguments. The provided arguments can be any property of the target Data class.

Parameters:

  • data – Dictionary of data to be added to the object, e.g.

  • property_group – Name or PropertyGroup.

  • compression – Compression level for data.

data = {
    "data_A": {
        'values': [v_1, v_2, ...],
        'association': 'VERTEX'
        },
    "data_B": {
        'values': [v_1, v_2, ...],
        'association': 'CELLS'
        },
}
Returns:

List of new Data objects.

add_data_to_group(data: list[Data | UUID] | Data | UUID, property_group: str | PropertyGroup) → PropertyGroup[source]

Append data children to a PropertyGroup All given data must be children of the parent object.

Parameters:

  • data – Data object, uid or name of data.

  • property_group – Name or PropertyGroup. A new group is created if none exist with the given name.

Returns:

The target property group.

add_default_visual_parameters()[source]

Add default visual parameters to the object.

property cells: ndarray

numpy.array of int: Array of indices defining the connection between vertices.

property comments

Fetch a CommentsData entity from children.

property converter
Returns:

The converter for the object.

copy(parent=None, copy_children: bool = True, clear_cache: bool = False, mask: ndarray | None = None, **kwargs)[source]

Function to copy an entity to a different parent entity.

Parameters:

  • parent – New parent for the copied object.

  • copy_children – Copy children entities.

  • clear_cache – Clear cache of data values.

  • mask – Array of indices to sub-sample the input entity.

  • kwargs – Additional keyword arguments.

Returns:

New copy of the input entity.

create_property_group(name=None, on_file=False, uid=None, **kwargs) → PropertyGroup[source]

Create a new PropertyGroup.

Parameters:

  • name – Name of the new property group.

  • on_file – If True, the property group is saved to file.

  • uid – Unique identifier for the new property group.

  • kwargs – Any arguments taken by the PropertyGroup class.

Returns:

A new PropertyGroup

abstract classmethod default_type_uid() → UUID[source]

Default entity type unique identifier

property entity_type: ObjectType

EntityType: Object type.

abstract property extent

Geography bounding box of the object.

Returns:

shape(2, 3) Bounding box defined by the bottom South-West and top North-East coordinates.

property faces: ndarray

Object faces.

find_or_create_property_group(name=None, uid=None, **kwargs) → PropertyGroup[source]

Find or create PropertyGroup from given name and properties.

Parameters:

  • name – Name of the property group.

  • uid – Unique identifier for the property group.

  • kwargs – Any arguments taken by the PropertyGroup class.

Returns:

A new or existing PropertyGroup

classmethod find_or_create_type(workspace: Workspace, **kwargs) → ObjectType[source]

Find or create a type instance for a given object class.

Parameters:

workspace – Target Workspace.

Returns:

The ObjectType instance for the given object class.

get_data(name: str | UUID) → list[Data][source]

Get a child Data by name.

Parameters:

name – Name of the target child data

Returns:

A list of children Data objects

get_data_list(attribute='name') → list[str][source]

Get a list of names of all children Data.

Returns:

List of names of data associated with the object.

get_property_group(name: UUID | str) → list[source]

Get a child PropertyGroup by name. :param name: the reference of the property group to get. :return: A list of children Data objects

property last_focus: str

bool: Object visible in camera on start.

abstract mask_by_extent(extent: ndarray, inverse: bool = False) → ndarray | None[source]

Sub-class extension of mask_by_extent().

property n_cells: int | None

int: Number of cells.

property n_vertices: int | None

int: Number of vertices.

property property_groups: list[PropertyGroup] | None

List of PropertyGroup.

remove_children(children: list[Entity | PropertyGroup])[source]

Remove children from the list of children entities.

Parameters:

children – List of entities

Warning

Removing a child entity without re-assigning it to a different parent may cause it to become inactive. Inactive entities are removed from the workspace by remove_none_referents().

remove_children_values(indices: list[int] | ndarray, association: str, clear_cache: bool = False)[source]
remove_data_from_groups(data: list[Data | UUID] | Data | UUID) → None[source]

Remove data children to all PropertyGroup of the object.

Parameters:

data – Data object, uid or name of data.

remove_property_group(property_group: PropertyGroup)[source]

Remove a property group from the object.

Parameters:

property_group – The property group to remove.

validate_data_association(attribute_dict)[source]

Get a dictionary of attributes and validate the data ‘association’ keyword.

property vertices: ndarray

numpy.array of float, shape (*, 3): Array of x, y, z coordinates defining the position of points in 3D space.

property visual_parameters: VisualParameters | None

Access the visual parameters of the object.

geoh5py.objects.object_type

class geoh5py.objects.object_type.ObjectType(workspace: Workspace, **kwargs)[source]

Bases: EntityType

Object type class

geoh5py.objects.octree

class geoh5py.objects.octree.Octree(object_type: ObjectType, **kwargs)[source]

Bases: GridObject

Octree mesh class that uses a tree structure such that cells can be subdivided it into eight octants.

base_refine()[source]

Refine the mesh to its base octree level resulting in a single cell along the shortest dimension.

property centroids

numpy.array of float, shape (n_cells, 3): Cell center locations in world coordinates.

centroids = [
    [x_1, y_1, z_1],
    ...,
    [x_N, y_N, z_N]
]
classmethod default_type_uid() → UUID[source]

Default type uid.

property n_cells: int | None

int: Total number of cells in the mesh

property octree_cells: ndarray | None

numpy.ndarray of int, shape (n_cells, 4): Array defining the i, j, k position and size of each cell. The size defines the width of a cell in number of base cells.

cells = [
    [i_1, j_1, k_1, size_1],
    ...,
    [i_N, j_N, k_N, size_N]
]
property origin

numpy.array of float, shape (3, ): Coordinates of the origin

property rotation: float

float: Clockwise rotation angle (degree) about the vertical axis.

property shape: tuple | None

list of int, len (3, ): Number of cells along the u, v and w-axis.

property u_cell_size: float | None

float: Base cell size along the u-axis.

property u_count: int | None

int: Number of cells along u-axis.

property v_cell_size: float | None

float: Base cell size along the v-axis.

property v_count: int | None

int: Number of cells along v-axis.

property w_cell_size: float | None

float: Base cell size along the w-axis.

property w_count: int | None

int: Number of cells along w-axis.

geoh5py.objects.points

class geoh5py.objects.points.Points(object_type: ObjectType, name='Points', **kwargs)[source]

Bases: ObjectBase

Points object made up of vertices.

copy(parent=None, copy_children: bool = True, clear_cache: bool = False, mask: ndarray | None = None, **kwargs)[source]

Sub-class extension of copy().

classmethod default_type_uid() → UUID[source]

Default entity type unique identifier

property extent: ndarray | None

Geography bounding box of the object.

Returns:

shape(2, 3) Bounding box defined by the bottom South-West and top North-East coordinates.

mask_by_extent(extent: ndarray, inverse: bool = False) → ndarray | None[source]

Sub-class extension of mask_by_extent().

remove_vertices(indices: list[int] | ndarray, clear_cache: bool = False)[source]

Safely remove vertices and corresponding data entries.

Parameters:

  • indices – Indices of vertices to remove.

  • clear_cache – Clear cached data and attributes.

property vertices: ndarray | None

vertices

geoh5py.objects.surface

class geoh5py.objects.surface.Surface(object_type: ObjectType, **kwargs)[source]

Bases: CellObject

Surface object defined by vertices and cells

property cells: ndarray | None

Array of vertices index forming triangles :return cells: numpy.array of int, shape (“*”, 3)

classmethod default_type_uid() → UUID[source]

Default type uid.