Revision 794 org.gvsig.proj/branches/refactor2018/org.gvsig.proj/org.gvsig.proj.catalog/org.gvsig.proj.catalog.api/src/main/java/org/gvsig/proj/catalogue/CRSDefinition.java
CRSDefinition.java | ||
---|---|---|
2 | 2 |
* gvSIG. Desktop Geographic Information System. |
3 | 3 |
* |
4 | 4 |
* Copyright (C) 2018 gvSIG Association. |
5 |
* |
|
6 |
* This file has been adapted from GeoAPI, see |
|
7 |
* the original copyright headers bellow. |
|
8 | 5 |
* |
9 | 6 |
* This program is free software; you can redistribute it and/or |
10 | 7 |
* modify it under the terms of the GNU General Public License |
... | ... | |
23 | 20 |
* |
24 | 21 |
* For any additional information, do not hesitate to contact us |
25 | 22 |
* at info AT gvsig.com, or visit our website www.gvsig.com. |
26 |
* |
|
27 |
* ---------- |
|
28 |
* |
|
29 |
* GeoAPI - Java interfaces for OGC/ISO standards |
|
30 |
* http://www.geoapi.org |
|
31 |
* |
|
32 |
* Copyright (C) 2004-2017 Open Geospatial Consortium, Inc. |
|
33 |
* All Rights Reserved. http://www.opengeospatial.org/ogc/legal |
|
34 |
* |
|
35 |
* Permission to use, copy, and modify this software and its documentation, with |
|
36 |
* or without modification, for any purpose and without fee or royalty is hereby |
|
37 |
* granted, provided that you include the following on ALL copies of the software |
|
38 |
* and documentation or portions thereof, including modifications, that you make: |
|
39 |
* |
|
40 |
* 1. The full text of this NOTICE in a location viewable to users of the |
|
41 |
* redistributed or derivative work. |
|
42 |
* 2. Notice of any changes or modifications to the OGC files, including the |
|
43 |
* date changes were made. |
|
44 |
* |
|
45 |
* THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE |
|
46 |
* NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED |
|
47 |
* TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT |
|
48 |
* THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY |
|
49 |
* PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. |
|
50 |
* |
|
51 |
* COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR |
|
52 |
* CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION. |
|
53 |
* |
|
54 |
* The name and trademarks of copyright holders may NOT be used in advertising or |
|
55 |
* publicity pertaining to the software without specific, written prior permission. |
|
56 |
* Title to copyright in this software and any associated documentation will at all |
|
57 |
* times remain with copyright holders. |
|
58 | 23 |
*/ |
59 | 24 |
package org.gvsig.proj.catalogue; |
60 | 25 |
|
26 |
import java.util.List; |
|
27 |
import java.util.Set; |
|
28 |
|
|
29 |
import org.gvsig.proj.catalogue.cs.CoordinateSystemAxis; |
|
30 |
import org.gvsig.proj.catalogue.datum.Datum; |
|
61 | 31 |
import org.gvsig.proj.catalogue.ref.Extent; |
62 | 32 |
|
63 | 33 |
/** |
64 |
* Base type of all Coordinate Reference Systems (CRS). |
|
65 |
* This is the base interface for two cases: |
|
66 |
* |
|
67 |
* <ul> |
|
68 |
* <li>{@link SingleCRS}, defined by a |
|
69 |
* {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate system} and a |
|
70 |
* {@linkplain org.opengis.referencing.datum.Datum datum};</li> |
|
71 |
* <li>{@link CompoundCRS}, defined as a sequence of {@code SingleCRS}.</li> |
|
72 |
* </ul> |
|
73 |
* |
|
74 |
* <h3>Purpose</h3> |
|
75 |
* A coordinate reference system (CRS) captures the choice of values for the parameters that constitute |
|
76 |
* the degrees of freedom of the coordinate space. The fact that such a choice has to be made, |
|
77 |
* either arbitrarily or by adopting values from survey measurements, leads to the large number |
|
78 |
* of coordinate reference systems in use around the world. It is also the cause of the little |
|
79 |
* understood fact that the latitude and longitude of a point are not unique. Without the full |
|
80 |
* specification of the coordinate reference system, coordinates are ambiguous at best and |
|
81 |
* meaningless at worst. |
|
82 |
* |
|
83 |
* Note: gvSIG derived these interfaces from GeoAPI in order to have a simpler API and also to |
|
84 |
* avoid namespace collisions (e.g. GeoAPI 3 vs GeoTools interfaces). There is no plans |
|
85 |
* to evolve these interfaces to adapt them to future GeoAPI versions. |
|
34 |
* Definition of a Coordinate Reference System (CRS). |
|
86 | 35 |
* |
36 |
* A CRS defines how a set of coordinates relate to real positions (on earth, on other |
|
37 |
* planet or in the space). A CRS defines the number of coordinate axis, its name, order and |
|
38 |
* direction, its units, the mathematical model used to define the geometric figure (ellipsoid) |
|
39 |
* to approximate the shape of the earth, the relationship of this mathematical model with the |
|
40 |
* earth (datum), among other concepts and parameters. Some CRSs include a projection, which |
|
41 |
* defines a mathematical model to approximate the surface of an area of the earth using a |
|
42 |
* planar surface. |
|
43 |
* |
|
44 |
* Note that a set of coordinates is meaningless if their CRS is not defined, as these |
|
45 |
* values can refer to different locations on the Earth depending on the CRS being used. |
|
46 |
* |
|
87 | 47 |
* @author gvSIG Team |
88 |
* @author Martin Desruisseaux (IRD) |
|
89 |
* @version 3.0 |
|
90 |
* @since 1.0 |
|
48 |
* @author Cesar Martinez Izquierdo |
|
91 | 49 |
*/ |
92 |
public interface CRSDefinition extends IdentifiedObject { |
|
50 |
public interface CRSDefinition { |
|
51 |
|
|
93 | 52 |
/** |
53 |
* A common name for this coordinate reference system |
|
54 |
* |
|
55 |
* @return the name, or {@code null} if none. |
|
56 |
*/ |
|
57 |
String getName(); |
|
58 |
|
|
59 |
/** |
|
60 |
* Gets a code that references an unambiguous definition of the coordinate reference |
|
61 |
* system for some authority. Examples: "EPSG:4326", "EPSG:25830". |
|
62 |
* |
|
63 |
* @return the identifier which was used to instantiate the object, or the |
|
64 |
* identifier that more closely matches the information used to instantiate |
|
65 |
* the object (e.g. if derived from an WKT definition) |
|
66 |
*/ |
|
67 |
String getIdentifier(); |
|
68 |
|
|
69 |
/** |
|
70 |
* Gets the list of identifiers which describe this coordinate reference system |
|
71 |
* definition. |
|
72 |
* |
|
73 |
* @return the list of object identifiers, or an empty collection if there is none. |
|
74 |
*/ |
|
75 |
Set<String> getIdentifiers(); |
|
76 |
|
|
77 |
/** |
|
78 |
* FIXME: GeoAPI |
|
94 | 79 |
* Area or region or timeframe in which this (coordinate) reference system is valid. |
95 | 80 |
* |
96 | 81 |
* @return the reference system valid domain, or {@code null} if not available. |
97 | 82 |
* @since 2.1 |
98 | 83 |
*/ |
99 | 84 |
Extent getDomainOfValidity(); |
85 |
|
|
86 |
/** |
|
87 |
* Textual description of the coordinate reference system, including remarks |
|
88 |
* and its scope. |
|
89 |
* |
|
90 |
* @return the description, or {@code null} if none. |
|
91 |
*/ |
|
92 |
String getDescription(); |
|
93 |
|
|
94 |
/** |
|
95 |
* Some CRSs include a projection, which defines a mathematical model to approximate |
|
96 |
* the surface of an area of the earth using a planar surface. CRS including a |
|
97 |
* projection are called projected CRSs |
|
98 |
* |
|
99 |
* @return true if the CRS is projected, false otherwise |
|
100 |
*/ |
|
101 |
boolean isProjected(); |
|
102 |
|
|
103 |
/** |
|
104 |
* Gets the type of coordinate reference system |
|
105 |
* |
|
106 |
* @return |
|
107 |
*/ |
|
108 |
CRSType getType(); |
|
109 |
|
|
110 |
/** |
|
111 |
* FIXME: GeoAPI |
|
112 |
* Returns a <cite>Well-Known Text</cite> (WKT) for this object. |
|
113 |
* Well-Known Texts (WKT) may come in two formats: |
|
114 |
* |
|
115 |
* <ul> |
|
116 |
* <li>The current standard, WKT 2, is defined by ISO 19162.</li> |
|
117 |
* <li>The legacy format, WKT 1, was defined by {@linkplain org.opengis.annotation.Specification#OGC_01009 OGC 01-009} |
|
118 |
* and is shown using Extended Backus Naur Form (EBNF) <a href="doc-files/WKT.html">here</a>.</li> |
|
119 |
* </ul> |
|
120 |
* |
|
121 |
* Implementations are encouraged to format according the most recent standard. |
|
122 |
* This operation may fail if unsupported or if this instance contains elements that do not have |
|
123 |
* WKT representation. |
|
124 |
* |
|
125 |
* @return the Well-Known Text (WKT) for this object. |
|
126 |
* @throws UnsupportedOperationException if this object can not be formatted as WKT. |
|
127 |
* |
|
128 |
* @departure extension |
|
129 |
* This method is not part of the OGC specification. It has been added in order to provide |
|
130 |
* the converse of the <code>CRSFactory.createFromWKT(String)</code> method, which is |
|
131 |
* defined in OGC 01-009. |
|
132 |
* |
|
133 |
* @see org.opengis.referencing.crs.CRSFactory#createFromWKT(String) |
|
134 |
*/ |
|
135 |
String toWKT() throws UnsupportedOperationException; |
|
100 | 136 |
|
137 |
/** |
|
138 |
* FIXME: GeoAPI & review definition |
|
139 |
* The ordered list of coordinate reference systems. |
|
140 |
* |
|
141 |
* @return the ordered list of coordinate reference systems. |
|
142 |
* |
|
143 |
* @departure generalization |
|
144 |
* ISO 19111 said <cite>"nesting of compound CRSs shall not be permitted; the individual single systems |
|
145 |
* shall be aggregated together"</cite>. However this approach causes data lost: it is difficult to add |
|
146 |
* a temporal CRS to an existing three-dimensional compound CRS without loosing the name and identifiers |
|
147 |
* of the 3D CRS, unless nesting is permitted. It is programmatically easier to convert nested CRSs to a |
|
148 |
* flat list of single CRSs when needed than to reconstruct the 3D CRS from the single components. |
|
149 |
* Consequently GeoAPI has been keep conformant with the legacy OGC 01-009 specification in this aspect, |
|
150 |
* which were allowing nested compound CRS. |
|
151 |
* |
|
152 |
* @since 2.3 |
|
153 |
*/ |
|
154 |
List<CRSDefinition> getComponents(); |
|
155 |
|
|
156 |
/** |
|
157 |
* Gets the number of axis of the associated CoordinateSystem |
|
158 |
* |
|
159 |
* @return |
|
160 |
*/ |
|
161 |
int getAxisCount(); |
|
162 |
|
|
163 |
/** |
|
164 |
* Returns the axis for the associated coordinate system at the specified dimension, |
|
165 |
* as officially defined by the authority. |
|
166 |
* |
|
167 |
* @param dimension |
|
168 |
* @return |
|
169 |
* @throws IndexOutOfBoundsException |
|
170 |
*/ |
|
171 |
CoordinateSystemAxis getAxis(int dimension) throws IndexOutOfBoundsException; |
|
172 |
|
|
173 |
/** |
|
174 |
* Returns the axis for the associated coordinate system at the specified |
|
175 |
* dimension as internally used by gvSIG, which will sometimes differ from |
|
176 |
* the order officially defined by the authority. |
|
177 |
* |
|
178 |
* The internal order is used for convenience and performance. gvSIG geometries |
|
179 |
* and gvSIG coordinate transformations always expect coordinates to be provided |
|
180 |
* using the internal order (xy axis order). However, some |
|
181 |
* protocols or formats require the coordinates to be encoded using the |
|
182 |
* official order. |
|
183 |
* |
|
184 |
* @param dimension |
|
185 |
* @return |
|
186 |
* @throws IndexOutOfBoundsException |
|
187 |
*/ |
|
188 |
CoordinateSystemAxis getAxisInternal(int dimension) throws IndexOutOfBoundsException; |
|
189 |
|
|
101 | 190 |
/** |
102 |
* Description of domain of usage, or limitations of usage, for which this |
|
103 |
* Reference System object is valid. |
|
191 |
* For derived CRSs, it returns the base coordinate reference system. |
|
104 | 192 |
* |
105 |
* @return the domain of usage, or {@code null} if none. |
|
193 |
* @return the base coordinate reference system or null if the CRS is not |
|
194 |
* derived |
|
195 |
* @see CRSType#isDerived() |
|
196 |
* @see CRSType#ProjectedCRSType |
|
197 |
* @see CRSType#OtherDerivedCRSType |
|
198 |
*/ |
|
199 |
CRSDefinition getBaseCRS(); |
|
200 |
|
|
201 |
/** |
|
202 |
* For derived CRSs, it returns the conversion from the {@linkplain #getBaseCRS() base CRS} |
|
203 |
* to this CRS. |
|
106 | 204 |
* |
107 |
* @departure historic |
|
108 |
* This method was initially derived from the ISO 19111 specification published in 2003. |
|
109 |
* Later revision (ISO 19111:2007) differs in 3 aspects: |
|
110 |
* <ul> |
|
111 |
* <li>ISO 19111:2007 moved this property from this type to the {@code SC_CRS} subtype. |
|
112 |
* GeoAPI keeps this property here for historical reasons.</li> |
|
113 |
* <li>ISO 19111:2007 changed the obligation from optional to mandatory |
|
114 |
* and requires the value to be <cite>"not known"</cite> if the scope is unknown. |
|
115 |
* GeoAPI lefts the obligation unchanged: optional with {@code null} value for unknown scope.</li> |
|
116 |
* <li>ISO 19111:2007 changed the multiplicity from singleton to a collection. |
|
117 |
* GeoAPI keeps the singleton type for historical reasons.</li> |
|
118 |
* </ul> |
|
205 |
* @return the conversion from the base CRS or null if the CRS is not derived |
|
206 |
* |
|
207 |
* @see CRSType#isDerived() |
|
208 |
* @see CRSType#ProjectedCRSType |
|
209 |
* @see CRSType#OtherDerivedCRSType |
|
119 | 210 |
*/ |
120 |
String getScope(); |
|
211 |
TransformationDefinition getConversionFromBase(); |
|
212 |
|
|
213 |
/** |
|
214 |
* Returns the datum associated directly or indirectly to this CRS. |
|
215 |
* In the case of a derived CRS, this method returns the |
|
216 |
* datum of the {@linkplain #getBaseCRS() base CRS}. In the case of |
|
217 |
* a compound CRS, it returns the datum associated to the horizontal component. |
|
218 |
* |
|
219 |
* @return the datum |
|
220 |
*/ |
|
221 |
Datum getDatum(); |
|
121 | 222 |
} |
Also available in: Unified diff