MapGazer - GPX files

A GPX (Global Positions eXchange format) file is used for storing one or more marks (tracks, routes, waypoints, images, areas, and scales, or any combination of these). GPX files are often created by a GPS (Global Positioning System) device or smartphone application; MapGazer can create routes, waypoints, images, areas, and scales, and can load or save all marks from or to GPX files.

A track is a recording of a where the device has been (e.g., the path taken for a walk). MapGazer lets you load tracks from GPX files and then trim them to delete ‘junk’ record points at the beginning or end of a recording.
For details and screenshots, please see Using Tracks.

A route is typically a plan for a journey; it has a start and an end point and often has intermediate route waypoints. MapGazer lets you create routes as well as load routes from GPX files. All routes can be modified by adding, deleting, or moving route waypoints.
For details and screenshots, please see Using Routes.

A waypoint is a single site of interest, either recorded during a journey or created in some other manner. MapGazer lets you adjust the position of a waypoint by dragging, and assign an icon to a waypoint.
For details and screenshots, please see Using Waypoints.

An image is a picture with a border than can be used to modify its shape and position and size on the map; it covers a fixed geographical area and so will be affected by zooming. This lets an image be used to show satellite or vertical drone images, or other graphics such as cave surveys. For the latter a graphics effect can be applied in which white areas are transparent. An image is loaded from a file (.jpg or .png) and will initially have a fixed aspect ratio and automatic effect selected.
For details and a screenshot, please see Using Images.

An area describes an area (a ‘rectangle’ defined by a South West point and a North East point); areas may be used for saving subsets of a map or creating images (which can be much larger than screenshots). MapGazer lets you create areas and modify them by dragging their borders, which may be constrained to a specific aspect ratio.
For details and a screenshot, please see Using Areas.

A scale is a visual indication of the scale of a map. MapGazer lets you create, move, and modify scales.
For details and a screenshot, please see Using Scales.

MapGazer can load the tracks, routes, waypoints, areas, and scales from one or more GPX files and display them as marks added to the map. All marks can be edited or deleted, and you can save either all the current marks or an individual mark to a GPX file. The properties of marks that can be edited and saved include their name, caption, colour, transparency, and link URL (Universal Resource Locator); some marks have additional properties (such as the Icon for a waypoint or the width of a scale).

Loading GPX files

To load a GPX file, use the Marks → Load marks from GPX file menu (or press the ‘L’ key). This will open a dialog which you can use to select the GPX file to open. Any tracks, routes, waypoints, and areas in the file will then immediately be marked on the map (you may have to change the map or move it for the marks to be in view, but MapGazer will attempt to centre the map on the newly-loaded marks).

Depending on the source of the GPX file, tracks, routes, waypoints, and areas may have a default (golden, brown, or red) colour or may have a colour selected at the time of recording or creation.

If you associate MapGazer with the file extension .gpx then opening a file with that extension will start MapGazer (if necessary) and load that GPX file.

The MapGazer package includes a sample map (MapGazer\MGMaps\SampleMap) and also a sample GPX track (with three waypoints) that shows the drive between two villages on that map (La Hermida and Bejes). You can load this from MapGazer\gpx\samples; see below for how this might appear in a MapGazer window.

All marks have associated status which will be shown (unless turned off – see General settings) at the top left of the screen whenever the cursor is over the mark. Right click on any mark for a pop-up menu of actions that can be carried out on the mark.

Saving to a GPX file

To save a GPX file, use the Marks → Save marks to GPX file menu item (or press the ‘s’ key). This will open a dialog which you can use to select or enter the GPX file to be written. All marks loaded and not deleted (or new marks) will then be written to the file, including the Scale and any modifications you have made to any marks. New or changed marks will be written with some cosmetic formatting; unchanged items are generally copied directly from the loaded GPX file.

You can also save an individual mark by right-clicking on it and using the Save ... to GPX file pop-up menu item.

When marks are saved to a GPX file a template GPX file is used for the header and footer data that envelop the data items. Normally this will be the default supplied by MapGazer, but you can also use your own custom template. For details, see MapGazer templates.

GPX file format

GPX files are ‘plain text’ files; they can be viewed and edited with a simple text editor such as Notepad. The data within a GPX file are marked-up using eXtensible Markup Language (XML), following an open standard documented at www.topografix.com/gpx/. Any characters that are not 7-bit ASCII are encoded using UTF-8; in addition, a small number of characters (e.g., ‘&’) are encoded as symbol entities or are treated as CDATA (please see the XML standard for more details).

