001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2013 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.referencing.crs;
033
034 import java.util.Map;
035 import org.opengis.referencing.cs.*;
036 import org.opengis.referencing.datum.*;
037 import org.opengis.referencing.operation.*;
038 import org.opengis.referencing.ObjectFactory;
039 import org.opengis.parameter.ParameterValueGroup; // For javadoc
040 import org.opengis.util.FactoryException;
041 import org.opengis.annotation.UML;
042
043 import static org.opengis.annotation.Specification.*;
044
045
046 /**
047 * Builds up complex {@linkplain CoordinateReferenceSystem coordinate reference systems}
048 * from simpler objects or values. {@code CRSFactory} allows applications to make
049 * {@linkplain CoordinateReferenceSystem coordinate reference systems} that cannot be
050 * created by a {@link CRSAuthorityFactory}. This factory is very flexible, whereas the
051 * authority factory is easier to use.
052 * So {@link CRSAuthorityFactory} can be used to make "standard" coordinate reference systems,
053 * and {@code CRSFactory} can be used to make "special" coordinate reference systems.
054 *
055 * <p>For example, the EPSG authority has codes for USA state plane coordinate systems
056 * using the NAD83 datum, but these coordinate systems always use meters. EPSG does
057 * not have codes for NAD83 state plane coordinate systems that use feet units. This
058 * factory lets an application create such a hybrid coordinate system.</p>
059 *
060 * @author Martin Desruisseaux (IRD)
061 * @version 3.0
062 * @since 1.0
063 *
064 * @see org.opengis.referencing.cs.CSFactory
065 * @see org.opengis.referencing.datum.DatumFactory
066 */
067 @UML(identifier="CS_CoordinateSystemFactory", specification=OGC_01009)
068 public interface CRSFactory extends ObjectFactory {
069 /**
070 * Creates a compound coordinate reference system from an ordered
071 * list of {@code CoordinateReferenceSystem} objects.
072 *
073 * @param properties Name and other properties to give to the new object.
074 * Available properties are {@linkplain ObjectFactory listed there}.
075 * @param elements ordered array of {@code CoordinateReferenceSystem} objects.
076 * @return The coordinate reference system for the given properties.
077 * @throws FactoryException if the object creation failed.
078 */
079 @UML(identifier="createCompoundCoordinateSystem", specification=OGC_01009)
080 CompoundCRS createCompoundCRS(Map<String, ?> properties,
081 CoordinateReferenceSystem... elements) throws FactoryException;
082
083 /**
084 * Creates a engineering coordinate reference system.
085 *
086 * @param properties Name and other properties to give to the new object.
087 * Available properties are {@linkplain ObjectFactory listed there}.
088 * @param datum Engineering datum to use in created CRS.
089 * @param cs The coordinate system for the created CRS.
090 * @return The coordinate reference system for the given properties.
091 * @throws FactoryException if the object creation failed.
092 */
093 @UML(identifier="createLocalCoordinateSystem", specification=OGC_01009)
094 EngineeringCRS createEngineeringCRS(Map<String, ?> properties,
095 EngineeringDatum datum,
096 CoordinateSystem cs) throws FactoryException;
097
098 /**
099 * Creates an image coordinate reference system.
100 *
101 * @param properties Name and other properties to give to the new object.
102 * Available properties are {@linkplain ObjectFactory listed there}.
103 * @param datum Image datum to use in created CRS.
104 * @param cs The Cartesian or Oblique Cartesian coordinate system for the created CRS.
105 * @return The coordinate reference system for the given properties.
106 * @throws FactoryException if the object creation failed.
107 */
108 ImageCRS createImageCRS(Map<String, ?> properties,
109 ImageDatum datum,
110 AffineCS cs) throws FactoryException;
111
112 /**
113 * Creates a temporal coordinate reference system.
114 *
115 * @param properties Name and other properties to give to the new object.
116 * Available properties are {@linkplain ObjectFactory listed there}.
117 * @param datum Temporal datum to use in created CRS.
118 * @param cs The Temporal coordinate system for the created CRS.
119 * @return The coordinate reference system for the given properties.
120 * @throws FactoryException if the object creation failed.
121 */
122 TemporalCRS createTemporalCRS(Map<String, ?> properties,
123 TemporalDatum datum,
124 TimeCS cs) throws FactoryException;
125
126 /**
127 * Creates a vertical coordinate reference system.
128 *
129 * @param properties Name and other properties to give to the new object.
130 * Available properties are {@linkplain ObjectFactory listed there}.
131 * @param datum Vertical datum to use in created CRS.
132 * @param cs The Vertical coordinate system for the created CRS.
133 * @return The coordinate reference system for the given properties.
134 * @throws FactoryException if the object creation failed.
135 */
136 @UML(identifier="createVerticalCoordinateSystem", specification=OGC_01009)
137 VerticalCRS createVerticalCRS(Map<String, ?> properties,
138 VerticalDatum datum,
139 VerticalCS cs) throws FactoryException;
140
141 /**
142 * Creates a geocentric coordinate reference system from a {@linkplain CartesianCS
143 * cartesian coordinate system}.
144 *
145 * @param properties Name and other properties to give to the new object.
146 * Available properties are {@linkplain ObjectFactory listed there}.
147 * @param datum Geodetic datum to use in created CRS.
148 * @param cs The cartesian coordinate system for the created CRS.
149 * @return The coordinate reference system for the given properties.
150 * @throws FactoryException if the object creation failed.
151 */
152 GeocentricCRS createGeocentricCRS(Map<String, ?> properties,
153 GeodeticDatum datum,
154 CartesianCS cs) throws FactoryException;
155
156 /**
157 * Creates a geocentric coordinate reference system from a {@linkplain SphericalCS
158 * spherical coordinate system}.
159 *
160 * @param properties Name and other properties to give to the new object.
161 * Available properties are {@linkplain ObjectFactory listed there}.
162 * @param datum Geodetic datum to use in created CRS.
163 * @param cs The spherical coordinate system for the created CRS.
164 * @return The coordinate reference system for the given properties.
165 * @throws FactoryException if the object creation failed.
166 */
167 GeocentricCRS createGeocentricCRS(Map<String, ?> properties,
168 GeodeticDatum datum,
169 SphericalCS cs) throws FactoryException;
170
171 /**
172 * Creates a geographic coordinate reference system.
173 * It could be <var>Latitude</var>/<var>Longitude</var> or
174 * <var>Longitude</var>/<var>Latitude</var>.
175 *
176 * @param properties Name and other properties to give to the new object.
177 * Available properties are {@linkplain ObjectFactory listed there}.
178 * @param datum Geodetic datum to use in created CRS.
179 * @param cs The ellipsoidal coordinate system for the created CRS.
180 * @return The coordinate reference system for the given properties.
181 * @throws FactoryException if the object creation failed.
182 */
183 @UML(identifier="createGeographicCoordinateSystem", specification=OGC_01009)
184 GeographicCRS createGeographicCRS(Map<String, ?> properties,
185 GeodeticDatum datum,
186 EllipsoidalCS cs) throws FactoryException;
187
188 /**
189 * Creates a derived coordinate reference system. If the transform is an affine
190 * map performing a rotation, then any mixed axes must have identical units.
191 * For example, a (<var>lat_deg</var>, <var>lon_deg</var>, <var>height_feet</var>)
192 * system can be rotated in the (<var>lat</var>, <var>lon</var>) plane, since both
193 * affected axes are in degrees. But the transform should not rotate this coordinate
194 * system in any other plane.
195 *
196 * <p>The {@code conversionFromBase} shall contains the {@linkplain Conversion#getParameterValues
197 * parameter values} required for the conversion. It may or may not contain the corresponding
198 * "{@linkplain Conversion#getMathTransform base to derived}" transform, at user's choice. If
199 * a transform is provided, this method may or may not use it at implementation choice.
200 * Otherwise it shall creates the transform from the parameters.</p>
201 *
202 * <p>It is the user's responsibility to ensure that the conversion performs all required steps,
203 * including unit conversions and change of axis order, if needed. Note that this behavior is
204 * different than {@link #createProjectedCRS createProjectedCRS} because transforms other than
205 * <cite>cartographic projections</cite> are not standardized.</p>
206 *
207 * @param properties Name and other properties to give to the new object.
208 * Available properties are {@linkplain ObjectFactory listed there}.
209 * @param baseCRS Coordinate reference system to base the projection on. The number of axes
210 * must matches the {@linkplain OperationMethod#getSourceDimensions source dimensions}
211 * of the conversion from base.
212 * @param conversionFromBase The
213 * {@linkplain CoordinateOperationFactory#createDefiningConversion defining conversion}.
214 * @param derivedCS The coordinate system for the derived CRS. The number of axes must matches
215 * the {@linkplain OperationMethod#getTargetDimensions target dimensions} of the conversion
216 * from base.
217 * @return The coordinate reference system for the given properties.
218 * @throws FactoryException if the object creation failed.
219 *
220 * @see CoordinateOperationFactory#createDefiningConversion(Map, OperationMethod, ParameterValueGroup)
221 * @see MathTransformFactory#createBaseToDerived(CoordinateReferenceSystem, ParameterValueGroup, CoordinateSystem)
222 *
223 * @since 2.1
224 */
225 @UML(identifier="createFittedCoordinateSystem", specification=OGC_01009)
226 DerivedCRS createDerivedCRS(Map<String,?> properties,
227 CoordinateReferenceSystem baseCRS,
228 Conversion conversionFromBase,
229 CoordinateSystem derivedCS) throws FactoryException;
230
231 /**
232 * Creates a projected coordinate reference system from a defining conversion.
233 * The {@code conversionFromBase} shall contains the {@linkplain Conversion#getParameterValues
234 * parameter values} required for the projection. It may or may not contain the corresponding
235 * "{@linkplain Conversion#getMathTransform base to derived}" transform, at user's choice. If
236 * a transform is provided, this method may or may not use it at implementation choice.
237 * Otherwise it shall creates the transform from the parameters.
238 *
239 * <p>The supplied conversion should <strong>not</strong> includes the operation steps for
240 * performing {@linkplain CoordinateSystemAxis#getUnit unit} conversions and change of
241 * {@linkplain CoordinateSystem#getAxis axis} order; those operations shall be inferred
242 * by this constructor by some code equivalent to:</p>
243 *
244 * <blockquote><code>
245 * MathTransform baseToDerived = {@linkplain MathTransformFactory#createBaseToDerived
246 * MathTransformFactory.createBaseToDerived}(baseCRS, parameters, derivedCS)
247 * </code></blockquote>
248 *
249 * This behavior is different than {@link #createDerivedCRS createDerivedCRS} because
250 * parameterized transforms are standardized for projections. See the {@linkplain
251 * MathTransformFactory#createParameterizedTransform note on cartographic projections}.
252 *
253 * @param properties Name and other properties to give to the new object.
254 * Available properties are {@linkplain ObjectFactory listed there}.
255 * @param baseCRS Geographic coordinate reference system to base the projection on. The number
256 * of axes must matches the {@linkplain OperationMethod#getSourceDimensions source dimensions}
257 * of the conversion from base.
258 * @param conversionFromBase The
259 * {@linkplain CoordinateOperationFactory#createDefiningConversion defining conversion}.
260 * @param derivedCS The coordinate system for the projected CRS. The number of axes must matches
261 * the {@linkplain OperationMethod#getTargetDimensions target dimensions} of the conversion
262 * from base.
263 * @return The coordinate reference system for the given properties.
264 * @throws FactoryException if the object creation failed.
265 *
266 * @see CoordinateOperationFactory#createDefiningConversion(Map, OperationMethod, ParameterValueGroup)
267 * @see MathTransformFactory#createBaseToDerived(CoordinateReferenceSystem, ParameterValueGroup, CoordinateSystem)
268 *
269 * @since 2.1
270 */
271 @UML(identifier="createProjectedCoordinateSystem", specification=OGC_01009)
272 ProjectedCRS createProjectedCRS(Map<String,?> properties,
273 GeographicCRS baseCRS,
274 Conversion conversionFromBase,
275 CartesianCS derivedCS) throws FactoryException;
276
277 /**
278 * Creates a coordinate reference system object from a XML string.
279 *
280 * @param xml Coordinate reference system encoded in XML format.
281 * @return The coordinate reference system for the given XML.
282 * @throws FactoryException if the object creation failed.
283 */
284 @UML(identifier="createFromXML", specification=OGC_01009)
285 CoordinateReferenceSystem createFromXML(String xml) throws FactoryException;
286
287 /**
288 * Creates a coordinate reference system object from a string.
289 * The <a href="../doc-files/WKT.html">definition for WKT</a>
290 * is shown using Extended Backus Naur Form (EBNF).
291 *
292 * @param wkt Coordinate system encoded in Well-Known Text format.
293 * @return The coordinate reference system for the given WKT.
294 * @throws FactoryException if the object creation failed.
295 */
296 @UML(identifier="createFromWKT", specification=OGC_01009)
297 CoordinateReferenceSystem createFromWKT(String wkt) throws FactoryException;
298 }