## com.bbn.openmap.proj.coords
Class UTMPoint

    java.lang.Object
      com.bbn.openmap.proj.coords.UTMPoint

Direct Known Subclasses:
  ZonedUTMPoint

public class UTMPoint
extends java.lang.Object

A class representing a UTM co-ordinate.

Adapted to Java by Colin Mummery (colin_mummery@yahoo.com) from C++ code by Chuck Gantz (chuck.gantz@globalstar.com)

Field Summary
`float` `easting` The easting component of the coordinate.
`float` `northing` The northing component of the coordinate.
`char` `zone_letter` For UTM, 'N' or 'S', to designate the northern or southern hemisphere.
`int` `zone_number` The zone number of the coordinate, must be between 1 and 60.

Constructor Summary
`UTMPoint()` Point to create if you are going to use the static methods to fill the values in.
`UTMPoint(float northing, float easting, int zone_number, char zone_letter)` Constructs a new UTM instance.
`UTMPoint(LatLonPoint llpoint)` Contruct a UTMPoint from a LatLonPoint, assuming a WGS_84 ellipsoid.
`UTMPoint(LatLonPoint llpoint, Ellipsoid ellip)` Construct a UTMPoint from a LatLonPoint and a particular ellipsoid.
`UTMPoint(UTMPoint point)` Contructs a new UTMPoint instance from values in another UTMPoint.

Method Summary
`protected char` `checkZone(char zone)` Method that provides a check for UTM zone letters.
`protected char` `getLetterDesignator(double lat)` Returns 'N' if the latitude is equal to or above the equator, 'S' if it's below.
`static int` `getZoneNumber(double lat, double lon)` Find zone number based on the given latitude and longitude in *degrees*.
`static UTMPoint` `LLtoUTM(LatLonPoint llpoint)` Converts a LatLonPoint to a UTM Point, assuming the WGS_84 ellipsoid.
`static UTMPoint` `LLtoUTM(LatLonPoint llpoint, Ellipsoid ellip, UTMPoint utmpoint)` Converts a set of Longitude and Latitude co-ordinates to UTM given an ellipsoid
`static UTMPoint` `LLtoUTM(LatLonPoint llpoint, Ellipsoid ellip, UTMPoint utmPoint, int zoneNumber, boolean isNorthern)` Converts a set of Longitude and Latitude co-ordinates to UTM given an ellipsoid and the UTM zone to use.
`static UTMPoint` `LLtoUTM(LatLonPoint llpoint, UTMPoint utmpoint)` Converts a LatLonPoint to a UTM Point.
`LatLonPoint` `toLatLonPoint()` Convert this UTMPoint to a LatLonPoint, and assume a WGS_84 ellisoid.
`LatLonPoint` `toLatLonPoint(Ellipsoid ellip)` Convert this UTMPoint to a LatLonPoint, and use the given ellipsoid.
`LatLonPoint` `toLatLonPoint(Ellipsoid ellip, LatLonPoint llpoint)` Fill in the given LatLonPoint with the converted values of this UTMPoint, and use the given ellipsoid.
`java.lang.String` `toString()` Returns a string representation of the object.
`static LatLonPoint` `UTMtoLL(Ellipsoid ellip, float UTMNorthing, float UTMEasting, int ZoneNumber, boolean isNorthern, LatLonPoint llpoint)` Converts UTM coords to lat/long given an ellipsoid.
`static LatLonPoint` `UTMtoLL(Ellipsoid ellip, float UTMNorthing, float UTMEasting, int zoneNumber, char zoneLetter, LatLonPoint llpoint)` Converts UTM coords to lat/long given an ellipsoid.
`static LatLonPoint` `UTMtoLL(Ellipsoid ellip, float UTMNorthing, float UTMEasting, java.lang.String UTMZone, LatLonPoint llpoint)` Converts UTM coords to lat/long given an ellipsoid.
`static LatLonPoint` `UTMtoLL(UTMPoint utm_point, Ellipsoid ellip, LatLonPoint llpoint)` Converts UTM coords to lat/long given an ellipsoid given an instance of UTMPoint.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### northing

    public float northing

  The northing component of the coordinate.

### easting

    public float easting

  The easting component of the coordinate.

### zone_number

    public int zone_number

  The zone number of the coordinate, must be between 1 and 60.

