Summary

Garmin.DeviceControl A library of GPS track and waypoint data structures along with parsing tools.

Version: 1.0

Author: Michael Bina michael.bina.at.garmin.com

if (Garmin == undefined) var Garmin = {};
/**
 * @fileoverview Garmin.DeviceControl A library of GPS track and waypoint data structures along with parsing tools.
 * 
 * @author Michael Bina michael.bina.at.garmin.com
 * @version 1.0
 */

/**
 * @class Garmin.Address
 * Address class reprsents a US postal address.<br>
 * @constructor 
 */
Garmin.Address = function(){};
Garmin.Address = Class.create();
Garmin.Address.prototype = {
    /**
     * @member Garmin.Address
     */
	initialize: function() {
		this.streetAddress = null;
		this.streetAddress2 = null;
		this.city = null;
		this.state = null;
		this.postalCode = null;
	},

	toString: function() {
		return "Address: (" + this.streetAddress + ", " + 
			  (this.streetAddress2 ? this.streetAddress2+", " : "") + 
			  (this.city ? this.city+", " : "") + 
			  (this.state ? this.state+" " : "") + 
			  (this.postalCode ? this.postalCode : "") + 
			  ")";
	}
};



/**
 * @class Garmin.WayPoint
 * A waypoint represents a stored location
 * Equivalent to a <wpt> in GPX format  
 * @constructor 
 * @param {Number} lat
 * @param {Number} lng
 * @param {Number} elev
 * @param {String} name
 */
Garmin.WayPoint = function(lat, lng, elev, name){};
Garmin.WayPoint = Class.create();
Garmin.WayPoint.prototype = {

	initialize: function(lat, lng, elev, name) {
		this.lat = lat;
		this.lng = lng;
		this.name = name;
		this.elev = elev;
		
		this.date = null;
	},

	/**
	 * @type String 
	 * @return The name of this waypoint
	 * @member Garmin.WayPoint
	 */
	getName: function() {
		return this.name;
	},

	/**
	 * Shortcut for directly getting the lat value
	 * 
	 * @type Number
	 * @return The value of the latitude for this point
	 * @member Garmin.WayPoint
	 */
	getLat: function() {
		return this.lat;
	},
	
	/**
	 * Shortcut for directly getting the longitude value
	 * 
	 * @type Number
	 * @return The value of the longitude for this point
	 * @member Garmin.WayPoint
	 */
	getLng: function() {
		return this.lng;
	},
	
	/**
	 * Shortcut for directly getting the elevation value
	 * 
	 * @type Number
	 * @return The value of the elevation for this point
	 * @member Garmin.WayPoint
	 */
	getElev: function() {
		return this.elev;
	},
	
	/**
	 * Shortcut for directly getting the date/time
	 * 
	 * @type Garmin.DateTimeFormat
	 * @return The DateTimeFormat object for this point
	 * @member Garmin.WayPoint
	 */
	getDate: function() {
		return this.date;
	},
	
	toString: function() {
		return "WayPoint Point: (" + this.getLat() + ", " +  this.getLng() + ")";
	}
};


/**
 * @class Garmin.TrackPoint
 * TrackPoint class reprsents a point from a track.<br>
 * A TrackPoint contains an associative array of measurements, which can be retrieved with a 
 * #getMeasurement call passing in a string index.<br>
 * Equivalent to a <trkpt> in GPX format  
 * @constructor 
 */
