geosoft.gxpy.gdb submodule¶

Geosoft databases for line-oriented spatial data.

Classes:

Geosoft_gdb Geosoft line database

Note

Regression tests provide usage examples: Tests

exception geosoft.gxpy.gdb.GdbException¶

Bases: Exception

Exceptions from geosoft.gxpy.gdb.

New in version 9.1.

class geosoft.gxpy.gdb.Geosoft_gdb¶

Bases: object

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

Constructors:

`open()`	open an existing file, or if not specified open/lock the current database
`new()`	create a new database

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 gxdb

# open the current database
gdb = gxdb.Geosoft_gdb.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 gxdb

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

    # open a database
    gdb = gxdb.Geosoft_gdb.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.Geosoft_gdb.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.Geosoft_gdb.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.

compression¶: database compression setting

coordinate_system¶: the coordinate system of the current xyz_channels().

data_has_changed¶: True if data has changed

db_size_kb¶: database size in kb

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.

extent_xyz()¶

Return the spatial extent of all selected data in the database.

Returns:	(xmin, ymin, zmin, xmax, ymax, zmax)

New in version 9.2.

file_name¶: Database file name.

free_blocks¶: number of free blocks

gxdb¶: geosoft.gxapi.GXDB instance

index_size_kb¶: index size in kb

is_channel(chan, raise_err=False)¶: Returns True if the channel name exists

is_line(line, raise_err=False)¶: Returns True if the line name exists

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
Raises:	GdbException if line not found or cannot be created

New in version 9.1.

lines(select=True)¶: Deprecated since version 9.2: use list_lines()

list_channels(chan=None)¶

Return a dict of channels in the database.

Parameters:

chan –

channel filter, default CHAN_ALL:

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

Parameters:	select=True – True to return selected lines, false to return all lines
Returns:	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.

lost_blocks¶: lost blocks that might be freed

max_blobs¶: maximum blobs allowed

max_block_size_bytes¶: maximum block size in bytes

max_channels¶: maximum number of channels allowed

max_lines¶: maximum number of lines allowed

metadata¶: Return the database metadata as a dictionary. Can be set, in which case the dictionary items passed will be added to, or replace existing metadata.

New in version 9.2.

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
Returns:	`Geosoft_gdb` instance

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:

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.

number_of_blocks¶: number of blocks

classmethod open(name=None)¶

Open an existing database.

Parameters:	name – name of the database, default is the current project database
Returns:	`Geosoft_gdb` instance

New in version 9.1.

page_size_bytes¶: blocking page size

pages_for_blobs¶: pages consumed by blobs

readLine(*args, **kwargs)¶: Deprecated since version 9.2: use read_line()

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_channel_va(line, channel, dtype=None)¶

Read VA data from a single channel, return in a va.

Parameters:	line – line name or symbol channel – channel name or symbol dtype – type wanted, default same as the channel data
Returns:	va

New in version 9.2.

read_channel_vv(line, channel, dtype=None)¶

Read data from a single channel, return in a vv.

Parameters:	line – line name or symbol channel – channel name or symbol dtype – type wanted, default same as the channel data
Returns:	vv

New in version 9.2.

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.

read_line_vv(line, channels=None, dtype=None, fid=None, common_fid=False)¶

Read a line of data into VVs stored in a dictionary by channel.

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.
common_fid – True to resample all channels to a common fiducial
fid – required fid (start, increment), ignored if common_fid=False. if common_fid=True and fid= is not defined, use the smallest common fid.

Returns:

list of tuples [(channel_name, vv), ...]

If a requested channel is a VA, it is 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

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

New in version 9.2.

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

Change selected state of a line, or group of lines

Parameters:	selection – string representing selection, comma-delimit multiple selections 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.

used_blob¶: number of blobs used

used_channels¶: number of channels used

used_lines¶: number of lines used

writeDataChan(*args, **kwargs)¶: Deprecated since version 9.2: use write_channel

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_channel_va(line, channel, va)¶

Write VA data to a single channel.

Parameters:	line – line name or symbol channel – channel name or symbol va – va data to write

New in version 9.2.

write_channel_vv(line, channel, vv)¶

Write data to a single channel.

Parameters:	line – line name or symbol channel – channel name or symbol vv – vv data to write

New in version 9.2.

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 read_line().

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.

write_line_vv(line, chan_data)¶

Write data to 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 read_line().

Parameters:	line – line to write to, name or symbol data – numpy array shape (records,channels). If single dimension, one channel. Channels are created if they do not exist. VA channels must exist. chan_data – list of tuples [(channel_name, vv), ]

Note

chan_data may contain VA data, which is defined by slice (ie. name[0], name[4]...). If VA data is included the VA channels must already exist.

New in version 9.2.

xyz_channels¶

The currently identified (x, y, z) channels. Methods that work on spatial locations will use these channels for locating the data at each fiducial of the data. Can be set using a tuple of two or three strings. For example:

gdb.xyz_channels = ('Easting', 'Northing')
gdb.xyz_channels = ('Easting', 'Northing', 'Elevation')

New in version 9.2.

Related Topics

Previous Topic

Next Topic

This Page

geosoft.gxpy.gdb submodule¶