### zone_letter

    public char zone_letter

  For UTM, 'N' or 'S', to designate the northern or southern hemisphere.

Constructor Detail

### UTMPoint

    public UTMPoint()

  Point to create if you are going to use the static methods to fill the values in.

### UTMPoint

    public UTMPoint(float northing,
                    float easting,
                    int zone_number,
                    char zone_letter)

  Constructs a new UTM instance.

Parameters:
  `northing` - The northing component.
  `easting` - The easting component.
  `zone_number` - The zone of the coordinate.
  `zone_letter` - For UTM, 'N' or 'S', to designate the northern or southern hemisphere.
Throws:
  `java.lang.Number` - format exception of N or S isn't used.

### UTMPoint

    public UTMPoint(UTMPoint point)

  Contructs a new UTMPoint instance from values in another UTMPoint.

### UTMPoint

    public UTMPoint(LatLonPoint llpoint)

  Contruct a UTMPoint from a LatLonPoint, assuming a WGS_84 ellipsoid.

### UTMPoint

    public UTMPoint(LatLonPoint llpoint,
                    Ellipsoid ellip)

  Construct a UTMPoint from a LatLonPoint and a particular ellipsoid.

Method Detail

### checkZone

    protected char checkZone(char zone)

  Method that provides a check for UTM zone letters. Returns an uppercase version of any valid letter passed in, 'N' or 'S'.

  Throws:
    `java.lang.NumberFormatException` - if zone letter is invalid.

### toLatLonPoint

    public LatLonPoint toLatLonPoint()

  Convert this UTMPoint to a LatLonPoint, and assume a WGS_84 ellisoid.

### toLatLonPoint

    public LatLonPoint toLatLonPoint(Ellipsoid ellip)

  Convert this UTMPoint to a LatLonPoint, and use the given ellipsoid.

### toLatLonPoint

    public LatLonPoint toLatLonPoint(Ellipsoid ellip,
                                     LatLonPoint llpoint)

  Fill in the given LatLonPoint with the converted values of this UTMPoint, and use the given ellipsoid.

### toString

    public java.lang.String toString()

  Returns a string representation of the object.

  Returns:
    String representation

### LLtoUTM

    public static UTMPoint LLtoUTM(LatLonPoint llpoint)

  Converts a LatLonPoint to a UTM Point, assuming the WGS_84 ellipsoid.

  Returns:
    UTMPoint, or null if something bad happened.

### LLtoUTM

    public static UTMPoint LLtoUTM(LatLonPoint llpoint,
                                   UTMPoint utmpoint)

  Converts a LatLonPoint to a UTM Point.

  Parameters:
    `llpoint` - the LatLonPoint to convert.
    `utmpoint` - a UTMPoint to put the results in. If it's null, a UTMPoint will be allocated.
  Returns:
    UTMPoint, or null if something bad happened. If a UTMPoint was passed in, it will also be returned on a successful conversion.

### LLtoUTM

    public static UTMPoint LLtoUTM(LatLonPoint llpoint,
                                   Ellipsoid ellip,
                                   UTMPoint utmpoint)

  Converts a set of Longitude and Latitude co-ordinates to UTM given an ellipsoid

  Parameters:
    `ellip` - an ellipsoid definition.
    `llpoint` - the coordinate to be converted
    `utmpoint` - A UTMPoint instance to put the results in. If null, a new UTMPoint will be allocated.
  Returns:
    A UTM class instance containing the value of `null` if conversion failed. If you pass in a UTMPoint, it will be returned as well if successful.

### LLtoUTM

    public static UTMPoint LLtoUTM(LatLonPoint llpoint,
                                   Ellipsoid ellip,
                                   UTMPoint utmPoint,
                                   int zoneNumber,
                                   boolean isNorthern)

  Converts a set of Longitude and Latitude co-ordinates to UTM given an ellipsoid and the UTM zone to use.

  Parameters:
    `ellip` - an ellipsoid definition.
    `llpoint` - the coordinate to be converted
    `utmPoint` - A UTMPoint instance to put the results in. If null, a new UTMPoint will be allocated.
    `zoneNumber` - the number of the zone
    `isNorthern` - true if zone is in norhering hemispehere
  Returns:
    A UTM class instance containing the value of `null` if conversion failed. If you pass in a UTMPoint, it will be returned as well if successful.

