Geosoft GX API¶

The complete Geosoft GX API is exposed to python developers through the geosoft.gxapi package. This includes all low-level classes and function calls that expose almost all Geosoft functionality to a developer.

The GXContext class¶

Before calling any other API function from a stand-alone script (a script that is not run as an extension from Geosoft Desktop), a GX Context must be created and held. This can be done by creating an instance of geosoft.gxapi.GXContext or an instance of geosoft.gxpy.gx.GXpy, which handles the details of GXContext for you. We recommend using geosoft.gxpy.gx.GXpy unless you have chosen to work only with the low-level geosoft.gxapi. Note that the low-level module geosoft.gxapi, although more complex, is more consistent across versions.

Creating a GX context requires any version of Geosoft Desktop to be installed on the target system, from which the library dll’s are located and loaded. Geosoft Desktop can be downloaded from Geosoft Downloads.

It is possible to redirect the location of dlls used by setting the GX_GEOSOFT_BIN_PATH environment variable to reference the location of the Geosoft binary files. Refer to the GX Developer Guide for more information.

class GXContext(wrapper)[source]¶

The main GX execution context.

A single instance of this object must be created per thread and persist before using any other class in the geosoft.gxapi module.

GXAPI Instance Resource Garbage Collection¶

The GXAPI Python garbage collection is not in reverse-order of creation, which can lead to resources that depend on prior resources being destroyed out of order. For example, the following will assert on exit:

vox = gxapi.GXVOX.create('v1.geosoft_voxel')
voxe = gxapi.GXVOXE.create(vox)

This is because Python garbage collection releases the vox instance before the voxe instance. To avoid this problem, when creating a class instance that depends on a prior class instance, explicitly free the dependant instance as follows:

vox = gxapi.GXVOX.create('v1.geosoft_voxel')
voxe = gxapi.GXVOXE.create(vox)  # voxe depends on vox

# ... do some work with voxe ...

# release the voxe resource to ensure it is released before vox
del voxe

Helper classes to pass immutable values by reference¶

Each of the classes below can be used to pass these immutable types by reference to the GX API. Instances of the objects have a value property that holds the reference to the immutable object.

class str_ref[source]¶

class bool_ref[source]¶

class int_ref[source]¶

class float_ref[source]¶

Default instances will be intialized with dummy values for float_ref and int_ref, an empty string for str_ref and False for bool_ref. One can also set the value during intialization or assigning to the value property.

Example usage:

import geosoft.gxapi as gxapi

ctx = gxapi.GXContext.create("sample", "1.0")
_3dn = gxapi.GX3DN.create(ctx)

# the GX3DN get_point_of_view() method requires float_ref class to return values
distance = gxapi.float_ref() # value property will be initially be gxapi.rDUMMY
rot1 = gxapi.float_ref(1.01) # value property will be equal to 1.01
rot2 = gxapi.float_ref(2.0)  # value property will be equal to 2.0
rot2.value = 4  # value propertyis changed to 4.0

# the values in the objects will be changed to the current point of view
_3dn.get_point_of_view(distance, rot1, rot2)

print(distance.value) # value property will now be 8.0
print(rot1.value) # value property will now be 0.0
print(rot2.value) # value property will now be 0.0

Exceptions¶

exception GXCancel[source]¶: A subclass of SystemExit which is raised when a script should cleanly exit due to a cancellation condition. Generally not caught since it will have the same effect as SystemExit for both standalone and Oasis montaj extension scripts. Raised from within API by geosoft.gxapi.GXSYS.cancel()

New in version 9.1.

exception GXExit[source]¶: A subclass of SystemExit which is raised when a script should cleanly exit due to a completion condition. Generally not caught since it will have the same effect as SystemExit for both standalone and Oasis montaj extension scripts. Raised from within API by geosoft.gxapi.GXSYS.exit()

New in version 9.1.

exception GXAPIError[source]¶: A subclass of RuntimeError which is raised whenever the GX Python API encounters initialization issues or other API violations. It generally indicates a bug in Python code.

New in version 9.1.

exception GXError(message, module, error_number)[source]¶: A subclass of RuntimeError which is raised whenever a GX Python API call encounters an error. Often the message string of these errors are informative to the user (e.g. File ‘x’ is locked in another application) but there could be cases where this is not the case. In most cases an attribute, number, is also available on the exception object that matches the number in the geosoft.ger file. These numbers instead of the string (which could change or even be translated) should be used to identify and handle very specific exceptions.

New in version 9.1.

Table of Contents

This Page