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