The GX Developer Python installation includes two packages:

Module	Description

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.

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.

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.

Module History

Both geosoft.gxapi and geosoft.gxpy evolve with each release of the Geosoft platform. A summary of new features can be found here:

Tutorial Files

Files for this lesson are here:

https://github.com/GeosoftInc/gxpy/tree/9.3/examples/tutorial/Geosoft%20modules%20-%20gxapi%20and%20gxpy

Run this script to download tutorial data:

https://github.com/GeosoftInc/gxpy/raw/9.3/examples/tutorial/Geosoft%20modules%20-%20gxapi%20and%20gxpy/get_data_files.py

Jupyter Notebook

On this page

1 GX API (geosoft.gxapi)
- 1.1 grid_dimension_gxapi.py
2 GXPY (geosoft.gxpy)
- - 2.1.1 grid_dimension_gxpy.py
  - 2.1.2 compression_ratio.py
- 2.2 geosoft.gxpy Submodules

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):

grid_dimension_gxapi.py

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:

line 1	typical import of geosoft.gxapi
line 3	creating a GX context with a program name and version number. The context is not used in this example, but it must be created and assigned to a variable that persists until the script exits.
line 6	opening the grid file test.grd, of type (GRD) - see Grid File Extensions.
lines 11-15	creating float reference classes to hold return values - see Helper Classes
line 16	call method get_info() - see GXIMG.get_info()
line 19	report

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.

Note

Examples that provide API patterns for many scenarios can be found in the legacy Geosoft GXC source code (9.3). However, there are differences between the GXC API and the Python geosoft.gxapi:

Class naming style is different. For example, CreateFile_IMG() in GXC is GXIMG.create_file() in Python.
Values passed by reference to be changed in the called method/function must be passed by one of the gxapi reference classes (see Helper Classes), with the value attribute holding the setting.
Destroy() methods do not appear in the Python gxapi, and class instances are automatically destroyed once a class instance loses context.

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:

grid_dimension_gxpy.py

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))

Note

reasonable default function parameters are defined wherever possible.
instance properties are usually accessible as instance properties (for example grid.dx is the grid x point separation).
settable properties can be set with an assignment (for example grid.dx = 0.01 will change the grid x cell separation for a grid opened as mode=gxpy.grid.FILE_READWRITE).

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:

compression_ratio.py

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.

Sub-Module	Description	Typical import

Sub-Module	Description	Typical import
gx	Works with your GX context and licensing.	`import geosoft.gxpy.gx as gxp`
agg	Image aggregates, which are used to render one or more grids together as images.	`import geosoft.gxpy.agg as gxagg`
coordinate_system	Coordinate system handling	`import geosoft.gxpy.coordinate_system as gxcs`
dataframe	Tables, which are compatible with Pandas dataframes	`import geosoft.gxpy.dataframe as gxdf`
gdb	Geosoft database (gdb) handling	`import geosoft.gxpy.gdb as gxgdb`
geometry	Basic geospatial geometric types	`import geosoft.gxpy.geometry as gxgm`
grid	Geosoft grid handling.	`import geosoft.gxpy.grid as gxgrd`
group	Drawing groups for 2D and 3D drawing into views.	`import geosoft.gxpy.group as gxg`
map	Geosoft maps, which are containers for 2D views and `geosoft_3dv` views.	`import geosoft.gxpy.map as gxmap`
metadata	Geosoft metadata	`import geosoft.gxpy.metadata as gxmeta`
project	Geosoft project instance to work with a Geosoft Desktop project.	`import geosoft.gxpy.project as gxpj`
system	System-level functions.	`import geosoft.gxpy.system as gxsys`
utility	General-purpose utilities.	`import geosoft.gxpy.utility as gxutil`
va	Geosoft vector array handling.	`import geosoft.gxpy.va as gxva`
view	2D and 3D (`geosoft_3dv`) views.	`import geosoft.gxpy.view as gxv`
viewer	Viewer for maps and `geosoft_3dv` files.	`import geosoft.gxpy.viewer as gxvwr`
vv	Geosoft vector handling.	`import geosoft.gxpy.vv as gxvv`