us.zuercher.gpx2map
Class Gpx2Map

java.lang.Object
  us.zuercher.gpx2map.Gpx2Map

public class Gpx2Map
extends Object

Gpx2Map provides an API for generating maps with GPX data plotted on them. It is intended to be interface-agnostic while simultaneously providing progress information as it proceeds.

Gpx2Map should never refer to System.out or System.err. Instead, use the private field out to produce informational messages and the ProgressMeterFactory parameter to execute(MessageSink, ProgressMeterFactory) to provide progress information.

Author:

Stephan Zuercher

Field Summary

private boolean	boundByCoords Indicates that the map boundaries should be set by user-specified values.
private boolean	boundByRoutes Indicates that the map boundaries should include all route-points.
private boolean	boundByTracks Indicates that the map boundaries should include all track-points.
private boolean	boundByWayPoints Indicates that the map boundaries should include all way-points.
private File	cacheDir Map tile cache directory.
static String	DEFAULT_CACHE_DIR Default cache directory name.
static String	DEFAULT_CACHE_DIR_SYS_PROP System property used to override the DEFAULT_CACHE_DIR.
private String	fontName Name of the font to use for labelling way-points, tracks and routes.
private float	fontSize Size of the font, in points, to use for labelling way-points, tracks and routes.
private List<File>	gpxFiles List of GPX files to parse.
private boolean	ignoreRoutes Ignore routes from the GPX file(s).
private boolean	ignoreTracks Ignore tracks from the GPX file(s).
private boolean	ignoreWayPoints Ignore way-points from the GPX file(s).
private boolean	joinTrackSegments Controls whether a track's segments are joined or not.
private boolean	labelRoutes Controls whether routes are labelled or not.
private boolean	labelTracks Controls whether tracks are labelled or not.
private MapSource	mapSource Map source instance.
private String	mapSourceName Configured name of the map source.
private Map<String,String>	mapSourceProperties Map of map source property names to values.
private Number	margin Margin size.
private MarginUnits	marginUnits Margin units.
private LatLon	nwBounds Northwest corner of map boundary.
private MessageSink	out Informational output.
private File	output Output Netpbm file.
private Color	routeColor Color used to plot route-points, route lines and route labels.
private MarkerStyle	routePointStyle Marker style used for route-points.
private int	routePointStyleRadius Size of marker style used for route-points.
private List<Route>	routes List of routes loaded from GPX files.
private LatLon	seBounds Southeast corner of map boundary.
private Color	trackColor Color used to plot track-points, track lines and track labels.
private MarkerStyle	trackPointStyle Marker style used for track-points.
private int	trackPointStyleRadius Size of marker style used for track-points.
private List<Track>	tracks List of tracks loaded from GPX files.
private Color	wayPointColor Color used to plot way-points their labels.
private List<WayPoint>	wayPoints List of way-points loaded from GPX files.
private MarkerStyle	wayPointStyle Marker style used for way-points.
private int	wayPointStyleRadius Size of marker style used for way-points.

Constructor Summary

Gpx2Map()
Constructs a new Gpx2Map instance.

Method Summary