Garmin.TrackPoint = function(){};
Garmin.TrackPoint = Class.create();
Garmin.TrackPoint.prototype = {
    /**
     * @member Garmin.TrackPoint
     */
	initialize: function() {
		this.measurements = null;
		this.date = null;
	},

	/**
	 * Get a Measurement from this TrackPoint
	 * If the measurement does not exist - return null
	 * 
	 * @param {String} context of the measurement we would like to get
	 * @type Object
	 * @return A measurement object (important to remember it's value is in measurementObject.value!)
	 * 	or null if the measurement doesn't exist
	 * @member Garmin.TrackPoint
	 */
	getMeasurement: function(context) {
		var meas = this.measurements[context];
		if(meas == undefined) {
		  meas = null;
		}
		return meas;
	},

	/**
	 * Determines if this TrackPoint point is valid for determing location
	 * @type Boolean
	 * @return True if lat/lon exist, false otherwise
	 * @member Garmin.TrackPoint
	 */
    isValidLocation: function() {
        return ( (this.getLat() != "null") && (this.getLat() != null) && (this.getLng() != "null") && (this.getLng() != null));
    },

	/**
	 * Shortcut for directly getting the lat value
	 * 
	 * @type Number
	 * @return The value of the latitude for this point
	 * @member Garmin.TrackPoint
	 */
	getLat: function() {
	    var meas = this.getMeasurement( "latitude" );
	    if(meas == null) {
	    	return null;
	    } else {
	    	return meas.value;
	    }
	},
	
	/**
	 * Shortcut for directly getting the longitude value
	 * 
	 * @type Number
	 * @return The value of the longitude for this point
	 * @member Garmin.TrackPoint
	 */
	getLng: function() {
		var meas = this.getMeasurement( "longitude" );
	    if(meas == null) {
	    	return null;
	    } else {
	    	return meas.value;
	    }	
	},
	
	/**
	 * Shortcut for directly getting the elevation value
	 * 
	 * @type Number
	 * @return The value of the elevation for this point
	 * @member Garmin.TrackPoint
	 */
	getElev: function() {
		var meas = this.getMeasurement( "elevation" );
	    if(meas == null) {
	    	return null;
	    } else {
	    	return meas.value;
	    }	
	},
	
	/**
	 * Shortcut for directly getting the date/time
	 * 
	 * @type  Garmin.DateTimeFormat
	 * @return The time for this point
	 * @member Garmin.TrackPoint
	 */
	getDate: function() {
		return this.date;
	},
	
	toString: function() {
		return "TrackPoint Point: (" + this.getLat() + ", " +  this.getLng() + ")";
	}
};



/**
 * 
 * Equivalent to a <trkseg> in GPX format
 * 
 * @class Garmin.TrackSegment
 * @constructor
 */
Garmin.TrackSegment = function(){};
Garmin.TrackSegment = Class.create();
Garmin.TrackSegment.prototype = {

    initialize: function() {
        this.points = new Array();
    },
    
    addTrackPoint: function(trackPointObject) {
    	this.points.push(trackPointObject);
    },
    
    /**
     * Find the nearest valid point to the index given
     * 
     * @param index is the index
     * @param incDirection is an int in the direction we'd like to look positive 
     * 	nums are forward, negative nums are backwards
     * 
     * @type Garmin.TrackPoint 
     * @return The nearest point (possibly the index) that has a validLocation
     * @member Garmin.TrackSegment
     */ 
    findNearestValidLocationPoint: function(index, incDirection) {
        if( this.getPoint( index ).isValidLocation() ) {
            return this.getPoint( index );
        } else if( index >= this.getLength() ) {
        	return this.findNearestValidLocationPoint(this.getLength()-1, -1);
        } else {
            return this.findNearestValidLocationPoint(index+incDirection, incDirection);
        }
    },

	/**
	 * Get the point specified on the track
	 * If the number is negative, get's the first
	 * If it's larger than possible, get's the last
	 * Otherwise it gets the number requested
	 *
	 * @param {Number} index is the point we want
     * @type Garmin.TrackPoint 
	 * @return A TrackPoint that fits the pattern described above 
     * @member Garmin.TrackSegment
	 */
    getPoint: function(index) {
        index = Math.floor(index);
    
        if(index >= this.getLength()) {
            return this.getEnd();
        }
        if(index <= 0) {
            return this.getStart();
        }
            
        return this.points[index];
    },

    /**
     * Quick method to get the first point
     * @type Garmin.TrackPoint 
     * @return The first point of this track
     * @member Garmin.TrackSegment
     */
    getStart: function() {
        return this.points[0];
    },

    /**
     * Quick method to get the last point
     * @type Garmin.TrackPoint 
     * @return The last point of this track
     * @member Garmin.TrackSegment
     */
    getEnd: function() {
        return this.points[this.getLength()-1];
    },

    /**
     * Get the latitude for the start point of this segment
     * @type Number
	 * @return Latitude of the first trackpoint
     * @member Garmin.TrackSegment
     */
    getStartLat: function() {
    	return this.getStart().getLat();
    },

    /**
     * Get the longitude for the start point of this segment
     * @type Number
	 * @return Longitude of the first trackpoint
     * @member Garmin.TrackSegment
     */
    getStartLng: function() {
    	return this.getStart().getLng();
    },

    /**
     * Get the data/time for the start point of this segment
     * @return {Garmin.DateTimeFormat} date/time of the first trackpoint
     * @member Garmin.TrackSegment
     */
    getStartDate: function() {
    	return this.getStart().getDate();
    },

    /**
     * Get the data/time for the end point of this segment
     * @type Garmin.DateTimeFormat
     * @return Date/time of the last trackpoint
     * @member Garmin.TrackSegment
     */
    getEndDate: function() {
    	return this.getEnd().getDate();
    },
    
    /**
     * Get the total duration for this track segment
	 * @type String
	 * @return String of Duration (hh:mm:ss)
     * @member Garmin.TrackSegment
     */
    getDuration: function() {
    	return this.getStartDate().getDurationTo(this.getEndDate());
    },

    /**
     * Get the total number of trackpoints in this segment
	 * @type Number
	 * @return Total number of trackpoints in this segment
     * @member Garmin.TrackSegment
     */
    getLength: function() {
        return this.points.length;
    },

    /**
	 * @type String
     * @member Garmin.TrackSegment
     */
    toString: function() {
        return "Track Segment w/ " + this.getLength() + " points.";
    }
};


