com.isti.util.gis
Class LocationDistance

java.lang.Object
  extended by com.isti.util.gis.LocationDistance
All Implemented Interfaces:
MeasurementUnitsInformation

public class LocationDistance
extends java.lang.Object
implements MeasurementUnitsInformation

Class LocationDistance calculates the distance and azimuth between two points. (Converted from "distance.c" in QPager280Source).


Nested Class Summary
static class LocationDistance.FoundLocationInfo
          Class FoundLocationInfo references a 'LocationInfoBlk' and contains a distance value.
static class LocationDistance.LocationInfoBlk
          Class LocationInfoBlk contains information for a point location.
 
Field Summary
static char[] ACCENT_CHARS
          Array of "accented" characters.
static int ACCENT_CHARS_LEN
          Length of "accented/unaccented" character arrays.
static double DEGTORAD
          Arc-degree to radian (pi / 180).
protected  LocationDistance.LocationInfoBlk[] locationInfoArray
          Array of 'LocationInfoBlk' objects loaded from file.
protected  int locationInfoArrLen
          Number of entries in 'locationInfoArray'.
static double RADTODEG
          Radian to arc-degree (180 / pi).
static char[] UNACCENT_CHARS
          Array of "unaccented" characters.
 
Fields inherited from interface com.isti.util.MeasurementUnitsInformation
DEFAULT_MEASUREMENT_UNITS, FEET, FEET_TO_METER, KILOM, KM_TO_MILE, METER, METER_TO_FEET, METER_TO_KM, METER_TO_MILE, MILE_TO_KM, MILE_TO_METER, MILES
 
Constructor Summary
LocationDistance(java.lang.String locationNoteDataFileName)
          Calculates the distance and azimuth between two points.
 
Method Summary
 UnsyncFifoHashtable findNearestPointObjs(double latVal, double lonVal, int maxNumPoints, double maxDistance)
          Returns a table containing the nearest points to the given point.
static java.lang.String getCharsetName()
          Get the charset name.
 int getMeasurementUnits()
          Gets the measurement units.
 LocationDistanceInformation getNearestPoint(double latVal, double lonVal)
          Returns a 'LocationDistanceInformation' object for the nearest point to the given point.
 LocationDistanceInformation getNearestPoint(double latVal, double lonVal, double maxDistance)
          Returns a 'LocationDistanceInformation' object for the nearest point to the given point.
 LocationDistanceInformation[] getNearestPoints(double latVal, double lonVal, int maxNumPoints, double maxDistance)
          Returns an array of 'LocationDistanceInformation' objects for the nearest points to the given point.
 java.lang.String getNearestPointString(double latVal, double lonVal)
          Returns a string containing location-distance information for the nearest point to the given point.
 java.lang.String getNearestPointString(double latVal, double lonVal, double maxDistance)
          Returns a string containing location-distance information for the nearest point to the given point.
static java.lang.String getUnaccentedName(java.lang.String nameStr)
          Replaces "accented" characters in the given string with "unaccented" equivilants.
 boolean isDataValid()
          Returns the status of the load of data from the location file.
static LocationDistance.LocationInfoBlk[] loadLocationFile(java.lang.String locFileName)
          Loads the given file of "lon lat name" entries into a list.
static LocationDistanceInformation[] selectNearestPoints(double latVal, double lonVal, java.lang.Object foundLocationsObj, int maxNumPoints, double maxDistance)
          Returns an array of 'LocationDistanceInformation' objects for the nearest points to the given point, using the given table or tables.
static LocationDistanceInformation[] selectNearestPoints(double latVal, double lonVal, java.lang.Object foundLocationsObj, int maxNumPoints, double maxDistance, int measurementUnits)
          Returns an array of 'LocationDistanceInformation' objects for the nearest points to the given point, using the given table or tables.
static void setCharsetName(java.lang.String charsetName)
          Set the charset name.
 void setMeasurementUnits(int mu)
          Sets the measurement units.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ACCENT_CHARS

public static final char[] ACCENT_CHARS
Array of "accented" characters.


UNACCENT_CHARS

public static final char[] UNACCENT_CHARS
Array of "unaccented" characters.


ACCENT_CHARS_LEN

public static final int ACCENT_CHARS_LEN
Length of "accented/unaccented" character arrays.


