- All Implemented Interfaces:
Serializable
,Comparable<AxesConvention>
,Constable
,AxisFilter
forConvention(AxesConvention)
method.
The following table summarizes the coordinate system aspects that may be modified by each enum value, with an example of change applied by the enum. Blank cells mean that the property is not changed by the enum value.
Property | Example | Normalized | Display |
Right handed |
Positive range |
---|---|---|---|---|---|
Axis order | (longitude, latitude) | ✔ | ✔ | ✔ | |
Axis direction | (east, north) | ✔ | ✔ | ||
Unit of measurement | Angular degrees & metres | ✔ | |||
Range of values | [0 … 360]° of longitude | ✔ |
Note on axis order
The axis order is specified by the authority (typically a national agency) defining the Coordinate Reference System (CRS). The order depends on the CRS type and the country defining the CRS. In the case of geographic CRS, the (latitude, longitude) axis order is widely used by geographers and pilotes for centuries. However, software developers tend to consistently use the (x,y) order for every kind of CRS. Those different practices resulted in contradictory definitions of axis order for almost every CRS of kindGeographicCRS
, for some ProjectedCRS
in the South hemisphere (South Africa, Australia, etc.)
and for some polar projections among others.
Recent OGC standards mandate the use of axis order as defined by the authority. Oldest OGC standards used the
(x,y) axis order instead, ignoring any authority specification. Many software products still use
the old (x,y) axis order, because it is easier to implement. Apache SIS supports both conventions.
By default, SIS creates CRS with axis order as defined by the authority. Those CRS are created by calls to the
CRS.forCode(String)
method. The actual axis order can be verified after the CRS
creation with System.out.println(crs)
. If (x,y) axis order is wanted for compatibility
with older OGC specifications or other software products, CRS forced to "longitude first" axis order can be created
using the DISPLAY_ORIENTED
or NORMALIZED
enumeration value.
Note on range of longitude values
Most geographic CRS have a longitude axis defined in the [-180 … +180]° range. All map projections in Apache SIS are designed to work in that range. This is also the range ofMath
trigonometric functions like atan2(y,x)
.
However, some data use the [0 … 360]° range instead. A geographic CRS can be shifted to that range of longitude values
using the POSITIVE_RANGE
enumeration value. The choice of longitude range will impact not only some
coordinate conversions, but also the methods that verify the domain of validity
(e.g. GeneralEnvelope.normalize()
).- Since:
- 0.4
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class Enum
Enum.EnumDesc<E extends Enum<E>>
-
Enum Constant Summary
Enum ConstantDescriptionAxes are reordered and oriented toward directions commonly used for displaying purpose.Axes order, direction and units of measurement are forced to commonly used predefined values.Axes having a wraparound range meaning are shifted to their ranges of positive values.Axes are ordered for a right-handed coordinate system. -
Method Summary
Modifier and TypeMethodDescriptionstatic AxesConvention
Returns the enum constant of this class with the specified name.static AxesConvention[]
values()
Returns an array containing the constants of this enum class, in the order they are declared.Methods inherited from class Enum
clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from interface AxisFilter
accept, getDirectionReplacement, getUnitReplacement
-
Enum Constant Details
-
NORMALIZED
Axes order, direction and units of measurement are forced to commonly used predefined values. This convention implies the following changes on a coordinate system:- Axes are oriented and ordered as defined for
DISPLAY_ORIENTED
coordinate systems. - Known units are normalized (this list may be expanded in future SIS versions):
- Angular units are set to
Units.DEGREE
. - Linear units are set to
Units.METRE
. - Temporal units are set to
Units.DAY
.
- Angular units are set to
Rational
The reason why we do not normalize the range and the prime meridian is because doing so would cause the conversion between old and new coordinate systems to be non-affine for axes havingRangeMeaning.WRAPAROUND
. Furthermore, changing the prime meridian would be a datum change rather than a coordinate system change, and datum changes are more difficult to handle by coordinate operation factories.- See Also:
- Axes are oriented and ordered as defined for
-
DISPLAY_ORIENTED
Axes are reordered and oriented toward directions commonly used for displaying purpose. Units of measurement are unchanged. This convention can be used for deriving a coordinate system with the (longitude, latitude) or (x,y) axis order. A similar concept appears in the Web Map Services (WMS) 1.3 specification, quoted here:6.7.2 Map CS — The usual orientation of the Map CS shall be such that the i axis is parallel to the East-to-West axis of the Layer CRS and increases Eastward, and the j axis is parallel to the North-to-South axis of the Layer CRS and increases Southward. This orientation will not be possible in some cases, as (for example) in an orthographic projection over the South Pole. The convention to be followed is that, wherever possible, East shall be to the right edge and North shall be toward the upper edge of the Map CS.
The above-cited (i,j) axes are mapped to display right and display down directions respectively. Other kinds of axis are mapped to east and north directions when possible. More specifically, Apache SIS tries to setup the following directions (replacing a direction by its "forward" counterpart when necessary, e.g.SOUTH
→NORTH
) in the order shown below:Axis directions and order Preferred axis sequences Purpose EAST
,NORTH
,UP
,FUTURE
Commonly used (x, y, z, t) directions for coordinates. DISPLAY_RIGHT
,DISPLAY_DOWN
Commonly used (x, y) directions for screen devices. ROW_POSITIVE
,COLUMN_POSITIVE
Indices in grids or matrices. API notes
we do not provide a "longitude or x axis first" enumeration value because such criterion is hard to apply to inter-cardinal directions and has no meaning for map projections over a pole. The display oriented enumeration name applies to a wider range of cases, but still have a loosely definition which may be adjusted in future Apache SIS versions. If a more stable definition is needed, consider usingRIGHT_HANDED
instead since right-handed coordinate systems have a more precise meaning in Apache SIS.- Since:
- 1.0
-
RIGHT_HANDED
Axes are ordered for a right-handed coordinate system. Axis directions, ranges or coordinate values and units of measurement are unchanged. In the two-dimensional case, the handedness is defined from the point of view of an observer above the plane of the system.Note that a right-handed coordinate system does not guarantee that longitude or x axis will be first in every cases. The most notable exception is the case of (West, North) orientations. The following table lists that case, together with other common axis orientations. The axes orientations implied by this
RIGHT_HANDED
enum is shown, together withDISPLAY_ORIENTED
axes for reference:Examples of left-handed and right-handed coordinate systems Left-handed Right-handed Display oriented Remarks North, East East, North East, North This is the most common case. West, North North, West East, North This right-handed system has latitude first. South, West West, South East, North Used for the mapping of southern Africa. South along 0°,
South along 90° WestSouth along 90° West,
South along 0°(Same as right-handed) Can be used for the mapping of North pole. - See Also:
-
POSITIVE_RANGE
Axes having a wraparound range meaning are shifted to their ranges of positive values. The units of measurement and range period (difference between maximum and minimum value) are unchanged.Usage
The most frequent usage of this enum is for shifting longitude values from the [-180 … +180]° range to the [0 … 360]° range. However, this enum could also be used with climatological calendars if their time axis has a wrapround range meaning.Note that conversions from an coordinate system using the [-180 … +180]° range to a coordinate system using the [0 … 360]° range may not be affine. For example, the data in the West hemisphere ([-180 … 0]°) may need to move on the right side of the East hemisphere ([180 … 360]°). Some geometries may need to be separated in two parts, and others may need to be merged.
- See Also:
-
-
Method Details
-
values
Returns an array containing the constants of this enum class, in the order they are declared.- Returns:
- an array containing the constants of this enum class, in the order they are declared
-
valueOf
Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
IllegalArgumentException
- if this enum class has no constant with the specified nameNullPointerException
- if the argument is null
-