Geosoft GX API

The complete Geosoft GX API is exposed to python developers through the geosoft.gxapi module. 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 geosoft.gxapi.GXContext

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.

See also

Class coordinate_system=:class:.gxpy.gx.GXpy

clear_ui_console() → None:

Clears the console owned by UI applications. Has no effect on consoles owning standalone scripts.

New in version 9.1.

static create((str)application, (str)version, (int)parent_wnd_id=0, flags=0) → GXContext:

Creates the GX execution context (will return the current one if it exists).

Parameters:
  • application – Calling application name (str)”
  • version – Calling application version (str)
  • parent_wnd_id – Calling application main window handle (HWND cast to unsigned on Windows) as an int (default 0)
  • flags – 0 default; 64 suppresses text progress messages; 128 suppresses GUI progress window
Returns:

A GX execution context.

New in version 9.1.

static current() → GXContext:

Get the current thread’s GX execution context (throws if not created yet).

Returns:A GX execution context.

New in version 9.1.

enable_application_windows((bool)enable) → None:

Used by to prevent user interaction while showing modal windows with APIs where it might be hard to use proper window parenting (e.g. in Python with PyQt, tkinter, wxPython etc.). Take care to enable window prior to any calls that need user interaction, e.g. The geosoft.gxapi.GXEMAP digitization methods.

Parameters:enable (bool) – True to enable, False to disable keyboard and mouse interaction

New in version 9.1.

get_active_wnd_id() → int:

Get currently active window (main window, floating document or other popup, 0 if not available).

Returns:Window handle as an int (HWND cast to unsigned on Windows)

New in version 9.1.

get_main_wnd_id() → int:

Get the main window handle (0 if not available).

Returns:Window handle as an int (HWND cast to unsigned on Windows)

New in version 9.1.

has_ui_console() → bool:

Checks if a console owned by UI applications is available

Returns:True is the parent has UI console.

New in version 9.1.

show_ui_console((bool)show) → None:

Shows or hides console owned by UI applications. Showing the console Will also bring the window to the front if behind other application windows. Has no effect on consoles owning standalone scripts.

Parameters:show – True to show False to Hide

New in version 9.1.

_sources/config.rst.txt

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 te 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 :code`value` property that holds the reference to the immutable.

class geosoft.gxapi.str_ref
class geosoft.gxapi.bool_ref
class geosoft.gxapi.int_ref
class geosoft.gxapi.float_ref

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 geosoft.gxapi.GXCancel

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 geosoft.gxapi.GXExit

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 geosoft.gxapi.GXAPIError

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 geosoft.gxapi.GXError

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.