Package org.apache.sis.referencing.cs
Class CoordinateSystems

public final class CoordinateSystems extends Static
Utility methods working onCoordinateSystem
objects and their axes. Those methods allow for example to estimate an angle between two axes or determining the change of axis directions and units between two coordinate systems. Since:
 0.4
Defined in the
sisreferencing
module


Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static Angle
angle(AxisDirection source, AxisDirection target)
Returns the arithmetic (counterclockwise) angle from the first axis direction to the second direction.static AxisDirection
directionAlongMeridian(AxisDirection baseDirection, double meridian)
Returns an axis direction from a pole along a meridian.static AxisDirection[]
getAxisDirections(CoordinateSystem cs)
Returns the axis directions for the specified coordinate system.static Integer
getEpsgCode(Class<? extends CoordinateSystem> type, CoordinateSystemAxis... axes)
Returns the EPSG code of a coordinate system using the units and directions of given axes.static Integer
getEpsgCode(Unit<?> unit, AxisDirection... directions)
Returns the EPSG code of a coordinate system using the given unit and axis directions.static AxisDirection
parseAxisDirection(String name)
Returns an axis direction code from the given direction name.static CoordinateSystem
replaceAngularUnit(CoordinateSystem cs, Unit<Angle> newUnit)
Returns a coordinate system derived from the given one but with all angular units replaced by the given unit.static CoordinateSystem
replaceAxes(CoordinateSystem cs, AxisFilter filter)
Returns a coordinate system derived from the given one but with a modified list of axes.static CoordinateSystem
replaceLinearUnit(CoordinateSystem cs, Unit<Length> newUnit)
Returns a coordinate system derived from the given one but with all linear units replaced by the given unit.static Matrix
swapAndScaleAxes(CoordinateSystem sourceCS, CoordinateSystem targetCS)
Returns an affine transform between two coordinate systems.



Method Detail

parseAxisDirection
public static AxisDirection parseAxisDirection(String name) throws IllegalArgumentException
Returns an axis direction code from the given direction name. Names are caseinsensitive. They may be: Cardinal directions like "north" and "east".
 Intercardinal directions "northeast" and "southsoutheast",
using either
''
,'_'
or spaces as separator between the cardinal points.  Directions from a pole like "South along 180 deg" and "South along 90° East",
using either the
"deg"
or"°"
symbol. Note that the meridian is not necessarily relative to Greenwich (seedirectionAlongMeridian(…)
for more information).
 Parameters:
name
 the direction name (e.g. "north", "northeast", etc.). Returns:
 the axis direction for the given name.
 Throws:
IllegalArgumentException
 if the given name is not a known axis direction.

directionAlongMeridian
public static AxisDirection directionAlongMeridian(AxisDirection baseDirection, double meridian)
Returns an axis direction from a pole along a meridian. The given meridian is usually, but not necessarily, relative to the Greenwich meridian.Example:directionAlongMeridian(AxisDirection.SOUTH, 90)
returns an axis direction for “South along 90°W”.Reference meridianThe reference meridian depends on the context. It is usually the prime meridian of the geodetic datum of the geographic CRS instance that contains (through its coordinate system) the axes having those directions. This policy is consistent with WKT 2 specification §7.5.4(iv). Parameters:
baseDirection
 the base direction, which must beAxisDirection.NORTH
orAxisDirection.SOUTH
.meridian
 the meridian in degrees, relative to a unspecified (usually Greenwich) prime meridian. Meridians in the East hemisphere are positive and meridians in the West hemisphere are negative. Returns:
 the axis direction along the given meridian.
 Since:
 0.6

angle
public static Angle angle(AxisDirection source, AxisDirection target)
Returns the arithmetic (counterclockwise) angle from the first axis direction to the second direction. This method returns a value between 180° and +180°, ornull
if no angle can be computed.Horizontal directionsFor any pair of compass directions which are not opposite directions, a positive angle denotes a righthanded system while a negative angle denotes a lefthanded system. Examples: The angle from
EAST
toNORTH
is 90°  The angle from
SOUTH
toWEST
is 90°  The angle from "North along 90° East" to "North along 0°" is 90°.
Note: in the case of directions like “South along 90°W”, the caller is responsible to make sure that the meridians are relative to the same prime meridian. This is the case if the axes are part of the sameCoordinateSystem
instance.Horizontal and vertical directionsBy convention this method defines the angle from any compass direction to theUP
vertical direction as 90°, and the angle of any compass direction to theDOWN
vertical direction as 90°. The sign of those angles gives no indication about whether the coordinate system is righthanded or lefthanded. Those angles are returned as instances ofElevationAngle
.All angles are approximations since this method does not take the Earth ellipsoidal or geoidal shape in account.
InvariantsFor any nonnull return value:angle(A, A) = 0°
angle(A, opposite(A)) = ±180°
angle(A, B) = angle(B, A)
 Parameters:
