Package org.apache.sis.measure

## Class Latitude

- Object
- - Angle
  - - Latitude

- All Implemented Interfaces:
    `Serializable`, `Comparable<Angle>`, `Formattable`

      public final class Latitude
      extends Angle

  A latitude angle in decimal degrees. Positive latitudes are North, while negative latitudes are South. The latitude symbol is the Greek lower-case letter phi (φ).

  Because the Earth is not a perfect sphere, there is small differences in the latitude values of a point depending on how the latitude is defined:

  - Geodetic latitude is the angle between the equatorial plane and a line perpendicular to the ellipsoid surface.
  - Geocentric latitude is the angle between the equatorial plane and a line going from the Earth center. It differs from geodetic latitude by less than 11 angular minutes.
  - Astronomical latitude is the angle between the equatorial plane and a line given by the direction of a plumb line (the "true vertical").
  - Above list is not exhaustive. There is also geomagnetic latitude, etc.
  The kind of latitude is unspecified by this `Latitude` class, and rather depends on the context: the latitude is geodetic if the coordinate reference system is geographic, or geocentric if the coordinate reference system is geocentric. If the context is unknown, then geodetic latitude can usually be assumed.
  Immutability and thread safety
  This final class is immutable and thus inherently thread-safe.
  Since:
    0.3
  See Also:
    `Longitude`, `AngleFormat`, `CoordinateFormat`, Serialized Form

  Defined in the `sis-utility` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static double` | `MAX_VALUE` | Maximum usual value for latitude (+90.0°).
    `static double` | `MIN_VALUE` | Minimum usual value for latitude (-90.0°).

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Latitude​(double φ)` | Construct a new latitude with the specified angular value.
    `Latitude​(String string)` | Constructs a newly allocated `Latitude` object that contain the angular value represented by the string.
    `Latitude​(DirectPosition position)` | Constructs a newly allocated object containing the latitude value of the given position.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static double` | `clamp​(double φ)` | Returns the given latitude value clamped to the [-90 … 90]° range.

    - ### Methods inherited from class Angle

      `compareTo, degrees, equals, formatTo, hashCode, radians, toString`

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### MIN_VALUE

          public static final double MIN_VALUE

      Minimum usual value for latitude (-90.0°).
      See Also:
        `DefaultCoordinateSystemAxis​.getMinimumValue()`, Constant Field Values

    - #### MAX_VALUE

          public static final double MAX_VALUE

      Maximum usual value for latitude (+90.0°).
      See Also:
        `DefaultCoordinateSystemAxis​.getMaximumValue()`, Constant Field Values

  - ### Constructor Detail

    - #### Latitude

          public Latitude​(double φ)

      Construct a new latitude with the specified angular value.
      Parameters:
        `\u03c6` - latitude value in decimal degrees.

    - #### Latitude

          public Latitude​(String string)
                   throws NumberFormatException

      Constructs a newly allocated `Latitude` object that contain the angular value represented by the string. The string should represent an angle in either fractional degrees (e.g. 45.5°) or degrees with minutes and seconds (e.g. 45°30'). The hemisphere (N or S) is optional (default to North).

      This is a convenience constructor mostly for testing purpose, since it uses a fixed locale. Developers should consider using `AngleFormat` for end-user applications instead than this constructor.

      Parameters:
        `string` - a string to be converted to a `Latitude`.
      Throws:
        `NumberFormatException` - if the string does not contain a parsable angle, or represents a longitude angle.
      See Also:
        `AngleFormat​.parse(String)`

    - #### Latitude

          public Latitude​(DirectPosition position)
                   throws IllegalArgumentException

      Constructs a newly allocated object containing the latitude value of the given position. For this method, the latitude value is defined as the angular value associated to the first axis oriented toward North or South. Note that this is not necessarily the geodetic latitudes used in geographic CRS; it may also be geocentric latitudes.

      If the axis direction is South, then the sign of the coordinate value is inverted. If the coordinate value uses another angular units than degrees, then a unit conversion is applied.

      Parameters:
        `position` - the coordinate from which to extract the latitude value in degrees.
      Throws:
        `IllegalArgumentException` - if the given coordinate it not associated to a CRS, or if no axis oriented toward North or South is found, or if that axis does not use angular units.
      Since:
        0.8

  - ### Method Detail

    - #### clamp

          public static double clamp​(double φ)

      Returns the given latitude value clamped to the [-90 … 90]° range. If the given value is outside the latitude range, then this method replaces it by ±90° with the same sign than the given φ value.

      Special cases:

      - NaN values are returned unchanged
      - ±∞ are mapped to ±90° (with the same sign)
      - ±0 are returned unchanged (i.e. the sign of negative and positive zero is preserved)
      Parameters:
        `\u03c6` - the latitude value in decimal degrees.
      Returns:
        the given value clamped to the [-90 … 90]° range, or NaN if the given value was NaN.
      Since:
        0.4
      See Also:
        `Longitude​.normalize(double)`