org.gicentre.utils.spatial

## Class UTM

- java.lang.Object
- - org.gicentre.utils.spatial.UTM

- All Implemented Interfaces:
    MapProjection
  Direct Known Subclasses:
    OSGB

      public class UTM
      extends java.lang.Object
      implements MapProjection

  Class for representing Universal Transverse Mercator projections. Includes forward and inverse transforms from/to lat,long. Uses transformation equations from Snyder (1987) Atlas of Map Projections, and the Ordnance Survey (2002) A Guide to Coordinate Systems of Great Britain. If explicit projection origins are not given, an appropriate UTM zone should be set before transforming in either direction. This can be determined by passing a reasonably central longitude/latitude coordinate pair to the constructor.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `FROM_LAT_LONG` Indicates a transformation from longitude/latitude
    `static int` | `TO_LAT_LONG` Indicates a transformation to longitude/latitude

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UTM(Ellipsoid ellipsoid, float lat, float lng)` Initialises the UTM converter with the given ellipsoid.
    `UTM(Ellipsoid ellipsoid, int zoneNumber, char zoneLetter)` Initialises the UTM converter with the given ellipsoid and zone.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `doInterpolation()` Indicates whether the transformation should use nearest neighbour (false) or some interpolator (true).
    `java.lang.String` | `getDescription()` Provides a general description of the transformation.
    `Ellipsoid` | `getEllipsoid()` Reports the ellipsoid used in the transformation.
    `java.lang.String` | `getZone()` Reports the full UTM zone of currently used by the projection.
    `char` | `getZoneLetter()` Reports the UTM zone letter currently used by the projection.
    `int` | `getZoneNumber()` Reports the UTM zone currently used by the projection.
    `processing.core.PVector` | `invTransformCoords(processing.core.PVector p)` Performs an inverse UTM transform on the given location.
    `processing.core.PVector` | `latLongToUTM(processing.core.PVector p)` Converts the given (`lat`,`lng`) coordinates into a UTM location.
    `processing.core.PVector` | `latLongToUTM(processing.core.PVector p, double lngOrigin, double latOrigin, double xOffset, double yOffset, double scaleFactor)` Converts the given (`lng`,`lat`) coordinates into a UTM location using the given scale factor and origins.
    `void` | `setInterpolation(boolean doInterpolation)` Sets whether the transformation should use nearest neighbour (false) or some interpolator (true).
    `void` | `setZone(float lat, float lng)` Sets the UTM zone determined by the given (`lat`,`lng`) location.
    `void` | `setZone(int zoneNumber, char zoneLetter)` Sets the zone number and letter for subsequent transformations.
    `processing.core.PVector` | `transformCoords(processing.core.PVector p)` Performs a forward transform on the given location.
    `processing.core.PVector` | `UTMToLatLong(processing.core.PVector p)` Converts the given UTM coordinates into a longitude/latitude location.
    `processing.core.PVector` | `UTMToLatLong(processing.core.PVector p, double lngOrigin, double latOrigin, double xOffset, double yOffset, double scaleFactor)` Converts the given UTM coordinates into a (`lng`,`lat`) referenced location.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### FROM_LAT_LONG

          public static final int FROM_LAT_LONG

      Indicates a transformation from longitude/latitude
      See Also:
        Constant Field Values

    - #### TO_LAT_LONG

          public static final int TO_LAT_LONG

      Indicates a transformation to longitude/latitude
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UTM

          public UTM(Ellipsoid ellipsoid,
                     int zoneNumber,
                     char zoneLetter)

      Initialises the UTM converter with the given ellipsoid and zone. The forward transformation will be from UTM to longitude/latitude.
      Parameters:
        `ellipsoid` - to use in projection.
        `zoneNumber` - Zone number of UTM projection.
        `zoneLetter` - Zone letter of UTM projection.

    - #### UTM

          public UTM(Ellipsoid ellipsoid,
                     float lat,
                     float lng)

      Initialises the UTM converter with the given ellipsoid. The initial longitude/latitude location sets the default UTM zone. This can be changed by calling the setZone() method. The forward transformation will be from longitude/latitude to UTM.
      Parameters:
        `ellipsoid` - to use in projection.
        `lat` - Initial latitude coordinate.
        `lng` - Initial longitude coordinate.

  - ### Method Detail

    - #### transformCoords

          public processing.core.PVector transformCoords(processing.core.PVector p)

      Performs a forward transform on the given location.
      Specified by:
        `transformCoords` in interface `MapProjection`
      Parameters:
        `p` - Point coordinates to transform.
      Returns:
        Transformed footprint.

    - #### invTransformCoords

          public processing.core.PVector invTransformCoords(processing.core.PVector p)

      Performs an inverse UTM transform on the given location.
      Specified by:
        `invTransformCoords` in interface `MapProjection`
      Parameters:
        `p` - Point coordinates to transform.
      Returns:
        Transformed footprint.

    - #### getDescription

          public java.lang.String getDescription()

      Provides a general description of the transformation.
      Specified by:
        `getDescription` in interface `MapProjection`
      Returns:
        Description of the transformation.

    - #### doInterpolation

          public boolean doInterpolation()

      Indicates whether the transformation should use nearest neighbour (false) or some interpolator (true).
      Returns:
        True if transformation should perform some local interpolation.

    - #### setInterpolation

          public void setInterpolation(boolean doInterpolation)

      Sets whether the transformation should use nearest neighbour (false) or some interpolator (true).
      Parameters:
        `doInterpolation` - True if transformation should perform some local interpolation.

    - #### latLongToUTM

          public processing.core.PVector latLongToUTM(processing.core.PVector p)

      Converts the given (`lat`,`lng`) coordinates into a UTM location. longitude/latitude should be in decimal degrees with positive North and positive East. The UTM zone to use should already have been set though the constructor or a call to `setzone()`.
      Parameters:
        `p` - Longitude/latitude point. Longitude varies within +-180 degrees, latitude within +-90 degrees.
      Returns:
        UTM location.

    - #### latLongToUTM

          public processing.core.PVector latLongToUTM(processing.core.PVector p,
                                                      double lngOrigin,
                                                      double latOrigin,
                                                      double xOffset,
                                                      double yOffset,
                                                      double scaleFactor)

      Converts the given (`lng`,`lat`) coordinates into a UTM location using the given scale factor and origins. longitude/latitude should be in decimal degrees with positive North and positive East. This version of the conversion does not require a UTM zone to be set as the origin is set explicitly.
      Parameters:
        `p` - Longitude/latitude point. Longitude varies within +-180 degrees, latitude within +-90 degrees.
        `lngOrigin` - Origin longitude (+-180.0).
        `latOrigin` - Origin latitude (+-90.0).
        `xOffset` - UTM coordinate X origin.
        `yOffset` - UTM coordinate Y origin.
        `scaleFactor` - Scale factor on central meridian used in transformation.
      Returns:
        UTM location.

    - #### UTMToLatLong

          public processing.core.PVector UTMToLatLong(processing.core.PVector p)

      Converts the given UTM coordinates into a longitude/latitude location. This requires a UTM zone to have been set (via constructor) in order to complete the conversion. longitude/latitude will be in decimal degrees with positive North and positive East.
      Parameters:
        `p` - Location of point as an easting and northing in the UTM projection (metres from local origin).
      Returns:
        location in geographical coordinates (longitude,latitude).

    - #### UTMToLatLong

          public processing.core.PVector UTMToLatLong(processing.core.PVector p,
                                                      double lngOrigin,
                                                      double latOrigin,
                                                      double xOffset,
                                                      double yOffset,
                                                      double scaleFactor)

      Converts the given UTM coordinates into a (`lng`,`lat`) referenced location. Longitude/latitude will be in decimal degrees with positive North and positive East. This transformation is independent of the UTM zone defined by the constructor since all parameters are given explicitly.
      Parameters:
        `p` - Location of point as an easting and northing in the UTM projection (metres from local origin).
        `lngOrigin` - Origin longitude (+-180)
        `latOrigin` - Origin latitude (+-90)
        `xOffset` - UTM coordinate X origin.
        `yOffset` - UTM coordinate Y origin.
        `scaleFactor` - Scale factor on central meridian used in transformation.
      Returns:
        location in geographical coordinates (longitude,latitude).

    - #### setZone

          public void setZone(float lat,
                              float lng)

      Sets the UTM zone determined by the given (`lat`,`lng`) location. Numbers vary from 1 to 60, where 1 is around 175W, and 60 is 175E. Letters vary from N,M,O...X going north from equator and M,L,K...C going south from equator.
      Parameters:
        `lat` - Latitude (+-90)
        `lng` - Longitude (+-180)

    - #### setZone

          public void setZone(int zoneNumber,
                              char zoneLetter)

      Sets the zone number and letter for subsequent transformations.
      Parameters:
        `zoneNumber` - Zone number to use.
        `zoneLetter` - Zone letter to use.

    - #### getZoneNumber

          public int getZoneNumber()

      Reports the UTM zone currently used by the projection. Numbers vary from 1 to 60, where 1 is around 175W, and 60 is 175E.
      Returns:
        UTM zone number (longitudinal zone).

    - #### getZoneLetter

          public char getZoneLetter()

      Reports the UTM zone letter currently used by the projection. Letters vary from N,M,O...X going north from equator and M,L,K...C going south from equator. Returns Z if outside 84N or 80S.
      Returns:
        UTM zone letter (latitudinal zone).

    - #### getZone

          public java.lang.String getZone()

      Reports the full UTM zone of currently used by the projection.
      Returns:
        UTM zone (e.g 19F for southern tip of South America).

    - #### getEllipsoid

          public Ellipsoid getEllipsoid()

      Reports the ellipsoid used in the transformation.
      Returns:
        Ellipsoid used in the UTM transformation.