### getLetterDesignator

    protected char getLetterDesignator(double lat)

  Returns 'N' if the latitude is equal to or above the equator, 'S' if it's below.

  Parameters:
    `lat` - The float value of the latitude.
  Returns:
    A char value

### UTMtoLL

    public static LatLonPoint UTMtoLL(UTMPoint utm_point,
                                      Ellipsoid ellip,
                                      LatLonPoint llpoint)

  Converts UTM coords to lat/long given an ellipsoid given an instance of UTMPoint.

  Parameters:
    `utm_point` - A UTMPoint instance.
    `ellip` - a ellipsoid definition.
    `llpoint` - a LatLonPoint, if you want it to be filled in with the results. If null, a new LatLonPoint will be allocated.
  Returns:
    A LatLonPoint class instance containing the lat/long value, or `null` if conversion failed. If you pass in a LatLonPoint, it will be returned as well, if successful.

### UTMtoLL

    public static LatLonPoint UTMtoLL(Ellipsoid ellip,
                                      float UTMNorthing,
                                      float UTMEasting,
                                      java.lang.String UTMZone,
                                      LatLonPoint llpoint)

  Converts UTM coords to lat/long given an ellipsoid. This is a convenience class where the Zone can be specified as a single string eg."61N" which is then broken down into the ZoneNumber and ZoneLetter.

  Parameters:
    `ellip` - an ellipsoid definition.
    `UTMNorthing` - A float value for the northing to be converted.
    `UTMEasting` - A float value for the easting to be converted.
    `UTMZone` - A String value for the UTM zone eg."61N".
    `llpoint` - a LatLonPoint, if you want it to be filled in with the results. If null, a new LatLonPoint will be allocated.
  Returns:
    A LatLonPoint class instance containing the lat/long value, or `null` if conversion failed. If you pass in a LatLonPoint, it will be returned as well, if successful.

### UTMtoLL

    public static LatLonPoint UTMtoLL(Ellipsoid ellip,
                                      float UTMNorthing,
                                      float UTMEasting,
                                      int ZoneNumber,
                                      boolean isNorthern,
                                      LatLonPoint llpoint)

  Converts UTM coords to lat/long given an ellipsoid. This is a convenience class where the exact Zone letter is not known. Instead only the hemisphere needs to be indicated.

  Parameters:
    `ellip` - an ellipsoid definition.
    `UTMNorthing` - A float value for the northing to be converted.
    `UTMEasting` - A float value for the easting to be converted.
    `ZoneNumber` - An int value indicating the float number.
    `isNorthern` - A boolean which is true for the northern hemisphere otherwise false for the southern.
    `llpoint` - a LatLonPoint, if you want it to be filled in with the results. If null, a new LatLonPoint will be allocated.
  Returns:
    A LatLonPoint class instance containing the lat/long value, or `null` if conversion failed. If you pass in a LatLonPoint, it will be returned as well, if successful.

### UTMtoLL

    public static LatLonPoint UTMtoLL(Ellipsoid ellip,
                                      float UTMNorthing,
                                      float UTMEasting,
                                      int zoneNumber,
                                      char zoneLetter,
                                      LatLonPoint llpoint)

  Converts UTM coords to lat/long given an ellipsoid.

  Equations from USGS Bulletin 1532
  East Longitudes are positive, West longitudes are negative.
  North latitudes are positive, South latitudes are negative.

  Parameters:
    `ellip` - an ellipsoid definition.
    `UTMNorthing` - A float value for the northing to be converted.
    `UTMEasting` - A float value for the easting to be converted.
    `zoneNumber` - An int value specifiying the UTM zone number.
    `zoneLetter` - A char value specifying the ZoneLetter within the ZoneNumber.
    `llpoint` - a LatLonPoint, if you want it to be filled in with the results. If null, a new LatLonPoint will be allocated.
  Returns:
    A LatLonPoint class instance containing the lat/long value, or `null` if conversion failed. If you pass in a LatLonPoint, it will be returned as well, if successful.

### getZoneNumber

    public static int getZoneNumber(double lat,
                                    double lon)

  Find zone number based on the given latitude and longitude in *degrees*.

  Parameters:
    `lat` -
    `lon` -
  Returns:

Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details