001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 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 * <p>
053 * So {@link CRSAuthorityFactory} can be used to make "standard" coordinate reference systems,
054 * and {@code CRSFactory} can be used to make "special" coordinate reference systems.
055 * <p>
056 * For example, the EPSG authority has codes for USA state plane coordinate systems
057 * using the NAD83 datum, but these coordinate systems always use meters. EPSG does
058 * not have codes for NAD83 state plane coordinate systems that use feet units. This
059 * factory lets an application create such a hybrid coordinate system.
060 *
061 * @author Martin Desruisseaux (IRD)
062 * @version 3.0
063 * @since 1.0
064 *
065 * @see org.opengis.referencing.cs.CSFactory
066 * @see org.opengis.referencing.datum.DatumFactory
067 */
068 @UML(identifier="CS_CoordinateSystemFactory", specification=OGC_01009)
069 public interface CRSFactory extends ObjectFactory {
070 /**
071 * Creates a compound coordinate reference system from an ordered
072 * list of {@code CoordinateReferenceSystem} objects.
073 *
074 * @param properties Name and other properties to give to the new object.
075 * Available properties are {@linkplain ObjectFactory listed there}.
076 * @param elements ordered array of {@code CoordinateReferenceSystem} objects.
077 * @return The coordinate reference system for the given properties.
078 * @throws FactoryException if the object creation failed.
079 */
080 @UML(identifier="createCompoundCoordinateSystem", specification=OGC_01009)
081 CompoundCRS createCompoundCRS(Map<String, ?> properties,
082 CoordinateReferenceSystem... elements) throws FactoryException;
083
084 /**
085 * Creates a engineering coordinate reference system.
086 *
087 * @param properties Name and other properties to give to the new object.
088 * Available properties are {@linkplain ObjectFactory listed there}.
089 * @param datum Engineering datum to use in created CRS.
090 * @param cs The coordinate system for the created CRS.
091 * @return The coordinate reference system for the given properties.
092 * @throws FactoryException if the object creation failed.
093 */
094 @UML(identifier="createLocalCoordinateSystem", specification=OGC_01009)
095 EngineeringCRS createEngineeringCRS(Map<String, ?> properties,
096 EngineeringDatum datum,
097 CoordinateSystem cs) throws FactoryException;
098
099 /**
100 * Creates an image coordinate reference system.
101 *
102 * @param properties Name and other properties to give to the new object.
103 * Available properties are {@linkplain ObjectFactory listed there}.
104 * @param datum Image datum to use in created CRS.
105 * @param cs The Cartesian or Oblique Cartesian coordinate system for the created CRS.
106 * @return The coordinate reference system for the given properties.
107 * @throws FactoryException if the object creation failed.
108 */
109 ImageCRS createImageCRS(Map<String, ?> properties,
110 ImageDatum datum,
111 AffineCS cs) throws FactoryException;
112
113 /**
114 * Creates a temporal coordinate reference system.
115 *
116 * @param properties Name and other properties to give to the new object.
117 * Available properties are {@linkplain ObjectFactory listed there}.
118 * @param datum Temporal datum to use in created CRS.
119 * @param cs The Temporal coordinate system for the created CRS.
120 * @return The coordinate reference system for the given properties.
121 * @throws FactoryException if the object creation failed.
122 */
123 TemporalCRS createTemporalCRS(Map<String, ?> properties,
124 TemporalDatum datum,
125 TimeCS cs) throws FactoryException;
126
127 /**
128 * Creates a vertical coordinate reference system.
129 *
130 * @param properties Name and other properties to give to the new object.
131 * Available properties are {@linkplain ObjectFactory listed there}.
132 * @param datum Vertical datum to use in created CRS.
133 * @param cs The Vertical coordinate system for the created CRS.
134 * @return The coordinate reference system for the given properties.
135 * @throws FactoryException if the object creation failed.
136 */
137 @UML(identifier="createVerticalCoordinateSystem", specification=OGC_01009)
138 VerticalCRS createVerticalCRS(Map<String, ?> properties,
139 VerticalDatum datum,
140 VerticalCS cs) throws FactoryException;
141
142 /**
143 * Creates a geocentric coordinate reference system from a {@linkplain CartesianCS
144 * cartesian coordinate system}.
145 *
146 * @param properties Name and other properties to give to the new object.
147 * Available properties are {@linkplain ObjectFactory listed there}.
148 * @param datum Geodetic datum to use in created CRS.
149 * @param cs The cartesian coordinate system for the created CRS.
150 * @return The coordinate reference system for the given properties.
151 * @throws FactoryException if the object creation failed.
152 */
153 GeocentricCRS createGeocentricCRS(Map<String, ?> properties,
154 GeodeticDatum datum,
155 CartesianCS cs) throws FactoryException;
156
157 /**
158 * Creates a geocentric coordinate reference system from a {@linkplain SphericalCS
159 * spherical coordinate system}.
160 *
161 * @param properties Name and other properties to give to the new object.
162 * Available properties are {@linkplain ObjectFactory listed there}.
163 * @param datum Geodetic datum to use in created CRS.
164 * @param cs The spherical coordinate system for the created CRS.
165 * @return The coordinate reference system for the given properties.
166 * @throws FactoryException if the object creation failed.
167 */
168 GeocentricCRS createGeocentricCRS(Map<String, ?> properties,
169 GeodeticDatum datum,
170 SphericalCS cs) throws FactoryException;
171
172 /**
173 * Creates a geographic coordinate reference system.
174 * It could be <var>Latitude</var>/<var>Longitude</var> or
175 * <var>Longitude</var>/<var>Latitude</var>.
176 *
177 * @param properties Name and other properties to give to the new object.
178 * Available properties are {@linkplain ObjectFactory listed there}.
179 * @param datum Geodetic datum to use in created CRS.
180 * @param cs The ellipsoidal coordinate system for the created CRS.
181 * @return The coordinate reference system for the given properties.
182 * @throws FactoryException if the object creation failed.
183 */
184 @UML(identifier="createGeographicCoordinateSystem", specification=OGC_01009)
185 GeographicCRS createGeographicCRS(Map<String, ?> properties,
186 GeodeticDatum datum,
187 EllipsoidalCS cs) throws FactoryException;
188
189 /**
190 * Creates a derived coordinate reference system. If the transform is an affine
191 * map performing a rotation, then any mixed axes must have identical units.
192 * For example, a (<var>lat_deg</var>, <var>lon_deg</var>, <var>height_feet</var>)
193 * system can be rotated in the (<var>lat</var>, <var>lon</var>) plane, since both
194 * affected axes are in degrees. But the transform should not rotate this coordinate
195 * system in any other plane.
196 * <p>
197 * The {@code conversionFromBase} shall contains the {@linkplain Conversion#getParameterValues
198 * parameter values} required for the conversion. It may or may not contain the corresponding
199 * "{@linkplain Conversion#getMathTransform base to derived}" transform, at user's choice. If
200 * a transform is provided, this method may or may not use it at implementation choice.
201 * Otherwise it shall creates the transform from the parameters.
202 * <p>
203 * It is the user's responsibility to ensure that the conversion performs all required steps,
204 * including unit conversions and change of axis order, if needed. Note that this behavior is
205 * different than {@link #createProjectedCRS createProjectedCRS} because transforms other than
206 * <cite>cartographic projections</cite> are not standardized.
207 *
208 * @param properties Name and other properties to give to the new object.
209 * Available properties are {@linkplain ObjectFactory listed there}.
210 * @param baseCRS Coordinate reference system to base the projection on. The number of axes
211 * must matches the {@linkplain OperationMethod#getSourceDimensions source dimensions}
212 * of the conversion from base.
213 * @param conversionFromBase The
214 * {@linkplain CoordinateOperationFactory#createDefiningConversion defining conversion}.
215 * @param derivedCS The coordinate system for the derived CRS. The number of axes must matches
216 * the {@linkplain OperationMethod#getTargetDimensions target dimensions} of the conversion
217 * from base.
218 * @return The coordinate reference system for the given properties.
219 * @throws FactoryException if the object creation failed.
220 *
221 * @see CoordinateOperationFactory#createDefiningConversion(Map, OperationMethod, ParameterValueGroup)
222 * @see MathTransformFactory#createBaseToDerived(CoordinateReferenceSystem, ParameterValueGroup, CoordinateSystem)
223 *
224 * @since 2.1
225 */
226 @UML(identifier="createFittedCoordinateSystem", specification=OGC_01009)
227 DerivedCRS createDerivedCRS(Map<String,?> properties,
228 CoordinateReferenceSystem baseCRS,
229 Conversion conversionFromBase,
230 CoordinateSystem derivedCS) throws FactoryException;
231
232 /**
233 * Creates a projected coordinate reference system from a defining conversion.
234 * The {@code conversionFromBase} shall contains the {@linkplain Conversion#getParameterValues
235 * parameter values} required for the projection. It may or may not contain the corresponding
236 * "{@linkplain Conversion#getMathTransform base to derived}" transform, at user's choice. If
237 * a transform is provided, this method may or may not use it at implementation choice.
238 * Otherwise it shall creates the transform from the parameters.
239 * <p>
240 * The supplied conversion should <strong>not</strong> includes the operation steps for
241 * performing {@linkplain CoordinateSystemAxis#getUnit unit} conversions and change of
242 * {@linkplain CoordinateSystem#getAxis axis} order; those operations shall be inferred
243 * by this constructor by some code equivalent to:
244 *
245 * <blockquote><code>
246 * MathTransform baseToDerived = {@linkplain MathTransformFactory#createBaseToDerived
247 * MathTransformFactory.createBaseToDerived}(baseCRS, parameters, derivedCS)
248 * </code></blockquote>
249 *
250 * This behavior is different than {@link #createDerivedCRS createDerivedCRS} because
251 * parameterized transforms are standardized for projections. See the {@linkplain
252 * MathTransformFactory#createParameterizedTransform note on cartographic projections}.
253 *
254 * @param properties Name and other properties to give to the new object.
255 * Available properties are {@linkplain ObjectFactory listed there}.
256 * @param baseCRS Geographic coordinate reference system to base the projection on. The number
257 * of axes must matches the {@linkplain OperationMethod#getSourceDimensions source dimensions}
258 * of the conversion from base.
259 * @param conversionFromBase The
260 * {@linkplain CoordinateOperationFactory#createDefiningConversion defining conversion}.
261 * @param derivedCS The coordinate system for the projected CRS. The number of axes must matches
262 * the {@linkplain OperationMethod#getTargetDimensions target dimensions} of the conversion
263 * from base.
264 * @return The coordinate reference system for the given properties.
265 * @throws FactoryException if the object creation failed.
266 *
267 * @see CoordinateOperationFactory#createDefiningConversion(Map, OperationMethod, ParameterValueGroup)
268 * @see MathTransformFactory#createBaseToDerived(CoordinateReferenceSystem, ParameterValueGroup, CoordinateSystem)
269 *
270 * @since 2.1
271 */
272 @UML(identifier="createProjectedCoordinateSystem", specification=OGC_01009)
273 ProjectedCRS createProjectedCRS(Map<String,?> properties,
274 GeographicCRS baseCRS,
275 Conversion conversionFromBase,
276 CartesianCS derivedCS) throws FactoryException;
277
278 /**
279 * Creates a coordinate reference system object from a XML string.
280 *
281 * @param xml Coordinate reference system encoded in XML format.
282 * @return The coordinate reference system for the given XML.
283 * @throws FactoryException if the object creation failed.
284 */
285 @UML(identifier="createFromXML", specification=OGC_01009)
286 CoordinateReferenceSystem createFromXML(String xml) throws FactoryException;
287
288 /**
289 * Creates a coordinate reference system object from a string.
290 * The <A HREF="../doc-files/WKT.html">definition for WKT</A>
291 * is shown using Extended Backus Naur Form (EBNF).
292 *
293 * @param wkt Coordinate system encoded in Well-Known Text format.
294 * @return The coordinate reference system for the given WKT.
295 * @throws FactoryException if the object creation failed.
296 */
297 @UML(identifier="createFromWKT", specification=OGC_01009)
298 CoordinateReferenceSystem createFromWKT(String wkt) throws FactoryException;
299 }