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}