geosoft.gxpy.vox submodule¶

Geosoft voxel (voxset) handling.

Classes:

Vox Geosoft voxel (voxset), subclass of geosoft.gxpy.spatialdata.SpatialData

Constants:

Z_ELEVATION:	0, z values are elevation
Z_DEPTH:	1, z values are depth
MODE_READ:	`geosoft.gxpy.spatialdata.MODE_READ`
MODE_READWRITE:	`geosoft.gxpy.spatialdata.MODE_READWRITE`
MODE_NEW:	`geosoft.gxpy.spatialdata.MODE_NEW`
INTERP_NEAREST:	`geosoft.gxapi.VOXE_EVAL_NEAR`
INTERP_LINEAR:	`geosoft.gxapi.VOXE_EVAL_INTERP`
INTERP_SMOOTH:	`geosoft.gxapi.VOXE_EVAL_BEST`

Note

Regression tests provide usage examples: Tests

New in version 9.3.1.

class Vox(name=None, gxvox=None, dtype=None, mode=None, overwrite=False)¶

Bases: geosoft.gxpy.spatialdata.SpatialData, collections.abc.Sequence

Vox (voxset) class.

Constructors:

`open()`	open an existing vox dataset
`new()`	create a new vox dataset

A vox instance supports iteration that yields (x, y, z, vox_value) by cell-centered points along horizontal rows, then columns, then depth slices starting at minimum z.

For example, the following prints the x, y, z, vox_value of every non-dummy cell in a vox:

import geosoft.gxpy.vox as gxvox

with gxvox.Vox.open('some.geosoft_voxel') as g:
    for x, y, z, v in g:
        if v is not None:
            print(x, y, z, v)

Specific vox cell values can be indexed (null vox values are None):

import geosoft.gxpy.vox as gxvox

with gxvox.Vox.open('some_voxel') as vox:
    for iz in range(vox.nz):
        for iy in range(vox.ny):
            for ix in range(vox.nx):
                x, y, z, v = vox[ix, iy, iz]
                if v is not None:
                    print(x, y, z, v)

New in version 9.3.1.

cells_x¶: Return array of X cell sizes

cells_y¶: Return array of Y cell sizes

cells_z¶: Return array of Z cell sizes

classmethod copy_vox(name, source_vox, data=None, temp=False, overwrite=False, dtype=None)¶

Create a new vox dataset to match a source vox, with optional new data.

Parameters:

name – dataset name, or a path to a persistent file. A file with extension geosoft_voxel will be created for vox instances that will persist (temp=True).
source_vox – Vox instance of the source vox
data – data to place in the vox, must have 3 dimensions (nz, ny, nx). If not specified a copy of source+vox data is used. Data arrays are indexed (z, y, x).
temp – True to create a temporary vox
overwrite – True to overwrite existing persistent vox
dtype – data type, default is the same as data, or np.float64 of no data.

New in version 9.3.1.

dtype¶: Working dtype for the data.

dx¶: constant X cell size, None if not constant, in which case use cells_x

dy¶: constant Y cell size, None if not constant, in which case use cells_y

dz¶: constant Z cell size, None if not constant, in which case use cells_z

extent¶: extent to the outer-cell edges of the vox as a geosoft.gxpy.geometry.Point2.

gxpg¶

geosoft.gxapi.GXPG instance (3D) for this vox.

The GXPG will always index z from minimum elevation (bottom of the vox).

New in version 9.3.1.

gxvox¶: gxapi.GXVOX instance handle

gxvoxe¶: Return a gxapi.GXVOXE instance

is_depth¶: True if z is depth. Can be set.

is_elevation¶: True if z is elevation. Can be set.

is_vectorvox¶: True if this is a vector voxel.

locations_x¶: Return array of X cell-center locations

locations_y¶: Return array of Y cell-center locations

locations_z¶: Return array of Z cell-center locations

classmethod new(name, data, temp=False, overwrite=False, dtype=None, origin=(0.0, 0.0, 0.0), cell_size=None, coordinate_system=None, depth=False)¶

Create a new vox dataset

Parameters:

