geosoft.gxpy.grid submodule¶

Geosoft grids and image handling, including all supported file formats

Classes:

Grid grid, which can be in memory or created from a file

Note

Regression tests provide usage examples: Tests

class geosoft.gxpy.grid.Grid(file_name=None, dtype=None, mode=None, kx=1, dim=None, overwrite=False)¶

Bases: object

Grid and image class.

Constructors:

`open()`	open an existing grid/image
`new()`	create a new grid/image
`copy()`	create a copy
`index_window()`	create a windowed grid based of grid indexes
`from_data_array()`	create a new grid from a 2d data array

A grid instance supports iteration that yields (x, y, z, grid_value) by points along rows. For example, the following prints the x, y, z, grid_value of every non-dummy point in a grid:

import geosoft.gxpy.grid as gxgrd

g = gxgrd.Grid.open('some.grd')
for x, y, z, v in g:
    if v != g.dummy_value
        print(x, y, z, v)

New in version 9.1.

close()¶: close the grid and release all instance resources.

coordinate_system¶: grid coordinate system as a geosoft.gxpy.coordinate_system.Coordinate_system instance

New in version 9.2.

classmethod copy(grd, file_name=None, dtype=None, overwrite=False)¶

Create a new Grid instance as a copy of an existing grid.

Parameters:	grd – `Grid` instance to save as a new grid, or a grid file name file_name – name of the new grid (file with optional decorations), default is in memory dtype – numpy data type, None to use type of the parent grid overwrite – True to overwrite if the file exists, False to no overwrite.

New in version 9.2.

static decorate_name(name, decorations='')¶: Deprecated since version 9.2: use gxpy.grid.name_parts()

decoration¶: grid descriptive decoration

New in version 9.2.

delete_files(delete=True)¶

Delete the files associated with this grid when deleting the grid object. Note that files are not deleted until all references to this object are deleted and garbage collection is performed.

Parameters:	delete – set to False to reverse a previous delete request

New in version 9.1.

dtype¶: numpy data type for the grid

New in version 9.2.

dummy_value¶: Return the grid data dummy value.

dx¶: separation between grid points in the grid x direction

New in version 9.2.

dy¶: separation between grid points in the grid y direction

New in version 9.2.

extent_2d()¶: Return the 2D extent of the grid on the grid plane :returns:(min_x, min_y, max_x, max_y)

New in version 9.2.

extent_3d()¶

Return the 3D extent of the grid in the base coordinate system.

Returns:	((min_x, min_y, min_z), (max_x, max_y, max_z))

New in version 9.2.

file_name¶: grid file name without decorations

New in version 9.2.

file_name_decorated¶: grid file name with decorations

New in version 9.2.

classmethod from_data_array(data, file_name, properties={})¶

Create grid from a 2D numpy array.

Parameters:	data – 2D numpy data array, ot a 2d list. Must be 2D. file_name – name of the file
Returns:	`Grid` instance

New in version 9.1.

get_value(x, y)¶

Return a grid value at a point as a float. For scalar data the point value will be interpolated between neighbors. For color data the nearest value is returned as a color int.

Parameters:	x – X location on the grid plane y – Y location on the grid plane
Returns:	grid value, or None if outside of grid area

gridtype¶: grid type (ie. ‘GRD’ or ‘HGD’)

New in version 9.2.

gximg¶: Retrun handle to the underlying GXIMG.

gxtype¶: Geosoft data type for the grid

New in version 9.2.

indexWindow(name, x0=0, y0=0, nx=None, ny=None)¶: Deprecated since version 9.2: gxpy.Grid.index_window()

classmethod index_window(grd, name=None, x0=0, y0=0, nx=None, ny=None, overwrite=False)¶

Create a windowed instance of a grid.

Parameters:	grd – `Grid` instance name – name for the windowed_grid, default is constructed from input grid x0 – integer index of the first X point y0 – integer index of the first Y point nx – number of points in x ny – number of points in y overwrite – True to overwrite existing file

New in version 9.2.

is_int¶: returns True if base grid type is integer, which includes color integers

metadata¶: Return the grid metadata as a dictionary. Can be set, in which case the dictionary items passed will be added to, or replace existing metadata.

See also

Geosoft metadata schema

New in version 9.2.

name¶: Grid name, usually the file name without path or extension.

New in version 9.2.

static name_parts(name)¶: Deprecated since version 9.2: use gxpy.grid.name_parts()

classmethod new(file_name=None, properties=None, overwrite=False)¶

Create a new grid file.

Parameters:	file_name – name of the grid file, None or ‘’ for a memory grid. (see supported file formats) properties – dictionary of grid properties overwrite – True to overwrite existing file

New in version 9.1.

nx¶: grid x dimension (number of columns)

New in version 9.2.

ny¶: grid y dimension (number of rows)

New in version 9.2.

classmethod open(file_name, dtype=None, mode=None)¶

Open an existing grid file.

Parameters:

file_name –
name of the grid file (see supported file formats)
dtype – numpy data type, None for the grid native type. If not the same as the native type a memory grid is created in the new type.
mode –
open mode:

FILE_READ only read the file, properties cannot be changed

FILE_READWRITE grid stays the same, but properties may change

New in version 9.1.

properties()¶

Get the grid properties dictionary

Returns:	dictionary of all grid properties

New in version 9.1.

read_column(column=None, start=0, length=0)¶

