API Documentation

davies.compass

davies.compass: Module for parsing and working with Compass source files

class davies.compass.Project(name=None, filename=None)

Representation of a Compass .MAK Project file. A Project is a container for DatFile objects.

See: Compass Project File Format

Variables:

• name – (string)
• filename – (string)
• base_location – (UTMLocation)
• linked_files – (list of DatFile)
• fixed_stations – (map of DatFile -> station -> UTMLocation)

add_linked_file(datfile)

Add a DatFile to linked_files.

add_linked_station(datfile, station, location=None)

Add a linked or fixed station

static read(fname)

Read a .MAK file and produce a Project

set_base_location(location)

Configure the project’s base location

write(outfilename=None)

Write or overwrite this .MAK file

class davies.compass.UTMLocation(easting, northing, elevation=0.0, zone=0, datum=None, convergence=0.0)

Represents a UTM-based coordinate for fixed stations.

class davies.compass.UTMDatum

Enumeration of common geographic datums.

class davies.compass.DatFile(name=None, filename=None)

Representation of a Compass .DAT File. A DatFile is a container for Survey objects.

See: Compass Survey Data File Format

Variables:

• name – (string) the DatFile’s “name”, not necessarily related to its filename
• filename – (string) underlying .DAT file’s filename
• surveys – (list of Survey)

add_survey(survey)

Add a Survey to surveys.

excluded_length

Surveyed length which does not count toward the included total

included_length

Surveyed length, not including “excluded” shots

length

Total surveyed length.

static read(fname)

Read a .DAT file and produce a Survey

write(outfname=None)

Write or overwrite a Survey to the specified .DAT file

class davies.compass.Survey(name='', date=None, comment='', team='', declination=0.0, file_format=None, corrections=(0.0, 0.0, 0.0), corrections2=(0.0, 0.0), cave_name='', shot_header=(), shots=None)

Representation of a Compass Survey object. A Survey is a container for Shot objects.

See: Compass Survey Data File Format

Variables:

• file_format – (str) format string which defines how Compass will view/edit underlying survey data; setting this property will in turn set all the other file format properties listed below; should be a string of 11 - 13 characters
• bearing_units – (chr) ‘D’
• length_units – (chr)
• passage_units – (chr)
• inclination_units – (chr)
• passage_dimension_order – (list of chr)
• shot_item_order – (list of chr)
• backsight – (chr)
• lrud_association – (chr)

add_shot(shot)

Add a shot dictionary to shots, applying this survey’s magnetic declination

excluded_length

Surveyed length which does not count toward the included total

included_length

Surveyed length, not including “excluded” shots

length

Total surveyed length, regardless of exclusion flags.

class davies.compass.Shot(*args, **kwargs)

Representation of a single shot in a Compass Survey.

See: Compass Survey Data File Format

__init__(*args, **kwargs)

Parameters:

• FROM – (str) from station
• TO – (str) to station
• BEARING – (float) forward compass in decimal degrees
• AZM2 – (float) back compass in decimal degrees
• INC – (float) forward inclination in decimal degrees
• INC2 – (float) back inclination in decimal degrees
• LENGTH – (float) distance in decimal feet
• FLAGS – (collection of Exclude) shot exclusion flags
• COMMENTS – (str) text comments, up to 80 characters long
• declination – (float) magnetic declination in decimal degrees

Variables:

declination – (float) set or get magnetic declination adjustment

azm

Corrected azimuth, taking into account backsight, declination, and compass corrections.

flags

Shot exclusion flags as a set

inc

Corrected inclination, taking into account backsight and clino corrections.

length

Corrected distance, taking into account tape correction.

class davies.compass.Exclude

Shot flags

class davies.compass.CompassProjectParser(projectfile)

Parser for Compass .MAK project files.

__init__(projectfile)

Parameters:projectfile – (string) filename

parse()

Parse our project file and return Project object or raise ParseException.

class davies.compass.CompassDatParser(datfilename)

Parser for Compass .DAT data files

__init__(datfilename)

Parameters:datfilename – (string) filename

parse()

Parse our data file and return a DatFile or raise ParseException.

exception davies.compass.ParseException

Exception raised when parsing fails.

davies.compass.plt

davies.compass.plt: Module for parsing and working with Compass .PLT plot files