name – dataset name, or a path to a persistent file. A file with extension geosoft_voxel or geosoft_vectorvoxel will be created for vox instances that will persist (temp=True).
data – data to place in the vox, must have 3 dimensions (nz, ny, nx) for simple scalar data, or (nx, ny, nz, 3) for vector data.f
temp – True to create a temporary vox which will be removed after use
overwrite – True to overwrite existing persistent vox
dtype – data type, default is the same as data, or np.float64 of no data.
origin – (x0, y0, z0) location of the center of the origin voxel cell.
cell_size – uniform cell size, or (dx, dy, dz) cell sizes in the x, y and z directions. The default is (1., 1., 1.). For variable cell size on a dimension, provide an array of the cell sizes along that dimension. The array length must match the data dimension along that axis. For example: cell_size=((1, 2.5, 1.5), (1, 1, 1, 1), (5, 4, 3, 2, 1)) will create a vox with (x, y, z) dimension (3, 4, 5) and sizes as specified in each dimension.
coordinate_system – coordinate system as required to create from geosoft.gxpy.Coordinate_system
depth – True to work with z as depth (positive down). The default is False, z is elevation (positive up)

New in version 9.3.1.

np(subset=None, dtype=None)¶

Return vox subset in a 3D numpy array.

Parameters:

subset –
define a subset ((start_x, start_y, start_z),(nx, ny, nz)). If not specified a numpy array of the entire vox is returned. Missing items are calculated from the vox, and negative indexes in start indicate a value from the last cell.

start=(None, None) equivalent: start=((0, 0, 0), (nx, ny, nz))

start=((4, 6, 11), None) equivalent: start=((4, 6, 11), (nx - 4, ny - 6, nz - 11))

start=((4, 6, 11), (None, None, 1) equivalent: start=((4, 6, 11), (nx - 4, ny - 6, 1))

start=((0, 0, -1), None equivalent: start=((0, 0, nx - 1), (nx, ny, 1))
dtype – desired np.dtype, default is same as vox dtype.

Returns:

numpy array of shape (nz, ny, nx). The order of z depends on is_depth property setting.

New in version 9.3.1.

nx¶: number of cells in vox X direction

ny¶: number of cells in vox Y direction

nz¶: number of cells in vox Z direction

classmethod open(name, gxapi_vox=None, dtype=None, mode=0, depth=False)¶

Open an existing vox.

Parameters:

name – name of the vox. If a name only the vox is resolved from the project. If a file name or complete path, the vox is resolved from the file system outside of the current project.
gxapi_vox – gxapi.GXVOX instance to create from GXVOX instance.
dtype – working dtype for retrieving data.
depth – True to work with z as depth (positive down), origin at the top of the vox. The default is False, z is elevation (positive up), origin at the bottom of the vox.
mode –
open mode:

MODE_READ only read the vox, properties cannot be changed

MODE_READWRITE vox stays the same, but properties and metadata may change

New in version 9.3.1.

origin_x¶: X location of the center of the vox origin cell.

origin_y¶: Y location of the center of the vox origin cell.

origin_z¶: Z location of the center of the vox origin cell, top for depth=True, bottom for depth=False

uniform_dx¶: True if X cell sizes are constant

uniform_dy¶: True if Y cell sizes are constant

uniform_dz¶: True if Z cell sizes are constant

value_at_location(xyz, interpolate=1)¶

Vox at a location.

Parameters:

xyz – tuple (x, y, z) location in the vox coordinate system
interpolate –
method by which to interpolate between cell centers:

INTERP_NEAREST same as value inside a cell.

INTERP_LINEAR linear interpolation between neighboring cell centers.

INTERP_SMOOTH smooth interpolation (slower than INTERP_LINEAR).

Returns:

vox value at that location

New in version 9.3.1.

xyz(ix, iy, iz)¶

Return the spatial location of a the center of a cell in the vox. Raises error if our of range of the data

Parameters:	ix – x index iy – y index iz – z index, from bottom for elevation, from top for depth
Returns:	(x, y, elevation) or (x, y, depth)

New in version 9.3.

exception VoxException(message)¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.vox.

delete_files(vox_name)¶

Delete all files associated with this vox name.

Parameters:	vox_name – name of the vox file

New in version 9.3.1.

elevation_from_depth(depth_origin, depth_cells)¶

Return elevation origin and elevation cells sizes from a depth origin and depth cell-sizes

Parameters:	depth_origin – top vox z origin as depth below 0 depth_cells – cell sizes with depth
Returns:	elevation origin (bottom cell), cell sizes up from origin

New in version 9.3.1.

locations_from_cells(cells, ref=0.0)¶

Return the cell center locations from an array of cell sizes.

Parameters:	cells – array of cell sizes ref – reference (origin) added to values
Returns:	location array

New in version 9.3.1.