DEGTORAD

public static final double DEGTORAD
Arc-degree to radian (pi / 180).

See Also:
Constant Field Values

RADTODEG

public static final double RADTODEG
Radian to arc-degree (180 / pi).

See Also:
Constant Field Values

locationInfoArray

protected final LocationDistance.LocationInfoBlk[] locationInfoArray
Array of 'LocationInfoBlk' objects loaded from file.


locationInfoArrLen

protected final int locationInfoArrLen
Number of entries in 'locationInfoArray'.

Constructor Detail

LocationDistance

public LocationDistance(java.lang.String locationNoteDataFileName)
Calculates the distance and azimuth between two points.

Parameters:
locationNoteDataFileName - location note data file name.
Method Detail

getCharsetName

public static java.lang.String getCharsetName()
Get the charset name.

Returns:
the charset name.

setCharsetName

public static void setCharsetName(java.lang.String charsetName)
Set the charset name.

Parameters:
charsetName - the charset name.

isDataValid

public boolean isDataValid()
Returns the status of the load of data from the location file.

Returns:
true if data was valid, false if an error occurred.

getNearestPoints

public LocationDistanceInformation[] getNearestPoints(double latVal,
                                                      double lonVal,
                                                      int maxNumPoints,
                                                      double maxDistance)
Returns an array of 'LocationDistanceInformation' objects for the nearest points to the given point. The spherical distance (in meters) and azimuth value (in degrees) for each point is determined and entered into the returned 'LocationDistanceInformation' objects.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
maxNumPoints - the maximum number of points to be returned.
maxDistance - the maximum-distance limit (in meters) for the returned points, or 0.0 for no limit.
Returns:
An array of 'LocationDistanceInformation' objects, or an empty array if no points within the maximum-distance limit could be found, or null if an error occurred.

getNearestPoint

public LocationDistanceInformation getNearestPoint(double latVal,
                                                   double lonVal,
                                                   double maxDistance)
Returns a 'LocationDistanceInformation' object for the nearest point to the given point. The spherical distance (in meters) and azimuth value (in degrees) for the point is determined and entered into the returned 'LocationDistanceInformation' object.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
maxDistance - the maximum-distance limit (in meters) for the returned points, or 0.0 for no limit.
Returns:
A 'LocationDistanceInformation' object, or null if no points within the maximum-distance limit could be found or if an error occurred.

getNearestPoint

public LocationDistanceInformation getNearestPoint(double latVal,
                                                   double lonVal)
Returns a 'LocationDistanceInformation' object for the nearest point to the given point. The spherical distance (in meters) and azimuth value (in degrees) for the point is determined and entered into the returned 'LocationDistanceInformation' object.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
Returns:
A 'LocationDistanceInformation' object, or null if no points could be found or if an error occurred.

getNearestPointString

public java.lang.String getNearestPointString(double latVal,
                                              double lonVal,
                                              double maxDistance)
Returns a string containing location-distance information for the nearest point to the given point.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
maxDistance - the maximum-distance limit (in meters) for the returned points, or 0.0 for no limit.
Returns:
A string containing location-distance information for the nearest point to the given point, or null if no points within the maximum-distance limit could be found or if an error occurred.

getNearestPointString

public java.lang.String getNearestPointString(double latVal,
                                              double lonVal)
Returns a string containing location-distance information for the nearest point to the given point.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
Returns:
A string containing location-distance information for the nearest point to the given point, or null if no points could be found or if an error occurred.

getMeasurementUnits

public int getMeasurementUnits()
Gets the measurement units.

Specified by:
getMeasurementUnits in interface MeasurementUnitsInformation
Returns:
the measurement units.

setMeasurementUnits

public void setMeasurementUnits(int mu)
Sets the measurement units.

Specified by:
setMeasurementUnits in interface MeasurementUnitsInformation
Parameters:
mu - the measurement units.

findNearestPointObjs

public UnsyncFifoHashtable findNearestPointObjs(double latVal,
                                                double lonVal,
                                                int maxNumPoints,
                                                double maxDistance)
