public enum AxesConvention extends Enum<AxesConvention> implements 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 | Conventionally oriented |
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 | ✔ |
GeographicCRS
, 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 softwares 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 softwares, CRS forced to "longitude first" axis order can be created using the
CONVENTIONALLY_ORIENTED
or NORMALIZED
enumeration value.
Math
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()
).AbstractCS.forConvention(AxesConvention)
,
AbstractCRS.forConvention(AxesConvention)
Defined in the sis-referencing
module
Enum Constant and Description |
---|
CONVENTIONALLY_ORIENTED
Axes are oriented toward conventional directions and ordered for a right-handed
coordinate system.
|
NORMALIZED
Axes order, direction and units of measure are forced to commonly used pre-defined values.
|
POSITIVE_RANGE
Axes having a wraparound
range meaning are
shifted to their ranges of positive values.
|
RIGHT_HANDED
Axes are ordered for a right-handed coordinate system.
|
Modifier and Type | Method and Description |
---|---|
static AxesConvention |
valueOf(String name)
Returns the enum constant of this type with the specified name.
|
static AxesConvention[] |
values()
Returns an array containing the constants of this enum type, in
the order they are declared.
|
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
accept, getDirectionReplacement, getUnitReplacement
public static final AxesConvention NORMALIZED
CONVENTIONALLY_ORIENTED
coordinate systems.NonSI.DEGREE_ANGLE
.SI.METRE
.NonSI.DAY
.CONVENTIONALLY_ORIENTED
or RIGHT_HANDED
instead.
RangeMeaning.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.
public static final AxesConvention CONVENTIONALLY_ORIENTED
More specifically, directions opposites to the following ones are replaced by their "forward" counterpart
(e.g. SOUTH
→ NORTH
):
Preferred AxisDirection |
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. |
RIGHT_HANDED
coordinate system.
Right-handed coordinate systems have a precise meaning in Apache SIS. However conventionally oriented coordinate systems have a looser definition. A similar concept appears in the Web Map Services (WMS) 1.3 specification, quoted here:
public static final AxesConvention RIGHT_HANDED
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 with CONVENTIONALLY_ORIENTED
axes for reference:
Left-handed | Right-handed | Conventionally 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° West |
South along 90° West, South along 0° |
(Same as right-handed) | Can be used for the mapping of North pole. |
public static final AxesConvention POSITIVE_RANGE
Note that projecting geometry objects from the old to the new coordinate system may require a non-affine conversion. Some geometries may need to be separated in two parts, and others may need to be merged.
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]°).
RangeMeaning.WRAPAROUND
public static AxesConvention[] values()
for (AxesConvention c : AxesConvention.values()) System.out.println(c);
public static AxesConvention valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullCopyright © 2010–2015 The Apache Software Foundation. All rights reserved.