Class Units

    • Method Detail

      • 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:
        ensure­Angular(Unit)
      • 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:
        METRE, ensure­Linear(Unit)
      • 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 sometime 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:
        ensure­Temporal(Unit)
      • 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:
        UNITY, ensure­Scale(Unit)
      • 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:
        Illegal­Argument­Exception - if unit is non-null and not an angular unit.
        See Also:
        is­Angular(Unit)
      • 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:
        Illegal­Argument­Exception - if unit is non-null and not a linear unit.
        See Also:
        is­Linear(Unit)
      • 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:
        Illegal­Argument­Exception - if unit is non-null and not a temporal unit.
        See Also:
        is­Temporal(Unit)
      • 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:
        Illegal­Argument­Exception - if unit is non-null and not a scale unit.
        See Also:
        is­Scale(Unit)
      • 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 Apache SIS 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.
        Since:
        0.8
      • 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​.get­System­Unit().
        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 can not be expressed by a single multiplication factor, then this method returns Double​.Na­N.
        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 can not 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.
        Since:
        1.0
        See Also:
        Math­Transforms​.linear(double, double)
      • 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 can not 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 can not get the coefficients.
        Since:
        0.8
      • derivative

        public static double derivative​(UnitConverter converter,
                                        double value)
        Returns the derivative of the given converter at the given value, or Na­N if this method can not 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.
        Returns:
        the derivative at the given point, or Na­N if unknown.
        See Also:
        Abstract­Math­Transform​.derivative(Direct­Position)
      • valueOf

        public static Unit<?> valueOf​(String uom)
                               throws ParserException
        Parses the given symbol. Invoking this method is equivalent to invoking Unit­Format​.parse(Char­Sequence) on a shared locale-independent instance. This method is capable to handle some symbols found during WKT parsing or in XML files. The list of symbols supported by this method is implementation-dependent and may change in future SIS versions.
        Parsing authority codes
        As a special case, if the given uom arguments is of the form "EPSG:####" or "urn:ogc:def:uom:EPSG:####" (ignoring case and whitespaces), then "####" is parsed as an integer and forwarded to the value­Of­EPSG(int) method.
        NetCDF unit symbols
        The attributes in netCDF files often merge the axis direction with the angular unit, as in "degrees_east" or "degrees_north". This value­Of method ignores those suffixes and unconditionally returns DEGREE for all axis directions. In particular, the units for "degrees_west" and "degrees_east" do not have opposite sign. It is caller responsibility to handle the direction of axes associated to netCDF units.
        Parameters:
        uom - the symbol to parse, or null.
        Returns:
        the parsed symbol, or null if uom was null.
        Throws:
        Parser­Exception - if the given symbol can not be parsed.
        See Also:
        Unit­Format​.parse(Char­Sequence)
      • 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 SIS.

        The EPSGData­Access class uses this method for fetching the base units, and derives automatically other units from the information found in the EPSG database. This method is also used by other classes not directly related to the EPSG database, like Common­Authority­Factory which uses EPSG codes for identifying units.

        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 Apache SIS 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.
        See Also:
        Geodetic­Authority­Factory​.create­Unit(String)
      • getEpsgCode

        public static Integer getEpsgCode​(Unit<?> unit,
                                          boolean inAxis)
        Returns the EPSG code of the given units, or null if unknown. This method is the converse of value­Of­EPSG(int).

        The same unit may be represented by different EPSG codes depending on the context:

        • EPSG:9102 – degree – is used for prime meridian and coordinate operation parameters.
        • EPSG:9122 – degree (supplier to define representation) – is used for coordinate system axes.
        When such choice exists, the code to return is determined by the in­Axis argument, which specifies whether the code will be used for axis definition or in other context.
        Parameters:
        unit - the unit for which to get the EPSG code.
        in­Axis - true for a unit used in Coordinate System Axis definition.
        Returns:
        the EPSG code of the given units, or null if unknown.
        Since:
        0.4
        See Also:
        Coordinate­Systems​.get­Epsg­Code(Unit, Axis­Direction...)