This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
new 7a696fe83a Change the order of `AxesConvention` enumeration values
from most conservative to most aggressive.
7a696fe83a is described below
commit 7a696fe83a14e167948245aac6373ef1fab7a800
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Thu Dec 5 17:51:40 2024 +0100
Change the order of `AxesConvention` enumeration values from most
conservative to most aggressive.
---
.../sis/referencing/crs/DefaultCompoundCRS.java | 2 +-
.../apache/sis/referencing/cs/AxesConvention.java | 218 +++++++++++----------
2 files changed, 113 insertions(+), 107 deletions(-)
diff --git
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/crs/DefaultCompoundCRS.java
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/crs/DefaultCompoundCRS.java
index 65bfccda6d..f9a0db01eb 100644
---
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/crs/DefaultCompoundCRS.java
+++
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/crs/DefaultCompoundCRS.java
@@ -539,7 +539,7 @@ public class DefaultCompoundCRS extends AbstractCRS
implements CompoundCRS {
if (crs == null) {
crs = this;
boolean changed = false;
- final boolean reorderCRS = convention.ordinal() <=
AxesConvention.DISPLAY_ORIENTED.ordinal();
+ final boolean reorderCRS = convention.ordinal() >=
AxesConvention.DISPLAY_ORIENTED.ordinal();
final List<? extends CoordinateReferenceSystem> elements =
reorderCRS ? singles : components;
final CoordinateReferenceSystem[] newComponents = new
CoordinateReferenceSystem[elements.size()];
for (int i=0; i<newComponents.length; i++) {
diff --git
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/AxesConvention.java
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/AxesConvention.java
index 42957c9488..87f8875454 100644
---
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/AxesConvention.java
+++
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/AxesConvention.java
@@ -76,6 +76,12 @@ import org.apache.sis.measure.Units;
* </tr>
* </table>
*
+ * <h2>Note on enumeration order</h2>
+ * The enumeration values are sorted from most conservative to most aggressive.
+ * The fist enumeration values make no change or change only the range of
values.
+ * Next enumeration values may change axis order but not the units of
measurement.
+ * The last enumeration values may change both axis order an units of
measurement.
+ *
* <h2>Note on axis order</h2>
* 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
@@ -112,66 +118,64 @@ import org.apache.sis.measure.Units;
*/
public enum AxesConvention implements AxisFilter {
/**
- * Axes order, direction and units of measurement are forced to commonly
used predefined values.
- * This convention implies the following changes on a coordinate system:
+ * The axis order as they were specified in the original coordinate system.
+ * The first time that a {@code forConvention(…)} method is invoked on a
new coordinate system (CS),
+ * a reference to that original CS is associated to this enumeration value
and can be retrieved from
+ * any derived object.
*
- * <ul>
- * <li>Axes are oriented and ordered as defined for {@link
#DISPLAY_ORIENTED} coordinate systems.</li>
- * <li>Known units are normalized (this list may be expanded in future
SIS versions):
- * <ul>
- * <li>Angular units are set to {@link Units#DEGREE}.</li>
- * <li>Linear units are set to {@link Units#METRE}.</li>
- * <li>Temporal units are set to {@link Units#DAY}.</li>
- * </ul>
- * </li>
- * </ul>
+ * @since 1.5
+ */
+ ORIGINAL,
+
+ /**
+ * Axes having a <i>wraparound</i> range meaning are shifted to their
ranges of positive values.
+ * The units of measurement and range period (difference between
+ * {@linkplain
org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#getMaximumValue()
maximum} and
+ * {@linkplain
org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#getMinimumValue()
minimum value})
+ * are unchanged.
*
- * This convention does not normalize longitude values to the [-180 …
+180]° range and does not set the
- * {@linkplain
org.apache.sis.referencing.datum.DefaultGeodeticDatum#getPrimeMeridian() prime
meridian} to Greenwich.
- * Those changes are not applied for avoiding discontinuity in conversions
from the non-normalized CRS to the normalized CRS.
+ * <h4>Usage</h4>
+ * 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.
*
- * <h4>Rational</h4>
- * 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
- * having {@link org.opengis.referencing.cs.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.
+ * <p>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.</p>
*
- * @see org.apache.sis.referencing.CommonCRS#normalizedGeographic()
- * @see CoordinateSystems#replaceAxes(CoordinateSystem, AxisFilter)
+ * @see org.opengis.referencing.cs.CoordinateSystemAxis#getRangeMeaning()
+ * @see org.opengis.referencing.cs.RangeMeaning#WRAPAROUND
*/
- NORMALIZED {
- @Override
- public Unit<?> getUnitReplacement(final CoordinateSystemAxis axis,
Unit<?> unit) {
- if (Units.isLinear(unit)) {
- unit = Units.METRE;
- } else if (Units.isAngular(unit)) {
- unit = Units.DEGREE;
- } else if (Units.isTemporal(unit)) {
- unit = Units.DAY;
- }
- return unit;
- }
+ POSITIVE_RANGE,
- @Override
- public AxisDirection getDirectionReplacement(final
CoordinateSystemAxis axis, final AxisDirection direction) {
- /*
- * For now we do not touch to inter-cardinal directions (e.g.
"North-East")
- * because it is not clear which normalization policy would match
common usage.
- */
- if (!AxisDirections.isIntercardinal(direction)) {
- /*
- * Change the direction only if the axis allows negative
values.
- * If the axis accepts only positive values, then the direction
- * is considered non-invertible.
- */
- if (axis == null || axis.getMinimumValue() < 0) {
- return AxisDirections.absolute(direction);
- }
- }
- return direction;
- }
- },
+ /**
+ * Axes are ordered for a <i>right-handed</i> 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.
+ *
+ * <p>Note that a right-handed coordinate system does not guarantee that
longitude or <var>x</var> 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 {@code RIGHT_HANDED} enum is
shown,
+ * together with {@link #DISPLAY_ORIENTED} axes for reference:</p>
+ *
+ * <table class="sis">
+ * <caption>Examples of left-handed and right-handed coordinate
systems</caption>
+ * <tr><th>Left-handed</th> <th>Right-handed</th> <th>Display
oriented</th> <th>Remarks</th></tr>
+ * <tr><td>North, East</td> <td>East, North</td> <td>East, North</td>
<td>This is the most common case.</td></tr>
+ * <tr><td>West, North</td> <td>North, West</td> <td>East, North</td>
<td>This right-handed system has latitude first.</td></tr>
+ * <tr><td>South, West</td> <td>West, South</td> <td>East, North</td>
<td>Used for the mapping of southern Africa.</td></tr>
+ * <tr><td>South along 0°,<br>South along 90° West</td>
+ * <td>South along 90° West,<br>South along 0°</td>
+ * <td>(Same as right-handed)</td>
+ * <td>Can be used for the mapping of North pole.</td></tr>
+ * </table>
+ *
+ * @see
org.apache.sis.referencing.cs.CoordinateSystems#angle(AxisDirection,
AxisDirection)
+ * @see <a href="https://en.wikipedia.org/wiki/Right_hand_rule";>Right-hand
rule on Wikipedia</a>
+ */
+ RIGHT_HANDED,
/**
* Axes are reordered and oriented toward directions commonly used for
displaying purpose.
@@ -228,64 +232,66 @@ public enum AxesConvention implements AxisFilter {
},
/**
- * Axes are ordered for a <i>right-handed</i> 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.
- *
- * <p>Note that a right-handed coordinate system does not guarantee that
longitude or <var>x</var> 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 {@code RIGHT_HANDED} enum is
shown,
- * together with {@link #DISPLAY_ORIENTED} axes for reference:</p>
- *
- * <table class="sis">
- * <caption>Examples of left-handed and right-handed coordinate
systems</caption>
- * <tr><th>Left-handed</th> <th>Right-handed</th> <th>Display
oriented</th> <th>Remarks</th></tr>
- * <tr><td>North, East</td> <td>East, North</td> <td>East, North</td>
<td>This is the most common case.</td></tr>
- * <tr><td>West, North</td> <td>North, West</td> <td>East, North</td>
<td>This right-handed system has latitude first.</td></tr>
- * <tr><td>South, West</td> <td>West, South</td> <td>East, North</td>
<td>Used for the mapping of southern Africa.</td></tr>
- * <tr><td>South along 0°,<br>South along 90° West</td>
- * <td>South along 90° West,<br>South along 0°</td>
- * <td>(Same as right-handed)</td>
- * <td>Can be used for the mapping of North pole.</td></tr>
- * </table>
+ * Axes order, direction and units of measurement are forced to commonly
used predefined values.
+ * This convention implies the following changes on a coordinate system:
*
- * @see
org.apache.sis.referencing.cs.CoordinateSystems#angle(AxisDirection,
AxisDirection)
- * @see <a href="https://en.wikipedia.org/wiki/Right_hand_rule";>Right-hand
rule on Wikipedia</a>
- */
- RIGHT_HANDED,
-
- /**
- * Axes having a <i>wraparound</i> range meaning are shifted to their
ranges of positive values.
- * The units of measurement and range period (difference between
- * {@linkplain
org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#getMaximumValue()
maximum} and
- * {@linkplain
org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#getMinimumValue()
minimum value})
- * are unchanged.
+ * <ul>
+ * <li>Axes are oriented and ordered as defined for {@link
#DISPLAY_ORIENTED} coordinate systems.</li>
+ * <li>Known units are normalized (this list may be expanded in future
SIS versions):
+ * <ul>
+ * <li>Angular units are set to {@link Units#DEGREE}.</li>
+ * <li>Linear units are set to {@link Units#METRE}.</li>
+ * <li>Temporal units are set to {@link Units#DAY}.</li>
+ * </ul>
+ * </li>
+ * </ul>
*
- * <h4>Usage</h4>
- * 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.
+ * This convention does not normalize longitude values to the [-180 …
+180]° range and does not set the
+ * {@linkplain
org.apache.sis.referencing.datum.DefaultGeodeticDatum#getPrimeMeridian() prime
meridian} to Greenwich.
+ * Those changes are not applied for avoiding discontinuity in conversions
from the non-normalized CRS to the normalized CRS.
*
- * <p>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.</p>
+ * <h4>Rational</h4>
+ * 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
+ * having {@link org.opengis.referencing.cs.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.
*
- * @see org.opengis.referencing.cs.CoordinateSystemAxis#getRangeMeaning()
- * @see org.opengis.referencing.cs.RangeMeaning#WRAPAROUND
+ * @see org.apache.sis.referencing.CommonCRS#normalizedGeographic()
+ * @see CoordinateSystems#replaceAxes(CoordinateSystem, AxisFilter)
*/
- POSITIVE_RANGE,
+ NORMALIZED {
+ @Override
+ public Unit<?> getUnitReplacement(final CoordinateSystemAxis axis,
Unit<?> unit) {
+ if (Units.isLinear(unit)) {
+ unit = Units.METRE;
+ } else if (Units.isAngular(unit)) {
+ unit = Units.DEGREE;
+ } else if (Units.isTemporal(unit)) {
+ unit = Units.DAY;
+ }
+ return unit;
+ }
- /**
- * The axis order as they were specified in the original coordinate system.
- * The first time that a {@code forConvention(…)} method is invoked on a
new coordinate system (CS),
- * a reference to that original CS is associated to this enumeration value
and can be retrieved from
- * any derived object.
- *
- * @since 1.5
- */
- ORIGINAL;
+ @Override
+ public AxisDirection getDirectionReplacement(final
CoordinateSystemAxis axis, final AxisDirection direction) {
+ /*
+ * For now we do not touch to inter-cardinal directions (e.g.
"North-East")
+ * because it is not clear which normalization policy would match
common usage.
+ */
+ if (!AxisDirections.isIntercardinal(direction)) {
+ /*
+ * Change the direction only if the axis allows negative
values.
+ * If the axis accepts only positive values, then the direction
+ * is considered non-invertible.
+ */
+ if (axis == null || axis.getMinimumValue() < 0) {
+ return AxisDirections.absolute(direction);
+ }
+ }
+ return direction;
+ }
+ };
/**
* Returns the conventions that only change axis order.
