geosoft.gxpy.gdb submodule¶

exception geosoft.gxpy.gdb.GDBException¶

Bases: Exception

Exceptions from this module.

New in version 9.1.

class geosoft.gxpy.gdb.GXdb¶

Bases: object

Class to work with Geosoft databases. This class wraps many of the functions found in geosoft.gxapi.GXDB.

Member ._db is the GXDB handle, which can be used to call gxapi methods.

Constructor open:
	open open an existing file, or if not specified open/lock the current database.
Member fileName:
	database file name

Some typical programming patterns

Python Oasis extension opens read through all data in the current database:

import os,sys
import numpy as np
import gxpy.gx as gxp
import gxpy.gdb as gxgdb

# open the current database
gdb = gxdb.GXdb.open(gxp)
lines = gdb.lines()
for line in lines:

    npd,ch,fid = gdb.read_line(line)
    # npd is a 2D numpy array to all data in this line.
    # ch is a list of the channels, one channel for each column in npd.
    # Array channels are expanded with channel names "name[0]", "name[1]" ...
    # fid is a tuple (start,increment) fiducial, which will be the minimum start and smallest increment.

    # ... do something with the data in npd ...

External Python program to open and read through all data in a database:

import os,sys
import numpy as np
import gxpy.gx as gxp
import gxpy.gdb as gxgdb

# initalize the gx environment - required for external programs.
gxp = gxu.GXpy()

# open a database
gdb = gxdb.GXdb.open(gxp,'test.gdb')
lines = gdb.lines()
for line in lines:

    npd,ch,fid = gdb.read_line(line)
    # npd is a 2D numpy array to all data in this line.
    # ch is a list of the channels, one channel for each column in npd.
    # Array channels are expanded with channel names "name[0]", "name[1]" ...
    # fid is a tuple (start,increment) fiducial, which will be the minimum start and smallest increment.

    # ... do something with the data in npd ...

The following creates a new channel that is the distance from the origin to the X,Y,Z location of every point. This code assumes that there are no dummies in the X, Y or Z channels (the next example shows how to deal with dummies).

...
gdb = gxdb.GXdb.open(gxp,'test.gdb')
lines = gdb.lines()
for line in lines:

    npd,ch,fid = gdb.read_line(line, channels=['X','Y','Z'])

    squares = npd.square(npd)
    dist = np.sqrt(npd[0] + npd[1] + npd[2])

    gdb.write_channel(line, 'distance', dist, fid)

Create a distance channel (as in previous example), with dummy handling:

...
gdb = gxdb.GXdb.open(gxp,'test.gdb')
lines = gdb.lines()
for l in lines:

    ln, lsymb = gdb.line_name_symb(l)

    data, ch, fid = gdb.read_line(lsymb, channels=['X','Y','Z'])
    dummy = gxu.gx_dummy(data.dtype)

    # get a dummy mask, True for all rows with a dummy
    dummy_mask = gxu.dummy_mask(data)

    squares = npd.square(npd)
    dist = np.sqrt(npd[0] + npd[1] + npd[2])

    # insert dummies using the dummy mask, then write
    dist[dummy_mask] = dummy
    gdb.write_channel(lsymb, 'distance', dist)

New in version 9.1.

channel_details(channel)¶

Return dictionary of channel details

Parameters: channel – channel name or symbol

Returns:

dictionary:

Key	Meaning
name	channel name
symbol	channel symbol
class	class name
format	format, one of gxapi.DB_CHAN_FORMAT constants
width	display width in characters
decimal	decimal places to display
unit	measurement unit
label	channel label, which can be different from the channel name
protect	proptection: 0 can be modified; 1 protected from modification
columns	number data columns, 1 for normal channels, n for VA channels
type	data type, one of gxapi.DB_CATEGORY_CHAN constants

New in version 9.1.

channel_dtype(channel)¶

Returns channel numpy dtype