void	addGpxFile(File gpxFile) Add a GPX file to the parse list.
private void	describeColorAndStyle(String id, Color color, MarkerStyle style, int radius, boolean labelled, String fontName, float fontSize) Describes the given color and style of an arbitrary entity.
private void	describeColorsAndStyles() Describes the colors and styles configured for tracks, way-points, and routes.
void	execute(MessageSink messageSink, ProgressMeterFactory progressMeterFactory) Using the configured settings, download map tiles, stitch them together into a map and plot way-points, tracks, and/or routes on it.
static File	getDefaultCacheDir() Obtains the default cache directory location.
static String	getDefaultCacheDirName() Obtain the default cache directory name.
boolean	isConfigured() Tests if this class has been configured.
private void	loadGpsData() Load GPS data for all GPX files.
private void	noteOutput() Note the output file to the MessageSink.
void	setBounding(boolean boundByTracks, boolean boundByWayPoints, boolean boundByRoutes, LatLon nwBounds, LatLon seBounds) Configure the bounds of the output map.
private void	setBoundingBox() Configures map boundaries based on values provided by calls to setBounding(boolean, boolean, boolean, LatLon, LatLon) and setMargin(Number, MarginUnits).
private void	setCacheDir() Configure the mapSource with the cacheDir and note the cache directory on the MessageSink.
void	setCacheDir(File cacheDir) Set the location of the cache directory.
void	setFontName(String fontName) Configure the font used for labelling way-points, tracks, and/or routes.
void	setFontSize(float size) Configure the font size, in points, used for labelling way-points, tracks, and/or routes.
void	setIgnoreRoutes() Configure Gpx2Map to ignore routes in the GPX files.
void	setIgnoreTracks() Configure Gpx2Map to ignore tracks in the GPX files.
void	setIgnoreWaypoints() Configure Gpx2Map to ignore way-points in the GPX files.
void	setJoinTrackSegments(boolean join) Configure whether track segments are joined with a line or not.
void	setLabelRoutes(boolean label) Configure route labelling.
void	setLabelTracks(boolean label) Configure track labelling.
private void	setMapProperties() Apply the configured map properties to mapSource.
private void	setMapSource() Internally set the MapSource using mapSourceName.
void	setMapSource(String mapSourceName) Set the map source name.
void	setMapSourceProperty(String mapSourceProperty, String value) Set a map source property.
void	setMargin(Number margin, MarginUnits units) Set map margin in the specific units.
private void	setMessageSink(MessageSink messageSink) Internally set the MessageSink.
void	setOutput(File output) Set the location of the output PPM file.
void	setRouteColor(Color color) Set the color for route-points, route lines and route labels.
void	setRoutePointStyle(MarkerStyle style) Configure the style for route-point markers.
void	setRoutePointStyleRadius(int radius) Configure the radius (size) for route-point markers.
void	setTrackColor(Color color) Set the color for track-points, track lines and track labels.
void	setTrackPointStyle(MarkerStyle style) Configure the style for track-point markers.
void	setTrackPointStyleRadius(int radius) Configure the radius (size) for track-point markers.
void	setWayPointColor(Color color) Set the color for way-points and labels.
void	setWayPointStyle(MarkerStyle style) Configure the style for way-point markers.
void	setWayPointStyleRadius(int radius) Configure the radius (size) for way-point markers.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CACHE_DIR

public static final String DEFAULT_CACHE_DIR

Default cache directory name.

See Also:

Constant Field Values

DEFAULT_CACHE_DIR_SYS_PROP

public static final String DEFAULT_CACHE_DIR_SYS_PROP

System property used to override the DEFAULT_CACHE_DIR.

See Also:

Constant Field Values

out

private MessageSink out

Informational output.

mapSourceName

private String mapSourceName

Configured name of the map source.

mapSourceProperties

private Map<String,String> mapSourceProperties

Map of map source property names to values.

mapSource

private MapSource mapSource

Map source instance. Configured using mapSourceName.

gpxFiles

private List<File> gpxFiles

List of GPX files to parse.

ignoreTracks

private boolean ignoreTracks

Ignore tracks from the GPX file(s). One of this, ignoreWayPoints, or ignoreRoutes must always be false. To put it another way, we can't ignore everything.

ignoreWayPoints

private boolean ignoreWayPoints

Ignore way-points from the GPX file(s). One of this, ignoreTracks, or ignoreRoutes must always be false. To put it another way, we can't ignore everything.

ignoreRoutes

private boolean ignoreRoutes

Ignore routes from the GPX file(s). One of this, ignoreWayPoints, or ignoreTracks must always be false. To put it another way, we can't ignore everything.

tracks

private List<Track> tracks

List of tracks loaded from GPX files. May be null.

wayPoints

private List<WayPoint> wayPoints

List of way-points loaded from GPX files. May be null.

routes

private List<Route> routes

List of routes loaded from GPX files. May be null.

trackColor

private Color trackColor

Color used to plot track-points, track lines and track labels.

wayPointColor

private Color wayPointColor

Color used to plot way-points their labels.

routeColor

private Color routeColor

Color used to plot route-points, route lines and route labels.

trackPointStyle

private MarkerStyle trackPointStyle

Marker style used for track-points.

trackPointStyleRadius

private int trackPointStyleRadius

Size of marker style used for track-points.

wayPointStyle

private MarkerStyle wayPointStyle

Marker style used for way-points.

wayPointStyleRadius

private int wayPointStyleRadius

Size of marker style used for way-points.

routePointStyle

private MarkerStyle routePointStyle

Marker style used for route-points.

routePointStyleRadius

private int routePointStyleRadius

Size of marker style used for route-points.

labelTracks

private boolean labelTracks

Controls whether tracks are labelled or not.

labelRoutes

private boolean labelRoutes

Controls whether routes are labelled or not.

output

private File output

Output Netpbm file.

cacheDir

private File cacheDir

Map tile cache directory.

fontName

private String fontName

Name of the font to use for labelling way-points, tracks and routes.

fontSize

private float fontSize

Size of the font, in points, to use for labelling way-points, tracks and routes.

joinTrackSegments

private boolean joinTrackSegments

Controls whether a track's segments are joined or not.

boundByTracks

private boolean boundByTracks

Indicates that the map boundaries should include all track-points. May be true in conjunction with boundByWayPoints and/or boundByRoutes. Mutually exclusive with boundByCoords.