source
 the source axis direction.target
 the target axis direction. Returns:
 the arithmetic angle (in degrees) of the rotation to apply on a line pointing toward
the source direction in order to make it point toward the target direction, or
null
if this value can not be computed.
 The angle from

swapAndScaleAxes
public static Matrix swapAndScaleAxes(CoordinateSystem sourceCS, CoordinateSystem targetCS) throws IllegalArgumentException, IncommensurableException
Returns an affine transform between two coordinate systems. Only units and axes order (e.g. transforming from (North, West) to (East, North) are taken in account by this method.ConditionsThe two coordinate systems must implement the same GeoAPI coordinate system interface. For example ifsourceCS
is aCartesianCS
, thentargetCS
must be aCartesianCS
too.Example: If coordinates insourceCS
are (x,y) tuples in metres and coordinates intargetCS
are (y,x) tuples in centimetres, then the transformation can be performed as below:┌ ┐ ┌ ┐ ┌ ┐ │y(cm)│ │ 0 100 0 │ │ x(m)│ │ x(cm)│ = │ 100 0 0 │ │ y(m)│ │ 1 │ │ 0 0 1 │ │ 1 │ └ ┘ └ ┘ └ ┘
 Parameters:
sourceCS
 the source coordinate system.targetCS
 the target coordinate system. Returns:
 the conversion from
sourceCS
totargetCS
as an affine transform. Only axis direction and units are taken in account.  Throws:
IllegalArgumentException
 if the CS are not of the same type, or axes do not match.IncommensurableException
 if the units are not compatible, or the conversion is nonlinear. See Also:
Matrices.createTransform(AxisDirection[], AxisDirection[])

replaceAxes
public static CoordinateSystem replaceAxes(CoordinateSystem cs, AxisFilter filter)
Returns a coordinate system derived from the given one but with a modified list of axes. The axes may be filtered (excluding some axes), reordered or have their unit and direction modified.Example: for replacing all angular units of a coordinate system to degrees (regardless what the original angular units were) while leaving other kinds of units unchanged, one can write:CoordinateSystem cs = ...; cs = CoordinateSystems.replaceAxes(cs, new AxisFilter() { @Override public Unit<?> getUnitReplacement(CoordinateSystemAxis axis, Unit<?> unit) { if (Units.isAngular(unit)) { unit = Units.DEGREE; } return unit; } });
Coordinate system normalizationThis method is often used together withswapAndScaleAxes(…)
for normalizing the coordinate values given to a math transform.Example:A rational for normalized axis order and units is explained in the Axis units and direction section in the description of the map projection package.CoordinateSystem sourceCS = ...; CoordinateSystem targetCS = ...; Matrix step1 = swapAndScaleAxes(sourceCS, replaceAxes(sourceCS, AxisConvention.NORMALIZED)); Matrix step2 = ...; // some transform working on coordinates with standard axis order and unit. Matrix step3 = swapAndScaleAxes(replaceAxes(targetCS, AxisConvention.NORMALIZED), targetCS);
 Parameters:
cs
 the coordinate system, ornull
.filter
 the modifications to apply on coordinate system axes. Returns:
 the modified coordinate system as a new instance,
or
cs
if the given coordinate system was null or does not need any change.  Throws:
IllegalArgumentException
 if the specified coordinate system can not be filtered. It may be because the coordinate system would contain an illegal number of axes, or because an axis would have an unexpected direction or unexpected unit of measurement. Since:
 0.6
 See Also:
AxesConvention.NORMALIZED

replaceLinearUnit
public static CoordinateSystem replaceLinearUnit(CoordinateSystem cs, Unit<Length> newUnit)
Returns a coordinate system derived from the given one but with all linear units replaced by the given unit. Nonlinear units (e.g. angular or scale units) are left unchanged.This convenience method is equivalent to the following code:
return CoordinateSystems.replaceAxes(cs, new AxisFilter() { @Override public Unit<?> getUnitReplacement(CoordinateSystemAxis axis, Unit<?> unit) { return Units.isLinear(unit) ? newUnit : unit; } });
 Parameters:
cs
 the coordinate system in which to replace linear units, ornull
.newUnit
 the new linear unit. Returns:
 the modified coordinate system as a new instance, or
null
if the givencs
was null, orcs
if all linear units were already equal to the given one.  Since:
 0.7
 See Also:
Units.isLinear(Unit)

replaceAngularUnit
public static CoordinateSystem replaceAngularUnit(CoordinateSystem cs, Unit<Angle> newUnit)
Returns a coordinate system derived from the given one but with all angular units replaced by the given unit. Nonangular units (e.g. linear or scale units) are left unchanged.This convenience method is equivalent to the following code:
return CoordinateSystems.replaceAxes(cs, new AxisFilter() { @Override public Unit<?> getUnitReplacement(CoordinateSystemAxis axis, Unit<?> unit) { return Units.isAngular(unit) ? newUnit : unit; } });
 Parameters:
cs
 the coordinate system in which to replace angular units, ornull
.newUnit
 the new angular unit. Returns:
 the modified coordinate system as a new instance, or
null
if the givencs
was null, orcs
if all angular units were already equal to the given one.  Since:
 0.7
 See Also:
Units.isAngular(Unit)

getAxisDirections
public static AxisDirection[] getAxisDirections(CoordinateSystem cs)
Returns the axis directions for the specified coordinate system. This method guarantees that the returned array is nonnull and does not contain any null direction. Parameters:
cs
 the coordinate system. Returns:
 the axis directions for the specified coordinate system.
 Throws:
NullArgumentException
 ifcs
is null, or one of its axes is null, or a value returned byCoordinateSystemAxis.getDirection()
is null. Since:
 0.8

getEpsgCode
public static Integer getEpsgCode(Class<? extends CoordinateSystem> type, CoordinateSystemAxis... axes)
Returns the EPSG code of a coordinate system using the units and directions of given axes. This method ignores axis metadata (names, abbreviation, identifiers, remarks, etc.). The axis minimum and maximum values are checked only if the range meaning is "wraparound". If no suitable coordinate system is known to Apache SIS, then this method returnsnull
.Current implementation uses a hardcoded list of known coordinate systems; it does not yet scan the EPSG database (this may change in future Apache SIS version). The current list of known coordinate systems is given below.
Known coordinate systems (CS) EPSG CS type Axis directions Horizontal unit 6424 Ellipsoidal east north degree 6422 Ellipsoidal north east degree 6425 Ellipsoidal east north grads 6403 Ellipsoidal north east grads 6429 Ellipsoidal east north radian 6428 Ellipsoidal north east radian 6426 Ellipsoidal east north up degree 6423 Ellipsoidal north east up degree 6427 Ellipsoidal east north up grads 6421 Ellipsoidal north east up grads 6431 Ellipsoidal east north up radian 6430 Ellipsoidal north east up radian 4400 Cartesian east north metre 4500 Cartesian north east metre 4491 Cartesian west north metre 4501 Cartesian north west metre 6503 Cartesian west south metre 6501 Cartesian south west metre 1039 Cartesian east north foot 1029 Cartesian north east foot 4403 Cartesian east north Clarke’s foot 4502 Cartesian north east Clarke’s foot 4497 Cartesian east north US survey foot  Parameters:
type
 the type of coordinate system for which an EPSG code is desired, as a GeoAPI interface.axes
 axes for which a coordinate system EPSG code is desired. Returns:
 EPSG codes for a coordinate system using the given axes (ignoring metadata), or
null
if unknown to this method. Note that a null value does not mean that a more extensive search in the EPSG database would not find a matching coordinate system.  Since:
 1.0
 See Also:
GeodeticAuthorityFactory.createCoordinateSystem(String)

getEpsgCode
public static Integer getEpsgCode(Unit<?> unit, AxisDirection... directions)
Returns the EPSG code of a coordinate system using the given unit and axis directions. This convenience method performs the work documented ingetEpsgCode(Class, CoordinateSystemAxis...)
, but requiring only a frequently used subset of information. If no suitable coordinate system is known to Apache SIS, then this method returnsnull
.Current implementation uses a hardcoded list of known coordinate systems; it does not yet scan the EPSG database (this may change in future Apache SIS version). The current list of known coordinate systems is documented above.
 Parameters:
unit
 desired unit of measurement. For threedimensional ellipsoidal coordinate system, this is the unit for the horizontal axes only; the vertical axis is in metres.directions
 desired axis directions. Returns:
 EPSG codes for a coordinate system using the given axis directions and unit of measurement,
or
null
if unknown to this method. Note that a null value does not mean that a more extensive search in the EPSG database would not find a matching coordinate system.  Since:
 0.8
 See Also:
Units.getEpsgCode(Unit, boolean)
,GeodeticAuthorityFactory.createCoordinateSystem(String)

