Documentation

gpxread

Read GPX file

Syntax

  • P = gpxread(filename) example
  • P = gpxread(URL)
  • ___ = gpxread(___,Name,Value) example

Description

example

P = gpxread(filename) reads point data from the GPS Exchange Format (GPX) file, filename, and returns an n-by-1 geopoint vector, P, where n is the number of waypoints, or points that define a route or track.

gpxread searches the file first for waypoints, then routes, and then tracks, and it returns the first type of data it finds. The Metadata field of P contains a string that identifies the feature type ('waypoint', 'track', or 'route') and any additional metadata associated with waypoint, route, or track. If the file contains multiple tracks or routes, P contains the points that define the first track or route in the file. If gpxread cannot find any features in the file, it returns an empty geopoint vector.

P = gpxread(URL) reads the GPX data from a URL. The URL must include the protocol type (for example, http://).

example

S = gpxread(___,'Index',V) returns data from the GPX file in a geoshape vector, rather than a geopoint vector, only if the file contains track or route data and you specify the value of ‘Index' as a vector, V. Use this syntax when you want to work with the data as a line, rather than as a collection of points.

example

___ = gpxread(___,Name,Value) reads data from a GPX file with additional options, specified by one or more Name,Value pair arguments, that control various characteristics of the import. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes ('') and is case insensitive. You can specify several name-value pair arguments in any order.

Examples

expand all

Read Waypoints and Display Them Over Image

Read and display waypoints from the boston_placenames.gpx file and overlay the points onto the boston.tif image.

Read waypoints from a GPX file.

p = gpxread('boston_placenames');

Read the image file.

[A,R] = geotiffread('boston');

Convert the length unit of the X and Y limits to meters for use with the projection structure.

proj = geotiffinfo('boston');
mstruct = geotiff2mstruct(proj);
R.XWorldLimits = R.XWorldLimits * proj.UOMLengthInMeters;
R.YWorldLimits = R.YWorldLimits * proj.UOMLengthInMeters;

Display the map.

figure('Renderer', 'zbuffer');
axesm(mstruct)
mapshow(A,R);

Display the names and positions of each point, overlaid over the image.

for k=1:length(p)
   textm(p(k).Latitude, p(k).Longitude, p(k).Name, ...
      'Color',[0 0 0],'BackgroundColor',[0.9 0.9 0],...
      'Interpreter','none');
end
geoshow(p);
xlim(R.XWorldLimits)
ylim(R.YWorldLimits)

Read and Display a Route

Read and display a route from Boston Logan International Airport to Mathworks in Natick, MA.

Read the route information from the GPX file.

route = gpxread('sample_route');

Compute latlim and lonlim with a 0.05 buffer.

[latlim, lonlim] = geoquadline(route.Latitude, route.Longitude);
[latlim, lonlim] = bufgeoquad(latlim, lonlim, .05, .05);

Display the route.

fig = figure;
pos = fig.Position;
fig.Position = [300 300 1.25*pos(3) 1.25*pos(4)];
ax = usamap(latlim, lonlim);
setm(ax, 'MLabelParallel', 43.5)
geoshow(route.Latitude, route.Longitude)

Extract the elements of route that include descriptions of turns, mark and color code each turn on the map, and construct a legend that displays the descriptions. Reverse the order, so that the legend displays the first turn at the top and the last at the bottom.

turns = route(~cellfun(@isempty, route.Description));
turns = turns(end:-1:1);
n = length(turns);
colors = cool(n);
for k=1:n
   geoshow(turns(k).Latitude, turns(k).Longitude, ...
       'DisplayType','point','MarkerEdgeColor',colors(k,:),...
       'Tag','turn','DisplayName',turns(k).Description)
end
legend(findobj(ax,'Tag','turn'),'Location','SouthOutside')

Read and Display Multiple Track Logs on a Webmap

Read track log from a GPX file and display overlaid on a webmap.

Read the track logs from a GPX file.

tracks = gpxread('sample_tracks', 'Index', 1:2);

Display the track logs on a webmap with a different color for each track log.

webmap('mapquestopenstreetmap')
colors = {'cyan', 'red'};
wmline(tracks, 'Color', colors)

Zoom the webmap to view the first track near the MathWorks campus in Natick.

[latlim, lonlim] = geoquadline(tracks(1).Latitude, tracks(1).Longitude);
wmlimits(latlim, lonlim)

Read and Display Waypoints and Track Log on a Webmap

Read waypoints and track log from the sample_mixed.gpx file.

wpt = gpxread('sample_mixed');
trk = gpxread('sample_mixed', 'FeatureType', 'track');

Display the waypoints and the track log on a webmap.

webmap('mapquestopenaerialmap')
wmline(trk, 'OverlayName', 'Track Logs');

Add web markers to mark the positions of each way point.

wmmarker(wpt, 'FeatureName', wpt.Name, 'OverlayName', 'Waypoints')

Display Elevation and Time-area Maps

Display elevation and time area maps and calculate distance using track logs.

Read track log from the sample_mixed.gpx file.

trk = gpxread('sample_mixed', 'FeatureType', 'track');

Convert the time value strings to serial date numbers using datenum, and then compute the time-of-day in hours-minutes-seconds.

timeStr = strrep(trk.Time, 'T', ' ');
timeStr = strrep(timeStr, '.000Z', '');
trk.DateNumber = datenum(timeStr, 31);
day = fix(trk.DateNumber(1));
trk.TimeOfDay = trk.DateNumber - day;

Display an area plot of the elevation and time values.

figure
area(trk.TimeOfDay, trk.Elevation)
datetick('x', 13, 'keepticks', 'keeplimits')
ylabel('elevation (meters)')
xlabel('time(Z) hours:minutes:seconds')
title({'Elevation Area Plot', datestr(day)});

Calculate and display ground track distance. Convert distance in meter to distance in U.S. survey mile.

e = wgs84Ellipsoid;
lat = trk.Latitude;
lon = trk.Longitude;
d = distance(lat(1:end-1), lon(1:end-1), lat(2:end), lon(2:end), e);
d = d * unitsratio('sm', 'meter');

Display the cumulative ground track distance and elapsed time.

trk.ElapsedTime = trk.TimeOfDay - trk.TimeOfDay(1);
figure
line(trk.ElapsedTime(2:end), cumsum(d))
datetick('x', 13)
ylabel('cumulative ground track distance (statute mile)')
xlabel('elapsed time  (hours:minutes:seconds)')
title({'Cumulative Ground Track Distance in Miles', datestr(day),  ...
   ['Total Distance in Miles: ' num2str(sum(d))]});

Input Arguments

expand all

filename — Name of GPX file to opencharacter string

Name of GPX file to open, specified as a character string. If the file is not in the current folder or in a folder on the MATLAB® path, you must specify the folder path. If the file name includes the extension '.gpx' (either uppercase or lowercase), you can omit the extension from filename.

Example: 'boston_placenames'

Data Types: char

URL — Internet location containing GPX dataUniform Resource Locator (URL)

Internet location containing GPX data, specified as a Uniform Resource Locator (URL). The URL must include protocol type (for example, http://).

Data Types: char

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'FeatureType','track'

'FeatureType' — Type of feature to read from file'auto' (default) | 'track' | 'route' | 'waypoint'

Type of feature to read from file, specified as one of the following character strings: 'track', 'route', 'waypoint', or 'auto'. If gpxread cannot find the specified feature in the file, it returns an empty geopoint vector.

Example: 'FeatureType','waypoint'

Data Types: char

'Index' — Index of waypoint, track, or route data in filescalar or vector of positive integers

Index of waypoint, track, or route data in file, specified as a scalar or vector of positive integers.

  • If the value is a scalar, gpxread returns the specified waypoint, route, or track as a geopoint vector. If the scalar value is greater than the total number of elements found in the file, gpxread returns an empty geopoint vector.

  • If the value is a vector, and the file contains waypoints, gpxread returns those waypoints specified by the vector. If the file contains routes or tracks (and does not contain waypoints), gpxread returns the specified routes or track logs in a geoshape vector. gpxread sets the Geometry field of the geoshape vector to 'line'.

Example: ‘Index', [1:2] would read up to two routes or tracks, if the file contained routes or tracks, in a geoshape vector.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

expand all

P — Waypoint, track, or route datan-by-1 geopoint vector

Waypoint, track, or route data, returned as an n-by-1 geopoint vector, where n is the number of points.

For a track log or route with multiple segments, gpxread concatenates the coordinates of the segments with NaN separators. NaN denotes numeric elements not found in the file. The empty string ('') is used to denote string elements not found in the file.

S — Track or route datan-by-1 geoshape vector

Track or route data, returned as an n-by-1 geopoint vector

More About

expand all

waypoint

A point of interest, or named feature on a map.

track

An ordered list of waypoints that describe a path.

route

An ordered list of waypoints representing a series of turn points leading to a destination.

Tips

  • Excluding extensions, GPX version 1.1 is fully supported. If any other version is detected, a warning is issued. However, in most cases, version 1.0 GPX files can be read successfully unless they contain certain metadata tags. For more information, see the GPX 1.1 Schema Documentation.

Was this topic helpful?