class davies.compass.plt.Plot(name=None)

Compass .PLT plot file. A Plot is a container for Segment objects.

add_fixed_point(name, coordinate)

Add a (Y, X, Z) tuple to fixed_points.

add_loop(n, common_sta, from_sta, to_sta, stations)

Add a loop tuple to loops.

add_segment(segment)

Add a Segment to segments.

set_bounds(ymin, ymax, xmin, xmax, zmin, zmax, edist=None)

Set Y,X,Z bounds for the plot.

class davies.compass.plt.Segment(name=None, date=None, comment=None)

Compass .PLT segment. A segment is a container for Command objects.

add_command(command)

Add a Command to commands.

set_bounds(ymin, ymax, xmin, xmax, zmin, zmax)

Set Y,X,Z bounds for the segment.

class davies.compass.plt.MoveCommand(y, x, z, name, l, r, u, d, edist, flags=None)

Compass .PLT plot command for moving the “plotting pen” to a specified Y,X,Z coordinate.

class davies.compass.plt.DrawCommand(y, x, z, name, l, r, u, d, edist, flags=None)

Compass .PLT plot command for drawing a line segment between two points.

class davies.compass.plt.CompassPltParser(pltfilename, strict_mode=False)

Parser for Compass .PLT plot files.

__init__(pltfilename, strict_mode=False)

Parameters:pltfilename – string filename

parse()

Parse our .PLT file and return Plot object or raise ParseException.

davies.pockettopo

davies.pockettopo: Module for parsing and working with exported PocketTopo survey data

class davies.pockettopo.TxtFile(name=None, length_units='m', angle_units=360)

Representation of a PocketTopo .TXT File. A TxtFile is a container for Survey objects.

Variables:

• name – (string) the TxtFile’s “name”
• length_units – (string) m (default) or feet
• angle_units – (int) 360 for degrees (default) or 400 for grads
• surveys – (list of Survey)
• reference_points – (dict of UTMLocation by station)

add_reference_point(station, utm_location)

Add a UTMLocation to reference_points.

add_survey(survey)

Add a Survey to surveys.

length

Total surveyed length.

static read(fname, merge_duplicate_shots=False, encoding='windows-1252')

Read a PocketTopo .TXT file and produce a TxtFile object which represents it

class davies.pockettopo.Survey(name=None, date=None, comment=None, declination=0.0, cave_name=None, length_units='m', angle_units=360, shots=None)

Representation of a PocketTopo Survey object. A Survey is a container for Shot objects.

add_shot(shot)

Add a Shot to shots, applying our survey’s declination to it.

length

Total surveyed cave length, not including splays.

total_length

Total surveyed length including splays.

class davies.pockettopo.MergingSurvey(name=None, date=None, comment=None, declination=0.0, cave_name=None, length_units='m', angle_units=360, shots=None)

Representation of a PocketTopo Survey object. A Survey is a container for Shot objects. This Survey implementation merges “duplicate” shots into a single averaged shot.

PocketTopo (and DistoX) convention is to use triple forward shots for mainline survey. When adding a new shot to this class with add_shot(), if we detect that the previous shot was between the same two stations, we average values and merge the two together instead of appending the duplicate shot. We use a “running” mean algorithm, so that this feature works for any number of subsequent duplicate shots (two, three, four...).

add_shot(shot)

Add a shot dictionary to shots, applying our survey’s declination, and optionally averaging and merging with duplicate previous shot.

class davies.pockettopo.Shot(*args, **kwargs)

Representation of a single shot in a PocketTopo Survey.

Parameters:

• FROM – (str) from station
• TO – (str) optional to station
• LENGTH – (float) distance
• AZM – (float) compass
• INC – (float) inclination
• COMMENT – (str)
• declination – (float) optional

Variables:

declination – (float) set or get the applied magnetic declination for the shot

azm

Corrected azimuth, taking into account declination.

inc

Corrected inclination.

is_splay

Is this shot a “splay shot”?

length

Corrected distance.

class davies.pockettopo.PocketTopoTxtParser(txtfilename, merge_duplicate_shots=False, encoding='windows-1252')

Parses the PocketTopo .TXT file format

parse()

Produce a TxtFile object from the .TXT file