geosoft.gxpy.utility submodule

Utility functions to support Geosoft Python scripts and modules.

exception geosoft.gxpy.utility.UtilityException

Bases: Exception

Exceptions from this module.

New in version 9.1.

geosoft.gxpy.utility.check_version(v, raise_on_fail=True)

Check the minimum API version.

Parameters:
  • v – minimum version string required (ie “9.1” or “9.2.4”)
  • raise_on_fail – if True, raises an error if the version check fails, returns False otherwise
Returns:

True if version is OK, False otherwise(unless raise_on_fail is False)

Note

A valid version consists of two or three dot-separated numeric components, with an optional development version tag on the end. The development version tag consists of the letter ‘b’ (for beta) followed by a number. If the numeric components of two version numbers are equal, then a development version will always be deemed earlier (lesser) than one without.

The following are valid version numbers (shown in order of used for meeting minimum requirements):

  • 9.1 or 9.1.0 (they are equivalent)
  • 9.1.1b0 (development version)
  • 9.1.1
  • 9.2

The following are examples of invalid version numbers:

  • 1
  • 2.7.2.2
  • 1.3.a4
  • 1.3pl1
  • 1.3c4

The rationale for this version numbering system is explained in the distutils documentation.

New in version 9.1.

geosoft.gxpy.utility.decode(s, f)

Decode a string (s) to a numpy format defined by string (f).

Parameters:
  • s – string to decode
  • f –

    format string:

    b Boolean
    i (signed) integer
    u unsigned integer
    f floating-point
    S string, interpreted as ‘U’ unicode
    a string, interpreted as ‘U’ unicode
    U unicode, requires length suffix, ie ‘U1’, ‘U14’
Times:

Times in the form hh:mm:ss.sss return a decimal hour.
Dates:

Dates in form yyyy-mm-dd, yyyy-m-d, yy/mm/dd or yyyy/m/d will be decoded naturally and return a decimal Gregorian year. Other date formats will raise a ValueErr.
Errors:
TypeError if unable to recognize type
ValueError if there is a problem with the string.

New in version 9.1.

geosoft.gxpy.utility.dict_from_lst(lst)
Returns:python dictionary from a Geosoft GXLST

New in version 9.1.

geosoft.gxpy.utility.display_message(title, message)

Display a message to the user.

Parameters:
  • title – message title
  • message – message

New in version 9.1.

geosoft.gxpy.utility.dtype_gx(gtype)
Returns:numpy dtype from a GX type

New in version 9.1.

geosoft.gxpy.utility.dummy_mask(npd)

Return a 1-D dummy mask that is True for all rows in a 2D numpy array that have a Geosoft dummy value.

Parameters:npd – numpy data array
Returns:numpy 1D array, True for any row that had a dummy in any data field

New in version 9.1.

geosoft.gxpy.utility.get_parameters(group='_', parms=None, default=None)

Get parameters from the Project Parameter Block. Note that parameter names will always be upper-case.

Parameters:
  • group – name in the parameter block group name
  • parms – if specified only these items are found and returned, otherwise all are found and returned
  • parms – default parameter setting returned for parameters not found, otherwise dict will not have the parameter.
Returns:

dictionary containing group parameters

New in version 9.1.

geosoft.gxpy.utility.get_shared_dict()

Get a dictionary shared by an external application. The shared dictionary is cleared (popped) so a subsequent call will return an empty dictionary.

New in version 9.1.

geosoft.gxpy.utility.gx_dtype(dtype)
Returns:GX type for a numpy dtype

New in version 9.1.

geosoft.gxpy.utility.gx_dummy(dtype)
Returns:GX dummy for this dtype

New in version 9.1.

geosoft.gxpy.utility.project_path()

Return the Geosoft project folder path.

New in version 9.1.

geosoft.gxpy.utility.rdecode(s)

Geosoft string (number, date, time, geographic) conversion to a number, always works.

Parameters:s – string to decode
Returns:decoded number, gxapi.rDUMMY if unable to decode the string

See rdecode_err(string) for more details.

New in version 9.1.

geosoft.gxpy.utility.rdecode_err(s)

Geosoft string conversion to a number, raising ValueError on failure

Parameters:s – string to be decoded
Returns:float of decoded string
If unable to decode string:
rdecode_err() raises ValueError
rdecode() returns gxapi.rDUMMY

Any string that begins with “*” character is interpreted as a dummy.

If unable to directly convert simple string, decoder will clean-up the string by removing leading/trailing white space and converting ‘o’ or ‘O’ to numeral ‘0’.

If decoder still fails, it will attempt to decode time and geographic formatted strings to return decimal hours or decimal degrees respectively:

Date:
yyyy-mm-dd
yyyy/mm/dd
date will be fractional Gregorian year
Time:
hh:mm:ss.ssAM/am
hh:mm:ss.ssPM/pm
PM/pm adds 12 hours (for example 2:30pm returns 14.5)
Geographic:
[+/-]deg mm ss.ss[N/S/E/W/n/s/e/w]
[+/-]deg.mm.ss.ss[N/S/E/W/n/s/e/w]
S/s and W/w return negative of decoded value

Example:
“-90 15 18.0” = “90 15 18.0W” = “90.15.18w”, returns -90.255
“14” = “14N” = “14.00.00” = “14 00 00”, returns 14.0

Note that mm and ss.ss can go over 60.0 and will be decoded as minutes or seconds as presented. For example, “20 90 0.00” will return 21.5.

New in version 9.1.

geosoft.gxpy.utility.run_external_python(script, script_args='', python_args='', dict=None, console=True, catcherr=True)

Run a python script as an external program, returning results as a dictionary. External program can call gxpy.utility.run_return(dict) to pass a dictionary back to caller.

Parameters:
  • script – full path of the python script
  • dict – dictionary to pass to child via set/get_run_dict()
  • script_args – command line arguments as a string
  • python_args – command line arguments as a string
  • console – True (default) will create a separate console for the process.
  • catcherr – True (default) Catch and re-raise errors from the sub-process.
Returns:

dictionary registered gxpy.utility.run_return(dict)

New in version 9.1.

geosoft.gxpy.utility.save_parameters(group='_', parms={})

Save parameters to the Project Parameter Block. Parameter group names and member names are converted to upper-case.

Parameters:
  • group – parameter block group name
  • parms – dict containing named parameter settings

New in version 9.1.

geosoft.gxpy.utility.set_shared_dict(dict=None)

Save a dictionary to be shared by an separate application. This is a companion file to run_external_python().

Parameters:dict – dictionary of parameters to save

New in version 9.1.

geosoft.gxpy.utility.temp_path()

Return the Geosoft temporary folder path.

New in version 9.1.

geosoft.gxpy.utility.time_stamp()
geosoft.gxpy.utility.user_path()

Return the Geosoft user configurations folder path.

New in version 9.1.

geosoft.gxpy.utility.yearFromJulianDay2(jd1, jd2)
Parameters:
Returns:

decimal Gregorian year (Western calendar year)

New in version 9.1.