The snaplist program is used to generate simple text reports of data and stations in the adjustment. It was initially developed to generate the information required for submitting GPS data on survey plans. These plans may require information such as projection bearings and sea level distances. snaplist derives these quantities from the GPS observations and creates an ASCII data file. This file can then be used as input for other software (such as CAD or word processing programs). snaplist may also be used for listing other aspects of data from adjustments.
Currently snaplist is limited to reporting on GPS observations and on the stations in an adjustment.
The format of the listing file generated is defined by a table format definition file. This is an ASCII file which defines the columns that will be printed in the output listing file. snaplist takes data from the binary file generated by SNAP and formats it into an output file using the definitions in the format definition file.
Before running snaplist you must create a SNAP binary file (by doing a network adjustment) and a table format definition file. You then run the program using the command:
snaplist binary_file [table_definition_file] output_file
In this command binary_file is the name of the SNAP binary file, table_definition_file is the name of the file defining the output table format, and output_file is the name of the file that will be created. The square brackets [] denote that the table definition file name is optional - they are not part of the command line.
If the table definition file name is not given then snaplist assumes that the name is snaplist. It also assumes the default extension .TBF for the file.
snaplist will look in the following places for the table definition file:
the directory containing the binary file
the users home directory (defined by the SNAPDIR environment variable)
the directory in which the snaplist program is stored.
The table definition file defines the format of the output file that snaplist will create. Essentially this file contains one or more table definitions, each of which defines several columns of data.
The format definition file is structured similarly to a SNAP command file. Each line in the file is a command consisting of one or more items separated by blank characters. The first item on the line is the name of the command. This may be followed by one or more parameters. For example the command may be delimiter, which defines the text to be used between columns in the generated table, and the value may be tab, meaning use a tab character. In the format definition file this is entered simply as
delimiter tab
The format definition file can contain comment lines which are ignored by snaplist. These are lines starting with the exclamation mark !.
Each output table is represented by a set of commands between a table and end_table command. The main commands used to define the table are the column command, which adds a column of output to the table and the data command which specifies the data that will be extracted into the table.
The overall structure of the file is thus
general
commands
table
table format commands
column ...
column ...
...
end_table
The following sections describe the formats of these commands
The following commands can occur outside a table definition:
text
text
to be copied to the output file
end_text
The text .. end_text commands define text that is to be copied directly to the output file without modification. Any amount of text can be included between these commands. The end_text command must start in the first column of the command definition file.
angle_format format_definition
Defines the format used for angles (such as bearings) in the output file. Angles are output as degrees, minutes, and seconds. The format_definition defines the text that will occur after each component of the angle. It is a string formatted as
#ddd#mmm#sss
where ddd is the string printed after the degrees, mmm is the string printed after the minutes, and sss is the string printed after the seconds. The character # is any character that does not occur in the strings and is used to delimit the three strings. Special characters can be included in the strings using the string format described below.
table
table
definition commands
end_table
The table command prints a table in the output file using the format defined by the table definition commands.
The following commands are used within a table definition to specify the layout of the table. The table definition must include a data, delimiter, and column command.
data data_source
Specifies the data that will be printed in the table. Currently data_source must be gps (for gps observations) or stations (for the stations).
delimiter delimiter_string
Defines the text that will be printed between each column of data. The delimiter string can be tab, comma, blank, none or text expressed using the string format described below.
quote quote_string
Defines the text that will be used on either side of quoted columns. (To specify that a column is quoted see the definition of the column command.) The quote string is defined in the same way as the delimiter_string.
coordsys code
Defines the coordinate system used to represent coordinates in tables of station data.
column name options
Adds a column to the table. name defines the data item that will be listed in the column, and the options provide additional formatting information. For GPS data name can be one of the following:
|
Name |
Data item |
|
from |
First station code |
|
to |
Second station code |
|
obs_ell_dist |
Observed ellipsoidal distance |
|
calc_ell_dist |
Calculated ellipsoidal distance |
|
ell_dist_err |
Error in ellipsoidal distance |
|
ppm_ell_dist_err |
Error in ellipsoidal distance as part per million |
|
rf_ell_dist_err |
Error in ellipsoidal distance as a representative fraction |
|
hor_vec_err |
Length of the error in horizontal component of vector |
|
ppm_hor_vec_err |
Error in horizontal component of vector as ppm of horizontal length of vector |
|
rf_hor_vec_err |
Error in the horizontal component of the vector as a representative fraction of the length of the horizontal vector. |
|
obs_prj_brng |
Observed projection bearing |
|
calc_prj_brng |
Calculated projection bearing |
|
prj_brng_err |
Error in projection bearing (in seconds) |
|
ppm_prj_brng_err |
Error in the projection bearing represented as part per million (or microradians) |
|
rf_prj_brng_err |
Error in the projection bearing as a representative fraction |
For station data the name can be one of
|
code |
The station code |
|
name |
The station name |
|
northing |
The station northing |
|
easting |
The station easting |
|
height |
The height of the station |
|
h_max_error |
The length of the major axis of the error ellipse |
|
h_min_error |
The length of the minor axis of the error ellipse |
|
h_max_brng |
The orientation of the major axis |
|
change_east |
The east component of the coordinate change |
|
change_north |
The east component of the coordinate change |
|
change_up |
The east component of the coordinate change |
The column command can include options which affect the formatting of the column. An option is generally formatted as option=value. There should be no spaces in or between the option and the value. The valid options are:
|
width=### | Specifies the number of characters used to print the column. If the data exceeds this width then the column is expanded to accommodate it. |
|
align=# | Defines the alignment of the data in the within the column. # can be one of left, centre, or right |
|
ndp=# | Defines the number of decimal places that will be used for numeric columns |
|
quote | Specifies that the field will be enclosed between quote characters (defined by the quote command). |
|
prefix=### | Defines a string that will be printed in front of the field (outside the quote marks). The format of the string is defined below |
|
suffix=### | Defines a string that will be printed after the field (outside the quote marks). The format of the string is defined below |
|
header=### | Defines the text that will be written as a label at the top of the column. The header can be written on more than one line by including new line characters \n in the string. See below for more information about formatting strings. |
Many of the commands and options define text strings that will be printed in the output file. These can include non-printing or special characters as well as normal text. When snaplist reads the string it interprets the backslash (\) and underscore (_) characters specially.
The underscore character is replaced by a blank character. This is used when a space character cannot be included in the string explicitly (for example in the prefix=### option of the column command).
The backslash character introduces an escape sequence. This is series of characters which represent another character which cannot be explicitly put into the command file. The escape sequences that snaplist recognises are:
|
\b | prints a blank character (equivalent to underscore) |
|
\n | print a new line |
|
\t | print a tab character |
|
\x## | print the character with hexadecimal value ##. For example to include carriage return (0D hex) the string would be \x0D. |
|
\\ | print the backslash character |
|
\_ | print the underscore character |