/**
 * A track is an ordered list of track segments.<br>
 * Equivalent to a <trk> in GPX format.
 * 
 * @class Garmin.Track
 * @constructor
 */
Garmin.Track = function(){}; 
Garmin.Track = Class.create();
Garmin.Track.prototype = {
    initialize: function() {
        this.segments = new Array();
    },
    
    /**
     * Add a segment to this track
	 * @type Garmin.TrackPoint
     * @member Garmin.Track
     */
    addSegment: function(trackSegment) {
    	this.segments.push(trackSegment);
    },

	/**
	 * Get the segment specified on the track
	 * If the number is negative, get's the first
	 * If it's larger than possible, get's the last
	 * Otherwise it gets the number requested
	 *
	 * @param index is the segment we want
	 * @type Garmin.TrackSegment
	 * @return A segment that fits the pattern described above 
     * @member Garmin.Track
	 */
    getSegment: function(index) {
        index = Math.floor(index);
    
        if(index >= this.getLastSegment()) {
            return this.getEnd();
        }
        if(index <= 0) {
            return this.getFirstSegment();
        }
            
        return this.segments[index];
    },

    /**
     * Get the first segment
	 * @type Garmin.TrackSegment
     * @return The first segment of this track
     * @member Garmin.Track
     */
    getFirstSegment: function() {
        return this.segments[0];
    },

    /**
     * Get the last segment
	 * @type Garmin.TrackSegment
     * @return The last segment of this track
     * @member Garmin.Track
     */
    getLastSegment: function() {
        return this.segments[this.getNumSegments()-1];
    },

    /**
     * Get the total length of the track
	 * @type Number
     * @member Garmin.Track
     */
    getNumSegments: function() {
        return this.segments.length;
    },

    /**
     * Get the start point for the track
	 * @type Garmin.TrackPoint
     * @member Garmin.Track
     */
    getStart: function() {
    	return this.getFirstSegment().getStart();
    },

    /**
     * Get the latitude of the start point for the track
	 * @type Number
     * @member Garmin.Track
     */
    getStartLat: function() {
    	return this.getFirstSegment().getStartLat();
    },

    /**
     * Get the lpngitude of the start point for the track
	 * @type Number
     * @member Garmin.Track
     */
    getStartLng: function() {
    	return this.getFirstSegment().getStartLng();
    },
    
    /**
     * Get the DateTimeFormat object for the start of this track
	 * @type Garmin.DateTimeFormat
     * @member Garmin.Track
     */
    getStartDate: function() {
    	return this.getFirstSegment().getStartDate();
    },

    /**
     * Get the end point for the track
	 * @type Garmin.TrackPoint
     * @member Garmin.Track
     */
    getEnd: function() {
    	return this.getLastSegment().getEnd();
    },

    /**
     * Get the DateTimeFormat object for the end of this track
	 * @type Garmin.DateTimeFormat
     * @member Garmin.Track
     */
    getEndDate: function() {
    	return this.getLastSegment().getEndDate();
    },
    
    /**
     * Get the total duration for this track
	 * @type String
     * @member Garmin.Track
     */
    getDuration: function() {
    	return this.getStartDate().getDurationTo(this.getEndDate());
    },

    /**
     * Get the total number of trackpoints in this track
	 * @type Number
     * @member Garmin.Track
     */
    getLength: function() {
		var length = 0;
		for( var i=0; i < this.segments.length; i++ ) {
			length += this.segments[i].getLength();
		}
        return length;
    },

    /**
	 * @type Boolean
	 * @return True if this track can be drawn on a map
     * @member Garmin.Track
     */
    isDrawable: function() {
    	return (this.getStartDate() != null);
    },

    toString: function() {
        return "Track w/ " + this.getNumSegments() + " segments.";
    }
};