The GPX markup rules allow the addition of extensions to the basic track, route, and waypoint data, and most applications that create GPX files do add various extensions. The extensions augment the data with additional features – for example, the colour to use for displaying a mark, or a tag that indicates that a route is to be treated as an area.

MapGazer uses the following extensions (special tags):

<mapgazer:aspectx>, <mapgazer:aspecty> – tags whose content is a positive integer describing the X or Y component of the aspect ratio of an Area; if both are present and valid the Area (wich may contain an image) will have a fixed aspect ratio.
<mapgazer:colour> – a tag whose content describes a mark’s colour. The content is eight hexadecimal digits defining four bytes: transparency, red, green, and blue (all integers in the range 0→255); for example, 00aa6000 describes the default brown colour for waypoints. A transparency of zero indicates that the colour is opaque.
MapGazer will also load colours from Garmin and MyTrails extensions; these are preserved. When a colour is changed its new value is saved in both MapGazer and MyTrails formats.
<mapgazer:effect> – a tag whose content is one of ‘auto’, ‘none’, ‘graphic’, or ‘colour’ (without quotes) which describes the effect to be applied to an image mark. It affects the image (if any) in an Area.
<mapgazer:heading> – a tag whose content is a number in the range 0→360. This describes the heading associated with a trackpoint or waypoint; e.g., the heading of a drone or the camera it is carrying – this is the heading it is pointing, not its direction of travel (it could be flying sideways).
<mapgazer:icon> – a tag whose content is the name of an icon to be associated with a waypoint. This name is the name of a file relative to the MapGazer icons folder, which is in the same folder as the MapGazer executable. For example, samples\photography.png. For more details, see Using icons.
<mapgazer:image border="1" caption="1"> – a tag whose content is packed image data (from a .jpg or .png file). The data are encoded as pars of hexadecimal characters for each byte of data, with no whitespace within the data string. The (optional) attributes must have values of 0 or 1 (default 1) and control whether the image border and any caption is displayed. An image is always within an Area and follows the Area’s aspect ratio, etc.
<mapgazer:photo/> – an empty tag added to a trackpoint to indicate a photo was taken here.
<mapgazer:routearea/> – an empty tag added to a route to indicate that it should be treated as an area mark (that is, it must have exactly five route waypoints that describe a rectangle, and may include an image).
<mapgazer:routeitem/> – an empty tag added to a route to indicate that it contains no geographical data; it is a ‘container’ for other information; currently only a Scale uses this extension.
<mapgazer:scale offsetx="0" offsety="0" target="15"/> – an empty tag that indicates that a route item describes a Scale. The scale is drawn at the given offsets in a window (or saved image) with an appropriate margin. The target attribute specifies the target width for the scale as a percentage of the window (or image) width; the actual width is set to suit a ‘round number’ distance – see Using scales for details.
<mapgazer:template/> – an empty tag used in a MapGazer template to indicate where saved marks will be placed. The tag itself is not saved when a GPX file is written.
<mapgazer:video/> – an empty tag added to a trackpoint to indicate that video was being recorded here.

A MapGazer Area mark is a special case of Route with exactly five waypoints such that a ‘rectangle’ is formed. An Image is an Area with associated image data.

Here is an example of a simple GPX file with no metadata and no extensions:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!-- A sample GPX file with just a waypoint. -->

<gpx xmlns="http://www.topografix.com/GPX/1/1"
  version="1.1"
  creator="MFC"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.topografix.com/GPX/1/1
  http://www.topografix.com/GPX/1/1/gpx.xsd">

  <wpt lat="43.377226" lon="-4.839000">
    <ele>370.381805</ele>
    <time>2014-07-02T14:33:03Z</time>
    <name>River sounds above Boriza</name>
  </wpt>

</gpx>

If a tag has no enclosed content (such as a track point) it can always be marked as an empty tag (instead of a start tag immediately followed by an end tag).

Sample GPX track and waypoints

Here is a screenshot showing the track and three waypoints loaded from the MapGazer sample GPX file; this shows a drive from La Hermida to Bejes. Note that the three waypoints could be changed from to or from an ‘X’, an icon, or a dot; see Using icons for more details.

La Hermida to Bejes

	MapGazer – GPX files
