org.apache.sis.referencing

Class CRS

Object

Static

CRS

public final class CRS
extends Static

Static methods working on Coordinate Reference Systems. The methods defined in this class can be grouped in two categories:

• Factory methods, the most notable one being forCode(String).
• Methods providing information, like isHorizontalCRS(CoordinateReferenceSystem).

Note on kinds of CRS

The getSingleComponents(CoordinateReferenceSystem) method decomposes an arbitrary CRS into a flat list of single components. In such flat list, vertical and temporal components can easily be identified by instanceof checks. But identifying the horizontal component is not as easy. The list below suggests ways to classify the components:

• if (crs instanceof TemporalCRS) determines if the CRS is for the temporal component.
• if (crs instanceof VerticalCRS) determines if the CRS is for the vertical component.
• if (CRS.isHorizontalCRS(crs)) determines if the CRS is for the horizontal component.

Since:

0.3

Defined in the sis-referencing module

Method Summary

Methods

Modifier and Type	Method and Description
static CoordinateReferenceSystem	forCode(String code) Returns the Coordinate Reference System for the given authority code.
static CoordinateReferenceSystem	fromWKT(String text) Creates a Coordinate Reference System object from a Well Known Text (WKT).
static CoordinateReferenceSystem	getComponentAt(CoordinateReferenceSystem crs, int lower, int upper) Returns the coordinate reference system in the given range of dimension indices.
static GeographicBoundingBox	getGeographicBoundingBox(CoordinateReferenceSystem crs) Returns the valid geographic area for the given coordinate reference system, or null if unknown.
static double	getGreenwichLongitude(GeodeticCRS crs) Returns the Greenwich longitude of the prime meridian of the given CRS in degrees.
static SingleCRS	getHorizontalComponent(CoordinateReferenceSystem crs) Returns the first horizontal coordinate reference system found in the given CRS, or null if there is none.
static List<SingleCRS>	getSingleComponents(CoordinateReferenceSystem crs) Returns the ordered list of single coordinate reference systems for the specified CRS.
static TemporalCRS	getTemporalComponent(CoordinateReferenceSystem crs) Returns the first temporal coordinate reference system found in the given CRS, or null if there is none.
static VerticalCRS	getVerticalComponent(CoordinateReferenceSystem crs, boolean allowCreateEllipsoidal) Returns the first vertical coordinate reference system found in the given CRS, or null if there is none.
static boolean	isHorizontalCRS(CoordinateReferenceSystem crs) Returns true if the given CRS is horizontal.

Methods inherited from class Object

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

Method Detail

forCode

public static CoordinateReferenceSystem forCode(String code)
                                         throws NoSuchAuthorityCodeException,
                                                FactoryException

Returns the Coordinate Reference System for the given authority code. The set of available codes depends on the CRSAuthorityFactory instances available on the classpath. There is many thousands of CRS defined by EPSG authority or by other authorities. The following table lists a very small subset of codes which are guaranteed to be available on any installation of Apache SIS version 0.4 or above:

Minimal set of supported authority codes

Code	Enum	CRS Type	Description
CRS:27	NAD27	Geographic	Like EPSG:4267 except for (longitude, latitude) axis order
CRS:83	NAD83	Geographic	Like EPSG:4269 except for (longitude, latitude) axis order
CRS:84	WGS84	Geographic	Like EPSG:4326 except for (longitude, latitude) axis order
EPSG:4047	SPHERE	Geographic	GRS 1980 Authalic Sphere
EPSG:4230	ED50	Geographic	European Datum 1950
EPSG:4258	ETRS89	Geographic	European Terrestrial Reference Frame 1989
EPSG:4267	NAD27	Geographic	North American Datum 1927
EPSG:4269	NAD83	Geographic	North American Datum 1983
EPSG:4322	WGS72	Geographic	World Geodetic System 1972
EPSG:4326	WGS84	Geographic	World Geodetic System 1984
EPSG:4936	ETRS89	Geocentric	European Terrestrial Reference Frame 1989
EPSG:4937	ETRS89	Geographic 3D	European Terrestrial Reference Frame 1989
EPSG:4978	WGS84	Geocentric	World Geodetic System 1984
EPSG:4979	WGS84	Geographic 3D	World Geodetic System 1984
EPSG:4984	WGS72	Geocentric	World Geodetic System 1972
EPSG:4985	WGS72	Geographic 3D	World Geodetic System 1972
EPSG:5715	DEPTH	Vertical	Mean Sea Level depth
EPSG:5714	MEAN_SEA_LEVEL	Vertical	Mean Sea Level height

This method accepts also the URN and URL syntax. For example the following codes are considered equivalent to "EPSG:4326":

• "urn:ogc:def:crs:EPSG::4326"
• "http://www.opengis.net/gml/srs/epsg.xml#4326"

Parameters:

code - The authority code.

Returns:

The Coordinate Reference System for the given authority code.

Throws:

NoSuchAuthorityCodeException - If there is no known CRS associated to the given code.

FactoryException - if the CRS creation failed for an other reason.

fromWKT

public static CoordinateReferenceSystem fromWKT(String text)
                                         throws FactoryException

Creates a Coordinate Reference System object from a Well Known Text (WKT). The default Apache SIS parser understands both version 1 (a.k.a. OGC 01-009) and version 2 (a.k.a. ISO 19162) of the WKT format.

Example: below is a slightly simplified WKT 2 string for a Mercator projection. For making this example smaller, some optional UNIT[…] and ORDER[…] elements have been omitted.

ProjectedCRS["SIRGAS 2000 / Brazil Mercator",
  BaseGeodCRS["SIRGAS 2000",
    Datum["Sistema de Referencia Geocentrico para las Americas 2000",
      Ellipsoid["GRS 1980", 6378137, 298.257222101]]],
  Conversion["Petrobras Mercator",
    Method["Mercator (variant B)", Id["EPSG",9805]],
    Parameter["Latitude of 1st standard parallel", -2],
    Parameter["Longitude of natural origin", -43],
    Parameter["False easting", 5000000],
    Parameter["False northing", 10000000]],
  CS[cartesian,2],
    Axis["easting (E)", east],
    Axis["northing (N)", north],
    LengthUnit["metre", 1],
  Id["EPSG",5641]]

Usage and performance considerations

This convenience method delegates to GeodeticObjectFactory.createFromWKT(String) using a default factory instance. This is okay for occasional use, but has the following limitations:

• Performance may be sub-optimal in a multi-thread environment.
• No control on the WKT conventions in use.
• No control on the handling of warnings.

Applications which need to parse a large amount of WKT strings should consider to use the WKTFormat class instead than this method.

Parameters:

text - Coordinate system encoded in Well-Known Text format (version 1 or 2).

Returns:

The parsed Coordinate Reference System.

Throws:

FactoryException - if the given WKT can not be parsed.

Since:

0.6

See Also:

org.apache.sis.io.wkt, Envelopes.fromWKT(CharSequence), WKT 2 specification

getGeographicBoundingBox

public static GeographicBoundingBox getGeographicBoundingBox(CoordinateReferenceSystem crs)

Returns the valid geographic area for the given coordinate reference system, or null if unknown. This method explores the domain of validity associated with the given CRS. If more than one geographic bounding box is found, then they will be added together.

Parameters:

crs - The coordinate reference system, or null.

Returns:

The geographic area, or null if none.

See Also:

#getEnvelope(CoordinateReferenceSystem), Extents.getGeographicBoundingBox(Extent)

isHorizontalCRS

public static boolean isHorizontalCRS(CoordinateReferenceSystem crs)

Returns true if the given CRS is horizontal. The current implementation considers a CRS as horizontal if it is two-dimensional and comply with one of the following conditions:

• is an instance of GeographicCRS, or
• is an instance of ProjectedCRS, or
• is an instance of EngineeringCRS (following ISO 19162 §16.1 definition of <horizontal crs>).

In case of doubt, this method conservatively returns false.

Parameters:

crs - The coordinate reference system, or null.

Returns:

true if the given CRS is non-null and likely horizontal, or false otherwise.

See Also:

getHorizontalComponent(CoordinateReferenceSystem)

TODO:

Future SIS implementation may extend the above conditions list. For example a radar station could use a polar coordinate system in a DerivedCRS instance based on a projected CRS. Conversely, a future SIS versions may impose more conditions on EngineeringCRS. See SIS-161.

getHorizontalComponent

public static SingleCRS getHorizontalComponent(CoordinateReferenceSystem crs)

Returns the first horizontal coordinate reference system found in the given CRS, or null if there is none. If the given CRS is already horizontal according isHorizontalCRS(CoordinateReferenceSystem), then this method returns it as-is. Otherwise if the given CRS is compound, then this method searches for the first horizontal component in the order of the single components list.

In the special case where a three-dimensional geographic CRS is found, this method will create a two-dimensional geographic CRS without the vertical axis.

Parameters:

crs - The coordinate reference system, or null.

Returns:

The first horizontal CRS, or null if none.

getVerticalComponent

public static VerticalCRS getVerticalComponent(CoordinateReferenceSystem crs,
                               boolean allowCreateEllipsoidal)

Returns the first vertical coordinate reference system found in the given CRS, or null if there is none. If the given CRS is already an instance of VerticalCRS, then this method returns it as-is. Otherwise if the given CRS is compound, then this method searches for the first vertical component in the order of the single components list.

Height in a three-dimensional geographic CRS