boundByWayPoints

private boolean boundByWayPoints

Indicates that the map boundaries should include all way-points. May be true in conjunction with boundByTracks and/or boundByRoutes. Mutually exclusive with boundByCoords.

boundByRoutes

private boolean boundByRoutes

Indicates that the map boundaries should include all route-points. May be true in conjunction with boundByWayPoints and/or boundByTracks. Mutually exclusive with boundByCoords.

boundByCoords

private boolean boundByCoords

Indicates that the map boundaries should be set by user-specified values. Mutually exclusive with boundByTracks, boundByWayPoints and boundByRoutes.

nwBounds

private LatLon nwBounds

Northwest corner of map boundary. See setBoundingBox().

seBounds

private LatLon seBounds

Southeast corner of map boundary. See setBoundingBox().

margin

private Number margin

Margin size.

marginUnits

private MarginUnits marginUnits

Margin units.

Constructor Detail

Gpx2Map

public Gpx2Map()

Constructs a new Gpx2Map instance.

Method Detail

isConfigured

public boolean isConfigured()

Tests if this class has been configured.

Returns:

true if configured, false otherwise

setMapSource

public void setMapSource(String mapSourceName)

Set the map source name.

Parameters:

mapSourceName - the map source name

setMapSourceProperty

public void setMapSourceProperty(String mapSourceProperty,
                                 String value)

Set a map source property. These values may cause errors when execute(MessageSink, ProgressMeterFactory) is called.

Parameters:

mapSourceProperty - map source property name, must correspond to a value returned by MapSource.getProperties().

value - property value

addGpxFile

public void addGpxFile(File gpxFile)

Add a GPX file to the parse list.

Parameters:

gpxFile - location of a GPX file

setOutput

public void setOutput(File output)

Set the location of the output PPM file.

Parameters:

output - location of the output PPM file.

setCacheDir

public void setCacheDir(File cacheDir)

Set the location of the cache directory. See getDefaultCacheDirName().

Parameters:

cacheDir - location of the cache directory.

setIgnoreTracks

public void setIgnoreTracks()

Configure Gpx2Map to ignore tracks in the GPX files.

setIgnoreWaypoints

public void setIgnoreWaypoints()

Configure Gpx2Map to ignore way-points in the GPX files.

setIgnoreRoutes

public void setIgnoreRoutes()

Configure Gpx2Map to ignore routes in the GPX files.

setBounding

public void setBounding(boolean boundByTracks,
                        boolean boundByWayPoints,
                        boolean boundByRoutes,
                        LatLon nwBounds,
                        LatLon seBounds)

Configure the bounds of the output map. The boolean track/way-point/route parameters take precedence over the latitude/longitude values.

Parameters:

boundByTracks - use tracks

boundByWayPoints - use way-points

boundByRoutes - use routes

nwBounds - use this location as the northwest corner of the map

seBounds - use this location as the southeast corner of the map

Throws:

IllegalArgumentException - if the parameters do not configure any bounds, if only one of the LatLon values is non-null, or if the LatLon values are not NW and SE corners

setMargin

public void setMargin(Number margin,
                      MarginUnits units)

Set map margin in the specific units.

Parameters:

margin - the number of margin units

units - the margin units

setTrackColor

public void setTrackColor(Color color)

Set the color for track-points, track lines and track labels.

Parameters:

color - color for track-points, track lines and track labels.

setLabelTracks

public void setLabelTracks(boolean label)

Configure track labelling.

Parameters:

label - enable/disable track labelling.

setTrackPointStyle

public void setTrackPointStyle(MarkerStyle style)

Configure the style for track-point markers.

Parameters:

style - the style for track-point markers.

setTrackPointStyleRadius

public void setTrackPointStyleRadius(int radius)

Configure the radius (size) for track-point markers. May be ignored by some styles.

Parameters:

radius - the radius (size) for track-point markers.

setJoinTrackSegments

public void setJoinTrackSegments(boolean join)

Configure whether track segments are joined with a line or not.

Parameters:

join - enable/disable track segment joining.

setWayPointColor

public void setWayPointColor(Color color)

Set the color for way-points and labels.

Parameters:

color - color for way-points and labels.

setWayPointStyle

public void setWayPointStyle(MarkerStyle style)

Configure the style for way-point markers.

Parameters:

style - the style for way-point markers.

setWayPointStyleRadius

public void setWayPointStyleRadius(int radius)

Configure the radius (size) for way-point markers. May be ignored by some styles.

Parameters:

radius - the radius (size) for way-point markers.

setRouteColor

public void setRouteColor(Color color)

Set the color for route-points, route lines and route labels.

Parameters:

color - color for route-points, route lines and route labels.

setLabelRoutes