Introduction Download MapGazer Getting started Using marks: Waypoints Tracks Routes Areas Images Scales Mark properties Using icons Using transparency General settings Getting maps Using map tools Go to location Coordinate formats GPX files Elevation data Aspect ratio Keyboard shortcuts Command line Thanks	A GPX (Global Positions eXchange format) file is used for storing one or more marks (tracks, routes, waypoints, images, areas, and scales, or any combination of these). GPX files are often created by a GPS (Global Positioning System) device or smartphone application; MapGazer can create routes, waypoints, images, areas, and scales, and can load or save all marks from or to GPX files. A track is a recording of a where the device has been (e.g., the path taken for a walk). MapGazer lets you load tracks from GPX files and then trim them to delete ‘junk’ record points at the beginning or end of a recording. For details and screenshots, please see Using Tracks. A route is typically a plan for a journey; it has a start and an end point and often has intermediate route waypoints. MapGazer lets you create routes as well as load routes from GPX files. All routes can be modified by adding, deleting, or moving route waypoints. For details and screenshots, please see Using Routes. A waypoint is a single site of interest, either recorded during a journey or created in some other manner. MapGazer lets you adjust the position of a waypoint by dragging, and assign an icon to a waypoint. For details and screenshots, please see Using Waypoints. An image is a picture with a border than can be used to modify its shape and position and size on the map; it covers a fixed geographical area and so will be affected by zooming. This lets an image be used to show satellite or vertical drone images, or other graphics such as cave surveys. For the latter a graphics effect can be applied in which white areas are transparent. An image is loaded from a file (`.jpg` or `.png`) and will initially have a fixed aspect ratio and automatic effect selected. For details and a screenshot, please see Using Images. An area describes an area (a ‘rectangle’ defined by a South West point and a North East point); areas may be used for saving subsets of a map or creating images (which can be much larger than screenshots). MapGazer lets you create areas and modify them by dragging their borders, which may be constrained to a specific aspect ratio. For details and a screenshot, please see Using Areas. A scale is a visual indication of the scale of a map. MapGazer lets you create, move, and modify scales. For details and a screenshot, please see Using Scales. MapGazer can load the tracks, routes, waypoints, areas, and scales from one or more GPX files and display them as marks added to the map. All marks can be edited or deleted, and you can save either all the current marks or an individual mark to a GPX file. The properties of marks that can be edited and saved include their name, caption, colour, transparency, and link URL (Universal Resource Locator); some marks have additional properties (such as the Icon for a waypoint or the width of a scale). Loading GPX files To load a GPX file, use the Marks → Load marks from GPX file menu (or press the ‘L’ key). This will open a dialog which you can use to select the GPX file to open. Any tracks, routes, waypoints, and areas in the file will then immediately be marked on the map (you may have to change the map or move it for the marks to be in view, but MapGazer will attempt to centre the map on the newly-loaded marks). Depending on the source of the GPX file, tracks, routes, waypoints, and areas may have a default (golden, brown, or red) colour or may have a colour selected at the time of recording or creation. If you associate MapGazer with the file extension `.gpx` then opening a file with that extension will start MapGazer (if necessary) and load that GPX file. The MapGazer package includes a sample map (`MapGazer\MGMaps\SampleMap`) and also a sample GPX track (with three waypoints) that shows the drive between two villages on that map (La Hermida and Bejes). You can load this from `MapGazer\gpx\samples`; see below for how this might appear in a MapGazer window. All marks have associated status which will be shown (unless turned off – see General settings) at the top left of the screen whenever the cursor is over the mark. Right click on any mark for a pop-up menu of actions that can be carried out on the mark. Saving to a GPX file To save a GPX file, use the Marks → Save marks to GPX file menu item (or press the ‘s’ key). This will open a dialog which you can use to select or enter the GPX file to be written. All marks loaded and not deleted (or new marks) will then be written to the file, including the Scale and any modifications you have made to any marks. New or changed marks will be written with some cosmetic formatting; unchanged items are generally copied directly from the loaded GPX file. You can also save an individual mark by right-clicking on it and using the Save ... to GPX file pop-up menu item. When marks are saved to a GPX file a template GPX file is used for the header and footer data that envelop the data items. Normally this will be the default supplied by MapGazer, but you can also use your own custom template. For details, see MapGazer templates. GPX file format GPX files are ‘plain text’ files; they can be viewed and edited with a simple text editor such as Notepad. The data within a GPX file are marked-up using eXtensible Markup Language (XML), following an open standard documented at `www.topografix.com/gpx/`. Any characters that are not 7-bit ASCII are encoded using UTF-8; in addition, a small number of characters (e.g., ‘&’) are encoded as symbol entities or are treated as CDATA (please see the XML standard for more details). The GPX markup rules allow the addition of extensions to the basic track, route, and waypoint data, and most applications that create GPX files do add various extensions. The extensions augment the data with additional features – for example, the colour to use for displaying a mark, or a tag that indicates that a route is to be treated as an area. MapGazer uses the following extensions (special tags): `<mapgazer:aspectx>`, `<mapgazer:aspecty>` – tags whose content is a positive integer describing the X or Y component of the aspect ratio of an Area; if both are present and valid the Area (wich may contain an image) will have a fixed aspect ratio. `<mapgazer:colour>` – a tag whose content describes a mark’s colour. The content is eight hexadecimal digits defining four bytes: transparency, red, green, and blue (all integers in the range 0→255); for example, `00aa6000` describes the default brown colour for waypoints. A transparency of zero indicates that the colour is opaque. MapGazer will also load colours from Garmin and MyTrails extensions; these are preserved. When a colour is changed its new value is saved in both MapGazer and MyTrails formats. `<mapgazer:effect>` – a tag whose content is one of ‘auto’, ‘none’, ‘graphic’, or ‘colour’ (without quotes) which describes the effect to be applied to an image mark. It affects the image (if any) in an Area. `<mapgazer:heading>` – a tag whose content is a number in the range 0→360. This describes the heading associated with a trackpoint or waypoint; e.g., the heading of a drone or the camera it is carrying – this is the heading it is pointing, not its direction of travel (it could be flying sideways). `<mapgazer:icon>` – a tag whose content is the name of an icon to be associated with a waypoint. This name is the name of a file relative to the MapGazer `icons` folder, which is in the same folder as the MapGazer executable. For example, `samples\photography.png`. For more details, see Using icons. `<mapgazer:image border="1" caption="1">` – a tag whose content is packed image data (from a `.jpg` or `.png` file). The data are encoded as pars of hexadecimal characters for each byte of data, with no whitespace within the data string. The (optional) attributes must have values of 0 or 1 (default 1) and control whether the image border and any caption is displayed. An image is always within an Area and follows the Area’s aspect ratio, etc. `<mapgazer:photo/>` – an empty tag added to a trackpoint to indicate a photo was taken here. `<mapgazer:routearea/>` – an empty tag added to a route to indicate that it should be treated as an area mark (that is, it must have exactly five route waypoints that describe a rectangle, and may include an image). `<mapgazer:routeitem/>` – an empty tag added to a route to indicate that it contains no geographical data; it is a ‘container’ for other information; currently only a Scale uses this extension. `<mapgazer:scale offsetx="0" offsety="0" target="15"/>` – an empty tag that indicates that a route item describes a Scale. The scale is drawn at the given offsets in a window (or saved image) with an appropriate margin. The target attribute specifies the target width for the scale as a percentage of the window (or image) width; the actual width is set to suit a ‘round number’ distance – see Using scales for details. `<mapgazer:template/>` – an empty tag used in a MapGazer template to indicate where saved marks will be placed. The tag itself is not saved when a GPX file is written. `<mapgazer:video/>` – an empty tag added to a trackpoint to indicate that video was being recorded here. A MapGazer Area mark is a special case of Route with exactly five waypoints such that a ‘rectangle’ is formed. An Image is an Area with associated image data. Here is an example of a simple GPX file with no metadata and no extensions: <?xml version="1.0" encoding="UTF-8" standalone="no" ?> <!-- A sample GPX file with just a waypoint. --> <gpx xmlns="http://www.topografix.com/GPX/1/1" version="1.1" creator="MFC" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd"> <wpt lat="43.377226" lon="-4.839000"> <ele>370.381805</ele> <time>2014-07-02T14:33:03Z</time> <name>River sounds above Boriza</name> </wpt> </gpx> If a tag has no enclosed content (such as a track point) it can always be marked as an empty tag (instead of a start tag immediately followed by an end tag). Sample GPX track and waypoints Here is a screenshot showing the track and three waypoints loaded from the MapGazer sample GPX file; this shows a drive from La Hermida to Bejes. Note that the three waypoints could be changed from to or from an ‘X’, an icon, or a dot; see Using icons for more details. La Hermida to Bejes