public final class CoordinateSystems extends Static
CoordinateSystem
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.Defined in the sis-referencing
module
Modifier and Type | Method and 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(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.
|
public static AxisDirection parseAxisDirection(String name) throws IllegalArgumentException
'-'
, '_'
or spaces as separator between the cardinal points."deg"
or "°"
symbol. Note that the meridian is not necessarily relative
to Greenwich (see directionAlongMeridian(…)
for more information).name
- the direction name (e.g. "north", "north-east", etc.).IllegalArgumentException
- if the given name is not a known axis direction.public static AxisDirection directionAlongMeridian(AxisDirection baseDirection, double meridian)
directionAlongMeridian(AxisDirection.SOUTH, -90)
returns an axis direction for
“South along 90°W”.baseDirection
- the base direction, which must be AxisDirection.NORTH
or AxisDirection.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.public static Angle angle(AxisDirection source, AxisDirection target)
null
if no angle can be computed.
EAST
to NORTH
is 90°SOUTH
to WEST
is -90°CoordinateSystem
instance.UP
vertical direction as 90°, and the angle of any compass direction to the DOWN
vertical direction as -90°. The sign of those angles gives no indication about whether the coordinate system
is right-handed or left-handed. Those angles are returned as instances of ElevationAngle
.
All angles are approximative since this method does not take the Earth ellipsoidal or geoidal shape in account.
angle(A, A) = 0°
angle(A, opposite(A)) = ±180°
angle(A, B) = -angle(B, A)
source
- the source axis direction.target
- the target axis direction.null
if this value can not be computed.public static Matrix swapAndScaleAxes(CoordinateSystem sourceCS, CoordinateSystem targetCS) throws IllegalArgumentException, IncommensurableException
sourceCS
is a CartesianCS
,
then targetCS
must be a CartesianCS
too.
sourceCS
are (x,y) tuples in metres
and coordinates in targetCS
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 │ └ ┘ └ ┘ └ ┘
sourceCS
- the source coordinate system.targetCS
- the target coordinate system.sourceCS
to targetCS
as an affine transform.
Only axis direction and units are taken in account.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 non-linear.Matrices.createTransform(AxisDirection[], AxisDirection[])
public static CoordinateSystem replaceAxes(CoordinateSystem cs, AxisFilter filter)
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; } });
swapAndScaleAxes(…)
for normalizing the
coordinate values given to a math transform.
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);
cs
- the coordinate system, or null
.filter
- the modifications to apply on coordinate system axes.cs
if the given coordinate system was null or does not need any change.IllegalArgumentException
- if the specified coordinate system can not be normalized.AxesConvention.NORMALIZED
public static CoordinateSystem replaceLinearUnit(CoordinateSystem cs, Unit<Length> newUnit)
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; } });
cs
- the coordinate system in which to replace linear units, or null
.newUnit
- the new linear unit.null
if the given cs
was null,
or cs
if all linear units were already equal to the given one.Units.isLinear(Unit)
public static CoordinateSystem replaceAngularUnit(CoordinateSystem cs, Unit<Angle> newUnit)
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; } });
cs
- the coordinate system in which to replace angular units, or null
.newUnit
- the new angular unit.null
if the given cs
was null,
or cs
if all angular units were already equal to the given one.Units.isAngular(Unit)
public static AxisDirection[] getAxisDirections(CoordinateSystem cs)
cs
- the coordinate system.NullArgumentException
- if cs
is null, or one of its axes is null,
or a value returned by CoordinateSystemAxis.getDirection()
is null.public static Integer getEpsgCode(Unit<?> unit, AxisDirection... directions)
null
.
Current implementation uses a hard-coded 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.
EPSG | CS type | Axis directions | 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 |
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 |
unit
- desired unit of measurement.directions
- desired axis directions.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.Units.getEpsgCode(Unit, boolean)
,
GeodeticAuthorityFactory.createCoordinateSystem(String)
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.