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.operation;
033
034 import java.util.Collection;
035 import org.opengis.referencing.IdentifiedObject;
036 import org.opengis.referencing.crs.CoordinateReferenceSystem;
037 import org.opengis.metadata.quality.PositionalAccuracy;
038 import org.opengis.metadata.extent.Extent;
039 import org.opengis.util.InternationalString;
040 import org.opengis.annotation.UML;
041 import org.opengis.annotation.Classifier;
042 import org.opengis.annotation.Stereotype;
043
044 import static org.opengis.annotation.Obligation.*;
045 import static org.opengis.annotation.Specification.*;
046
047
048 /**
049 * A mathematical operation on coordinates that transforms or converts coordinates to
050 * another coordinate reference system. Many but not all coordinate operations (from
051 * {@linkplain CoordinateReferenceSystem coordinate reference system} <var>A</var> to
052 * {@linkplain CoordinateReferenceSystem coordinate reference system} <var>B</var>)
053 * also uniquely define the inverse operation (from
054 * {@linkplain CoordinateReferenceSystem coordinate reference system} <var>B</var> to
055 * {@linkplain CoordinateReferenceSystem coordinate reference system} <var>A</var>).
056 * In some cases, the operation method algorithm for the inverse operation is the same
057 * as for the forward algorithm, but the signs of some operation parameter values must
058 * be reversed. In other cases, different algorithms are required for the forward and
059 * inverse operations, but the same operation parameter values are used. If (some)
060 * entirely different parameter values are needed, a different coordinate operation
061 * shall be defined.
062 *
063 * @author Martin Desruisseaux (IRD)
064 * @version 3.1
065 * @since 1.0
066 *
067 * @navassoc 2 - - CoordinateReferenceSystem
068 * @navassoc - - - PositionalAccuracy
069 * @navassoc - - - Extent
070 * @navassoc 1 - - MathTransform
071 *
072 * @see CoordinateOperationAuthorityFactory#createCoordinateOperation(String)
073 * @see CoordinateOperationAuthorityFactory#createFromCoordinateReferenceSystemCodes(String, String)
074 * @see CoordinateOperationFactory#createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem)
075 */
076 @Classifier(Stereotype.ABSTRACT)
077 @UML(identifier="CC_CoordinateOperation", specification=ISO_19111)
078 public interface CoordinateOperation extends IdentifiedObject {
079 /**
080 * Key for the <code>{@value}</code> property.
081 * This is used for setting the value to be returned by {@link #getOperationVersion()}.
082 *
083 * @see #getOperationVersion()
084 */
085 String OPERATION_VERSION_KEY = "operationVersion";
086
087 /**
088 * Key for the <code>{@value}</code> property.
089 * This is used for setting the value to be returned by {@link #getCoordinateOperationAccuracy()}.
090 *
091 * @see #getCoordinateOperationAccuracy()
092 *
093 * @since 2.1
094 */
095 String COORDINATE_OPERATION_ACCURACY_KEY = "coordinateOperationAccuracy";
096
097 /**
098 * Key for the <code>{@value}</code> property.
099 * This is used for setting the value to be returned by {@link #getDomainOfValidity()}.
100 *
101 * @see #getDomainOfValidity()
102 *
103 * @since 2.1
104 */
105 String DOMAIN_OF_VALIDITY_KEY = "domainOfValidity";
106
107 /**
108 * Key for the <code>{@value}</code> property.
109 * This is used for setting the value to be returned by {@link #getScope()}.
110 *
111 * @see #getScope()
112 */
113 String SCOPE_KEY = "scope";
114
115 /**
116 * Returns the source CRS. The source CRS is mandatory for {@linkplain Transformation
117 * transformations} only. {@linkplain Conversion Conversions} may have a source CRS that
118 * is not specified here, but through
119 * {@link org.opengis.referencing.crs.GeneralDerivedCRS#getBaseCRS()} instead.
120 *
121 * @return The source CRS, or {@code null} if not available.
122 *
123 * @see Conversion#getSourceCRS()
124 * @see Transformation#getSourceCRS()
125 */
126 @UML(identifier="sourceCRS", obligation=CONDITIONAL, specification=ISO_19111)
127 CoordinateReferenceSystem getSourceCRS();
128
129 /**
130 * Returns the target CRS. The target CRS is mandatory for {@linkplain Transformation
131 * transformations} only. {@linkplain Conversion Conversions} may have a target CRS
132 * that is not specified here, but through
133 * {@link org.opengis.referencing.crs.GeneralDerivedCRS} instead.
134 *
135 * @return The target CRS, or {@code null} if not available.
136 *
137 * @see Conversion#getTargetCRS()
138 * @see Transformation#getTargetCRS()
139 */
140 @UML(identifier="targetCRS", obligation=CONDITIONAL, specification=ISO_19111)
141 CoordinateReferenceSystem getTargetCRS();
142
143 /**
144 * Version of the coordinate transformation (i.e., instantiation due to the stochastic
145 * nature of the parameters). Mandatory when describing a transformation, and should not
146 * be supplied for a conversion.
147 *
148 * @return The coordinate operation version, or {@code null} in none.
149 */
150 @UML(identifier="operationVersion", obligation=CONDITIONAL, specification=ISO_19111)
151 String getOperationVersion();
152
153 /**
154 * Estimate(s) of the impact of this operation on point accuracy. Gives
155 * position error estimates for target coordinates of this coordinate
156 * operation, assuming no errors in source coordinates.
157 *
158 * @return The position error estimates, or an empty collection if not available.
159 *
160 * @since 2.1
161 */
162 @UML(identifier="coordinateOperationAccuracy", obligation=OPTIONAL, specification=ISO_19111)
163 Collection<PositionalAccuracy> getCoordinateOperationAccuracy();
164
165 /**
166 * Area or region or timeframe in which this coordinate operation is valid.
167 *
168 * @return The coordinate operation valid domain, or {@code null} if not available.
169 *
170 * @since 2.1
171 */
172 @UML(identifier="domainOfValidity", obligation=OPTIONAL, specification=ISO_19111)
173 Extent getDomainOfValidity();
174
175 /**
176 * Description of domain of usage, or limitations of usage, for which this operation is valid.
177 *
178 * @return A description of domain of usage, or {@code null} if none.
179 *
180 * @departure historic
181 * This method has been kept conformant with the specification published in 2003.
182 * The revision published in 2007 replaced the singleton by a collection and changed the
183 * obligation from "optional" to "mandatory", requiring a return value of
184 * "<cite>not known</cite>" if the scope is unknown. This change is still under review.
185 */
186 @UML(identifier="scope", obligation=OPTIONAL, specification=ISO_19111)
187 InternationalString getScope();
188
189 /**
190 * Gets the math transform. The math transform will transform positions in the
191 * {@linkplain #getSourceCRS source coordinate reference system} into positions in the
192 * {@linkplain #getTargetCRS target coordinate reference system}. It may be {@code null}
193 * in the case of {@linkplain CoordinateOperationFactory#createDefiningConversion
194 * defining conversions}.
195 *
196 * @return The transform from source to target CRS, or {@code null} if not applicable.
197 */
198 @UML(identifier="CT_CoordinateTransformation.getMathTransform", specification=OGC_01009)
199 MathTransform getMathTransform();
200 }