GX API (geosoft.gxapi)

The geosoft.gxapi package provides a Python API to the entire Geosoft GX Developer low-level API.  The low-level API supports multiple languages and uses the legacy Geosoft object API, in which class instances are created using a create() method that returns an object instance handle, which is in turn used to access the class methods.  This style of object-oriented programming was developed by Geosoft to support early C development.  

For example, the following Python script uses the geosoft.gxapi to open a grid and report the grid dimensions and other grid details (the next section does the same thing using geosoft.gxpy):

import geosoft.gxapi as gxapi

gxc = gxapi.GXContext.create('grid_dimension', '0.1')

# create an instance of the GXIMG class from grid file 'test.grd'
img = gxapi.GXIMG.create_file(gxapi.GS_FLOAT,
                              'test.grd(GRD)',
                              gxapi.IMG_FILE_READONLY)

# create reference items to support return immutable values from GXIMG.get_info()
x_sep = gxapi.float_ref()
y_sep = gxapi.float_ref()
x_origin = gxapi.float_ref()
y_origin = gxapi.float_ref()
rotation = gxapi.float_ref()
img.get_info(x_sep, y_sep, x_origin, y_origin, rotation)

# report
print('\n dimension (nx, ny): ({}, {})'.format(img.nx(), img.ny()),
      '\n separation (x, y): ({}, {})'.format(x_sep.value, y_sep.value),
      '\n origin (x, y): ({}, {})'.format(x_origin.value, y_origin.value),
      '\n rotation: {}'.format(rotation.value))

Output using tutorial grid test.grd.

 dimension (nx, ny): (191, 134) 
 separation (x, y): (0.0002777777777777778, 0.0002777777777777778) 
 origin (x, y): (139.20694444444442, -34.68944444444445) 
 rotation: 0.0

This example shows:

All classes and functions in the GX API (geosoft.gxapi) work in the same way, and may require many lines of code to deal with similarly simple needs.

GXPY (geosoft.gxpy)

The geosoft.gxpy package provides a pythonic interface to the lower-level GX API, and in doing so much of the complexity of dealing with the GX API and low-level classes has been coded into the geosoft.gxpy classes.  For example, the following code reports the same information about a grid file as the example in the previous section:

import geosoft.gxpy as gxpy

gxc = gxpy.gx.GXpy()
grid = gxpy.grid.Grid.open('test.grd(GRD)')

print(' dimension (nx, ny): ({}, {})'.format(grid.nx, grid.ny),
      '\n separation (x, y): ({}, {})'.format(grid.dx, grid.dy),
      '\n origin (x, y): ({}, {})'.format(grid.x0, grid.y0),
      '\n rotation: {}'.format(grid.rot))

You will find that many gxpy classes map closely to underlying gxapi classes, but with a simpler, more consistent and often more flexible interface.  For example, instances of the geosoft.gxpy.grid class map directly to a single instance of the geosoft.gxapi.GXIMG class. In these cases, one attribute of the gxpy instance will be the gxapi instance, usually with the lower-case name of the gxapi class.  For example, an instance of the geosoft.gxpy.Grid class will have attribute gximg, which is an instance of the geosoft.gxapi.GXIMG class.  This can be used to directly call a gxapi method to handle situations that are not handled by the gxpy module.  For example, to determine the compression ratio of a compressed grid, call the gxapi.GXIMG.query_double() method using the gximg attribute of the grid instance:

import geosoft.gxpy as gxpy
import geosoft.gxapi as gxapi

gxc = gxpy.gx.GXpy()
grid = gxpy.grid.Grid.open('test.grd(GRD)')

cr = grid.gximg.query_double(gxapi.IMG_QUERY_COMPRESSION_RATIO)

print('compression ratio: {}'.format(cr))
# compression ratio: 34.123512946116165

The geosoft.gxpy source code is also a good reference for seeing how to work with many parts of the geosoft.gxapi should you need to do more than is available in the geosoft.gxpy module.  The geosoft.gxpy module will always offer a subset of the full geosoft.gxapi functionality, though with each release of the Geosoft platform Geosoft will advance the capabilities of both geosoft.gxpy and geosoft.gxapi (see the Geosoft module history).

The geosoft.gxpy module is written entirely in Python and you will find the release source code in the geosoft folder of your Python site-packages.  You can also find current development and previous versions of the gxpy module on github.

geosoft.gxpy Submodules

The following are sub-modules of geosoft.gxpy. Detailed API reference information is available on-line on the gxpy modules reference page.