Several commands (for example reject, ignore, fix) use a list of station codes to identify the stations that are affected.
The simplest form of station list is simply a list of station codes and often this is all that is required. For example:
fix ABCD 1234 BM1
which specifies that the three stations ABCD, 1234, and BM1 will be fixed.
Note that the commands or, and, except, inside, ignore_missing, warn_missing, and reject_missing are treated specially in station lists. To specify these as station codes they must be prefixed with a backslash character "\". For example to fix a station called INSIDE the following command would be used:
fix ABCD 1234 \INSIDE
When a group of stations will be referenced in several adjustments or long lists of stations it may be convenient to Sometimes it may be more convenient to put the list into a station list file. This could be useful for a long list of stations, or where the same list is going to be used in several adjustments.
For example if you wanted to be able to easily exclude all benchmarks from an adjustment you could create a file called benchmrk.stl. Each line in the file would be the code of a benchmark. Then in the command file you would include the command
reject @benchmrk
to reject them.
A station list file may contain any number of station codes and station code ranges and polygon definitions. The file can include comments as lines starting with the character !.
For more complex scenarios such as large adjustments created by automatically by scripts it may be useful to identify the stations by criteria such as location or coordinate order rather than explicitly listing the stations. To allow this the station station list can include multiple criteria. Each item in the list (items are separated by whitespace) defines a criteria. By default the criteria are treated as alternatives - a station matching any one of criteria is treated selected. However this behaviour can be modified by including and or except operators in the list. This is detailed below.
The station list can include any of the following items:
individual station codes. Where a station code would be confused with a station list keyword such as and then it is specified by prepending with a \, for example "\AND".
ranges of stations codes - entered as two station codes separated by a hyphen (eg 5-15). Station ranges are interpreted by ordering the codes numerically using the leading digits in the code, and then alphabetically using any remaining characters in the code. Using this scheme the range 5-15 would include 10 and 10A, but not 100.
a station name containing wildcard characters "?" or "*". The "?" wildcard matches any single character, and the "*" character matches any number of characters (including none).
stations specified by order - entered as order=order (eg order=3). This can be used if the coordinate file specifies station orders. More than one order can be selected by separating orders with a "/" (eg order=1/2/3).
stations specified by other classifications defined in the coordinate file - entered as class_name=value (eg mark_type=pin). More than one value can be specified by separating values with a "/" (eg mark_type=pin/spike).
stations defined in a station list file - entered as @filename. The default extension for a station list file is ".stl".
stations defined by a polygon spatial extent - entered as inside crdsys wktfile or outside crdsys wktfile. Here crdsys is the coordinate system in which the polygon is defined and wktfile is the name of a file containing the coordinates of a polygon extent in WKT (well known text) format. The default extension for the file is ".wkt".
the command or between items. This is implicit between items in a list, for example if the list is "ABCD 1234", then this is interpreted as "a station with code ABCD or 1234". If it is useful for clarity then the "or" can be written in the list.
the command and followed by a list of conditions at least one of which must be met which act as a filter on the selected stations.
the command except which identifies stations not to be included in the selection. The list can only include one except command. The rest of list defines stations which are not selected.
the commands ignore_missing, warn_missing, or fail_missing. These control the handling of station codes following in the list which are not in the command file. By default missing stations are treated as an error. Alternatively they can be ignored, or generate a warning but not a failure.
The commands and and except are not very intuitive and deserve further explanation. The station list is divided into items by blank characters, and each item may be one of those listed above. By default items are treated as alternative conditions (that is separated by or commands). The and command starts a new set of items. Only the stations included in both sets of items are included. For example the list
ABCD order=1 order=2 and @marktype=PEG @marktype=TUBE and inside NZMG aoi.wkt
would include station ABCD and stations with order 1 or order 2, but only if they had classification marktype PEG or TUBE and if they were inside the polygon defined in the aoi.wkt file.
The except condition starts a list of stations not included in the selection. There can only be one except in the command, and everything following it defines stations that are not selected. This can include items separated by and and or. For example
free all except order=0 and @purpose=CORS
would free all stations except those that are both order 0 and CORS stations. By contrast the command
free all except order=0 @purpose=CORS
would free all stations except those that are either order 0 or CORS stations.
Station lists cannot begin with and, or, or except.
Note that in a station list file each line is treated as a separate station list. A station matching any line in the file is selected. Each line can include and and except commands, and these are treated independently for each line.
The well known text format used to define polygons for the inside and outside commands is a common format for GIS systems. Many polygons can be defined in the file. However a very simplistic algorithm is used to parse the file, so it may give incorrect results if the file contains other data. The critical part of the file are one or more sequences of:
(x1 y1, x2, y2, ... , xn yn )
where x and y are the longitude and latitude or easting and northing coordinates. Any such list is treated as defining a polygon edge (either outside edge or edge of a hole in the polygon). The routine does not do any more complex testing for a valid WKT definition. The final coordinates in each such list must be the same as the initial coordinates. Note that if the file contains overlapping polygons then a point that inside an even number of them will be considerered outside the total extent. Similarly a point that is inside an odd number of them is considered inside the total extent. This algorithm handles polygons definitions which include holes.