Class DefaultCoordinateSystemAxis
- All Implemented Interfaces:
Serializable
,Formattable
,Deprecable
,LenientComparable
,org.opengis.referencing.cs.CoordinateSystemAxis
,org.opengis.referencing.IdentifiedObject
Axis names
In some case, the axis name is constrained by ISO 19111 depending on the coordinate reference system type. This constraint works in two directions. For example, the names "geodetic latitude" and "geodetic longitude" shall be used to designate the coordinate axis names associated with aGeographicCRS
. Conversely, these names shall not be used
in any other context. See the GeoAPI CoordinateSystemAxis
javadoc for more information.
Immutability and thread safety
This class is immutable and thus thread-safe if the property values (not necessarily the map itself) given to the constructor are also immutable. Unless otherwise noted in the javadoc, this condition holds if all components were created using only SIS factories and static constants.- Since:
- 0.4
- Version:
- 0.8
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
TheORDER[…]
element to be formatted insideAXIS[…]
element. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate String
The abbreviation used for this coordinate system axes.Some names to be treated as equivalent.private static final String[]
Aliases for the "x" and "y" abbreviations (special cases).private org.opengis.referencing.cs.AxisDirection
Direction of this coordinate system axis.static final String
Key for the"maximumValue"
property to be given to the constructor.private double
Minimal and maximal value for this axis, or negative/positive infinity if none.static final String
Key for the"minimumValue"
property to be given to the constructor.private double
Minimal and maximal value for this axis, or negative/positive infinity if none.static final String
Key for the"rangeMeaning"
property to be given to the constructor.private org.opengis.referencing.cs.RangeMeaning
The range meaning for this axis, ornull
if unspecified.private static final long
Serial number for inter-operability with different versions.private javax.measure.Unit<?>
The unit of measure used for this coordinate system axis.Fields inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
DEPRECATED_KEY, LOCALE_KEY
Fields inherited from interface org.opengis.referencing.IdentifiedObject
ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Constructs a new object in which every attributes are set to a null value.DefaultCoordinateSystemAxis
(Map<String, ?> properties, String abbreviation, org.opengis.referencing.cs.AxisDirection direction, javax.measure.Unit<?> unit) Constructs an axis from a set of properties.protected
DefaultCoordinateSystemAxis
(org.opengis.referencing.cs.CoordinateSystemAxis axis) Creates a new coordinate system axis with the same values than the specified one. -
Method Summary
Modifier and TypeMethodDescriptionstatic DefaultCoordinateSystemAxis
castOrCopy
(org.opengis.referencing.cs.CoordinateSystemAxis object) Returns a SIS axis implementation with the same values than the given arbitrary implementation.protected long
Invoked byhashCode()
for computing the hash code when first needed.boolean
equals
(Object object, ComparisonMode mode) Compares the specified object with this axis for equality.private boolean
equalsIgnoreMetadata
(org.opengis.referencing.cs.CoordinateSystemAxis that, ComparisonMode mode, boolean cr) Compares the unit and direction of this axis with the ones of the given axis.protected String
Formats this axis as a Well Known TextAxis[…]
element.Returns the abbreviation used for this coordinate system axes.org.opengis.referencing.cs.AxisDirection
Returns the direction of this coordinate system axis.private static org.opengis.referencing.cs.CoordinateSystem
getEnclosingCS
(Formatter formatter) Returns the enclosing coordinate system, ornull
if none.Class<? extends org.opengis.referencing.cs.CoordinateSystemAxis>
Returns the GeoAPI interface implemented by this class.private Double
Invoked by JAXB at marshalling time for fetching the maximum value, ornull
if none.double
Returns the maximum value normally allowed for this axis, in the unit of measure for the axis.private Double
Invoked by JAXB at marshalling time for fetching the minimum value, ornull
if none.double
Returns the minimum value normally allowed for this axis, in the unit of measure for the axis.org.opengis.referencing.cs.RangeMeaning
javax.measure.Unit<?>
getUnit()
Returns the unit of measure used for this coordinate system axis.boolean
Returnstrue
if either the primary name or at least one alias matches the given string according heuristic rules.private static boolean
isHeuristicMatchForNameXY
(String xy, String name) Special cases for "x" and "y" names.private static void
outOfRange
(String name, Double value) Invoked at unmarshalling time if a minimum or maximum value is out of range.private void
setAbbreviation
(String value) Invoked by JAXB at unmarshalling time.private void
setDirection
(org.opengis.referencing.cs.AxisDirection value) Invoked by JAXB at unmarshalling time.private void
setMaximum
(Double value) Invoked by JAXB at unmarshalling time for setting the maximum value.private void
setMinimum
(Double value) Invoked by JAXB at unmarshalling time for setting the minimum value.private void
setRangeMeaning
(org.opengis.referencing.cs.RangeMeaning value) Invoked by JAXB at unmarshalling time.private void
setUnit
(javax.measure.Unit<?> value) Invoked by JAXB at unmarshalling time.Methods inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
castOrCopy, equals, formatTo, getAlias, getDescription, getIdentifiers, getName, getRemarks, hashCode, isDeprecated
Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toString, toWKT
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.opengis.referencing.IdentifiedObject
getAlias, getIdentifiers, getName, getRemarks, toWKT
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
MINIMUM_VALUE_KEY
Key for the"minimumValue"
property to be given to the constructor. This is used for setting the value to be returned bygetMinimumValue()
.- See Also:
-
MAXIMUM_VALUE_KEY
Key for the"maximumValue"
property to be given to the constructor. This is used for setting the value to be returned bygetMaximumValue()
.- See Also:
-
RANGE_MEANING_KEY
Key for the"rangeMeaning"
property to be given to the constructor. This is used for setting the value to be returned bygetRangeMeaning()
.- See Also:
-
ALIASES
Some names to be treated as equivalent. This is needed because axis names are the primary way to distinguish betweenCoordinateSystemAxis
instances. Those names are strictly defined by ISO 19111 as "Geodetic latitude" and "Geodetic longitude" among others, but the legacy WKT specifications from OGC 01-009 defined the names as "Lon" and "Lat" for the same axis.Keys in this map are names in lower cases. Values are any object that allow us to differentiate latitude from longitude.
Similar strings appear in
formatTo(Formatter)
andorg.apache.sis.io.wkt.GeodeticObjectParser.parseAxis(…)
.- See Also:
-
ALIASES_XY
Aliases for the "x" and "y" abbreviations (special cases). "x" and "y" are sometimes used (especially in WKT) for meaning "Easting" and "Northing". However, we shall not add "x" and "y" as aliases in theALIASES
map, because experience has shown that doing so cause a lot of undesirable side effects. The "x" abbreviation is used for too many things ("Easting", "Westing", "Geocentric X", "Display right", "Display left") and likewise for "y". Declaring them as aliases introduces confusion in many places. Instead, the "x" and "y" cases are handled in a special way by theisHeuristicMatchForNameXY(…)
method.Names at even index are for "x" and names at odd index are for "y".
-
abbreviation
The abbreviation used for this coordinate system axes. Examples are "X" and "Y".Consider this field as final! This field is modified only at unmarshalling time by
setAbbreviation(String)
- See Also:
-
direction
private org.opengis.referencing.cs.AxisDirection directionDirection of this coordinate system axis. In the case of Cartesian projected coordinates, this is the direction of this coordinate system axis locally.Consider this field as final! This field is modified only at unmarshalling time by
setDirection(AxisDirection)
- See Also:
-
unit
private javax.measure.Unit<?> unitThe unit of measure used for this coordinate system axis.Consider this field as final! This field is modified only at unmarshalling time by
setUnit(Unit)
- See Also:
-
minimumValue
private double minimumValueMinimal and maximal value for this axis, or negative/positive infinity if none.Consider this field as final! This field is modified only at unmarshalling time by
setMinimum(Double)
orsetMaximum(Double)
-
maximumValue
private double maximumValueMinimal and maximal value for this axis, or negative/positive infinity if none.Consider this field as final! This field is modified only at unmarshalling time by
setMinimum(Double)
orsetMaximum(Double)
-
rangeMeaning
private org.opengis.referencing.cs.RangeMeaning rangeMeaningThe range meaning for this axis, ornull
if unspecified.Consider this field as final! This field is modified only at unmarshalling time by
setRangeMeaning(RangeMeaning)
- See Also:
-
-
Constructor Details
-
DefaultCoordinateSystemAxis
public DefaultCoordinateSystemAxis(Map<String, ?> properties, String abbreviation, org.opengis.referencing.cs.AxisDirection direction, javax.measure.Unit<?> unit) Constructs an axis from a set of properties. The properties given in argument follow the same rules than for the super-class constructor. Additionally, the following properties are understood by this constructor:Recognized properties (non exhaustive list) Property name Value type Returned by "minimumValue" Number
getMinimumValue()
"maximumValue" Number
getMaximumValue()
"rangeMeaning" RangeMeaning
getRangeMeaning()
Defined in parent class (reminder) "name" ReferenceIdentifier
orString
AbstractIdentifiedObject.getName()
"alias" GenericName
orCharSequence
(optionally as array)AbstractIdentifiedObject.getAlias()
"identifiers" ReferenceIdentifier
(optionally as array)AbstractIdentifiedObject.getIdentifiers()
"remarks" InternationalString
orString
AbstractIdentifiedObject.getRemarks()
properties
map are considered ignorable metadata (except the axis name) while information provided as explicit arguments may have an impact on coordinate transformation results. Exceptions to this rule are theminimumValue
andmaximumValue
in the particular case whererangeMeaning
isRangeMeaning.WRAPAROUND
.If no minimum, maximum and range meaning are specified, then this constructor will infer them from the axis unit and direction.
- Parameters:
properties
- the properties to be given to the identified object.abbreviation
- the abbreviation used for this coordinate system axis.direction
- the direction of this coordinate system axis.unit
- the unit of measure used for this coordinate system axis.- See Also:
-
DefaultCoordinateSystemAxis
protected DefaultCoordinateSystemAxis(org.opengis.referencing.cs.CoordinateSystemAxis axis) Creates a new coordinate system axis with the same values than the specified one. This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.This constructor performs a shallow copy, i.e. the properties are not cloned.
- Parameters:
axis
- the coordinate system axis to copy.- See Also:
-
DefaultCoordinateSystemAxis
private DefaultCoordinateSystemAxis()Constructs a new object in which every attributes are set to a null value. This is not a valid object. This constructor is strictly reserved to JAXB, which will assign values to the fields using reflection.
-
-
Method Details
-
castOrCopy
public static DefaultCoordinateSystemAxis castOrCopy(org.opengis.referencing.cs.CoordinateSystemAxis object) Returns a SIS axis implementation with the same values than the given arbitrary implementation. If the given object isnull
, then this method returnsnull
. Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged. Otherwise a new SIS implementation is created and initialized to the values of the given object.- Parameters:
object
- the object to get as a SIS implementation, ornull
if none.- Returns:
- a SIS implementation containing the values of the given object (may be the
given object itself), or
null
if the argument was null.
-
getInterface
Returns the GeoAPI interface implemented by this class. The SIS implementation returnsCoordinateSystemAxis.class
.Note for implementers: Subclasses usually do not need to override this method since GeoAPI does not defineCoordinateSystemAxis
sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their own set of interfaces.- Overrides:
getInterface
in classAbstractIdentifiedObject
- Returns:
CoordinateSystemAxis.class
or a user-defined sub-interface.
-
getDirection
public org.opengis.referencing.cs.AxisDirection getDirection()Returns the direction of this coordinate system axis. This direction is often approximate and intended to provide a human interpretable meaning to the axis. A coordinate system cannot contain two axes having the same direction or opposite directions.Examples: north or south, east or west, up or down.
- Specified by:
getDirection
in interfaceorg.opengis.referencing.cs.CoordinateSystemAxis
- Returns:
- the direction of this coordinate system axis.
-
getAbbreviation
Returns the abbreviation used for this coordinate system axes. Examples are "X" and "Y".- Specified by:
getAbbreviation
in interfaceorg.opengis.referencing.cs.CoordinateSystemAxis
- Returns:
- the coordinate system axis abbreviation.
-
getUnit
public javax.measure.Unit<?> getUnit()Returns the unit of measure used for this coordinate system axis. If thisCoordinateSystemAxis
was given by
, then all coordinate values at dimension i in a coordinate tuple shall be recorded using this unit of measure.CoordinateSystem.getAxis
(i)- Specified by:
getUnit
in interfaceorg.opengis.referencing.cs.CoordinateSystemAxis
- Returns:
- the unit of measure used for coordinate values along this coordinate system axis.
-
getMinimumValue
public double getMinimumValue()Returns the minimum value normally allowed for this axis, in the unit of measure for the axis. If there is no minimum value, then this method returns negative infinity.- Specified by:
getMinimumValue
in interfaceorg.opengis.referencing.cs.CoordinateSystemAxis
- Returns:
- the minimum value normally allowed for this axis.
-
getMaximumValue
public double getMaximumValue()Returns the maximum value normally allowed for this axis, in the unit of measure for the axis. If there is no maximum value, then this method returns negative infinity.- Specified by:
getMaximumValue
in interfaceorg.opengis.referencing.cs.CoordinateSystemAxis
- Returns:
- the maximum value normally allowed for this axis.
-
outOfRange
Invoked at unmarshalling time if a minimum or maximum value is out of range.- Parameters:
name
- the property name. Will also be used as "method" name for logging purpose, since the setter method "conceptually" do not exist (it is only for JAXB).value
- the invalid value.
-
getRangeMeaning
public org.opengis.referencing.cs.RangeMeaning getRangeMeaning()Returns the meaning of axis value range specified by the minimum and maximum values. If there is no minimum and maximum values (i.e. if those values are negative infinity and positive infinity respectively), then this method returnsnull
.- Specified by:
getRangeMeaning
in interfaceorg.opengis.referencing.cs.CoordinateSystemAxis
- Returns:
- the meaning of axis value range, or
null
if unspecified.
-
isHeuristicMatchForName
Returnstrue
if either the primary name or at least one alias matches the given string according heuristic rules. This method performs the comparison documented in thesuper-class
, with an additional flexibility for latitudes and longitudes:"Lat"
,"Latitude"
and"Geodetic latitude"
are considered equivalent."Lon"
,"Longitude"
and"Geodetic longitude"
are considered equivalent.
Future evolutions
This method implements heuristic rules learned from experience while trying to provide inter-operability with different data producers. Those rules may be adjusted in any future SIS version according experience gained while working with more data producers.- Overrides:
isHeuristicMatchForName
in classAbstractIdentifiedObject
- Parameters:
name
- the name to compare.- Returns:
true
if the primary name of at least one alias matches the specifiedname
.- See Also:
-
isHeuristicMatchForNameXY
Special cases for "x" and "y" names. "x" is considered equivalent to "Easting" or "Westing", but the converse is not true. Note: by avoiding to put "x" in theALIASES
map, we avoid undesirable side effects like considering "Easting" as equivalent to "Westing".- Parameters:
xy
- the name which may be "x" or "y".name
- the second name to compare with.- Returns:
true
if the second name is equivalent to "x" or "y" (depending on thexy
value), orfalse
otherwise.
-
equalsIgnoreMetadata
private boolean equalsIgnoreMetadata(org.opengis.referencing.cs.CoordinateSystemAxis that, ComparisonMode mode, boolean cr) Compares the unit and direction of this axis with the ones of the given axis. The range minimum and maximum values are compared only ifcr
istrue
, i.e. it is caller responsibility to determine if range shall be considered as metadata.- Parameters:
that
- the axis to compare with this axis.mode
- whether the unit comparison is an approximation or exact.cr
-true
for comparing also the range minimum and maximum values.- Returns:
true
if unit, direction and optionally range extremum are equal.
-
equals
Compares the specified object with this axis for equality. The strictness level is controlled by the second argument. This method compares the following properties in every cases: In the particular case wheregetRangeMeaning()
isWRAPAROUND
, thengetMinimumValue()
andgetMaximumValue()
are considered non-ignorable metadata and will be compared for every modes. All other properties are compared only for modes stricter thanComparisonMode.IGNORE_METADATA
.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classAbstractIdentifiedObject
- Parameters:
object
- the object to compare tothis
.mode
-STRICT
for performing a strict comparison, orIGNORE_METADATA
for comparing only properties relevant to coordinate transformations.- Returns:
true
if both objects are equal.- See Also:
-
computeHashCode
protected long computeHashCode()Invoked byhashCode()
for computing the hash code when first needed. SeeAbstractIdentifiedObject.computeHashCode()
for more information.- Overrides:
computeHashCode
in classAbstractIdentifiedObject
- Returns:
- the hash code value. This value may change in any future Apache SIS version.
-
getEnclosingCS
Returns the enclosing coordinate system, ornull
if none. In ISO 19162 compliant WKT the coordinate reference system should be the first parent (formatter.getEnclosingElement(1)
) and the coordinate system shall be obtained from that CRS (yes, this is convolved. This is because of historical reasons, since compatibility with WKT 1 was a requirement of WKT 2). -
formatTo
Formats this axis as a Well Known TextAxis[…]
element.Constraints for WKT validity
The ISO 19162 specification puts many constraints on axis names, abbreviations and directions allowed in WKT. Most of those constraints are inherited from ISO 19111 — seeCoordinateSystemAxis
javadoc for some of those. The current Apache SIS implementation does not verify whether this axis name and abbreviation are compliant; we assume that the user created a valid axis. The only actions (derived from ISO 19162 rules) taken by this method (by default) are:- Replace “Geodetic latitude” and “Geodetic longitude” names (case insensitive) by “latitude” and “longitude” respectively.
- For latitude and longitude axes, replace “φ” and “λ” abbreviations by “B” and “L” respectively (from German “Breite” and “Länge”, used in academic texts worldwide). Note that “L” is also the transliteration of Greek letter “lambda” (λ).
- In
SphericalCS
, replace “φ” and “θ” abbreviations by “U” and “V” respectively. - In
PolarCS
, replace “θ” abbreviation by “U”.
WKTFormat.setTransliterator(Transliterator)
.- Overrides:
formatTo
in classAbstractIdentifiedObject
- Parameters:
formatter
- the formatter where to format the inner content of this WKT element.- Returns:
"Axis"
.- See Also:
-
setAbbreviation
Invoked by JAXB at unmarshalling time.- See Also:
-
setDirection
private void setDirection(org.opengis.referencing.cs.AxisDirection value) Invoked by JAXB at unmarshalling time.- See Also:
-
setUnit
private void setUnit(javax.measure.Unit<?> value) Invoked by JAXB at unmarshalling time.- See Also:
-
setRangeMeaning
private void setRangeMeaning(org.opengis.referencing.cs.RangeMeaning value) Invoked by JAXB at unmarshalling time.- See Also:
-
getMinimum
Invoked by JAXB at marshalling time for fetching the minimum value, ornull
if none.- See Also:
-
setMinimum
Invoked by JAXB at unmarshalling time for setting the minimum value. -
getMaximum
Invoked by JAXB at marshalling time for fetching the maximum value, ornull
if none.- See Also:
-
setMaximum
Invoked by JAXB at unmarshalling time for setting the maximum value.
-