org.geotoolkit.measure
Class Units

Object
  Static
      Units

public final class Units
extends Static

A set of units to use in addition of SI and NonSI.

Since:

2.1

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

utility/geotk-utility (download)

View source code for this class

Field Summary

static Unit<Angle>	DEGREE_MINUTE_SECOND Pseudo-unit for degree - minute - second.
static Unit<Duration>	MILLISECOND Unit for milliseconds.
static Unit<Dimensionless>	PPM Parts per million.
static Unit<Angle>	SEXAGESIMAL_DMS Pseudo-unit for sexagesimal degree.

Method Summary

static double	derivative(UnitConverter converter, double value) Returns an estimation of the derivative of the given converter at the given value.
static Unit<Angle>	ensureAngular(Unit<?> unit) Makes sure that the specified unit is either null or an angular unit.
static Unit<Length>	ensureLinear(Unit<?> unit) Makes sure that the specified unit is either null or a linear unit.
static Unit<Dimensionless>	ensureScale(Unit<?> unit) Makes sure that the specified unit is either null or a scale unit.
static Unit<Duration>	ensureTemporal(Unit<?> unit) Makes sure that the specified unit is either null or a temporal unit.
static boolean	isAngular(Unit<?> unit) Returns true if the given unit is a linear unit.
static boolean	isLinear(Unit<?> unit) Returns true if the given unit is a linear unit.
static boolean	isScale(Unit<?> unit) Returns true if the given unit is a dimensionless scale unit.
static boolean	isTemporal(Unit<?> unit) Returns true if the given unit is a temporal unit.
static <A extends Quantity> Unit<A>	multiply(Unit<A> unit, double factor) Multiplies the given unit by the given factor.
static <A extends Quantity> double	toStandardUnit(Unit<A> unit) Returns the factor by which to multiply the standard unit in order to get the given unit.
static Unit<?>	valueOf(String uom) Parses the given symbol.
static Unit<?>	valueOfEPSG(int code) Returns a hard-coded unit from an EPSG code.

Methods inherited from class Object

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

Field Detail

MILLISECOND

public static final Unit<Duration> MILLISECOND

Unit for milliseconds. Useful for conversion from and to Date objects.

SEXAGESIMAL_DMS

public static final Unit<Angle> SEXAGESIMAL_DMS

Pseudo-unit for sexagesimal degree. Numbers in this pseudo-unit has the following format: sign - degrees - decimal point - minutes (two digits) - integer seconds (two digits) - fraction of seconds (any precision).

This unit is non-linear and not practical for computation. Consequently, it should be avoid as much as possible. Unfortunately, this pseudo-unit is extensively used in the EPSG database (code 9110).

TODO:

JSR-275 bug

DEGREE_MINUTE_SECOND

public static final Unit<Angle> DEGREE_MINUTE_SECOND

Pseudo-unit for degree - minute - second. Numbers in this pseudo-unit has the following format: signed degrees (integer) - arc-minutes (integer) - arc-seconds (real, any precision).

This unit is non-linear and not practical for computation. Consequently, it should be avoid as much as possible. Unfortunately, this pseudo-unit is extensively used in the EPSG database (code 9107).

TODO:

JSR-275 bug

PPM

public static final Unit<Dimensionless> PPM

Parts per million.

TODO:

JSR-275 bug

Method Detail

isTemporal

public static boolean isTemporal(Unit<?> unit)

Returns true if the given unit is a temporal unit. Temporal units are convertible to SI.SECOND.

Parameters:

unit - The unit to check (may be null).

Returns:

true if the given unit is non-null and temporal.

Since:

3.00

See Also:

ensureTemporal(Unit)

isLinear

public static boolean isLinear(Unit<?> unit)

Returns true if the given unit is a linear unit. Linear units are convertible to SI.METRE.

Parameters:

unit - The unit to check (may be null).

Returns:

true if the given unit is non-null and linear.

Since:

3.00

See Also:

ensureLinear(Unit)

isAngular

public static boolean isAngular(Unit<?> unit)

Returns true if the given unit is a linear unit. Linear units are convertible to NonSI.DEGREE_ANGLE.

Angular units are dimensionless, which may be a cause of confusion with other dimensionless units like Unit.ONE 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.

Since:

3.00

See Also:

ensureAngular(Unit)

isScale

public static boolean isScale(Unit<?> unit)

