com.c5corp.c5gps
Class TrackLog

java.lang.Object
  com.c5corp.c5gps.GpsType
      com.c5corp.c5gps.GpsPointCollection
          com.c5corp.c5gps.TrackLog

All Implemented Interfaces:

java.util.Enumeration

Direct Known Subclasses:

VirtualHikerTrackLog

public class TrackLog
extends GpsPointCollection
implements java.util.Enumeration

The public class TrackLog class encapsulates data a tracklog file. TrackLog metadata include three fields - a track name, a version (such as "Version CSV:2" indicating that how the log was stored, and a Datum string. (Such as NAD27_CONUS).

Note that if you are loading a TrackLog from a java.io.File, you would use a descendent of the com.c5corp.c5gps.filters.GpsDataFilter class to get a reference to get an instance of this class.

Another important matter to note is that all of the C5UTM GpsDataFileType classes and the data classes they encapsulate are intended for use with a relational database application. There are fields in typical GPS data that are ignored by these classes, and often, floating point type numbers are rounded to intergers. While data read from files will often be of this type, any extracted from the database will be of the subclass type com.c5corp.c5utm.DbTrackLog.

Since:

2.0

Author:

Brett Stalbaum Copyright 2002-2006 see LICENSE.txt and UCSD_LICENSE.txt

See Also:

GpsDataFilter, CsvTrackLogListFilter

Field Summary

protected C5UTMconfs	confs
protected java.util.Vector<TrackPoint>	trackPoints

Fields inherited from class com.c5corp.c5gps.GpsType

hdatum

Constructor Summary

TrackLog()
Default TrackLog constuctor.

TrackLog(java.lang.String trackName, java.lang.String version, java.lang.String datum, int zoneOffset)
Constructor taking a name, version, datum, and zoneOffest value.

TrackLog(java.util.Vector<TrackLog> trackLogs)
Creates a TrackLog from a java.util.Vector containing other TrackLog objects.

Method Summary

void	addTrackPoint(java.lang.String type, int zoneNum, int easting, int northing, java.util.Calendar date, int altitude) Adds a TrackPoint to the TrackLog.
void	addTrackPoint(java.lang.String type, int zoneNum, int easting, int northing, int altitude) Adds a TrackPoint to the TrackLog, with a default (epochal) date.
void	addTrackPoint(java.lang.String type, int zoneNum, int easting, int northing, int month, int day, int year, int hour, int minute, int second, int altitude) Adds a TrackPoint to the TrackLog.
void	addTrackPoint(java.lang.String type, int zoneNum, java.lang.String zoneChar, int easting, int northing, java.util.Calendar date, int altitude) Adds a TrackPoint to the TrackLog.
void	addTrackPoint(java.lang.String type, int zoneNum, java.lang.String zoneChar, int easting, int northing, int altitude) Adds a TrackPoint to the TrackLog, with a default (epochal) date.
void	addTrackPoint(java.lang.String type, int zoneNum, java.lang.String zoneChar, int easting, int northing, int month, int day, int year, int hour, int minute, int second, int altitude) Adds a TrackPoint to the TrackLog.
int	calculateCumulativeDistance() Returns the cumulative distance between all points in the track Returns a sentinel value of -1 if there are no internal TrackPoints in the TrackLog.
int	calculateCumulativeElevationChange() The cumulative elevation change is always a positive value, because it it is calculated via the absolute value of elevational change from between sequential points in the track.
int	calculateDistance() Returns the simple straight line distance (in meters) between begin point and end point.
int	calculateEastingRange() Finds the range between the minimum and maximum easting values
int	calculateElevationDifference() The elevation difference between beginning point and end point.
double	calculateElevationEfficencyRatio() The elevation efficiency ratio is the nominal elevation change divided by the cumulative elevation change.
int	calculateMaximumSlope() Calculates the maximum slope (as a percentage) between any two adjacent points in the track.
int	calculateMinMaxElevationDifference() The elevation difference between the minimum elevation and the maximum elevation.
int	calculateNorthingRange() Find the range between the minimum and maximum northing values.
int	calculateSWcornerEasting() Finds the southwest corner easting for the area enclosing the track log
int	calculateSWcornerNorthing() Finds the southwest corner northing for the area enclosing the track log
double	calculateTrackStdev() Calculates and returns the standard deviation of the elevations in the track.
double	calculateTrackStraightnessRatio() The straightness ratio is the straight-line distance (begin point to end point) divided by the cumulative distance of the track.
int	countTrackPoints() Returns the number of TrackPoints in the Track Log
boolean	equals(TrackLog trackLog) Compares another Tracklog to this to see if they are equivalent tracks.
java.lang.String	getCleanTrackName() accessor for the track name, truncates at any "|" characters and removes white space in favor of "_", giving a gps friendly name for a track
java.lang.String	getDatum() accessor for the datum string
protected double	getDistance(TrackPoint one, TrackPoint two) Returns the distance between two trackpoints
java.lang.String	getTrackName() accessor for the track name
TrackPoint[]	getTrackPoints() returns an array of TrackPoint objects
java.lang.String	getVersion() version (such as "Version 2:CSV").
int	getZoneOffset() accessor for the zone offset
int[]	getZones() Returns a sorted array of integers representing the zones found in the TrackLog TrackPoint objects
boolean	hasMoreElements() implements java.util.Enumeration
boolean	isRoundTrip() A track log is a round trip if it starts and begins within 100 meters of the start point.
boolean	isSnapped() A raw GPS tracklog is a vector.
TrackLog	makeCopy() returns a TrackLog object that is a copy of this TrackLog
TrackPoint	nextElement() implements java.util.Enumeration
void	removeDuplicateTrackPoints() Removes duplicate TrackPoints from the TrackLog, where duplicate is defined as a sequentially duplicated point with the exact zone, easting and northing.
void	reset() resets the java.util.Enumeration to the first element
TrackLog[]	segmentTrackLog() Segments The TrackLog into individual segments such that the last point in each new segment is also the furthest point from the starting point of the segment.
void	setDatum(java.lang.String datum) mutator for the datum string
protected void	setIsSnapped(boolean isSnapped) mutator for the isSnapped value
void	setTimeToGmt() Changes the internal Calendar representation for each TrackPoint in this TrackLog to GMT, and sets the zone offset for this object to 0 (GMT).
void	setTrackName(java.lang.String trackName) mutator for track name
void	setVersion(java.lang.String version) mutator for version string
void	setZoneOffset(int zoneOffset) mutator for the zone offset from GMT
int	size() returns the number of elements (TrackPoints) in this TrackLog.
void	snapToDatabase(java.sql.Connection connection) Snaps TrackPoints in the input track log to their closest Points in the database.
TrackLog	subSegment(int from, int to) returns a TrackLog object representing TrackPoints element "from" to the element "to".
java.lang.String	toString() Overrides toString()

Methods inherited from class java.lang.Object

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

Field Detail

trackPoints

protected java.util.Vector<TrackPoint> trackPoints

confs

protected C5UTMconfs confs

Constructor Detail

TrackLog

public TrackLog()

Default TrackLog constuctor. Used when creating artificial track logs.

TrackLog

public TrackLog(java.util.Vector<TrackLog> trackLogs)

Creates a TrackLog from a java.util.Vector containing other TrackLog objects. This creates a new singular TrackLog object from Multiple TrackLogs, with the TrackPoints in the order in which they are in containing TrackLogs and the Vector. All Calendars in the TrackPoint objects are converted to GMT.

Parameters:

trackLogs - Vector of trackLogs to concatenate into a new TrackLog

TrackLog

public TrackLog(java.lang.String trackName,
                java.lang.String version,
                java.lang.String datum,
                int zoneOffset)

Constructor taking a name, version, datum, and zoneOffest value.

Parameters:

trackName - the name of the track

version - the g7towin version, such as "Version CSV:2"

datum - the datum

zoneOffset - the zone offset from GMT

Method Detail

hasMoreElements

public boolean hasMoreElements()

implements java.util.Enumeration

Specified by:

hasMoreElements in interface java.util.Enumeration

Returns:

true if has more elements

See Also:

Enumeration

nextElement

public TrackPoint nextElement()
                       throws java.util.NoSuchElementException

implements java.util.Enumeration

Specified by:

nextElement in interface java.util.Enumeration

Returns:

the next WayPoint

Throws:

java.util.NoSuchElementException

See Also:

Enumeration

reset

public void reset()

resets the java.util.Enumeration to the first element

getZoneOffset

public int getZoneOffset()

accessor for the zone offset

Returns:

the zone offset

getTrackName

public java.lang.String getTrackName()

accessor for the track name

Returns:

the track name

getCleanTrackName

public java.lang.String getCleanTrackName()

accessor for the track name, truncates at any "|" characters and removes white space in favor of "_", giving a gps friendly name for a track

Returns:

a gps friendly name for a track

getVersion

public java.lang.String getVersion()

version (such as "Version 2:CSV"). The user is responsible for setting this value if they wish to override the default values of any com.c5corp.c5gps.filters.AbstractGpsFilter that may be used. The filters will normally know the correct version info and might override the user value.

Returns:

the version string

See Also:

GpsDataFilter

getDatum

public java.lang.String getDatum()

accessor for the datum string

Returns:

Sring representing the datum

isSnapped

public boolean isSnapped()

A raw GPS tracklog is a vector. The data in the database is a raster. If the tracklog vector points have been "snapped to" the raster, this method will return true.

Returns:

isSnapped true if the TrackLog has been snapped to the values in the database

See Also:

snapToDatabase(java.sql.Connection)

setIsSnapped

protected void setIsSnapped(boolean isSnapped)

mutator for the isSnapped value

Parameters:

isSnapped - true sets this TrackLog to snapped

setZoneOffset

public void setZoneOffset(int zoneOffset)

mutator for the zone offset from GMT

Parameters:

zoneOffset - offset from GMT

setVersion

public void setVersion(java.lang.String version)

mutator for version string

Parameters:

version - sets the g7towin version string

setTrackName

public void setTrackName(java.lang.String trackName)

mutator for track name

Parameters:

trackName - the name of the track

setDatum

public void setDatum(java.lang.String datum)

mutator for the datum string

Parameters:

datum - the datum string

getTrackPoints

public TrackPoint[] getTrackPoints()

returns an array of TrackPoint objects

Returns:

array of TrackPoints

addTrackPoint

public void addTrackPoint(java.lang.String type,
                          int zoneNum,
                          int easting,
                          int northing,
                          int altitude)

Adds a TrackPoint to the TrackLog, with a default (epochal) date.

Parameters:

type - the GpsPointRecord type

zoneNum - the UUM zone of the point

easting - the UTM easting

northing - the UTM northing

altitude - the altitude

addTrackPoint

public void addTrackPoint(java.lang.String type,
                          int zoneNum,
                          java.lang.String zoneChar,
                          int easting,
                          int northing,
                          int altitude)

Adds a TrackPoint to the TrackLog, with a default (epochal) date.

Parameters:

type - the GpsPointRecord type

zoneNum - the UTM zone of the point

zoneChar - the UTM grid zone designation character (GZD)

easting - the UTM easting

northing - the UTM northing

altitude - the altitude of the point

addTrackPoint

public void addTrackPoint(java.lang.String type,
                          int zoneNum,
                          int easting,
                          int northing,
                          java.util.Calendar date,
                          int altitude)

Adds a TrackPoint to the TrackLog. The Calendar ob refecting the date can be any arbitrary time zone (see the Calendar class), but note that the setTimeToGmt() method of this class can change them all to a GMT representation.

Parameters:

type - the GpsPointRecord type

zoneNum - the UUM zone of the point

easting - the UTM easting

northing - the UTM northing

date - the date (and time) the point was taken

altitude - the altitude of the point

See Also:

setTimeToGmt()

addTrackPoint

public void addTrackPoint(java.lang.String type,
                          int zoneNum,
                          java.lang.String zoneChar,
                          int easting,
                          int northing,
                          java.util.Calendar date,
                          int altitude)

Adds a TrackPoint to the TrackLog. The Calendar ob refecting the date can be any arbitrary time zone (see the Calendar class), but note that the setTimeToGmt() method of this class can change them all to a GMT representation.

Parameters:

type - the GpsPointRecord type

zoneNum - the UTM zone of the point

zoneChar - the UTM grid zone designation character (GZD)

easting - the UTM easting

northing - the UTM northing

date - the date (and time) the point was taken

altitude - the altitude of the point * @see #setTimeToGmt()

addTrackPoint

public void addTrackPoint(java.lang.String type,
                          int zoneNum,
                          int easting,
                          int northing,
                          int month,
                          int day,
                          int year,
                          int hour,
                          int minute,
                          int second,
                          int altitude)

Adds a TrackPoint to the TrackLog. Uses the zone offset in this class to set the Calendar ob to the correct GMT representation.

Parameters:

type - the GpsPointRecord type

zoneNum - the UUM zone of the point

easting - the UTM easting

northing - the UTM northing

month - the month

day - the day

year - the year

hour - the hour

minute - the minute

second - the second

altitude - the altitude of the point

See Also:

Calendar

addTrackPoint

public void addTrackPoint(java.lang.String type,
                          int zoneNum,
                          java.lang.String zoneChar,
                          int easting,
                          int northing,
                          int month,
                          int day,
                          int year,
                          int hour,
                          int minute,
                          int second,
                          int altitude)

Adds a TrackPoint to the TrackLog. Uses the zone offset in this class to set the Calendar ob to the correct GMT representation.

Parameters:

type - the GpsPointRecord type

zoneNum - the UTM zone of the point

zoneChar - the UTM grid zone designation character (GZD)

easting - the UTM easting

northing - the UTM northing

month - the month

day - the day

year - the year

hour - the hour

minute - the minute

second - the second

altitude - the altitude of the point

See Also:

Calendar

setTimeToGmt

public void setTimeToGmt()

Changes the internal Calendar representation for each TrackPoint in this TrackLog to GMT, and sets the zone offset for this object to 0 (GMT).

See Also:

TrackPoint, getZoneOffset()

calculateElevationEfficencyRatio

public double calculateElevationEfficencyRatio()

The elevation efficiency ratio is the nominal elevation change divided by the cumulative elevation change. The elevation efficiency ratio describes how efficient the track is regarding the traversal of the elevation between start and finish. A ratio of 1 would be most efficient (ie, the track was all uphill or all downhill). A ratio of 0 indicates that the track required elevation change for no ultimate elevation difference, (ie, a path that begins and ends at the same elevation is equal to 0.) Returns a sentinel value of -1 if there are no internal TrackPoints in the TrackLog.

Returns:

the elevation efficiency ratio

calculateTrackStraightnessRatio

public double calculateTrackStraightnessRatio()

The straightness ratio is the straight-line distance (begin point to end point) divided by the cumulative distance of the track. A ratio of 1 would mean that the path is a straight line A ratio of 0 would mean that the path is a loop of some kind undefined would be a path with no cumulative distance traveled (a one point path) Returns a sentinel value of -1 if there are no internal TrackPoints in the TrackLog.

Returns:

straightness ratio

calculateDistance

public int calculateDistance()

Returns the simple straight line distance (in meters) between begin point and end point. Returns a sentinel value of -1 if there are no internal TrackPoints in the TrackLog. Returns a sentinel value of -1 if there are not at least two internal TrackPoints in the TrackLog.

Returns:

straight line distance between begin and end point in track

calculateCumulativeDistance

public int calculateCumulativeDistance()

Returns the cumulative distance between all points in the track Returns a sentinel value of -1 if there are no internal TrackPoints in the TrackLog. Returns a sentinel value of -1 if there are not at least two internal TrackPoints in the TrackLog.

Returns:

the cumulative distance of the track

calculateCumulativeElevationChange

public int calculateCumulativeElevationChange()

The cumulative elevation change is always a positive value, because it it is calculated via the absolute value of elevational change from between sequential points in the track. It characterized the the path in terms of change. Returns a sentinel value of -1 if there are not at least two internal TrackPoints in the TrackLog.

Returns:

the cumulative elevation change

calculateElevationDifference

public int calculateElevationDifference()

The elevation difference between beginning point and end point. Returns a sentinel value of -100000000 if there are not at least two internal TrackPoints in the TrackLog.

Returns:

the elevation difference between the first and last point in the track

calculateMinMaxElevationDifference

public int calculateMinMaxElevationDifference()

The elevation difference between the minimum elevation and the maximum elevation. Returns a sentinel value of -1 if there are not at least two internal TrackPoints in the TrackLog.

Returns:

the elevation difference between the minimum elevation and the maximum elevation

calculateMaximumSlope

public int calculateMaximumSlope()

Calculates the maximum slope (as a percentage) between any two adjacent points in the track. Note that, internally, this method checks the configuration of the C5UTM database installation to ensure that the calculation is done with the same horizontal and vertical units. All TrackLog objects are assumed to use the same units as the database installation. This method assumes that your Tracklogs follows this rule. But it is possible that any of your own programmatically derived artificial Trackpoints (which you may produce using the TrackPoint and TrackLog class methods and constructors ), could be assuming different units. So be careful that if your TrackPoints are artificially derived programmatically, that your elevataions are in the units assumed by the database. Returns a sentinel value of -1 if there are not at least two internal TrackPoints in the TrackLog.

It is also important to note that GPS elevations, which can be +/- 100 meters in accuracy, can really distort this value.

Returns:

the maximum slope in the file.

See Also:

TrackPoint, C5UTMconfs

calculateTrackStdev

public double calculateTrackStdev()

Calculates and returns the standard deviation of the elevations in the track. Note that GPS elevations often have a lot of error. It is possible to create a DbTrackLog from a TrackLog, where the coordinates will be snapped to the UTM points in the Database containing accurate ground elevations, provided the appropriate dems have been added to the database. Importantly, however, GPS records altitude, not ground elevation.

It is also important to note that GPS elevations, which are +/- 100 meters in accuracy, can really distort this value.

Returns:

the standard deviation of the elevations in the track

See Also:

GpsDataFilter

snapToDatabase

public void snapToDatabase(java.sql.Connection connection)

Snaps TrackPoints in the input track log to their closest Points in the database. This method radically increases the accuracy of the elevations in a TrackLog by going the surveyed (orginally DEM) data set for elevation data to replace notoriously inaccurate GPS elevations, but importantly, at the cost of snapping to the easting and northing to the closest points in the 30 meter resolution database. Even Basic GPS commonly has a higher horizontal accuracy than this; as low as 4 meters with WAAS, so this method tends to reduce horizontal accuracy. The snapping also creates many duplicate spatial points that can be deleted with removeDuplicateTrackPoints().

Parameters:

connection - The db connection

See Also:

removeDuplicateTrackPoints()

removeDuplicateTrackPoints

public void removeDuplicateTrackPoints()

Removes duplicate TrackPoints from the TrackLog, where duplicate is defined as a sequentially duplicated point with the exact zone, easting and northing.

calculateNorthingRange

public int calculateNorthingRange()

Find the range between the minimum and maximum northing values.

Returns:

the northing range of the area containing the track, from the sw corner

calculateEastingRange

public int calculateEastingRange()

Finds the range between the minimum and maximum easting values

Returns:

the easting range of the area containing the track, from the sw corner

calculateSWcornerEasting

public int calculateSWcornerEasting()

Finds the southwest corner easting for the area enclosing the track log

Returns:

the south west corner easting value of the area containing the track

calculateSWcornerNorthing

public int calculateSWcornerNorthing()

Finds the southwest corner northing for the area enclosing the track log

Returns:

the south west corner northing value of the area containing the track

isRoundTrip

public boolean isRoundTrip()

A track log is a round trip if it starts and begins within 100 meters of the start point.

Returns:

true if the track is round trip

countTrackPoints

public int countTrackPoints()

Returns the number of TrackPoints in the Track Log

Returns:

the number of TrackPoints

segmentTrackLog

public TrackLog[] segmentTrackLog()

Segments The TrackLog into individual segments such that the last point in each new segment is also the furthest point from the starting point of the segment. If you use these segments to create a new unified TrackLog, the result will be the same as the original TrackLog.

Returns:

at TrackLog[] of the split segments

getZones

public int[] getZones()

Returns a sorted array of integers representing the zones found in the TrackLog TrackPoint objects

Returns:

a sorted array of zones represented in the track

makeCopy

public TrackLog makeCopy()

returns a TrackLog object that is a copy of this TrackLog

Returns:

a copy of this

subSegment

public TrackLog subSegment(int from,
                           int to)
                    throws java.lang.ArrayIndexOutOfBoundsException

returns a TrackLog object representing TrackPoints element "from" to the element "to". This is useful for analyzing arbitrary sub tracks and for animating a track log.

Parameters:

from - the start point of the sub segment

to - the end point of the sub segment

Returns:

a TrackLog representing the TrackPoints "from" to "to"

Throws:

java.lang.ArrayIndexOutOfBoundsException

getDistance

protected double getDistance(TrackPoint one,
                             TrackPoint two)

Returns the distance between two trackpoints

Parameters:

one - point one

two - point two

Returns:

the distance between one and two

size

public int size()

returns the number of elements (TrackPoints) in this TrackLog.

Returns:

the number of trackpoints

equals

public boolean equals(TrackLog trackLog)

Compares another Tracklog to this to see if they are equivalent tracks. For this to be the case, two severe conditions must be met:

1. The number of TrackPoints in the track log must be equal
2. The coordinates (zone, gzd, easting, northing) in each of the TrackPoints must correspond exactly

Parameters:

trackLog - the TrackLog to compare

Returns:

true if the tracks are equal

toString

public java.lang.String toString()

Overrides toString()

Overrides:

toString in class java.lang.Object