Package org.jscience.geography.coordinates

Class UTM

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, javolution.lang.Immutable, javolution.lang.Realtime, javolution.lang.ValueType, javolution.xml.XMLSerializable, org.opengis.spatialschema.geometry.DirectPosition, org.opengis.spatialschema.geometry.geometry.Position, org.opengis.util.Cloneable
    public final class UTM
extends Coordinates<ProjectedCRS<?>>
    This class represents the projected Universal Transverse Mercator (UTM) coordinates onto the WGS84 ellipsoid.

    The UTM system is limited to values between -80 and +84 degrees latitude. Values beyond these limits (i.e., the polar regions) are projected using the Universal Polar Stereographic (UPS) projection. Although mathematically distinct, the two projections are represented identically. This class returns correct results for both UTM and UPS projections. The conversion routines for this class were derived from formulas described in the Defense Mapping Agency Technical Manual 8358.2.

    Version:
    3.0, February 25, 2006
    Author:
    Paul D. Anderson
    See Also:
    Wikipedia: Universal Transverse Mercator Coordinate System, Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static ProjectedCRS<UTM> CRS
      Holds the coordinate reference system for all instances of this class.
      static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UPS_FALSE_EASTING
      The UPS "false easting" value.
      static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UPS_FALSE_NORTHING
      The UPS "false northing" value.
      static double UPS_SCALE_FACTOR
      The UPS scale factor.
      static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UTM_FALSE_EASTING
      The UTM "false easting" value.
      static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UTM_FALSE_NORTHING
      The UTM "false northing" value.
      static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Angle> UTM_NORTHERN_LIMIT
      The northern limit of the UTM grid.
      static double UTM_SCALE_FACTOR
      The UTM scale factor.
      static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Angle> UTM_SOUTHERN_LIMIT
      The southern limit of the UTM grid.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      UTM copy()
      Returns a copy of these coordinates allocated by the calling thread (possibly on the stack).
      double eastingValue​(javax.measure.unit.Unit<javax.measure.quantity.Length> unit)
      Returns the projected distance of the position from the central meridian.
      static double getCentralMeridian​(int longitudeZone, char latitudeZone)
      Returns the central meridian (in radians) for the specified UTM/UPS zone.
      ProjectedCRS<UTM> getCoordinateReferenceSystem()
      Returns the reference system for this coordinates.
      int getDimension()
      OpenGIS® - The length of coordinate sequence (the number of entries).
      static char getLatitudeZone​(LatLong latLong)
      Returns the UTM/UPS latitude zone identifier for the specified coordinates.
      static int getLongitudeZone​(LatLong latLong)
      Returns the UTM/UPS longitude zone number for the specified coordinates.
      double getOrdinate​(int dimension)
      OpenGIS® - Returns the ordinate at the specified dimension.
      static boolean isNorthPolar​(LatLong latLong)
      Returns true if the position indicated by the coordinates is north of the northern limit of the UTM grid (84 degrees).
      static boolean isSouthPolar​(LatLong latLong)
      Returns true if the position indicated by the coordinates is south of the southern limit of the UTM grid (-80 degrees).
      char latitudeZone()
      Returns the latitude zone identifier.
      static UTM latLongToUps​(LatLong latLong, ReferenceEllipsoid ellipsoid)
      Converts latitude/longitude coordinates to UPS coordinates based on the specified reference ellipsoid.
      static UTM latLongToUtm​(LatLong latLong, ReferenceEllipsoid ellipsoid)
      Converts latitude/longitude coordinates to UTM coordinates based on the specified reference ellipsoid.
      int longitudeZone()
      Returns the longitude zone identifier.
      double northingValue​(javax.measure.unit.Unit<javax.measure.quantity.Length> unit)
      Returns the projected distance of the point from the equator.
      static LatLong upsToLatLong​(UTM ups, ReferenceEllipsoid ellipsoid)
      Converts the UPS coordinates to latitude/longitude coordinates, based on the specified reference ellipsoid.
      static LatLong utmToLatLong​(UTM utm, ReferenceEllipsoid ellipsoid)
      Converts the UTM coordinates to latitude/longitude coordinates, based on the specified reference ellipsoid.
      static UTM valueOf​(int longitudeZone, char latitudeZone, double easting, double northing, javax.measure.unit.Unit<javax.measure.quantity.Length> unit)
      Returns the projected UTM position corresponding to the specified coordinates.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • UTM_SCALE_FACTOR

        public static final double UTM_SCALE_FACTOR
        The UTM scale factor. This the exact scale factor only on a pair of lines lying either side of the central meridian, but the effect is to reduce overall distortion within the UTM zone to less than one part per thousand.
        See Also:
        Constant Field Values

      • UTM_FALSE_EASTING

        public static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UTM_FALSE_EASTING
        The UTM "false easting" value. This quantity is added to the true easting to avoid using negative numbers in the coordinates.

      • UTM_FALSE_NORTHING

        public static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UTM_FALSE_NORTHING
        The UTM "false northing" value. This quantity is added to the true northing for coordinates in the southern hemisphere only to avoid using negative numbers in the coordinates.

      • UTM_NORTHERN_LIMIT

        public static final javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Angle> UTM_NORTHERN_LIMIT
        The northern limit of the UTM grid. Beyond this limit the distortion introduced by the transverse Mercator projection is impractically large, and the UPS grid is used instead.

      • UTM_SOUTHERN_LIMIT

        public static final javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Angle> UTM_SOUTHERN_LIMIT
        The southern limit of the UTM grid. Beyond this limit the distortion introduced by the transverse Mercator projection is impractically large, and the UPS grid is used instead.

      • UPS_FALSE_EASTING

        public static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UPS_FALSE_EASTING
        The UPS "false easting" value. This quantity is added to the true easting to avoid using negative numbers in the coordinates.

      • UPS_FALSE_NORTHING

        public static javax.measure.Measure<java.lang.Integer,​javax.measure.quantity.Length> UPS_FALSE_NORTHING
        The UPS "false northing" value. This quantity is added to the true northing to avoid using negative numbers in the coordinates. The UPS system, unlike the UTM system, always includes the false northing.

      • CRS

        public static final ProjectedCRS<UTM> CRS
        Holds the coordinate reference system for all instances of this class.

    • Method Detail

      • valueOf

        public static UTM valueOf​(int longitudeZone,
                          char latitudeZone,
                          double easting,
                          double northing,
                          javax.measure.unit.Unit<javax.measure.quantity.Length> unit)
        Returns the projected UTM position corresponding to the specified coordinates.
        Parameters:
        longitudeZone - the longitude zone number.
        latitudeZone - the longitude zone character.
        easting - the easting value stated in the specified unit.
        northing - the northing value stated in the specified unit.
        unit - the easting/northing length unit.
        Returns:
        the corresponding surface position.

      • longitudeZone

        public final int longitudeZone()
        Returns the longitude zone identifier.
        Returns:
        the longitude zone number.

      • latitudeZone

        public final char latitudeZone()
        Returns the latitude zone identifier.
        Returns:
        the latitude zone character.

      • eastingValue

        public final double eastingValue​(javax.measure.unit.Unit<javax.measure.quantity.Length> unit)
        Returns the projected distance of the position from the central meridian.
        Parameters:
        unit - the length unit of the easting to return.
        Returns:
        the easting stated in the specified unit.

      • northingValue

        public final double northingValue​(javax.measure.unit.Unit<javax.measure.quantity.Length> unit)
        Returns the projected distance of the point from the equator.
        Parameters:
        unit - the length unit of the northing to return.
        Returns:
        the northing stated in the specified unit.

      • getOrdinate

        public double getOrdinate​(int dimension)
                   throws java.lang.IndexOutOfBoundsException
        Description copied from class: Coordinates
        OpenGIS® - Returns the ordinate at the specified dimension.
        Specified by:
        getOrdinate in interface org.opengis.spatialschema.geometry.DirectPosition
        Specified by:
        getOrdinate in class Coordinates<ProjectedCRS<?>>
        Parameters:
        dimension - The dimension in the range 0 to dimension-1.
        Returns:
        The coordinate at the specified dimension.
        Throws:
        java.lang.IndexOutOfBoundsException - if the specified dimension is out of bounds.

      • isNorthPolar

        public static boolean isNorthPolar​(LatLong latLong)
        Returns true if the position indicated by the coordinates is north of the northern limit of the UTM grid (84 degrees).
        Parameters:
        latLong - The coordinates.
        Returns:
        True if the latitude is greater than 84 degrees.

      • isSouthPolar

        public static boolean isSouthPolar​(LatLong latLong)
        Returns true if the position indicated by the coordinates is south of the southern limit of the UTM grid (-80 degrees).
        Parameters:
        latLong - The coordinates.
        Returns:
        True if the latitude is less than -80 degrees.

      • getLatitudeZone

        public static char getLatitudeZone​(LatLong latLong)
        Returns the UTM/UPS latitude zone identifier for the specified coordinates.
        Parameters:
        latLong - The coordinates.
        Returns:
        the latitude zone character.

      • getLongitudeZone

        public static int getLongitudeZone​(LatLong latLong)
        Returns the UTM/UPS longitude zone number for the specified coordinates.
        Parameters:
        latLong - The coordinates.
        Returns:
        the longitude zone number.

      • getCentralMeridian

        public static double getCentralMeridian​(int longitudeZone,
                                        char latitudeZone)
        Returns the central meridian (in radians) for the specified UTM/UPS zone.
        Parameters:
        longitudeZone - The UTM/UPS longitude zone number.
        latitudeZone - The UTM/UPS latitude zone character.
        Returns:
        The central meridian for the specified zone.

      • latLongToUtm

        public static UTM latLongToUtm​(LatLong latLong,
                               ReferenceEllipsoid ellipsoid)
        Converts latitude/longitude coordinates to UTM coordinates based on the specified reference ellipsoid.
        Parameters:
        latLong - The latitude/longitude coordinates.
        ellipsoid - The reference ellipsoid.
        Returns:
        The UTM coordinates.

      • latLongToUps

        public static UTM latLongToUps​(LatLong latLong,
                               ReferenceEllipsoid ellipsoid)
        Converts latitude/longitude coordinates to UPS coordinates based on the specified reference ellipsoid.
        Parameters:
        latLong - The latitude/longitude coordinates.
        ellipsoid - The reference ellipsoid.
        Returns:
        The UPS coordinates.

      • utmToLatLong

        public static LatLong utmToLatLong​(UTM utm,
                                   ReferenceEllipsoid ellipsoid)
        Converts the UTM coordinates to latitude/longitude coordinates, based on the specified reference ellipsoid.
        Parameters:
        utm - The UTM coordinates.
        ellipsoid - The reference ellipsoid.
        Returns:
        The latitude/longitude coordinates.

      • upsToLatLong

        public static LatLong upsToLatLong​(UTM ups,
                                   ReferenceEllipsoid ellipsoid)
        Converts the UPS coordinates to latitude/longitude coordinates, based on the specified reference ellipsoid.
        Parameters:
        ups - The UPS coordinates.
        ellipsoid - The reference ellipsoid.
        Returns:
        The latitude/longitude coordinates.

      • copy

        public UTM copy()
        Description copied from class: Coordinates
        Returns a copy of these coordinates allocated by the calling thread (possibly on the stack).
        Specified by:
        copy in interface javolution.lang.ValueType
        Specified by:
        copy in class Coordinates<ProjectedCRS<?>>
        Returns:
        an identical and independant copy of these coordinates .