Module tech.uom.seshat
Package tech.uom.seshat

Class Units

Object
Units
public final class Units extends Object
Provides constants for various Units of Measurement together with static methods working on Unit instances. Unit names and definitions in this class follow the definitions provided in the EPSG geodetic dataset (when the unit exists in that dataset), except “year” which has been renamed “tropical year”. This class focuses on the most commonly used units in the geospatial domain: angular units (degree, arc-second, …), linear units (kilometre, nautical mile, …) and temporal units (day, year, …), but some other kind of units are also provided for completeness. The main quantities are listed below, together with some related units:
Some quantities and related units
Quantity typeSystem unitSome conventional units
Fundamental:
Length (L) METRE CENTIMETRE, KILOMETRE, NAUTICAL_MILE, STATUTE_MILE, FOOT
Mass (M) KILOGRAM
Time (T) SECOND MILLISECOND, MINUTE, HOUR, DAY, WEEK, TROPICAL_YEAR
ElectricCurrent (I) AMPERE
Temperature (Θ) KELVIN CELSIUS, FAHRENHEIT
AmountOfSubstance (N) MOLE
LuminousIntensity (J) CANDELA
Dimensionless:
Angle RADIAN DEGREE, ARC_MINUTE, ARC_SECOND, GRAD
SolidAngle STERADIAN
Derived:
Area (A) SQUARE_METRE HECTARE
Volume (V) CUBIC_METRE
Speed (ν) METRES_PER_SECOND KILOMETRES_PER_HOUR
Pressure PASCAL HECTOPASCAL, DECIBAR, BAR, ATMOSPHERE
Since:
1.0

  • Field Details

  • Method Details

    • isAngular

      public static boolean isAngular(Unit<?> unit)
      Returns true if the given unit is a linear unit. Linear units are convertible to DEGREE.

      Angular units are dimensionless, which may be a cause of confusion with other dimensionless units like UNITY or PPM. This method take care of differentiating angular units from other dimensionless units.

      Parameters:
      unit - the unit to check (may be null).
      Returns:
      true if the given unit is non-null and angular.
      See Also:

    • isLinear

      public static boolean isLinear(Unit<?> unit)
      Returns true if the given unit is a linear unit. Linear units are convertible to METRE.
      Parameters:
      unit - the unit to check (may be null).
      Returns:
      true if the given unit is non-null and linear.
      See Also:

    • isPressure

      public static boolean isPressure(Unit<?> unit)
      Returns true if the given unit is a pressure unit. Pressure units are convertible to PASCAL. Those units are sometimes used instead of linear units for altitude measurements.
      Parameters:
      unit - the unit to check (may be null).
      Returns:
      true if the given unit is non-null and a pressure unit.

    • isTemporal

      public static boolean isTemporal(Unit<?> unit)
      Returns true if the given unit is a temporal unit. Temporal units are convertible to SECOND.
      Parameters:
      unit - the unit to check (may be null).
      Returns:
      true if the given unit is non-null and temporal.
      See Also:

    • isScale

      public static boolean isScale(Unit<?> unit)
      Returns true if the given unit is a dimensionless scale unit. This include UNITY and PPM.
      Parameters:
      unit - the unit to check (may be null).
      Returns:
      true if the given unit is non-null and a dimensionless scale.
      See Also:

    • ensureAngular

      public static Unit<Angle> ensureAngular(Unit<?> unit) throws IllegalArgumentException
      Makes sure that the specified unit is either null or an angular unit. This method is used for argument checks in constructors and setter methods.
      Parameters:
      unit - the unit to check, or null if none.
      Returns:
      the given unit argument, which may be null.
      Throws:
      IllegalArgumentException - if unit is non-null and not an angular unit.
      See Also:

    • ensureLinear

      public static Unit<Length> ensureLinear(Unit<?> unit) throws IllegalArgumentException
      Makes sure that the specified unit is either null or a linear unit. This method is used for argument checks in constructors and setter methods.
      Parameters:
      unit - the unit to check, or null if none.
      Returns:
      the given unit argument, which may be null.
      Throws:
      IllegalArgumentException - if unit is non-null and not a linear unit.
      See Also:

    • ensureTemporal

      public static Unit<Time> ensureTemporal(Unit<?> unit) throws IllegalArgumentException
      Makes sure that the specified unit is either null or a temporal unit. This method is used for argument checks in constructors and setter methods.
      Parameters:
      unit - the unit to check, or null if none.
      Returns:
      the given unit argument, which may be null.
      Throws:
      IllegalArgumentException - if unit is non-null and not a temporal unit.
      See Also:

    • ensureScale

      public static Unit<Dimensionless> ensureScale(Unit<?> unit) throws IllegalArgumentException
      Makes sure that the specified unit is either null or a scale unit. This method is used for argument checks in constructors and setter methods.
      Parameters:
      unit - the unit to check, or null if none.
      Returns:
      the given unit argument, which may be null.
      Throws:
      IllegalArgumentException - if unit is non-null and not a scale unit.
      See Also:

    • multiply

      public static <Q extends Quantity<Q>> Unit<Q> multiply(Unit<Q> unit, double numerator, double denominator)
      Multiplies the given unit by the given ratio. For example, multiplying CENTIMETRE by 254/100 gives INCH. Invoking this method is equivalent to invoking Unit.multiply(numerator / denominator) except that the use of a ration of integer values help Seshat to improve accuracy when more than one arithmetic operation are chained.
      Type Parameters:
      Q - the quantity measured by the unit.
      Parameters:
      unit - the unit to multiply.
      numerator - the numerator of the multiplication factor.
      denominator - the denominator of the multiplication factor.
      Returns:
      the unit multiplied by the given factor.

    • toStandardUnit

      public static <Q extends Quantity<Q>> double toStandardUnit(Unit<Q> unit)
      Returns the factor by which to multiply the standard unit in order to get the given unit. The "standard" unit is usually the SI unit on which the given unit is based, as given by Unit.getSystemUnit().
      Example: if the given unit is KILOMETRE, then this method returns 1000 since a measurement in kilometres must be multiplied by 1000 in order to give the equivalent measurement in the "standard" units (here METRE).
      If the given unit is null or if the conversion to the "standard" unit cannot be expressed by a single multiplication factor, then this method returns Double.NaN.
      Type Parameters:
      Q - the quantity measured by the unit, or null.
      Parameters:
      unit - the unit for which we want the multiplication factor to standard unit, or null.
      Returns:
      the factor by which to multiply a measurement in the given unit in order to get an equivalent measurement in the standard unit, or NaN if the conversion cannot be expressed by a scale factor.

    • converter

      public static UnitConverter converter(Number scale, Number offset)
      Creates a linear converter from the given scale and offset.
      Parameters:
      scale - the scale factor, or null if none (default value of 1).
      offset - the offset, or null if none (default value of 0).
      Returns:
      a converter for the given scale and offset.

    • coefficients

      public static Number[] coefficients(UnitConverter converter)
      Returns the coefficients of the given converter expressed as a polynomial equation. This method returns the first of the following choices that apply:
      • If the given converter is identity, returns an empty array.
      • If the given converter shifts the values without scaling them (for example the conversion from Kelvin to Celsius degrees), returns an array of length 1 containing only the offset.
      • If the given converter scales the values (optionally in addition to shifting them), returns an array of length 2 containing the offset and scale factor, in that order.
      This method returns null if it cannot get the polynomial equation coefficients from the given converter.
      Parameters:
      converter - the converter from which to get the coefficients of the polynomial equation, or null.
      Returns:
      the polynomial equation coefficients (may be any length, including zero), or null if the given converter is null or if this method cannot get the coefficients.

    • derivative

      public static double derivative(UnitConverter converter, double value)
      Returns the derivative of the given converter at the given value, or NaN if this method cannot compute it.
      Parameters:
      converter - the converter for which we want the derivative at a given point, or null.
      value - the point at which to compute the derivative. Ignored (can be Double.NaN) if the conversion is linear.
      Returns:
      the derivative at the given point, or NaN if unknown.

    • valueOf

      public static Unit<?> valueOf(String uom) throws MeasurementParseException
      Parses the given symbol. Invoking this method is equivalent to invoking UnitFormat.parse(CharSequence) on a shared locale-independent instance. The list of symbols supported by this method is implementation-dependent and may change in future Seshat versions.

      Parsing authority codes

      If the given uom arguments is of the form "EPSG:####", "urn:ogc:def:uom:EPSG:####" or "http://www.opengis.net/def/uom/EPSG/0/####" (ignoring case and whitespaces around separators), then "####" is parsed as an integer and forwarded to the valueOfEPSG(int) method.

      Note on netCDF unit symbols

      In netCDF files, values of "unit" attribute are concatenations of an angular unit with an axis direction, as in "degrees_east" or "degrees_north". This valueOf(…) method ignores those suffixes and unconditionally returns DEGREE for all axis directions.
      Parameters:
      uom - the symbol to parse, or null.
      Returns:
      the parsed symbol, or null if uom was null.
      Throws:
      MeasurementParseException - if the given symbol cannot be parsed.
      See Also:

    • valueOfEPSG

      public static Unit<?> valueOfEPSG(int code)
      Returns a hard-coded unit from an EPSG code. The code argument given to this method shall be a code identifying a record in the "Unit of Measure" table of the EPSG geodetic dataset. If this method does not recognize the given code, then it returns null.

      The list of units recognized by this method is not exhaustive. This method recognizes the base units declared in the TARGET_UOM_CODE column of the above-cited table, and some frequently-used units. The list of recognized units may be updated in any future version of Seshat. The currently recognized values are:

      EPSG codes for units
      Angular units
      CodeUnit
      9101radian
      9102decimal degree
      9103minute
      9104second
      9105grad
      9107degree-minute-second
      9108degree-minute-second
      9109microradian
      9110sexagesimal degree-minute-second
      9111sexagesimal degree-minute
      9122decimal degree
      Linear units
      CodeUnit
      1025millimetre
      1033centimetre
      9001metre
      9002foot
      9003US survey foot
      9030nautical mile
      9036kilometre
      9093statute mile
      Time units
      CodeUnit
      1029year
      1040second
      Scale units
      CodeUnit
      9201unity
      9202parts per million
      9203unity
      Note: EPSG uses code 9102 (degree) for prime meridian and coordinate operation parameters, and code 9122 (degree (supplier to define representation)) for coordinate system axes. But Seshat considers those two codes as synonymous.
      Parameters:
      code - the EPSG code for a unit of measurement.
      Returns:
      the unit, or null if the code is unrecognized.
      Since:
      1.1

    • getEpsgCode

      public static OptionalInt getEpsgCode(Unit<?> unit)
      Returns the EPSG code of the given units, or empty if unknown. This method is the converse of valueOfEPSG(int).
      Parameters:
      unit - the unit for which to get the EPSG code.
      Returns:
      the EPSG code of the given units, or empty if unknown.
      Since:
      1.1