GPSMan Files

GPSMan 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, polylines, laps 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, polylines and tracks a position format and a datum must be given.

  • !Format: P T D, where P is the position format (DMS, DMM, DDD, GRA,UTM/UPS or a coordinates grid name), T is the time offset relative to UTC (a floating-point number between -12 and 12, 1 meaning 1 hour less than UTC), and D is the datum name (to end of line). The time offset must be given in files having waypoints with creation dates, tracks, or laps. Different time offsets are not allowed in the same file (beware of concatenating data files!).

  • !Position: P, where P is the position format (DMS, DMM, DDD, GRA,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, definition of route name (or number) N. After the name and a tabulation character, a comment will appear. After the comment a new tabulation may appear followed by fields (separated by tabulations) giving attribute-value pairs under the form Attr=Val. The possible attributes are: width, colour, and mapbak, for the width in pixels and the colour of lines on the map window, and the map background to load along with the route if the map is empty. 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: N, definition of track named N. After the name and a tabulation character, fields (separated by tabulations) may occur that have attribute-value pairs under the form Attr=Val. The possible attributes are: width, colour, and mapbak, for the width in pixels and the colour of lines on the map window, and the map background to load along with the track if the map is empty. 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 and the beginnings of segments (!TS: command).

  • !L: N, definition of polyline named N. After the name and a tabulation character, fields (separated by tabulations) may occur that have attribute-value pairs under the form Attr=Val. The possible attributes are: width, colour, and mapbak, for the width in pixels and the colour of lines on the map window, and the map background to load along with the track if the map is empty. 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 polyline points and the beginnings of segments (!LS: command).

  • !LAP: T, definition of a lap with time-stamp T. After the name and a tabulation, fields (separated by tabulations) give: the duration (hours:minutes:seconds, minutes:seconds, or seconds), total distance (metre), begin position, end position, calories, track index. A position may be empty, and if not has its sub-fields separated by a space. After such a line there may appear a remark (see !NB: command below). These lines are ignored if the support for laps is not active.

  • !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, line or group; must appear after a !R:, !T:, !G:, or !LN: command, or after a line describing a waypoint. The text is terminated by a blank line.

  Ancillary commands

  used

  • to describe route stages: !RS:.
  • to define the type of group elements (see below): !GW:, !GR:, !GT:, !GL:, !GLAP: and !GG:.
  • to begin a different segment of a track (except the first one): !TS:.
  • to begin a different segment of a polyline (except the first one): !LS:.

• 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 (either as a value in metres, or as a list with value in metres, value in external unit and external unit), symbol (possible values: GPSMan symbol names, see file symbols.tcl), dispopt (possible values: GPSMan display option names, see file symbols.tcl), mapback for the map background to load along with the waypoint if the map is empty. After such a line there may appear a remark (see !NB: command above). A route waypoint must be given in full, and not solely by its name as before version 6.1; there is a separate script in the distribution (directory util, file wpsinfull.tcl) to convert old files.

• 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 and the depth (each one either as a value in metres, or as a list with value in metres, value in external unit and external unit), 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 points in a polyline (a !L: command appeared before) have a tabulation character followed by the position and the altitude (each one either as a value in metres, or as a list with value in metres, value in external unit and external unit), all fields being separated by tabulation characters. The positions must all be given in the same datum and format (there can be no commands to change the format, position format or datum between the !L: command and the last point).

• 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:, !GL:, !GLAP:, or !GG: that stand for group waypoint, route, track, polyline, lap and group, respectively, and describes the type of the element (laps will be discarded if support for them is not selected). 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, DDD or GRA 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, M for Magellan); 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).
  • for compatibility with older versions some attribute-value pairs no longer used for coding hidden information are still accepted when reading.

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 an accepted graphics 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, with S 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 an accepted graphics 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.

Preparing an image information file can be done by using GPSMan in command-line mode: see the description of the georef command.

Least Squares files

These are files giving either waypoint names or the geodetic coordinates of control points, as well as their pixel coordinates to be used in computing the parameters of any kind of transformation by the Least Squares fit method. They follow the same conventions as other GPSMan files and contain the following, in the given order:

1. optional !Format: P T D, !Position: P, and/or !Datum: D commands, in any order, describing the position format and datum to use, "WGS 84" and DDD being the defaults;
2. lines for each point with fields separated by tabulations in one of the formats
   1. the position, in the selected/default datum and format, and the pixel coordinates
   2. the command !W:, a waypoint name, and the pixel coordinates,
   the pixel coordinates given in the order horizontal, vertical, with vertical coordinates increasing downwards. There must be at least 3 points and waypoints referred in the file must be defined beforehand.

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, GRA, UTM/UPS or a coordinates grid name).
6. a !PFDatum: Dpf command, where Dpf is the datum name for the map cursor coordinates.
7. a !Scale: S command, with S the floating-point value of the map scale in pixel/metre.

GPSMan User Manual
Copyright 1998-2013 Miguel Filgueiras,

GPSMan User Manual and the GPSMan logo images by Miguel Filgueiras are licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.

GPSMan Files