In ISO 19111 model, ellipsoidal heights are indissociable from geographic CRS because such heights without their (latitude, longitude) locations make little sense. Consequently a standard-conformant library should return null when asked for the VerticalCRS component of a geographic CRS. This is what getVerticalComponent(…) does when the allowCreateEllipsoidal argument is false.

However in some exceptional cases, handling ellipsoidal heights like any other kind of heights may simplify the task. For example when computing difference between heights above the same datum, the impact of ignoring locations may be smaller (but not necessarily canceled). Orphan VerticalCRS may also be useful for information purpose like labeling a plot axis. If the caller feels confident that ellipsoidal heights are safe for his task, he can set the allowCreateEllipsoidal argument to true. In such case, this getVerticalComponent(…) method will create a temporary VerticalCRS from the first three-dimensional GeographicCRS in last resort, only if it can not find an existing VerticalCRS instance. Note that this is not a valid CRS according ISO 19111 — use with care.

Parameters:

crs - The coordinate reference system, or null.

allowCreateEllipsoidal - true for allowing the creation of orphan CRS for ellipsoidal heights. The recommended value is false.

Returns:

The first vertical CRS, or null if none.

getTemporalComponent

public static TemporalCRS getTemporalComponent(CoordinateReferenceSystem crs)

Returns the first temporal coordinate reference system found in the given CRS, or null if there is none. If the given CRS is already an instance of TemporalCRS, then this method returns it as-is. Otherwise if the given CRS is compound, then this method searches for the first temporal component in the order of the single components list.

Parameters:

crs - The coordinate reference system, or null.

Returns:

The first temporal CRS, or null if none.

getSingleComponents

public static List<SingleCRS> getSingleComponents(CoordinateReferenceSystem crs)

Returns the ordered list of single coordinate reference systems for the specified CRS. This method performs the following choices:

• If the given CRS is null, returns an empty list.
• If the given CRS is an instance of SingleCRS, returns that instance in a singleton list.
• If the given CRS is an instance of CompoundCRS, returns a flattened list of its components. Some components may themselves be other CompoundCRS instances, in which case those compound CRS are also expanded in their list of SingleCRS components.
• Otherwise throws a ClassCastException.

Example: Apache SIS allows 4-dimensional (x,y,z,t) coordinate reference system to be built in two different ways as shown below:

Hierarchical structure	Flat list
CompoundCRS — (x, y, z, t) ├─CompoundCRS — (x, y, z) │ ├─ProjectedCRS — (x, y) │ └─VerticalCRS — (z) └─TemporalCRS — (t)	CompoundCRS — (x, y, z, t) ├─ProjectedCRS — (x, y) ├─VerticalCRS — (z) └─TemporalCRS — (t)

This method guaranteed that the returned list is a flat one as shown on the right side. Note that such flat lists are the only one allowed by ISO/OGC standards for compound CRS. The hierarchical structure is an Apache SIS flexibility.

Parameters:

crs - The coordinate reference system, or null.

Returns:

The single coordinate reference systems, or an empty list if the given CRS is null.

Throws:

ClassCastException - if a CRS is neither a SingleCRS or a CompoundCRS.

See Also:

DefaultCompoundCRS.getSingleComponents()

getComponentAt

public static CoordinateReferenceSystem getComponentAt(CoordinateReferenceSystem crs,
                                       int lower,
                                       int upper)

Returns the coordinate reference system in the given range of dimension indices. This method processes as below:

• If the given crs is null, then this method returns null.
• Otherwise if lower is 0 and upper is the number of CRS dimensions, then this method returns the given CRS unchanged.
• Otherwise if the given CRS is an instance of CompoundCRS, then this method searches for a component where:
  • The number of dimensions is equals to upper - lower;
  • The sum of the number of dimensions of all previous CRS is equals to lower.
  If such component is found, then it is returned.
• Otherwise (i.e. no component match), this method returns null.

This method does not attempt to build new CRS from the components. For example it does not attempt to create a 3D geographic CRS from a 2D one + a vertical component.

Parameters:

crs - The coordinate reference system to decompose, or null.

lower - The first dimension to keep, inclusive.

upper - The last dimension to keep, exclusive.

Returns:

The sub-coordinate system, or null if the given crs was null or can not be decomposed for dimensions in the [lower … upper] range.

Throws:

IndexOutOfBoundsException - If the given index are out of bounds.

Since:

0.5

See Also:

GeneralEnvelope.subEnvelope(int, int)

getGreenwichLongitude

public static double getGreenwichLongitude(GeodeticCRS crs)

Returns the Greenwich longitude of the prime meridian of the given CRS in degrees. If the prime meridian uses an other unit than degrees, then the value will be converted.

Parameters:

crs - The coordinate reference system from which to get the prime meridian.

Returns:

The Greenwich longitude (in degrees) of the prime meridian of the given CRS.

Since:

0.5

See Also:

DefaultPrimeMeridian.getGreenwichLongitude(Unit)