public void setLabelRoutes(boolean label)

Configure route labelling.

Parameters:

label - enable/disable route labelling.

setRoutePointStyle

public void setRoutePointStyle(MarkerStyle style)

Configure the style for route-point markers.

Parameters:

style - the style for route-point markers.

setRoutePointStyleRadius

public void setRoutePointStyleRadius(int radius)

Configure the radius (size) for route-point markers. May be ignored by some styles.

Parameters:

radius - the radius (size) for route-point markers.

setFontName

public void setFontName(String fontName)

Configure the font used for labelling way-points, tracks, and/or routes.

Parameters:

fontName - the name of the font to use (e.g. "Helvetica").

setFontSize

public void setFontSize(float size)

Configure the font size, in points, used for labelling way-points, tracks, and/or routes.

Parameters:

size - the size of the font, in points

execute

public void execute(MessageSink messageSink,
                    ProgressMeterFactory progressMeterFactory)
             throws UnknownMapSourceException,
                    UnknownMapSourcePropertyException,
                    MissingRequiredMapSourcePropertyException,
                    GpxParsingException,
                    BoundingException,
                    IOException

Using the configured settings, download map tiles, stitch them together into a map and plot way-points, tracks, and/or routes on it.

Parameters:

messageSink - sink for informational messages

progressMeterFactory - factory for ProgressMeter objects used to indicate progress

Throws:

UnknownMapSourceException - if the configured map source name is not known

UnknownMapSourcePropertyException - if a configured map source property is not known to the map source

GpxParsingException - if a GPX file cannot be parsed

BoundingException - if bounds are set incompatibly with the loaded GPX data (e.g., bound by tracks, but no tracks are loaded).

IOException - if there's an error downloading, converting, or stitching map tiles; or if there's an error plotting data on the map

MissingRequiredMapSourcePropertyException - if a required map source property was not set.

setMessageSink

private void setMessageSink(MessageSink messageSink)

Internally set the MessageSink.

Parameters:

messageSink - the MessageSink to use.

setMapSource

private void setMapSource()
                   throws UnknownMapSourceException

Internally set the MapSource using mapSourceName.

Throws:

UnknownMapSourceException - if the mapSourceName cannot be found

noteOutput

private void noteOutput()
                 throws IOException

Note the output file to the MessageSink.

Throws:

IOException - if the output cannot be converted to canonical form.

setCacheDir

private void setCacheDir()
                  throws IOException

Configure the mapSource with the cacheDir and note the cache directory on the MessageSink.

Throws:

IOException - if the cache dir cannot be converted to canonical form.

getDefaultCacheDirName

public static String getDefaultCacheDirName()

Obtain the default cache directory name. First checks to see if a system property named DEFAULT_CACHE_DIR_SYS_PROP exists. If so, its value is returned. Otherwise, returns DEFAULT_CACHE_DIR.

Returns:

the name of the default cache directory

getDefaultCacheDir

public static File getDefaultCacheDir()

Obtains the default cache directory location. See getDefaultCacheDirName().

Returns:

the location of the default cache directory.

setMapProperties

private void setMapProperties()
                       throws UnknownMapSourcePropertyException,
                              MissingRequiredMapSourcePropertyException

Apply the configured map properties to mapSource.

Throws:

UnknownMapSourcePropertyException - if a map source property name is not known

MissingRequiredMapSourcePropertyException - if a required map source property was not provided

loadGpsData

private void loadGpsData()
                  throws GpxParsingException

Load GPS data for all GPX files.

Throws:

GpxParsingException - if any GPX file contains an error or cannot be parsed.

setBoundingBox

private void setBoundingBox()
                     throws BoundingException

Configures map boundaries based on values provided by calls to setBounding(boolean, boolean, boolean, LatLon, LatLon) and setMargin(Number, MarginUnits). Upon return the nwBounds and seBounds fields reflect the map boundaries including margins. If the map is bounded by user-defined coordinates (see boundByCoords), the coordinates are adjusted to reflect the margins. If the map is bounded by tracks, routes, or way-points, the fields are set to the appropriate values, including margins.

Throws:

BoundingException - if the configured bounds cannot be applied

describeColorsAndStyles

private void describeColorsAndStyles()

Describes the colors and styles configured for tracks, way-points, and routes.

describeColorAndStyle

private void describeColorAndStyle(String id,
                                   Color color,
                                   MarkerStyle style,
                                   int radius,
                                   boolean labelled,
                                   String fontName,
                                   float fontSize)

Describes the given color and style of an arbitrary entity.

Parameters:

id - the entity's name

color - the color to be applied

style - the style to be applied

radius - the size of the style

labelled - whether the entity is to be labelled

fontName - the font to be used

fontSize - the size of the font