public final class CRS extends Static
forCode(String)
.isHorizontalCRS(CoordinateReferenceSystem)
.forCode(…)
, fromWKT(…)
and findOperation(…)
. An usage example is like below
(see the Apache SIS™ Coordinate
Reference System (CRS) codes page for the complete list of EPSG codes):
CoordinateReferenceSystem source = CRS.forCode("EPSG:4326"); // WGS 84 CoordinateReferenceSystem target = CRS.forCode("EPSG:3395"); // WGS 84 / World Mercator CoordinateOperation operation = CRS.findOperation(source, target, null); if (CRS.getLinearAccuracy(operation) > 100) { // If the accuracy is coarser than 100 metres (or any other threshold at application choice) // maybe the operation is not suitable. Decide here what to do (throw an exception, etc). } MathTransform mt = operation.getMathTransform(); DirectPosition position = new DirectPosition2D(20, 30); // 20°N 30°E (watch out axis order!) position = mt.transform(position, position); System.out.println(position);
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.Defined in the sis-referencing
module
Modifier and Type | Method and Description |
---|---|
static CoordinateReferenceSystem |
compound(CoordinateReferenceSystem... components)
Creates a compound coordinate reference system from an ordered list of CRS components.
|
static CoordinateOperation |
findOperation(CoordinateReferenceSystem sourceCRS,
CoordinateReferenceSystem targetCRS,
GeographicBoundingBox areaOfInterest)
Finds a mathematical operation that transforms or converts coordinates from the given source to the
given target coordinate reference system.
|
static CoordinateReferenceSystem |
forCode(String code)
Returns the Coordinate Reference System for the given authority code.
|
static CoordinateReferenceSystem |
fromAuthority(CoordinateReferenceSystem crs,
CRSAuthorityFactory factory,
WarningListener<?> listener)
Replaces the given coordinate reference system by an authoritative description, if one can be found.
|
static CoordinateReferenceSystem |
fromWKT(String text)
Creates a Coordinate Reference System object from a Well Known Text (WKT).
|
static CoordinateReferenceSystem |
fromXML(String xml)
Creates a coordinate reference system object from a XML string.
|
static CRSAuthorityFactory |
getAuthorityFactory(String authority)
Returns the system-wide authority factory used by
forCode(String) and other SIS methods. |
static CoordinateReferenceSystem |
getComponentAt(CoordinateReferenceSystem crs,
int lower,
int upper)
Returns the coordinate reference system in the given range of dimension indices.
|
static Envelope |
getDomainOfValidity(CoordinateReferenceSystem crs)
Returns the domain of validity of the specified coordinate reference system, or
null if unknown. |
static GeographicBoundingBox |
getGeographicBoundingBox(CoordinateOperation operation)
Returns the valid geographic area for the given coordinate operation, or
null if unknown. |
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 double |
getLinearAccuracy(CoordinateOperation operation)
Returns a positional accuracy estimation in metres for the given operation, or
NaN if unknown. |
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. |
static CoordinateReferenceSystem |
suggestCommonTarget(GeographicBoundingBox regionOfInterest,
CoordinateReferenceSystem... sourceCRS)
Suggests a coordinate reference system which could be a common target for coordinate operations having the
given sources.
|
public static CoordinateReferenceSystem forCode(String code) throws NoSuchAuthorityCodeException, FactoryException
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:
This method accepts also the URN and URL syntaxes. For example the following codes are considered equivalent to
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:5041 WGS84
Projected WGS 84 / UPS North (E,N) EPSG:5042 WGS84
Projected WGS 84 / UPS South (E,N) EPSG:322## WGS72
Projected WGS 72 / UTM zone ##N EPSG:323## WGS72
Projected WGS 72 / UTM zone ##S EPSG:326## WGS84
Projected WGS 84 / UTM zone ##N EPSG:327## WGS84
Projected WGS 84 / UTM zone ##S EPSG:5715 DEPTH
Vertical Mean Sea Level depth EPSG:5714 MEAN_SEA_LEVEL
Vertical Mean Sea Level height
"EPSG:4326"
:
"EPSG::4326"
"urn:ogc:def:crs:EPSG::4326"
"http://www.opengis.net/def/crs/epsg/0/4326"
"http://www.opengis.net/gml/srs/epsg.xml#4326"
"urn:ogc:def:crs,crs:EPSG::4326,crs:EPSG::5714"
"http://www.opengis.net/def/crs-compound?
1=http://www.opengis.net/def/crs/epsg/0/4326&
2=http://www.opengis.net/def/crs/epsg/0/5714"
URNs (but not URLs) can also combine a geodetic datum with an ellipsoidal coordinate system for creating a new geographic CRS, or a base geographic CRS with a conversion and a Cartesian coordinate system for creating a new projected coordinate reference system.
Note that theIdentifiedObjects.lookupURN(IdentifiedObject, Citation)
method can be seen as a converse of this method.
More codes may also be supported depending on which extension modules are available.
See for example the bindings to Proj.4 library.code
- the authority code.NoSuchAuthorityCodeException
- if there is no known CRS associated to the given code.FactoryException
- if the CRS creation failed for an other reason.getAuthorityFactory(String)
,
GeodeticAuthorityFactory
,
EPSG Geodetic Registrypublic static CoordinateReferenceSystem fromWKT(String text) throws FactoryException
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]]
"org.apache.sis.io.wkt"
.
In particular, this method verifies if the description provided by the WKT matches the description provided
by the authority ("EPSG:5641"
in above example) and reports discrepancies.
Note that this comparison between parsed CRS and authoritative CRS is specific to this convenience method;
other APIs documented in see also section do not perform this comparison automatically.
Should the WKT description and the authoritative description be in conflict, the WKT description prevails
as mandated by ISO 19162 standard (see fromAuthority(…)
if a different behavior is needed).
GeodeticObjectFactory.createFromWKT(String)
using a default factory instance. This is okay for occasional use, but has the following limitations:
WKTFormat
class instead than this method.text
- coordinate system encoded in Well-Known Text format (version 1 or 2).FactoryException
- if the given WKT can not be parsed.WKTFormat
,
GeodeticObjectFactory.createFromWKT(String)
,
Envelopes.fromWKT(CharSequence)
,
WKT 2 specificationpublic static CoordinateReferenceSystem fromXML(String xml) throws FactoryException
XML
class.
If the unmarshalling produced warnings, they will be reported in a logger named "org.apache.sis.xml"
.
In particular, this method verifies if the description provided by the XML matches the description provided by
the authority code given in <gml:identifier>
element, and reports discrepancies.
Note that this comparison between unmarshalled CRS and authoritative CRS is specific to this convenience method;
other APIs documented in see also section do not perform this comparison automatically.
Should the XML description and the authoritative description be in conflict, the XML description prevails
(see fromAuthority(…)
if a different behavior is needed).
xml
- coordinate reference system encoded in XML format.FactoryException
- if the object creation failed.GeodeticObjectFactory.createFromXML(String)
,
XML.unmarshal(String)
public static CoordinateReferenceSystem fromAuthority(CoordinateReferenceSystem crs, CRSAuthorityFactory factory, WarningListener<?> listener) throws FactoryException
In such cases, Apache SIS behavior inPROJCS["WGS 84 / Pseudo-Mercator",
(…base CRS omitted for brevity…)
PROJECTION["Mercator (variant A)"],
— wrong: shall be "Popular Visualisation Pseudo Mercator"
(…parameters and axes omitted for brevity…)
AUTHORITY["EPSG", "3857"]]
fromWKT(String)
, fromXML(String)
and other methods is
conform to the ISO 19162 specification:
"Should any attributes or values given in the cited identifier be in conflict with attributes or values given explicitly in the WKT description, the WKT values shall prevail."In situations where the opposite behavior is desired (i.e. to make the authority identifier prevails), this method can be invoked. This method performs the following actions:
fromWKT(String)
and fromXML(String)
, so the warnings
argument should be null
when fromAuthority(…)
is invoked for the CRS parsed by one of above-mentioned methods.
A non-null warnings
argument is more useful for CRS parsed by WKTFormat
or XML.unmarshal(String)
for instance.crs
- the CRS to replace by an authoritative CRS, or null
.factory
- the factory where to search for authoritative definitions, or null
for the default.listener
- where to send warnings, or null
for ignoring warnings.crs
argument itself), or null
if the given CRS was null.FactoryException
- if an error occurred while querying the authority factory.public static CoordinateReferenceSystem suggestCommonTarget(GeographicBoundingBox regionOfInterest, CoordinateReferenceSystem... sourceCRS)
null
.
suggestCommonTarget(…)
method can used
for choosing a common CRS which is less likely to fail.regionOfInterest
- the geographic area for which the coordinate operations will be applied,
or null
if unknown.sourceCRS
- the coordinate reference systems for which a common target CRS is desired.null
if this method did not find a common target CRS. The returned CRS may be different than
all given CRS.public static CoordinateOperation findOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, GeographicBoundingBox areaOfInterest) throws FactoryException
CoordinateOperationContext
.CoordinateOperation
instance, the following methods can be invoked
for checking if the operation suits the caller's needs:
getGeographicBoundingBox(CoordinateOperation)
for checking if the operation is valid in the caller's area of interest.getLinearAccuracy(CoordinateOperation)
for checking if the operation has sufficient accuracy for caller's purpose.OperationNotFoundException
.sourceCRS
- the CRS of source coordinates.targetCRS
- the CRS of target coordinates.areaOfInterest
- the area of interest, or null
if none.sourceCRS
to targetCRS
.OperationNotFoundException
- if no operation was found between the given pair of CRS.FactoryException
- if the operation can not be created for another reason.DefaultCoordinateOperationFactory.createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, CoordinateOperationContext)
public static double getLinearAccuracy(CoordinateOperation operation)
NaN
if unknown.
This method applies the following heuristics:
AbstractCoordinateOperation
, then delegate to the
operation getLinearAccuracy()
method.AbstractCoordinateOperation.getLinearAccuracy()
for more details on the above heuristic rules.operation
- the coordinate operation for which to get the accuracy estimation, or null
.findOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, GeographicBoundingBox)
public static GeographicBoundingBox getGeographicBoundingBox(CoordinateOperation operation)
null
if unknown.
This method explores the domain of validity
associated with the given operation. If more than one geographic bounding box is found, then this method
computes their union.
Fallback: if the given operation does not declare explicitely a domain of validity, then this
method computes the intersection of the domain of validity declared by source and target CRS. If no CRS
declare a domain of validity, then this method returns null
.
operation
- the coordinate operation for which to get the domain of validity, or null
.null
if unspecified.findOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, GeographicBoundingBox)
,
Extents.getGeographicBoundingBox(Extent)
public static GeographicBoundingBox getGeographicBoundingBox(CoordinateReferenceSystem crs)
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 this method
computes their union.
together.crs
- the coordinate reference system for which to get the domain of validity, or null
.null
if unspecified.getDomainOfValidity(CoordinateReferenceSystem)
,
Extents.getGeographicBoundingBox(Extent)
public static Envelope getDomainOfValidity(CoordinateReferenceSystem crs)
null
if unknown.
If non-null, then the returned envelope will use the same coordinate reference system them the given CRS
argument.crs
- the coordinate reference system, or null
.null
if none.getGeographicBoundingBox(CoordinateReferenceSystem)
public static CoordinateReferenceSystem compound(CoordinateReferenceSystem... components) throws FactoryException
getVerticalComponent(crs, true)
.
GeographicCRS
or ProjectedCRS
or EngineeringCRS
).VerticalCRS
or a ParametricCRS
(but not both).TemporalCRS
.components
- the sequence of coordinate reference systems making the compound CRS.components[0]
if the given array contains only one component.IllegalArgumentException
- if the given array is empty or if the array contains incompatible components.FactoryException
- if the geodetic factory failed to create the compound CRS.GeodeticObjectFactory.createCompoundCRS(Map, CoordinateReferenceSystem...)
public static boolean isHorizontalCRS(CoordinateReferenceSystem crs)
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:
GeographicCRS
(or an equivalent GeodeticCRS
), orProjectedCRS
, orEngineeringCRS
(following
ISO 19162 §16.1
definition of <horizontal crs>).false
.crs
- the coordinate reference system, or null
.true
if the given CRS is non-null and likely horizontal, or false
otherwise.getHorizontalComponent(CoordinateReferenceSystem)
DerivedCRS
instance based on a projected CRS.
Conversely, a future SIS versions may impose more conditions on EngineeringCRS
.
See SIS-161.public static SingleCRS getHorizontalComponent(CoordinateReferenceSystem crs)
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 or projected CRS is found, this method will create a two-dimensional geographic or projected CRS without the vertical axis.
crs
- the coordinate reference system, or null
.null
if none.public static VerticalCRS getVerticalComponent(CoordinateReferenceSystem crs, boolean allowCreateEllipsoidal)
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.
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.
crs
- the coordinate reference system, or null
.allowCreateEllipsoidal
- true
for allowing the creation of orphan CRS for ellipsoidal heights.
The recommended value is false
.null
if none.compound(CoordinateReferenceSystem...)
public static TemporalCRS getTemporalComponent(CoordinateReferenceSystem crs)
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.crs
- the coordinate reference system, or null
.null
if none.public static List<SingleCRS> getSingleComponents(CoordinateReferenceSystem crs)
SingleCRS
, returns that instance in a singleton list.CompoundCRS
, returns a flattened list of its
components. Some components may themselves be
other CompoundCRS
instances, in which case those compound CRS are also flattened in their
list of SingleCRS
components.ClassCastException
.Hierarchical structure | Flat list |
---|---|
|
|
crs
- the coordinate reference system, or null
.null
.ClassCastException
- if a CRS is neither a SingleCRS
or a CompoundCRS
.DefaultCompoundCRS.getSingleComponents()
public static CoordinateReferenceSystem getComponentAt(CoordinateReferenceSystem crs, int lower, int upper)
crs
is null
, then this method returns null
.lower
is 0 and upper
is the number of CRS dimensions,
then this method returns the given CRS unchanged.CompoundCRS
, then this method
searches for a component where:
upper - lower
;lower
.null
.crs
- the coordinate reference system to decompose, or null
.lower
- the first dimension to keep, inclusive.upper
- the last dimension to keep, exclusive.null
if the given crs
was null
or can not be decomposed for dimensions in the [lower
… upper
] range.IndexOutOfBoundsException
- if the given index are out of bounds.GeneralEnvelope.subEnvelope(int, int)
public static double getGreenwichLongitude(GeodeticCRS crs)
crs
- the coordinate reference system from which to get the prime meridian.DefaultPrimeMeridian.getGreenwichLongitude(Unit)
public static CRSAuthorityFactory getAuthorityFactory(String authority) throws FactoryException
forCode(String)
and other SIS methods.
If the given authority is non-null, then this method returns a factory specifically for that authority.
Otherwise, this method returns the MultiAuthoritiesFactory
instance that manages all other factories.
The authority
argument can be "EPSG"
, "OGC"
or any other authority found
on the classpath. In the "EPSG"
case, whether the full set of EPSG codes is supported or not
depends on whether a connection to the database
can be established. If no connection can be established, then this method returns a small embedded
EPSG factory containing at least the CRS defined in the forCode(String)
method javadoc.
User-defined authorities can be added to the SIS environment by creating a CRSAuthorityFactory
implementation with a public no-argument constructor, and declaring the fully-qualified name of that class
in a file at the following location:
META-INF/services/org.opengis.referencing.crs.CRSAuthorityFactory
authority
- the authority of the desired factory (typically "EPSG"
or "OGC"
),
or null
for the MultiAuthoritiesFactory
instance that manage all factories.FactoryException
- if no factory can be returned for the given authority.forCode(String)
,
MultiAuthoritiesFactory
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.