Parameters:	channel – channel name or symbol
Returns:	numpy dtype

New in version 9.1.

channel_fid(line, channel)¶

Return the fiducial of a line, channel

Parameters:	line – line name or symbol channel – channel name or symbol
Returns:	(start,increment)

channel_name_symb(chan)¶

Return channel name, symbol

Parameters:	chan – channel name, or symbol number
Returns:	line name, symbol, returns (‘’,-1) if invalid
Raises:	GDBException if channel does not exist

New in version 9.1.

channel_width(channel)¶

Channel array width, 1 for normal channels, >1 for VA channels.

Parameters:	channel – channel symbol or name
Returns:	array dimension, 1 for non-array channels

New in version 9.1.

commit()¶: Commit database changes.

New in version 9.1.

delete_channel(channels)¶

Delete channel(s) by name or symbol.

Parameters:	channels – channel name or symbol, or a list of channel names or symbols

New in version 9.1.

delete_line(s)¶

Delete a line by name or symbol.

Parameters:	s – line name or symbol

New in version 9.1.

discard()¶: Discard database changes.

New in version 9.1.

file_name()¶

Returns:	database file name

New in version 9.1.

line_details(line)¶

Return dictionary of line details

Parameters: line – channel name or symbol

Returns:

dictionary:

Key	Meaning
name	line name
symbol	line symbol
type	line type, one of gxapi.DB_LINE_TYPE
category	one of SYMB_LINE
date	date of the line
number	numeric line number
flight	flight number
version	line version number
groupclass	class name for grouped lines, ‘’ if not a grouped line

New in version 9.1.

line_name_symb(line, create=False)¶

Return line name, symbol

Parameters:	line – line name, or symbol number create – True to create a line if one does not exist
Returns:	line name, symbol, returns (‘’,-1) if invalid
Raises:	GDBException if line not found or cannot be created

New in version 9.1.

list_channels(chan=None)¶

Return a dict of channels in the database.

Parameters:

chan –

channel filter, default returns all channels

CHAN_ALL	all channels, normal and VA
CHAN_NORMAL	normal channels only
CHAN_ARRAY	VA channels only

Returns: dictionary {channel_names: channel_symbols}

New in version 9.1.

list_lines(select=True)¶: List of lines in the database :param select=True: True to return selected lines, false to return all lines :return: dictionary (line name: symbol)

New in version 9.1.

list_values(chan, max=1000, selected=True, dupl=50, progress=None, stop=None)¶

Build a list of unique values in a channel. Uniqueness depends on the current display format for the field.

Parameters:	chan – channel to scan max=1000 – maximum values allowed, once this maximum is reached scanning stops selected=True – True to scan only selected lines dupl – Stop growing list after this many lines fail to grow the list, 0 scans all lines progress – progress reporting function stop – stop check function
Returns:	list of values, represented as a string

New in version 9.1.

classmethod new(name, maxLines=500, maxChannels=200, maxBlobs=0, pageSize=1024, comp=None)¶

Create a new database.

Parameters:	name – database name maxLines – maximum number of lines, default 500 maxChannels – maximum number of channels, default 200 maxBlobs – maximum number of blobs, default lineschannels+20 comp* – compression: \| COMP_NONE \| COMP_SPEED (default) \| COMP_SIZE

New in version 9.1.

new_channel(name, dtype=<class 'numpy.float64'>, array=1, details={'width': 12, 'decimal': 2})¶

Return a channel symbol, create if it does not exist.

Parameters:	name – channel name dtype – numpy dtype (ie. np.int64) array – array columns (default is 1) details – dictionary containing channel details, see channel_details()
Returns:	channel symbol

Examples:

..code:

symb = gdb.newChan('X')
symb = gdb.newChan('X', dtype=np.float64, details={'decimal':4})

New in version 9.1.

new_line(line, linetype=None, group='')¶

Get a line symbol. If line exists an error is raised.

Parameters:

line – line name
linetype –
line type for creating a new line, ignored if group defines

SYMB_LINE_NORMAL normal lines, name is a string

SYMB_LINE_FLIGHT flight lines, first letter is line type
group – group name for a grouped class

Returns:

line symbol

New in version 9.1.

classmethod open(name=None)¶

Open an existing database.

Parameters:	name – name of the database, default is the current database
Returns:	GXdb instance

New in version 9.1.

read_channel(line, channel, dtype=None)¶

Read data from a single channel.

Parameters:	line – line name or symbol channel – channel name or symbol dtype – type wanted, default same as the channel data
Returns:	numpy data, fid (start, increment)

New in version 9.1.

read_line(line, channels=None, dtype=None, fid=None, dummy=None)¶

Read a line of data into a numpy array.

Parameters:

line – line to read, string or symbol number
channels – list of channels, strings or symbol number. If empty, read all channels
dtype – numpy data type for the array, default np.float64 for multi-channel data, data type for single channel data. Use “<Unnn” for string type.
fid – required fiducial as tuple (start,incr), default smallest in data
dummy –
dummy_handling for multi-channel read, default leaves dummies in place:

READ_REMOVE_DUMMYROWS remove rows with dummies, fiducials lose meaning

READ_REMOVE_DUMMYCOLUMNS remove columns with dummies

Returns:

2D numpy array shape(records,channels), list of channel names, (fidStart,fidIncr)

Raises:

GDBException if first channel requested is empty

VA channels are expanded by element with channel names name[0], name[1], etc.

Examples:

# npd - returned numpy array shape (n, number of channels)
# ch  - list of returned channels names, array channels expanded to array[0], array[1], ...
# fid - tuple (fidStart,fidIncrement), channels resampled as necessary

npd,ch,fid = gdb.read_line('L100')                           # read all channels in line "L100"
npd,ch,fid = gdb.read_line(681)                              # read all channels in line symbol 681
npd,ch,fid = gdb.read_line('L100','X')                       # read channel 'X' from line 'L100'
npd,ch,fid = gdb.read_line('L100',2135)                      # read channel symbol 2135 from 'L100"
npd,ch,fid = gdb.read_line('L100',channels=['X','Y','Z'])    # read a list of channels to (n,3) array
npd,ch,fid = gdb.read_line('L100','X',np.int32)              # read channel 'X' into integer array

New in version 9.1.

select_lines(selection='', select=True)¶

Change selected state of a line, or group of lines :param selection: string representing selection, comma-delimit multiple selections :param select=True: True to select, False to deselect

“L99:800” will select all lines of type “L” in range 99 through 800.

Use a “T” prefix for Tie lines.

Use an “F” prefix to specify lines of a specific flight.

For example, “F10” would select all lines of flight 10.

Use an empty string (“”) to select/deselect ALL lines.

New in version 9.1.

set_channel_details(channel, detail)¶

Set/change channel details from dictionary

Parameters:	channel – channel name or symbol detail – dictionary, see chan_details

New in version 9.1.

vv_np(npdata, fid=(0.0, 1.0))¶: return a VV copy of the numpy data.

write_channel(line, channel, data, fid=(0.0, 1.0))¶

Write data to a single channel.

Parameters:	line – line name or symbol channel – channel name or symbol data – numpy array (2D for VA channel) fid – tuple (fid start, increment), default (0.0,1.0)

New in version 9.1.

write_line(line, data, channels=None, fid=(0.0, 1.0))¶

Write data to a multiple channels in a line. If no channel list is provided it assumes that the data is for all channels from the line, the compliment of readDataLine().

Parameters:	line – line to write to, name or symbol data – numpy array shape (records,channels). If single dimension, one channel channels – channel name or symbol list, or a single name/symbol. If a single name is specified for multi-column data, a VA channel is assumed. fid – option fid tupple (start, increment), default (0.0,1.0)

New in version 9.1.