Files

Files

GPSMan uses text files to store data. The Load/Save options in the menus deal with files in GPSMan format. The Import/Export options deal with files in foreign formats. In the GPStrans format (described in the documentation of GPStrans), all positions are exported in DDD format, although any available position format is accepted in imported files.

Files in GPSMan format can be either item information files (with data of different types: waypoints, routes, tracks and/or groups), or image information files (for saving information on background images for the map).

These file formats are independent of the language used. That is, there will not be commands in Tobagonian even if a lang*.tcl file was provided for it and GPSMan was set to use that language.

Item information files

Item information files in GPSMan format (based on the GPStrans format) are as follows:

• lines whose first character is a ! character are commands:

  Format definition commands

  used to describe the format used thereafter; before the definition of waypoints, routes or tracks a position format and a datum must be given.

  • !Format: P T D, where P is the position format (one of DMS, DMM, DDD, UTM/UPS), T is time offset relative to UTC (a floating-point number between -12 and 12), and D is the datum name (to end of line).
  • !Position: P, where P is the position format (one of DMS, DMM, DDD, UTM/UPS or a coordinates grid name).
  • !Datum: D, where D is the datum name (to end of line).
  • !Creation: B, where B (one of yes or no) states whether creation date fields are used.

  Data commands

  used to start a data section:

  • !W:, next lines (up to another data command or end of file) describe waypoints.
  • !R: N C, definition of route number N, with comment C (up to end of line). After such a line there may appear a remark (see !NB: command below). Next lines (up to another data command or end of file) describe the route waypoints and the route stages if any.
  • !T: M, definition of track named M. After the name and a tabulation character, fields (separated by tabulations) may occur that have attribute-value pairs under the form Attr=Val describing hidden information. After such a line there may appear a remark (see !NB: command below). Next lines (up to another data command, format definition command or end of file) describe the track points.
  • !G: M, definition of a group named M. After such a line there may appear a remark (see !NB: command below). Next lines (up to another data command, format definition command or end of file) describe the group elements.
  • !NB: T, text remark T for waypoint, route, track or group; must appear after a !R: or !T: command, or after a line describing a waypoint. The text is terminated by a blank line.

  Ancillary commands

  used

  • to describe route stages: !RS:; and
  • to define the type of group elements (see below): !GW:, !GR:, !GT:, and !GG:.

• lines describing waypoints (a !W: or !R: command appeared before) have a name, a comment, a creation date (but see the !Creation: command) and a position; all these fields are separated by tabulation characters. After these fields, in the same line and also separated by tabulations, there may be pairs under the form Attr=Val, where Attr is an attribute and Val the corresponding value; attributes currently in use, apart from those for hidden information: alt for altitude in metres, symbol (possible values: GPSMan symbol names, see file symbols.tcl), and dispopt (possible values: GPSMan display option names, see file symbols.tcl). After such a line there may appear a remark (see !NB: command above). A route waypoint may be given solely by its name if it has been defined before in the file.
• lines describing route stages (only one between two consecutive route waypoints) start by !RS: followed by a tabulation, a field with the comment, a tabulation, and a field with the label. Attribute-value pairs for hidden information may appear after a new tabulation and separated by tabulations. Empty stages should not appear.
• lines describing points in a track (a !T: command appeared before) have a tabulation character followed by a date, the position, the altitude in meters, and the depth in meters, all fields being separated by tabulation characters. If the altitude and the depth are undefined both fields are omitted; if only the depth is undefined its field is omitted; otherwise the altitude field must be present and should be void if the altitude is undefined. GPSMan accepts track point positions in any available format, but will convert them to DMS.
• lines describing elements of a group (a !G: command appeared before) have a first field followed by a tabulation character followed by a name (up to end of line). The first field is either empty or of the form !GW:, !GR:, !GT:, or !GG: that stand for group waypoint, route, track and group, respectively, and describes the type of the element. If this field is empty the type is the same as that of the previous element. A group is assumed to be well-founded: it cannot be an element of itself even in an indirect way.
• positions given by latitude/longitude are given as two fields (each as a DMS, DMM, or DDD coordinate); positions in UTM/UPS have four fields: East zone number, North zone letter, x- and y-coordinates; positions in other coordinates grids have three fields: zone (possibly empty), easting and northing. All fields are separated by a tabulation character.
• blank lines are ignored, except as terminators of remarks (see !NB: command above).
• file comments (ignored by GPSMan) start by a % character that can be preceded only by spaces and extend to the end of line.
• attribute-value pairs that describe hidden information are written as follows:
  • the attribute name starts with a capital letter that uniquely identifies the brand of the receiver (G for Garmin, L for Lowrance); the rest of the name depends on the implementation but normally will describe the protocol and the data field;
  • the value is a string containing standard ASCII characters excluding all control characters (i.e., all codes must be >= 32 and <127); the codification of the value is also implementation dependent (for an example, see the comments in proc HiddenCode in file garmin.tcl).

Image information files

These are files containing the following information:

1. a !Image: P command, with P the absolute path of the file containing the image in GIF or PNM format;
2. a !Datum: D command, with D the datum name for the coordinates;
3. a !Projection: NP As command, with NP the name of the projection to use and As a sequence of attribute-value pairs under the form Atr=Val describing projection parameters; the tabulation is used as separator for NP and each pair;
4. a !Transf: NT As command, with NT the name of the coordinate transformation to use and As a sequence of attribute-value pairs as in the previous command;
5. a !Scale: S command, where S is the floating-point value of the map scale in pixel/metre.

After this there may be one or more lines with a !Image at: XG,YG P command, where P is the absolute path of the file containing the image in GIF or PNM format, and XG,YG are the grid coordinates of the image. The grid coordinates of the first-loaded image are 0,0. GX changes by 1 (-1) for each image to the right (left), and GY changes by 1 (-1) for each image down (up).

No newlines are allowed within these commands, and arguments are separated by spaces or tabulation characters unless otherwise stated. Paths must use the slash (/) as separator.

Map information files

These are files currently used only for saving the state of the map when there is no background image. They follow the same conventions as the image information files and contain the following commands:

1. a !Map: command;
2. a !Datum: D command, with D the datum name for the coordinates;
3. a !Projection: NP As command, with NP the name of the projection to use and As a sequence of attribute-value pairs under the form Atr=Val describing projection parameters; the tabulation is used as separator for NP and each pair;
4. a !Transf: NT As command, with NT the name of the coordinate transformation to use and As a sequence of attribute-value pairs as in the previous command;
5. !Position: P, where P is the position format (one of DMS, DMM, DDD, UTM/UPS or a coordinates grid name).
6. a !Scale: S command, where S is the floating-point value of the map scale in pixel/metre.

GPSMan User Manual
©Miguel Filgueiras, mig_at_ncc.up.pt, DCC-FC & LIACC, Universidade do Porto, 2002

Files