Geosoft GX API

The Geosoft GX API is exposed to python developers through the geosoft.gxapi module. The API includes the full set of low-level function calls that expose almost all Geosoft functionality to developer.

The GXContext class

class geosoft.gxapi.GXContext

The main GX execution context

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

clear_ui_console() → None:

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

Returns:Nothing
Return type:None

New in version 9.1.

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

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

Parameters:
  • application (str) – Calling application name”
  • version (str) – Calling application version
  • parent_wnd_id (int) – Calling application main window handle (HWND cast to unsigned on Windows) as an int (default 0)
Returns:

A GX execution context.
Return type:

geosoft.gxapi.GXContext

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.
Return type:geosoft.gxapi.GXContext

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
Returns:Nothing
Return type:None

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)
Return type:int

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)
Return type:int

New in version 9.1.

has_ui_console() → bool:

Checks if a console owned by UI applications is available

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

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 (bool) – True to show False to Hide
Returns:Nothing
Return type:None

New in version 9.1.

Note

There should be a single instance of this class constructed in a global location prior to using any other GX API classes and their methods. By default the module will only function if an installed Oasis montaj product is found since it loads the dlls that are shipped with Oasis montaj for the actual functionality.

It is possible to redirect the location of dlls used by setting the GX_GEOSOFT_BIN_PATH environment variable. This can be done either using the normal Windows mechanisms (i.e. via set command line or Advanced System Settings->Environment Variables) or directly in Python code by using os.putenv("GX_GEOSOFT_BIN_PATH", ...). If your intention is to use the public standalone API that is shipped with GX Developer then this should be set to wherever the GeosoftFiles redistributable folder is copied or installed.

The UI console functions are inteded for extension scripts or scripts running in Oasis montaj or other UI applications and are launched with geosoft.gxapi.GXSYS.run_gx(). The GX execution engine will detect if it is not running in a console and create a console for that can be shown or hidden by default with a setting.

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.