The GX Developer Python installation includes two packages:
| Module | Description |
|---|---|
| geosoft.gxapi | This is the complete low-level GX API and includes all functions that are part of the standard Geosoft API. This is a direct mapping of the API available to all development languages, and as such the API has a procedural style, which is not considered "pythonic". However, calling into the geosoft.gxapi does provide access to the complete Geosoft development environment as well as the highest level of version stability due the legacy of the Geosoft API. The geosoft.gxapi is assured to be forward version compatible while the gxpy module is currently best-effort in this regard.<br>Usage of the geosoft.gxapi follows the same code patterns you will find in Geosoft's legacy GXs that are part of Geosoft Desktop. |
| geosoft.gxpy | The geosoft.gxpy package contains a set of modules that a provide a higher-level and more approachable "pythonic" interface to underlying geosoft.gxapi. Many standard Python needs are included in the modules, and we suggest that straight-forward Python applications can and should work with mostly with the geosoft.gxpy package.<br><br>The geosoft.gxpy package covers only part of the full function of the geosoft.gxapi module and with each release of GX Developer Geosoft will continue to expand and extend geosoft.gxpy. |
See also: tutorial page
In [1]:
import geosoft.gxpy.gx as gx
import geosoft.gxpy.utility as gxu
gxc = gx.GXpy()
url = 'https://github.com/GeosoftInc/gxpy/raw/9.3/examples/tutorial/Geosoft%20modules%20-%20gxapi%20and%20gxpy/'
gxu.url_retrieve(url + 'test.grd')
gxu.url_retrieve(url + 'test.grd.gi')
gxc = None
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):
In [2]:
import geosoft.gxapi as gxapi
import geosoft.gxpy.utility as gxu
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))
gxc = None
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:
In [3]:
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))
gxc = None
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.querydouble() method using the gximg attribute of the grid instance:
In [4]:
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_rCOMPRESSION_RATIO)
print('compression ratio: {}'.format(cr))
gxc = None