geosoft.gxpy.grid_utility submodule

Geosoft grid and image utilities.

See also

geosoft.gxpy.grid, geosoft.gxapi.GXIMG, geosoft.gxapi.GXIMU

Note

Regression tests provide usage examples: Tests

exception GridUtilityException(message)[source]

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.grid_utility.

New in version 9.4.

calculate_slope_standard_deviation(grid)[source]

Return the standard deviation of the slopes.

Parameters

grid – geosoft.gxpy.grid.Grid instance, or a grid file name

Returns

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)[source]

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 instance

    RETURN_LIST_OF_PPOINT

    return results as a list of geosoft.gxpy.geometry.PPoint instances

    RETURN_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 and return_as=RETURN_GDB, a temporary database is created.

  • overwrite – True to overwrite gdb if it exists.

Returns

depends on return_as setting

Note

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.

derivative(grid, derivative_type, file_name=None, overwrite=False, dtype=None, fft=True)[source]

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 result

Note

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.

expression(grids, expr, result_file_name=None, overwrite=False)[source]

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)[source]

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.

flood(grid, file_name=None, overwrite=False, tolerance=None, max_iterations=250, pass_tol=99.0)[source]

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.

See also

geosoft.gxpy.grid.Grid.minimum_curvature

New in version 9.4.

grid_bool(g1, g2, joined_grid=None, opt=1, size=3, olap=1)[source]

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='')[source]

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 instance

Note

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)[source]

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 or TREND_ALL for all data

  • overwrite – True to overwrite existing file_name

Returns

Grid instance

sample(grid, xyz)[source]

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.

tilt_depth(grid, resolution=None, return_as=0, gdb=None, overwrite=False, fft=True)[source]

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 instance

    RETURN_LIST_OF_PPOINT

    return results as a list of geosoft.gxpy.geometry.PPoint instances

    RETURN_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 and return_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 setting

Note

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.