Python is a powerful environment for creating scientific processing applications, and is ideally suited to creating stand-alone external programs that work with the Geosoft data processing environment. GX Developer includes a Python package that can be installed with Python 3.x to support stand-alone 32-bit or 64-bit Python 3 applications, which will will work with an installed Geosoft Oasis montaj environment (version 8.2 or later). The GX API provides access to all data read and write functions as well as most of Geosoft's processing functionality, which can be combined with Python-oriented processes to create specialized applications or workflows.

Note that as of this writing (Oasis montaj 8.5) only support running Python scripts as an external application independent of a running Oasis montaj session. This is suitable for creating stand-alone Python-oriented workflows that need to work with Oasis montaj projects or data files. If you want to create a workflow that runs from an open Geosoft project, you can also create a Geosoft GX that runs (shells) a Python script (32-bit or 64-bit) to perform the processing function, which then returns control to the running Oasis montaj. The external program is able to to access almost all the functions in the Geosoft API, including the ability to open, read and write Geosoft files. The functions that are not available usually require the Oasis montaj UI and an open project.

Some uses for GX Developer for Python:

Create a stand-alone application to import an unsupported data format into Geosoft.
Export all or selected data from a Geosoft data file to some other format.
Add support for Geosoft data files to Python-based processing environment.
Access Geosoft's advanced processing functions from a Python program.
Create a specialized data processing algorithm that can be applied to data stored in a Geosoft environment.
Create a processing application that takes advantage of a 64-bit memory model and operating system.

Content

Configuring Python for Geosoft development

Configuring your system to run Python involves first installing Python and all the Python packages that your application requires; then installing the Geosoft package specific to your version of Python.

Note that Python can be configured many ways according to the needs of the Python developer. Here we describe the configurations recommended by Geosoft, though advanced Python developers may choose other configuration options. If you choose an alternate configuration you should understand the details of the Geosoft recommendation so that you can configure your system correctly.

Frequently Asked Questions

Python version 2.7 or 3.4? The Geosoft distribution packages only support Python version 3.4. Python 2.7, which was released in 2010, was the end of development for Python 2.x, and for this reason we have chosen not to support Python 2.7 (or earlier). If you are new to Python, you should start with Python 3. If you have legacy Python 2 code that you want to run with a Geosoft environment you may need to make modifications to the code to work with Python 3. See https://docs.python.org/2/howto/pyporting.html for infomation on what may be required to port Python 2 code to Python 3.

