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

See also

geosoft.gxpy.spatialdata, geosoft.gxpy.vox_display, geosoft.gxapi.GXVOX

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.

__init__(name=None, gxvox=None, dtype=None, mode=None, overwrite=False)

Initialize self. See help(type(self)) for accurate signature.

property cells_x

Return array of X cell sizes

property cells_y

Return array of Y cell sizes

property 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.

property dtype

Working dtype for the data.

property dx

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

property dy

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

property dz

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

property extent

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

property 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.

property gxvox

gxapi.GXVOX instance handle

property gxvoxe

Return a gxapi.GXVOXE instance

property is_depth

True if z is depth. Can be set.

property is_elevation

True if z is elevation. Can be set.

property is_vectorvox

True if this is a vector voxel.

property locations_x

Return array of X cell-center locations

property locations_y

Return array of Y cell-center locations

property 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.

property nx

number of cells in vox X direction

property ny

number of cells in vox Y direction

property 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.

property origin_x

X location of the center of the vox origin cell.

property origin_y

Y location of the center of the vox origin cell.

property origin_z

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

property uniform_dx

True if X cell sizes are constant

property uniform_dy

True if Y cell sizes are constant

property 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.