Parameters:	column – column to read, if not specified the next column is read starting from column 0 start – the first point in the column, default is 0 length – number of points to read, the default is to the end of the col.
Returns:	`geosoft.gxvv.GXvv` instance

New in version 9.1.

read_row(row=None, start=0, length=0)¶

Parameters:	row – row to read, if not specified the next row is read starting from row 0 start – the first point in the row, default is 0 length – number of points to read, the default is to the end of the row.
Returns:	`geosoft.gxvv.GXvv`

New in version 9.1.

rot¶

grid rotation angle, degrees azimuth

Note that grid rotations in the gxapi GXIMG are degrees clockwise, which is the opposite of degree azimuth, used here. All horizontal plane angles in the Python gxpy module are degrees azimuth for consistency.

New in version 9.2.

set_properties(properties)¶

Set grid properties from a properties dict. Settable property keys are:

‘x0’ grid X origin location (default 0.0)

‘y0’ grid Y origin location (0.0)

‘dx’ grid X point separation (1.0)

‘dy’ grid Y point separation (1.0)

‘rot’ grid rotation angle in degrees azimuth (0.0)

‘coordinate_system’ coordinate system (unchanged)

Not all keys need be passed, though typically one will get the properties from the grid and modify those that need to change and pass the properties back.

Parameters:	properties – properties dictionary

New in version 9.1.

unit_of_measure¶: Units of measurement (a string) for the grid data, can be set.

New in version 9.2.

write_rows(data, ix0=0, iy0=0, order=1)¶

Write data to a grid by rows.

Parameters:	data – array of data to write ix0 – grid X index of first point iy0 – grid Y index of first point, top index if writing rows top to bottom order – 1: bottom to top; -1: top to bottom

New in version 9.1.

x0¶: grid origin x location in the plane coordinate system

New in version 9.2.

xyz(item)¶

Returns the (x, y, z) location of an indexed point in the grid.

Parameters:	item – tuple (ix, iy) grid point, or the point number counting by row
Returns:	trye (x, y, z) location

New in version 9.2.1.

xyzv()¶

Return a numpy float array of (x, y, z, v) grid points.

x, y, z) is the location of each grid point in 3D space and v is the grid value at that location. Dummies will be numpy.nan.

New in version 9.2.

y0¶: grid origin y location in the plane coordinate system

New in version 9.2.

exception geosoft.gxpy.grid.GridException¶

Bases: Exception

Exceptions from geosoft.gxpy.grid.

New in version 9.1.

geosoft.gxpy.grid.array_locations(properties)¶: Create an array of (x,y,z) points for a grid defined by properties :param properties: grid properties :returns: array of points, shaped (ny, nx, 3)

New in version 9.1.

geosoft.gxpy.grid.decorate_name(name, decorations='')¶

Properly decorate a grid name.

Parameters:	name – file name decorations – file decorations, semicolon delimited
Returns:	decorated file name

New in version 9.1.

geosoft.gxpy.grid.delete_files(file_name)¶

Delete all files associates with this grid name.

Parameters:	file_name –

New in version 9.2.

geosoft.gxpy.grid.gridBool(*args, **kwargs)¶: Deprecated since version 9.2: use grid_bool

geosoft.gxpy.grid.gridMosaic(*args, **kwargs)¶: Deprecated since version 9.2: use :py:method: grid_mosaic

geosoft.gxpy.grid.grid_bool(g1, g2, joinedGrid, opt=1, size=3, olap=1)¶

Parameters:

g1,g2 – Grid of grids to merge
new – new output grid, overwritten if it exists
opt –
logic to use on overlap points, default 1 (OR):

0 AND, both grids must have valid value

1 OR, either grid has a valid value

2 XOR, same as OR, except overlap is dummied
size –
size of the output grid, default is minimum size

0 minimum size - dummy regions clipped

1 size to grid 1

2 size to grid 2

3 size to maximum including both grids
olap –
what to do with overlapping valid points, default uses grid 1

0 average points

1 use grid 1

2 use grid 2

Returns:

Grid instance of the merged output grid, must be closed with a call to close().

New in version 9.1.

geosoft.gxpy.grid.grid_mosaic(mosaic, gridList, typeDecoration='', report=None)¶

Combine a set of grids into a single grid. Raises an error if the resulting grid is too large.

Parameters:	mosaic – name of the output grid, returned. Decorate with ‘(HGD)’ to get an HGD gridList – list of input grid names typeDecoration – decoration for input grids if not default report – string reporting function, report=print to print progress
Returns:	:class`Grid` instance, must be closed with a call to close().

New in version 9.1.

geosoft.gxpy.grid.name_parts(name)¶

Return folder, undecorated file name + ext, file root, ext, decorations.

If extension is not specified, ”.grd” assumed

For example:

>>> import geosoft.gxpy.grid as gxgrd
>>> namep = gxgrd.name_parts("f:/someFolder/name.grd(GRD;TYPE=SHORT)")
>>> print(namep)
('f:/someFolder/','name.grd','name','.grd','(GRD;TYPE=SHORT)')

New in version 9.1.

Related Topics

Previous Topic

Next Topic

This Page

geosoft.gxpy.grid submodule¶

‘x0’	grid X origin location (default 0.0)
‘y0’	grid Y origin location (0.0)
‘dx’	grid X point separation (1.0)
‘dy’	grid Y point separation (1.0)
‘rot’	grid rotation angle in degrees azimuth (0.0)
‘coordinate_system’	coordinate system (unchanged)