001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-2024 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.referencing.operation;
019
020import java.util.Map;
021import org.opengis.referencing.IdentifiedObject;
022import org.opengis.parameter.ParameterDescriptorGroup;
023import org.opengis.annotation.UML;
024
025import static org.opengis.annotation.Obligation.*;
026import static org.opengis.annotation.Specification.*;
027
028
029/**
030 * Algorithm or procedure used to perform a coordinate operation.
031 * Most operation methods use a number of operation {@linkplain org.opengis.parameter.ParameterDescriptor parameters},
032 * although some coordinate conversions use none.
033 * Each {@linkplain CoordinateOperation coordinate operation} using the method assigns
034 * {@linkplain org.opengis.parameter.ParameterValue values} to these parameters.
035 *
036 * <p>As this class comes close to the heart of any coordinate transformation software,
037 * it is recommended to make extensive use of {@linkplain #getIdentifiers() identifiers},
038 * referencing well-known datasets wherever possible. The {@linkplain #getName() name} may be ambiguous
039 * because there is yet no standard way of spelling or naming the various coordinate operation methods.
040 * Client software requesting a coordinate operation to be executed by a coordinate transformation implementation may
041 * therefore ask for an operation method this server doesn't recognise, although a perfectly valid method may be available.
042 * Some recommended EPSG identifiers are reproduced below
043 * (see {@linkplain org.opengis.annotation.Specification#ISO_19162 ISO 19162}
044 * or the <a href="https://epsg.org/">EPSG repository</a> for a more complete list):</p>
045 *
046 * <table class="ogc">
047 *   <caption>EPSG identifier for some operation method names</caption>
048 *   <tr><th>Name</th>                                <th>Alias</th>                       <th>Identifier</th></tr>
049 *   <tr><td>Albers Equal Area</td>                   <td>Albers</td>                      <td>9822</td></tr>
050 *   <tr><td>Hotine Oblique Mercator (variant A)</td> <td>Rectified skew orthomorphic</td> <td>9812</td></tr>
051 *   <tr><td>Hotine Oblique Mercator (variant B)</td> <td>Rectified skew orthomorphic</td> <td>9815</td></tr>
052 *   <tr><td>Lambert Azimuthal Equal Area</td>        <td>Lambert Equal Area</td>          <td>9820</td></tr>
053 *   <tr><td>Lambert Conic Conformal (1SP)</td>       <td>Lambert Conic Conformal</td>     <td>9801</td></tr>
054 *   <tr><td>Lambert Conic Conformal (2SP)</td>       <td>Lambert Conic Conformal</td>     <td>9802</td></tr>
055 *   <tr><td>Mercator (variant A)</td>                <td>Mercator</td>                    <td>9804</td></tr>
056 *   <tr><td>Mercator (variant B)</td>                <td>Mercator</td>                    <td>9805</td></tr>
057 *   <tr><td>Oblique stereographic</td>               <td>Double stereographic</td>        <td>9809</td></tr>
058 *   <tr><td>Transverse Mercator</td>                 <td>Gauss-Boaga / Gauss-Krüger</td>  <td>9807</td></tr>
059 * </table>
060 *
061 * <h2>Example</h2>
062 * An operation method named <q>Mercator (variant A)</q> (EPSG:9804) declares the following parameters.
063 * Note that implementations can optionally assign
064 * {@linkplain org.opengis.parameter.ParameterDescriptor#getDefaultValue() default values} to those parameters.
065 * <ul>
066 *   <li><q>Latitude of natural origin</q> in degrees.</li>
067 *   <li><q>Longitude of natural origin</q> in degrees.</li>
068 *   <li><q>Scale factor at natural origin</q> as a dimensionless number.</li>
069 *   <li><q>False easting</q> in metres.</li>
070 *   <li><q>False northing</q> in metres.</li>
071 * </ul>
072 *
073 * @author  OGC Topic 2 (for abstract model and documentation)
074 * @author  Martin Desruisseaux (IRD, Geomatys)
075 * @version 3.1
076 * @since   1.0
077 *
078 * @see CoordinateOperation
079 * @see MathTransformFactory#getAvailableMethods(Class)
080 * @see CoordinateOperationFactory#getOperationMethod(String)
081 * @see CoordinateOperationAuthorityFactory#createOperationMethod(String)
082 * @see CoordinateOperationFactory#createOperationMethod(Map, ParameterDescriptorGroup)
083 */
084@UML(identifier="OperationMethod", specification=ISO_19111)
085public interface OperationMethod extends IdentifiedObject {
086    /*
087     * NOTE FOR JAVADOC WRITER:
088     * The "method" word is ambiguous here, because it can be "Java method" or "coordinate operation method".
089     * In this interface, we reserve "method" for coordinate operation methods as much as possible.
090     */
091
092    /**
093     * Key for the <code>{@value}</code> property.
094     * This is used for setting the value to be returned by {@link #getFormula()}.
095     *
096     * @see #getFormula()
097     */
098    String FORMULA_KEY = "formula";
099
100    /**
101     * Formula(s) or procedure used by this operation method. This may be a reference to a
102     * publication. Note that the operation method may not be analytic, in which case this
103     * attribute references or contains the procedure, not an analytic formula.
104     *
105     * @return the formula used by this method.
106     */
107    @UML(identifier="formulaReference", obligation=MANDATORY, specification=ISO_19111)
108    Formula getFormula();
109
110    /**
111     * Number of dimensions in the source CRS of this operation method.
112     * Note that some operation methods work with an arbitrary number of
113     * dimensions (e.g. <i>Affine Transform</i>) and may return {@code null}.
114     *
115     * @return the dimension of source CRS, or {@code null} if unknown.
116     *
117     * @see MathTransform#getSourceDimensions()
118     *
119     * @deprecated This attribute has been removed from ISO 19111:2019.
120     */
121    @Deprecated(since = "3.1")
122    @UML(identifier="sourceDimensions", obligation=OPTIONAL, specification=ISO_19111, version=2007)
123    default Integer getSourceDimensions() {
124        return null;
125    }
126
127    /**
128     * Number of dimensions in the target CRS of this operation method.
129     * Note that some operation methods work with an arbitrary number of
130     * dimensions (e.g. <i>Affine Transform</i>) and may return {@code null}.
131     *
132     * @return the dimension of target CRS, or {@code null} if unknown.
133     *
134     * @see MathTransform#getTargetDimensions()
135     *
136     * @deprecated This attribute has been removed from ISO 19111:2019.
137     */
138    @Deprecated(since = "3.1")
139    @UML(identifier="targetDimensions", obligation=OPTIONAL, specification=ISO_19111, version=2007)
140    default Integer getTargetDimensions() {
141        return null;
142    }
143
144    /**
145     * Returns the set of parameters.
146     * If the operation has no parameter, then this method shall return an empty group.
147     *
148     * @return the parameters, or an empty group (never {@code null}) if none.
149     *
150     * @departure easeOfUse
151     *   The sequence if {@code GeneralParameter} is replaced by a {@code ParameterGroup}
152     *   because it provides method for fetching parameters by their names.
153     *
154     * @see SingleOperation#getParameterValues()
155     */
156    @UML(identifier="parameter", obligation=OPTIONAL, specification=ISO_19111)
157    ParameterDescriptorGroup getParameters();
158}