Returns true if the given unit is a dimensionless scale unit. This include Unit.ONE and PPM.

Parameters:

unit - The unit to check (may be null).

Returns:

true if the given unit is non-null and a dimensionless scale.

Since:

3.00

See Also:

ensureScale(Unit)

ensureTemporal

public static Unit<Duration> 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.

Since:

3.17

See Also:

isTemporal(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:

IllegalArgumentException - if unit is non-null and not a linear unit.

Since:

3.17

See Also:

isLinear(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:

IllegalArgumentException - if unit is non-null and not an angular unit.

Since:

3.17

See Also:

isAngular(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:

IllegalArgumentException - if unit is non-null and not a scale unit.

Since:

3.17

See Also:

isScale(Unit)

multiply

public static <A extends Quantity> Unit<A> multiply(Unit<A> unit,
                                                    double factor)

Multiplies the given unit by the given factor. For example multiplying SI.METRE by 1000 gives SI.KILOMETRE. Invoking this method is equivalent to invoking Unit.times(double) except for the following:

• A small tolerance factor is applied for a few factors commonly used in GIS. For example multiply(SI.RADIANS, 0.0174532925199...) will return NonSI.DEGREE_ANGLE even if the given numerical value is slightly different than pi/180. The tolerance factor and the set of units handled especially may change in future Geotk versions.
• This method tries to returns unique instances for some common units.

Type Parameters:

A - The quantity measured by the unit.

Parameters:

unit - The unit to multiply.

factor - The multiplication factor.

Returns:

The unit multiplied by the given factor.

Since:

3.07

toStandardUnit

public static <A extends Quantity> double toStandardUnit(Unit<A> 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.

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 metres).

Type Parameters:

A - The quantity measured by the unit.

Parameters:

unit - The unit for which we want the multiplication factor to standard unit.

Returns:

The factor by which to multiply a measurement in the given unit in order to get an equivalent measurement in the standard unit.

Since:

3.07

derivative

public static double derivative(UnitConverter converter,
                                double value)

Returns an estimation of the derivative of the given converter at the given value. This method is a workaround for a method which existed in previous JSR-275 API but have been removed in more recent releases. This method will be deprecated in the removed API is reinserted in future JSR-275 release.

Current implementation computes the derivative as below:

return converter.convert(value + 1) - converter.convert(value);

The above is exact for linear converters, which is the case of the vast majority of unit converters in use. It may not be exact for a few unusual converter like the one from SEXAGESIMAL_DMS to decimal degrees for example.

Parameters:

converter - The converter for which we want the derivative at a given point.

value - The point at which to compute the derivative.

Returns:

The derivative at the given point.

Since:

3.07

valueOf

public static Unit<?> valueOf(String uom)
                       throws IllegalArgumentException

Parses the given symbol. This method is similar to Unit.valueOf(CharSequence), but hands especially a few symbols found in WKT parsing or in XML files. The list of symbols handled especially is implementation-dependent and may change in future Geotk versions.

Parsing authority codes
As a special case, if the given uom arguments is of the form "EPSG:xxx" (ignoring case and whitespaces), then "xxx" is parsed as an integer and given to valueOfEPSG(int).

Parameters:

uom - The symbol to parse, or null.

Returns:

The parsed symbol, or null if uom was null.

Throws:

IllegalArgumentException - if the given symbol can not be parsed.

Since:

3.07

TODO:

The org.geotoolkit.image.io.plugin.NetcdfMetadataTranscoder class needs that we parse the "degrees_west" symbol in such a way that the conversion from "degrees_west" to "degrees_east" reverse the sign of the values. This is not yet supported by current implementation.

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 database. 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 Geotk.

The DirectEpsgFactory 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 code not directly related to the EPSG database, like AutoCRSFactory which uses EPSG code for identifying units.

The values currently recognized are:

Linear units

Angular units

Scale units

Code	Unit
9001	metre
9002	foot
9030	nautical mile
9036	kilometre

Code	Unit
9101	radian
9102	decimal degree
9103	minute
9104	second
9105	grade
9107	degree-minute-second
9108	degree-minute-second
9109	microradian
9110	sexagesimal degree-minute-second
9122	decimal degree

Code	Unit
9201	one
9202	part per million
9203	one

Parameters:

code - The EPSG code for a unit of measurement.

Returns:

The unit, or null if the code is unrecognized.

Since:

3.09