/**
 * Used to parse track and/or waypoint data from a number of Xml formats.<br>
 * Currently only supports tracks from a GPX file.
 * 
 * @class Garmin.GpsDataFactory
 * @constructor
 */
Garmin.GpsDataFactory = function(){}; 
Garmin.GpsDataFactory = Class.create();
Garmin.GpsDataFactory.prototype = {

    initialize: function() {
    	this.tracks = new Array();
    	this.waypoints = new Array();
    },

    /**
     * Get the tracks parsed by this factory
	 * @type Array<Garmin.Tracks>
     * @member Garmin.GpsDataFactory
     */
	getTracks: function() {
		return this.tracks;
	},

    /**
     * Get the waypoints parsed by this factory
	 * @type Array<Garmin.WayPoint>
     * @member Garmin.GpsDataFactory
     */
	getWaypoints: function() {
		return this.waypoints;
	},

    /**
     * Parse a gpx string and save the tracks found as objects
	 * @param {String} xml string in GPX format
     * @member Garmin.GpsDataFactory
     */
    parseGpxString: function(gpxString) {
		var gpxDocument = Garmin.XmlConverter.toDocument(gpxString);
		
		this.parseGpxDocument(gpxDocument);
	},

    /**
     * Parse a gpx document and save the tracks and waypoints found
	 * @param {Document} xml document in GPX format
     * @member Garmin.GpsDataFactory
     */
    parseGpxDocument: function(gpxDocument) {
		this.parseGpxTracks(gpxDocument);
		this.parseGpxWaypoints(gpxDocument);
    },

    /**
     * Parse a GPX xml document for tracks
	 * @param {Document} xml document in GPX format
     * @type Array<Garmin.Track>
     * @member Garmin.GpsDataFactory
     */
	parseGpxTracks: function(gpxDocument) {
		var tracks = new Array();

    	var trackNodes = gpxDocument.getElementsByTagName("trk");

		// triple for-loop fun
		for( var i=0; i < trackNodes.length; i++ ) {
			var trk = new Garmin.Track();

			var trackSegments = trackNodes[i].getElementsByTagName("trkseg");
	
			for( var j=0; j < trackSegments.length; j++ ) {
				var trkseg = new Garmin.TrackSegment();
				
				var trackPoints = trackSegments[j].getElementsByTagName("trkpt");
		
				for( var k=0; k < trackPoints.length; k++ ) {
					var trkpt = new Garmin.TrackPoint();

					var lat = trackPoints[k].getAttribute("lat");
					var lng = trackPoints[k].getAttribute("lon");
					var ele = trackPoints[k].getElementsByTagName("ele")[0].childNodes[0].nodeValue;
					
					var timeNodes = trackPoints[k].getElementsByTagName("time");
					if(timeNodes.length > 0) {
						var time = timeNodes[0].childNodes[0].nodeValue;
						trkpt.date = (new Garmin.DateTimeFormat()).parseXsdDateTime(time);
					}
					
					trkpt.measurements = {
						latitude: {
							value: lat,
							context: "latitude"
						},
						longitude: {
							value: lng,
							context: "longitude"
						},
						elevation: {
							value: ele,
							context: "feet"
						}
					};
					
					trkseg.addTrackPoint(trkpt);
				}
				
				trk.addSegment(trkseg);
			}

			tracks.push(trk);
		}

    	this.tracks = tracks;
    	return tracks;
	},

    /**
     * Parse a GPX xml document for waypoints
	 * @param {Document} xml document in GPX format
     * @type Array<Garmin.WayPoint>
     * @member Garmin.GpsDataFactory
     */
	parseGpxWaypoints: function(gpxDocument) {
		var waypoints = new Array();

    	var waypointNodes = gpxDocument.getElementsByTagName("wpt");

		for( var i=0; i < waypointNodes.length; i++ ) {
			var waypointNode = waypointNodes[i];

			var lat = waypointNode.getAttribute("lat");
			var lng = waypointNode.getAttribute("lon");
			var name = waypointNode.getElementsByTagName("name")[0].childNodes[0].nodeValue;

			var elevNode = waypointNode.getElementsByTagName("ele");
			var ele = null;
			if(elevNode.length > 0) {
				ele = elevNode[0].childNodes[0].nodeValue;
			}

			var wpt = new Garmin.WayPoint(lat, lng, ele, name);

			waypoints.push(wpt);
		}

    	this.waypoints = waypoints;
    	return waypoints;
	},

    /**
     * Take a list of tracks and waypoints and generate a GPX xml string
	 * @param {Array<Garmin.Track>} Tracks
	 * @param {Array<Garmin.WayPoint>} Waypoints
     * @type String
     * @member Garmin.GpsDataFactory
     */
	produceGpxString: function(tracks, waypoints) {
		gpxString = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\" ?>";
	
		gpxString += "<gpx xmlns=\"http://www.topografix.com/GPX/1/1\" creator=\"Garmin Communicator Plug-In API\" version=\"1.1\" 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\">";
		
		if(tracks != null) {
			for( var i=0; i < tracks.length; i++ ) {
				gpxString += this.produceTrackGpxString(tracks[i]);
			}
		}

		if(waypoints != null) {		
			for( var i=0; i < waypoints.length; i++ ) {
				gpxString += this.produceWaypointGpxString(waypoints[i]);
			}
		}
		gpxString += "</gpx>";
	
		return gpxString;
	},

    /**
     * Take a track object and generate a GPX xml string (without gpx or xml headers)
	 * @param {Garmin.Track} Track
     * @type String
     * @member Garmin.GpsDataFactory
     */
	produceTrackGpxString: function(track) {
		gpxString = "<trk>";

		for( var i=0; i < track.getNumSegments(); i++ ) {
			var segment = track.getSegment(i);
			
			gpxString += "<trkseg>";
			for(var j=0; j < segment.getLength(); j++) {
				var point = segment.getPoint(j);
				
				gpxString += "<trkpt lat=\"" + point.getLat() + "\" lon=\"" + point.getLng() + "\">";
				if(point.getElev()) {
					gpxString += "<ele>" + point.getElev() + "</ele>";
				}
				if(point.getDate()) {
					gpxString += "<time>" + point.getDate().getXsdString() + "</time>";
				}
				gpxString += "</trkpt>";
			}
			gpxString += "</trkseg>";

		}
		
		gpxString += "</trk>";
	
		return gpxString;
	},

    /**
     * Take a waypoint object and generate a GPX xml string (without gpx or xml headers)
	 * @param {Garmin.WayPoint} WayPoint
     * @type String
     * @member Garmin.GpsDataFactory
     */
	produceWaypointGpxString: function(waypoint) {
		gpxString = "<wpt lat=\"" + waypoint.getLat() + "\" lon=\"" + waypoint.getLng() + "\">";
	
		if(waypoint.getElev()) {
			gpxString += "<ele>" + waypoint.getElev() + "</ele>";
		}
		if(waypoint.getName()) {
			gpxString += "<name>" + waypoint.getName() + "</name>";
		}
		
		gpxString += "</wpt>";
	
		return gpxString;
	},

    /**
     * 
     * @type String
     * @member Garmin.GpsDataFactory
     */
    toString: function() {
        return "GpsDataFactory.";
    }
};

