geosoft.gxpy.grid_utility submodule¶
Geosoft grid and image utilities.
Note
Regression tests provide usage examples: Tests
-
exception
GridUtilityException
(message)¶ Bases:
geosoft.GXRuntimeError
Exceptions from
geosoft.gxpy.grid_utility
.New in version 9.4.
-
calculate_slope_standard_deviation
(grid)¶ Return the standard deviation of the slopes.
Parameters: grid – geosoft.gxpy.grid.Grid
instance, or a grid file nameReturns: Standard deviation of grid slopes Note
This method calculates the standard deviation of the horizontal differences in the X and Y directions for the supplied image. This is useful for shading routines. A good default scaling factor is 2.5 / standard deviation.
The image will be sub-sampled to a statistically meaningful number.
The cell sizes are used to determine the slopes.
New in version 9.4.
-
contour_points
(grid, value, max_segments=1000, resolution=None, return_as=1, gdb=None, overwrite=False)¶ Return a set of point segments that represent the spatial locations of contours threaded through the grid.
Parameters: - grid – grid file of
geosoft.gxpy.grid.Grid
instance - value – contour value
- max_segments – maximum expected number of segments, raises error if there are more actual segments.
- resolution – the separation between points along the contours. If not specified the minimum
grid cell size is used. Set
resolution=0
, for use the locations as returned by the contouring algorithm. - return_as –
return results as:
RETURN_PPOINT return results as a single geosoft.gxpy.geometry.PPoint
instanceRETURN_LIST_OF_PPOINT return results as a list of geosoft.gxpy.geometry.PPoint
instancesRETURN_GDB return result as a geosoft.gxpy.gdb.Geosoft_gdb
instance - gdb – return database name, or a
geosoft.gxpy.gdv.Geosoft_database
instance. If not specified andreturn_as=RETURN_GDB
, a temporary database is created. - overwrite –
True
to overwrite gdb if it exists.
Returns: depends on
return_as
settingNote
Contours through 3D oriented grids will be oriented in 3D. Grids that are not 3D oriented will have a z value 0.0.
New in version 9.4.
- grid – grid file of
-
derivative
(grid, derivative_type, file_name=None, overwrite=False, dtype=None, fft=True)¶ Return a derivative of a grid or a tilt-angle
Parameters: - grid –
geosoft.gxpy.grid.Grid
instance, or a file name - derivative_type –
Which derivative to calculate, (grid_data_uom/distance):
DERIVATIVE_X in the grid X direction DERIVATIVE_Y in the grid Y direction DERIVATIVE_Z in the grid Z direction DERIVATIVE_XYZ the total derivative sqrt(dx**2 + dy**2 + dz**2) (analytic signal) TILT_ANGLE tilt angle, atan2(dz, sqrt(dx**2 + dy**2)) (radians) - file_name – returned derivative file name,
None
for a temporary file - overwrite – True to overwrite existing file
- dtype – dtype for the return grid, default is the same as the passed grid.
- fft –
False
calculate Z derivative with a space-domain convolution rather than an FFT.
Returns: geosoft.gxpy.grid.Grid
instance that contains the derivative resultNote
Derivative units_of_measure are grid_unit_of_measure / distance, except for the tilt angle, which is radians.
Horizontal derivatives are calculated in the space domain based on the difference between neighboring cell values, and the Z derivative can be calculated using an FFT or a 5x5 space-domain convolution. An FFT calculation will generally produce a better result and it will be able to work with longer wavelengths, but at the expense of speed and edge effects in cases of very powerful anomalies along the edge of a grid.
- grid –
-
expression
(grids, expr, result_file_name=None, overwrite=False)¶ Apply an expressing to grids.
Parameters: - grids – dictionary of named grid operands, or a list of grids (see example below). If a list is provided the operand names will be ‘g1’, ‘g2’, ‘g3’, etc…
- expr – expression string to apply, conforms to Python/C math expression syntax. The expression can have multiple lines, each line terminated by a ‘;’ character.
- result_file_name – optional result grid file name, if
None
a temporary grid is created. - overwrite – True to overwrite existing grid
Returns: Grid
instance that contains the resuilt of the expression.Example
import geosoft.gxpy.grid as gxgrd # add using file names sum = gxgrd.expression(('some_grid', 'some_other_grid'), 'g1+g2') # add using Grid instances grid_1 = gxgrd.Grid.open('some_grid') grid_2 = gxgrd.Grid.open('some_other_grid') sum = gxgrd.expression((grid_1, grid_2), 'g1+g2') # add using named operands sum = gxgrd.expression({'a': grid_1, 'b': grid_2}, 'a+b')
-
feather
(grid, width, edge_value=None, file_name=None, overwrite=False)¶ Feather the edge of a grid to a constant value at the edge.
Parameters: - grid –
geosoft.gxpy.grid.Grid
instance, or a file name - file_name – feathered grid file name, temporary created if
None
. - overwrite –
True
to overwrite existing file - width – feather width in cells around the grid, must be <= half the grid dimension
- edge_value – edge value, default is the data mean
Returns: feathered grid
geosoft.gxpy.grid.Grid
New in version 9.4.
- grid –
-
flood
(grid, file_name=None, overwrite=False, tolerance=None, max_iterations=250, pass_tol=99.0)¶ Flood blank areas in a grid based on a minimum-curvature surface.
Parameters: - grid –
geosoft.gxpy.grid.Grid
instance, or a grid file name - file_name – flooded grid file name, temporary created if
None
. - overwrite –
True
to overwrite existing file - tolerance – data fit tolerance, default is 0.001 times the data standard deviation
- max_iterations – maximum iterations for fiting the surface
- pass_tol – percentage of data that needs to pass the tolerance test when definint the minimum-curfacture surface. The default is 99%.
Returns: geosoft.gxpy.grid.Grid
instance of a flooded grid.New in version 9.4.
- grid –
-
grid_bool
(g1, g2, joined_grid=None, opt=1, size=3, olap=1)¶ Combine two grids into a single grid, with boolean logic to determine the result.
Parameters: - g1 – Grids to merge
- g2 –
- joined_grid – joined output grid name, overwritten if it exists. Default makes a temporary grid.
- opt –
option logic to determine output grid points:
BOOL_AND blank unless g1 and g2 BOOL_OR blank unless g1 or g2 BOOL_XOR blank where g1 and g2 - size –
size of the output grid, default is minimum size
BOOL_SIZE_GRID1 output size matches g1 BOOL_SIZE_GRID2 output size matches g2 BOOL_SIZE_MIN output size minimised to non-blank area BOOL_SIZE_MAX output size g1 + g2: - olap –
what to do with overlapping valid points, default uses grid 1
BOOL_OVERLAP_AVERAGE averave values where grids overlap BOOL_OVERLAP_GRID1 use g1 where grids overlap BOOL_OVERLAP_GRID2 use g2 where grids overlap
Returns: Grid
instance of the merged output grid, must be closed with a call to close().Note
If the grid coordinate systems differ, g2 is reprojected to the coordinate system og g1.
New in version 9.4.
-
grid_mosaic
(mosaic, grid_list, type_decorate='')¶ 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
- grid_list – list of input grid names
- type_decorate – decoration for input grids if not default
Returns: geosoft.gxpy.grid.Grid
instanceNote
If the coordinate systems are different the grids are reprojected to the coordinate system of the first grid.
New in version 9.4.
-
remove_trend
(grid, file_name=None, method=1, overwrite=False)¶ Calculate a polynomial trend surface and return trend-removed grid.
Parameters: - grid –
geosoft.gxpy.grid.Grid
instance, or a file name - file_name – trend-removed grid file name, if
None
a temporary grid is created. - method – base trend on
TREND_EDGE
for edge data orTREND_ALL
for all data - overwrite – True to overwrite existing file_name
Returns: Grid
instance- grid –
-
sample
(grid, xyz)¶ Return grid values sampled at the point locations.
Parameters: - grid –
geosoft.gxpy.grid.Grid
instance or a grid file name. - xyz –
geosoft.gxpy.geometry.PPoint
instance, or a numpy array shapped (-1, 3) that holds the desired (x, y, z) locations. If a PPoint instance is passed it will be reporjected to the grid coordinate system if necessary.
Returns: 1-dimensional numpy array of grid data values that match the passes PPoint or XYZ.
Note
Sampled data values use linear interpolation between grid points.
New in version 9.1.
- grid –
-
tilt_depth
(grid, resolution=None, return_as=0, gdb=None, overwrite=False, fft=True)¶ Return estimate of the depth sources of potential filed anomalies.
Parameters: - grid –
geosoft.gxpy.grid.Grid
instance or a grid file name. Ideally the grid should be RTP. - resolution – zero-contour sampling resolution, defaults to 4 times the grid cell size.
- return_as –
return results as:
RETURN_PPOINT return results as a single geosoft.gxpy.geometry.PPoint
instanceRETURN_LIST_OF_PPOINT return results as a list of geosoft.gxpy.geometry.PPoint
instancesRETURN_GDB return result as a geosoft.gxpy.gdb.Geosoft_gdb
instance - gdb – return database name, or a
geosoft.gxpy.gdv.Geosoft_database
instance. If not specified andreturn_as=RETURN_GDB
, a temporary database is created. - overwrite – True to overwrite existing gdb.
- fft –
False
to use a space-domain convolution. The default uses an FFT, which will in general produce a cleaner and more accurate result, though it may be slower.
Returns: depends on
return_as
settingNote
Given a TMI grid, or the vertical derivative of the gravity anomaly, calculate contact source depths using the tilt-depth method. The contact source depth is the reciprocol of the horizontal gradient of the tilt-derivative at the zero-contour of the tilt derivative.
New in version 9.4.
- grid –