Which Python distribution? There are many distributions of Python, but Geosoft uses and recommends the WinPython distribution (http://winpython.sourceforge.net/) as this includes all the packages that are required to work with Geosoft code together with the most important and widely used packages that make up what is considered complete for a scientific application. Most notable among these is SciPy (including NumPy), which is a requirement for Geosoft. At time of writing, the latest Python distribution supported by WinPython is version 3.4, and Geosoft provides a 32-bit and 64-bit package that will work with that version.

32 or 64-bit Python? Geosoft provides packages for both 32-bit and 64-bit Python 3. However, we strongly recommend that you use the 64-bit version for any applications that target modern computers. The only reason to create 32-bit applications would be if you need to run your application on older computers that only have 32-bit Windows installed. Note that any reasonably large Python application will have challenges dealing with the memory limitations of a 32-bit environment, so if you choose to work with 32-bit Python you should be skilled in writing memory-restricted programs. Memory limitations are much less an issue with 64-bit Python applications, though even on 64-bit systems you may find yourself memory-limited for very large processing tasks. Note that the Geosoft libraries that make up the Geosoft environment support both a 32-bit and 64-bit systems, and include a memory manager that detects and optimizes memory usage for either 32-bit or 64-bit memory environments. Geosoft-oriented applications will generally run faster in a 64-bit environment.

Which IDE? Which Integrated Development Environment (IDE) to use is the personal choice of the developer. Although WinPython includes the Spyder IDE, at Geosoft we use and recommend the PyCharm IDE (http://www.jetbrains.com/pycharm/), which has both a no-cost "Community Edition" intended for education and personal use, and a very reasonably priced "Professional Edition" for professional use. Note also that WinPython (and most complete Python distributions such as Anaconda or Canopy) include IPython. Although not strictly an IDE, IPython does provide an environment for rapid algorithm development, experimentation and documentation and can be very good for researchers.

Which GUI? If you are developing simple data processing applications you may not need a GUI development environment. But if you are developing interactive applications you will need to decide which GUI development environment you wish to use. At Geosoft, we use Qt via the PySide API (https://pypi.python.org/pypi/PySide).

GX application or stand-alone? Although the current Python package only supports the creation of stand-alone applications, you may want to create a workflow that runs directly from the context of an open Geosoft project, in which case you will need to create a Geosoft GX that can be launched from Oasis montaj. In this case, you can create a GX that interacts with the user (determines which channels to process, processing parameters, etc.), prepares the project data and runs the Python script as a separate process. The GX then waits for the process to finish, after which resources are re-opened and presented to your user.

WinPython Distribution

Reference: https://winpython.github.io/

Step	What	Comments
1	Install WinPython https://winpython.github.io/	Choose the most recent version of 64-bit WinPython 3.4.x. The 32-bit version is also supported, though it is not recommended unless you must support 32-bit programs.
2	Register Python on your system	The Geosoft Python package installers require Python to be configured in the registry on your Windows system. To do this, run the "`WinPython Control Panel.exe`", which you will find in your WinPython installation folder: Select `Advanced > Register`: Registering the WinPython installation sets environment variables so that installers know the "registered" version of python, which is assumed to be your default Python. This does not add the Python folder to your path. If you need Python.exe to be found in the path you will need to add the folder that contains Python.exe to the path. For example, if you install WinPython 3.4.3 into the c:/Python folder, the folder that contains Python.exe is: `C:\Python\WinPython-64bit-3.4.3.1\python-3.4.3.amd64`
3	Install GX Developer	Download and install GX Developer. To download GX Developer, use your Geosoft ID, and register as a GX Developer. After registering you will have access to the GX Developer on-line forum, which can be used to get help using GX Developer, and to collaborate with other developers. After installing GX Developer you will find a folder named "`...\python`", which includes the Geosoft Python packages required in the next step.
4	Install the Geosoft Python package	Geosoft provides two package installers, one for 32-bit Python (win32) and one for 64-bit (amd64): `geosoft.gx_py34-8.4.0-win-amd64.exe geosoft.gx_py34-8.4.0-win32.exe` Choose and run the appropriate installer. On the Setup screen, choose Python Version 3.4 installation. Note that this installation will only work with Python 3.4.x: Other Distributions: If you need to use a Python 3.4 distribution other than WinPython, you can register your distribution using the instructions for that distribution. We also provide copies of the site-packages folders that support the GX API for Python 3.4. You can copy-paste these folders as they are directly into the .../lib/site-packages folder of the 32-bit or 64-bit version of Python. Note that the folder must match the Python Version and memory model. For example, to install the Geosoft 64-bit package into a 64-bit Python 3.4 distribution, copy the folder: `C:\Program Files (x86)\Geosoft\GX Developer\python\Python3.4-64\site-packages\geosoft` And paste to your distribution site-packages folder. For example, an anaconda distribution might be located here: `C:\Users\Bob\Anaconda3\envs\py34\Lib\site-packages` After copying, you will have a geosoft folder in your site-packages folder: `C:\Users\Bob\Anaconda3\envs\py34\Lib\site-packages\geosoft`
5	Add/set environment variable `GX_GEOSOFT_BIN_PATH` to point to the Geosoft `Geodist.dll`, which is located in one of these places: C:\Program Files (x86)\Geosoft\bin C:\Program Files (x86)\Geosoft\GX Developer\redist\bin\GeosoftFiles\bin	Finally, you will need to create an environment variable, GX_GEOSOFT_BIN_PATH, which the Python API uses to locate the Geosoft Geodist.dll. In a typical Oasis montaj installation this is found in “C:\Program Files (x86)\Geosoft\bin\”. Alternatively, you can use the redistributable file included in the GX Developer installation, which is typically found in "C:\Program Files (x86)\Geosoft\GX Developer\redist\bin\GeosoftFiles\bin" Open your "Control Panel", select "System and Security", "System", then "Advanced system settings" and click on "Environment Variables...": Look under "System variables". If "`GX_GEOSOFT_BIN_PATH`" exists, select the variable in the list and "Edit...". Should "`GX_GEOSOFT_BIN_PATH`" not exist, select "New..." to add this system variable, which must point to the bin folder of your Geosoft installation as follows: For advanced users: instead of setting up a global environment variable, you can manually set the directory containing geodist.dll in your scripts with the following lines of code: >>> import os >>> os.environ['GX_GEOSOFT_BIN_PATH'] = 'C:\\path\\containing\\geodist' Ensure that you have set this environment variable before creating your GX context (see next step). This approach to locating geodist.dll can be useful if you wish to target multiple Geosoft environments on the same machine.
6	Validate your setup	open a command shell run `python.exe` from the WinPython installation folders that you installed in step 1. For example: `C:\Python\WinPython-64bit-3.4.3.1\python-3.4.3.amd64\python.exe` This will present ">>>" to allow you to enter a python code script. Enter the following four lines: >>> import geosoft.gx as gx >>> ctx = gx.GXContext.create("TestApp", "1.0") >>> gx.GXSYS.file_exist(ctx, "c:\\filename.txt") >>> exit() The first line imports gx symbols from the Geosoft GX package. This confirms that step 4 was successful. The second line creates a gx context, which both confirms that the Geodist.dll can be found and that you are signed-in to Geosoft. This verifies that the Geosoft bin path can be found, either from an existing Geosoft installation, or from the GX_GEOSOFT_BIN_PATH. If you receive an error message "Geosoft: Error loading Geodist dll", the GX_GEOSOFT_BIN_PATH is either not set, or references the wrong path. Review step 5 above. If you are NOT signed-in to Geosoft, you will be challenged to authenticate who you are. Note that users of scripts you write will also need to be signed-in to use your scripts. You and your users must have internet access to authenticate, but only for the first time or if expressly signed-out. Once once signed-in to Geosoft, users stay signed-in, even if off-line, unless they expressly sign-out by hovering over the Geosoft Connect icon in the system tray, right-mouse and select "Sign Out". We do not recommend signing-out. On 64-bit systems, if you or your user takes too long to authenticate (should authentication be required), the D-Bus server may time-out and you will receive "Error connecting to D-Bus ...". The Python execution will fail and you will need to restart your script. The third line executes a gx wrapper function, which confirms that the gx context has been correctly initialized and that you have correctly signed in with Geosoft Connect. This function will return 0 if the file exists, or 1 if the file does not exist. The last line exits the Python script. If this test works without reporting errors your system is properly configured.
7	Install other modules	Your Python script may require a generally available module that is not included in the WinPython or Anaconda distribution. For example, if a script used the module "YAML" and you get an error importing the "YAML" module, you will need to install the "YAML" package into Python. WinPython: Packages are installed either by downloading and running an "exe" file, just as we have done with with GX Developer API in step 4, or a package zip file can be downloaded from the package supplier. In the case of PyYAML, both options are supported. If you download the zip file, use the "WinPython Control Panel.exe" to add the package. First add the zip file (drag-drop, or browse to select), select the file and click on "Install packages": Anaconda: With Anacoda, most packages can be installed directly from their source using the conda.exe application (found in the Anaconda3/scripts folder). To install PyYaml, run the following from a command prompt: `conda.exe install -n py34 pyyaml`

Python Installed Files

The GX Developer installation contains the following Python specific files:

python\geosoft.gx-py34-8.4.0.win32.exe	Installer for 32-Bit Python distributions. This will install the geosoft site package to registered 32-bit Python 3.4 installation.
python\geosoft.gx-py34-8.4.0.win-amd64.exe	Installer for 64-Bit Python distributions. This will install the geosoft site package to registered 64-bit Python 3.4 installation
python\Python3.4-32\site-packages\geosoft python\Python3.4-64\site-packages\geosoft	Complete site-package folders that can be copied to site-packages folder of a Python installations that does not support "exe" style installations.
python\examples\	This folder contains simple example Python scripts that demonstrate use of the API. See also python.zip v1.1, which includes a GX (python.gx) that will run a python script from Oasis montaj. This includes versions of the example programs that will work with python.gx.

Getting Started with Python

Learning Python

GX Developer for Python is intended for experienced python developers, so learning Python is outside the scope of this document. For new Python developers, there are many online Python resources. You will find that Google search is your best assistant as you learn and continue to use Python. Here are some resources you may find helpful to get you going:

Python.org – the Python.org website has the definitive documentation for every version of Python and has an excellent Python for Beginners section
Google Python Class – Google is a big supporter of Python and has created a pretty good online course.
There is a very nice online Python text at linuxtopia.
Stackoverflow forums are an excellent source of topical help and you will find that Google searchs with questions like "python how do I ...?" will bring you to useful and specific Stackoverflow developer threads.
Experimentation – Python is interactive. You can test and run code as you write it, create functions on the fly and so on. The chanadd2 and chanadd3 code examples in particular are intended to be loaded into a shell and deconstructed.
Code examples – Once you’ve learned a few Python basics, check out the code examples included with this distribution. They include examples of working with databases and grids and demonstrate a number of Python concepts.

API Documentation

You will find the Geosoft Python GX API reference here:

GX Developer 8.5 API reference for Python

Python Samples

Update 2016-2-5

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.