// Dynamic include of required libraries and check for Prototype
// Code taken from scriptaculous
// TODO: put this code in a library and reuse is instead of copying it to new files
var GarminGpsDataStructures = {
	require: function(libraryName) {
	  // inserting via DOM fails in Safari 2.0, so brute force approach
	  document.write('<script type="text/javascript" src="'+libraryName+'"></script>');
	},

	load: function() {
	  if((typeof Prototype=='undefined') || 
	     (typeof Element == 'undefined') || 
	     (typeof Element.Methods=='undefined') ||
	     parseFloat(Prototype.Version.split(".")[0] + "." +
	                Prototype.Version.split(".")[1]) < 1.5)
	     throw("GarminGpsDataStructures requires the Prototype JavaScript framework >= 1.5.0");
	  
	  $A(document.getElementsByTagName("script")).findAll( function(s) {
	    return (s.src && s.src.match(/GarminGpsDataStructures\.js(\?.*)?$/))
	  }).each( function(s) {
	    var path = s.src.replace(/GarminGpsDataStructures\.js(\?.*)?$/,'');
	    var includes = s.src.match(/\?.*load=([a-z,]*)/);
	    (includes ? includes[1] : 'Util-DateTimeFormat,Util-XmlConverter').split(',').each(
	     function(include) { GarminGpsDataStructures.require(path+include+'.js') });
	  });
	}
}

GarminGpsDataStructures.load();