Returns a table containing the nearest points to the given point. The returned array is sorted using the distance values, ascending.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
maxNumPoints - the maximum number of points to be returned.
maxDistance - the maximum-distance limit (in meters) for the returned points, or 0.0 for no limit.
Returns:
A new 'UnsyncFifoHashtable' object containing 'FoundLocationInfo' objects, one for each found point (with the 'distanceValue' field of each object set to the spherical-distance value for that point) and with the table sorted by ascending order using the 'distanceValue' field.

selectNearestPoints

public static LocationDistanceInformation[] selectNearestPoints(double latVal,
                                                                double lonVal,
                                                                java.lang.Object foundLocationsObj,
                                                                int maxNumPoints,
                                                                double maxDistance)
                                                         throws java.lang.ClassCastException
Returns an array of 'LocationDistanceInformation' objects for the nearest points to the given point, using the given table or tables. The given table or tables may contain 'LocationDistance' objects or 'FoundLocationInfo' objects (generated via the 'findNearestPointObjs()' method). The returned array is sorted using the distance values, ascending. The spherical distance (in meters) and azimuth value (in degrees) for each point is determined and entered into the returned 'LocationDistanceInformation' objects.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
foundLocationsObj - a List object holding 'LocationDistance' objects; or an 'UnsyncFifoHashtable' object or list of 'UnsyncFifoHashtable' objects, with each table holding 'FoundLocationInfo' objects.
maxNumPoints - the maximum number of points to be returned, or 0 for no limit (if 'FoundLocationInfo' objects were given).
maxDistance - the maximum-distance limit (in meters) for the returned points, or 0.0 for no limit.
Returns:
An array of 'LocationDistanceInformation' objects, or an empty array if no points within the maximum-distance limit could be found.
Throws:
java.lang.ClassCastException - if the 'foundLocationsObj' parameter does not reference a list of 'LocationDistance' objects, an 'UnsyncFifoHashtable' object or a list of 'UnsyncFifoHashtable' objects, or if any 'UnsyncFifoHashtable' value entry is not a 'FoundLocationInfo' object.

selectNearestPoints

public static LocationDistanceInformation[] selectNearestPoints(double latVal,
                                                                double lonVal,
                                                                java.lang.Object foundLocationsObj,
                                                                int maxNumPoints,
                                                                double maxDistance,
                                                                int measurementUnits)
                                                         throws java.lang.ClassCastException
Returns an array of 'LocationDistanceInformation' objects for the nearest points to the given point, using the given table or tables. The given table or tables may contain 'LocationDistance' objects or 'FoundLocationInfo' objects (generated via the 'findNearestPointObjs()' method). The returned array is sorted using the distance values, ascending. The spherical distance (in meters) and azimuth value (in degrees) for each point is determined and entered into the returned 'LocationDistanceInformation' objects.

Parameters:
latVal - the latitude for the given point, in degrees.
lonVal - the longitude for the given point, in degrees.
foundLocationsObj - a List object holding 'LocationDistance' objects; or an 'UnsyncFifoHashtable' object or list of 'UnsyncFifoHashtable' objects, with each table holding 'FoundLocationInfo' objects.
maxNumPoints - the maximum number of points to be returned, or 0 for no limit (if 'FoundLocationInfo' objects were given).
maxDistance - the maximum-distance limit (in meters) for the returned points, or 0.0 for no limit.
measurementUnits - the measurement units.
Returns:
An array of 'LocationDistanceInformation' objects, or an empty array if no points within the maximum-distance limit could be found.
Throws:
java.lang.ClassCastException - if the 'foundLocationsObj' parameter does not reference a list of 'LocationDistance' objects, an 'UnsyncFifoHashtable' object or a list of 'UnsyncFifoHashtable' objects, or if any 'UnsyncFifoHashtable' value entry is not a 'FoundLocationInfo' object.

getUnaccentedName

public static java.lang.String getUnaccentedName(java.lang.String nameStr)
Replaces "accented" characters in the given string with "unaccented" equivilants.

Parameters:
nameStr - the string to use.
Returns:
A string with with "accented" characters replaced, or the original string if no "accented" characters were found.

loadLocationFile

public static LocationDistance.LocationInfoBlk[] loadLocationFile(java.lang.String locFileName)
Loads the given file of "lon lat name" entries into a list. Duplicate entries are not added to the list.

Parameters:
locFileName - the name of the file to use.
Returns:
An array of 'LocationInfoBlk' objects, or null if an error occurred.