Versions Compared

Version Old Version 4 New Version 5
Changes made by

Maki Rider (Unlicensed)

Maki Rider (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

The examples and code provided for creating stand-alone programs that use the GX Developer are provided as a guide so you know what is possible. Note that the examples provided are not tested in the Current API. As a consequence, there may be minor discrepancies between the documentation and the working examples, and the working examples may require minor changes to be functional in the current release.

The GX Developer environment provides APIs for accessing Geosoft technologies from other programming languages so you can create stand-alone programs that can read and/or write Geosoft files, or access Geosoft library functions.  API's are provided for:

  • 'C' style API which can be accessed by any language which supports the C calling convention
  • C# .NET API which can be used by any of Microsoft's .Net languages
  • C++ API in 32 bit or 64 bit which can be used by external applications 
  • Python API which can be used from standalone Python 3 scripts (both 32-bit and 64-bit).

External standalone applications can use the Geosoft redistributables to access the free and public parts of the APIs or can leverage a licensed installation, to integrate Geosoft functionality into your own application or other software packages. See Using the GX API Externally for details on how to redistribute stand-alone programs.

Note that stand-alone programs run in their own memory space and do not have access to the Oasis montaj GUI elements, including GX Developer dialogs, user messages, eDB and eMAP classes, although the formal API includes these methods as it is auto-generated from the GX API. If you call methods that depend on the Oasis montaj user interface, these methods will fail.

Stand-alone programs can be combined with a GX that collects interactive information from a user using the GXC language and then calls your program using the iShellExecute_SYS function.  Note that your program cannot open a database of map that is open in Oasis montaj, so if this is required the GX should close the database or map before running your program, and then re-open the database or map on completion. The only exception is if your program only needs to read a shared database, in which case the database can remain open in Oasis montaj. Attempting to write to an open database will fail.

Initialization and User Authentication

The GX API is initialized by a call to GXContext.create(application, version), where application is a string that describes your application, and version is a string for your version information.

Initializing the GX API establishes the credentials of the person running your program. These credentials are required to grant access to various features in the API used by your program.  Although most of the GX API is available to anyone with a Geosoft ID (freely and easily established at https://my.geosoft.com), certain features are restricted to authorized users in order to support licensing restrictions, both with Geosoft and with Geosoft's partners. Attempting to create context with a call to GXContect.create() will trigger the need for your user to be authenticated.  Authentication is managed by Geosoft Connect, which is part of the Geosoft library and part of all installed Geosoft technologies. There are two scenarios to be aware of:

Your program running with installed Geosoft technology:  In most cases, we expect your users will have some version of Geosoft installed, which as a mimimum may simply be the free Geosoft viewer. In this case your user will likely already be authenticated and GXContext.create() will use this authentication such that your user will not be challenged to sign-in. If for some reason we cannot determine the the credentials of your user, they will be challenged to authenticate (sign-in) using their Geosoft ID credentials.  Authenticating, in this case, requires an Internet connection.

Your program running independently: It is also possible to run your program from a system without any existing Geosoft technology.   In this case you will have shipped the Geosoft DLL's to support the GX API calls together with your program.  The first time your program calls GXContext.create(), your user will be challenged to provide their Geosoft ID and password on a sign-in dialog.  Should your user not have a Geosoft ID, they will have the opportunity to register on my.geosoft.com.  Once registered and authenticated, the authentication information is maintained on your user's system and, under normal circumstances, your users will not be challenged again. Note that an Internet connection is required to register a new Geosoft ID, and to authenticate for the first time. Once authentication is established an Internet connection is no longer required as the saved authentication is used each time your user runs your program.

IMPORTANT: Should your users need to use your program without an Internet connection, possibly in the field or while travelling, they must establish their identity on their system before disconnecting from the Internet.  This can be done by simply running your program once when connected to the Internet. This only needs to be done once.

Info
titleSections on this page

Table of Contents

Stand-Alone Python Script

A stand-alone python program (script) can be run from directly from Python without Oasis montaj, but and you can still access GXAPI and the GXPY modules for any functions that do not depend on Oasis montaj.

  • Use the "if __name__ == "__main__":" to isolate the stand-alone code execution path.
  • Methods in the gxpy.om module are not available.
  • Methods in the gxapi module that require Oasis montaj interface (such as GXEDB, GXEMAP, etc.) are not available.

  • You must create a GXContext before calling any Geosoft modules:

    Code Block
    # example using geosoft.gxpy
include geosoft.gxpy as gxpy
if __name__ == "__main__":
    gxc = gxpy.gx.GXpy()
	# ... your code follows ...
    Code Block
    # example using geosoft.gxapi
include geosoft.gxpy as gxapi
if __name__ == "__main__":
    gxc = gxapy.GXContext.create("my program","1.0")
	# ... your code follows ...

Python GX

There are cases where you may want to organize your workflow to use a stand-alone Python script.  For example, a python GUI application like PyQt may require a stand-alone instance.

Info
titleUpdate 2016-2-5

Image Removed

Python.gx is a GX that will run a Python script directly from an open Oasis montaj project. The GX saves all current state information to a YAML file, which the Python script can open to obtain state information, such as the current database, displayed channels, current map, etc. You will find the Python GX and source code, together with script examples here: python.zip v1.1

You will find a number of Python examples in:

 C:\Program Files (x86)\Geosoft\GX Developer\apps\examples\python

ChanAdd.py - This is a simple example of reading and writing from a Geosoft database. It also demonstrates working with command line arguments, writing to a file and how to get lists of channels and lines from a database.

GridCopy.py - A simple example showing how to copy a grid. It demonstrates the use of the GXIMG interface

GridFilter.py - This is a more sophisticated grid handling routine. The GXIMU.grid_filt function upon which it depends is complicated, because it is very flexible. It requires 10 parameters, several of which are inter-dependent. The user can specify a predefined filter or a filename containing the filter elements.  In the GX version of this utility the user can also input a filter string directly, though this has not been implemented here.

You should copy these samples to a working folder on your system, and then review how they work and experiment with your own modifications.   A number of Python concepts are demonstrated, including a filtered list comprehension, slicing, several styles of iteration and print statements, and simple text file processing
  • .
 The intention of these examples is simply to get you started
  • .
Python is a very rich language and the possibilities are limitless.

In all cases we use the Python argparse class to provide consistent use of the command line.  for example, running:

python ChanAdd.py -h

will display the command line help for the ChanAdd.py script.

You will see that all scripts will import gx.geosoft as gx, and a GX context is obtained by calling gx.GXContext.create(). Most calls into the GX API will require the GX copntext to be provided as the first argument.

The GX API also includes many constants, and you will see examples of obtaining and using these constants in these sample files.

Note that some GX methods need to pass back a simple immutable data value (string, boolean, integer or float) by reference, but passing by reference is not possible in Python.  For these situations, the GX API provides a set of simple classes which can be used to pass a mutable value that can be shared between the caller and the called function.  Search for "immutable values by reference" in the on-line documentation for more information.

And finally, we include source code for all Geosoft GX tools as part of the GX Developer package.  You can use these for reference to see how more complicated things are achieved in a GX, and the Python code will be very similar
  • .