001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2009-2023 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.Set;
021import org.opengis.util.FactoryException;
022import org.opengis.referencing.AuthorityFactory;
023import org.opengis.referencing.NoSuchAuthorityCodeException;
024import org.opengis.referencing.crs.CoordinateReferenceSystem;
025import org.opengis.referencing.datum.DatumEnsemble;
026import org.opengis.annotation.UML;
027
028import static org.opengis.annotation.Specification.*;
029
030
031/**
032 * Services supported by the coordinate operation packages.
033 *
034 * @author  OGC Topic 2 (for abstract model and documentation)
035 * @author  Martin Desruisseaux (Geomatys)
036 * @version 3.1
037 * @since   3.1
038 */
039@UML(identifier="RegisterOperations", specification=ISO_19111)
040public interface RegisterOperations extends AuthorityFactory {
041    /**
042     * Extracts <abbr>CRS</abbr> details from the registry.
043     *
044     * @param  code  <abbr>CRS</abbr> identifier allocated by the authority.
045     * @return the <abbr>CRS</abbr> for the given authority code.
046     * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
047     * @throws FactoryException if the object creation failed for some other reason.
048     */
049    @UML(identifier="findCoordinateReferenceSystem", specification=ISO_19111)
050    CoordinateReferenceSystem findCoordinateReferenceSystem(String code) throws FactoryException;
051
052    /**
053     * Extracts coordinate operation details from the registry.
054     *
055     * @param  code  operation identifier allocated by the authority.
056     * @return the operation for the given authority code.
057     * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
058     * @throws FactoryException if the object creation failed for some other reason.
059     */
060    @UML(identifier="findCoordinateOperation", specification=ISO_19111)
061    CoordinateOperation findCoordinateOperation(String code) throws FactoryException;
062
063    /**
064     * Finds or infers any coordinate operations for which the given <abbr>CRS</abbr>s are the source and target,
065     * in that order.
066     *
067     * <h4>Implementation considerations</h4>
068     * Coordinate transformation services should be able to automatically derive coordinate operations
069     * that are not stored explicitly in any permanent data store, in other words determine their own
070     * concatenated or inverse operations. The reason is that it is practically impossible to store
071     * all possible pairs of coordinate reference systems in explicitly defined coordinate operations.
072     *
073     * <p>Coordinate transformation services should also be able to derive or infer the inverse of any
074     * coordinate operation (from <var>B</var> to <var>A</var>) from its complementary forward operation
075     * (<var>A</var> to <var>B</var>). Geodetic datasets may record
076     * only one of the two operations that may exist between any two coordinate reference systems.
077     * The inverse operation is then inferred by the application software logic from the stored operation.
078     * In some cases, the algorithm for the inverse operation is the same as the forward algorithm,
079     * and only the signs of the parameter values reversed.
080     * In some other cases, the forward and inverse methods imply two algorithms, but the parameters values are the same.
081     * The latter situation generally applies to map projections.</p>
082     *
083     * <p>The implementation should apply meaningful constraints and validations to this process.
084     * For example, it may be mathematically possible to derive a concatenated coordinate operation
085     * that will transform North American Datum 1983 coordinates to Australian National Datum,
086     * but in a practical sense that operation would be meaningless.
087     * The operation can be determined as invalid with a comparison of the two areas of validity
088     * and the conclusion that there is no overlap between these.</p>
089     *
090     * @param  source  the source <abbr>CRS</abbr>.
091     * @param  target  the target <abbr>CRS</abbr>.
092     * @return coordinate operations found or inferred between the given pair <abbr>CRS</abbr>s. May be an empty set.
093     * @throws FactoryException if an error occurred while searching for coordinate operations.
094     */
095    @UML(identifier="findCoordinateOperations", specification=ISO_19111)
096    Set<CoordinateOperation> findCoordinateOperations(CoordinateReferenceSystem source, CoordinateReferenceSystem target)
097            throws FactoryException;
098
099    /**
100     * Determine whether two <abbr>CRS</abbr>s are members of one ensemble.
101     * If this method returns {@code true}, then for low accuracy purposes coordinate sets referenced
102     * to these <abbr>CRS</abbr>s may be merged without coordinate transformation.
103     * The attribute {@link DatumEnsemble#getEnsembleAccuracy()} gives some indication
104     * of the inaccuracy introduced through such merger.
105     *
106     * @param  source  the source <abbr>CRS</abbr>.
107     * @param  target  the target <abbr>CRS</abbr>.
108     * @return whether the two <abbr>CRS</abbr>s are members of one ensemble.
109     * @throws FactoryException if an error occurred while searching for ensemble information in the registry.
110     */
111    @UML(identifier="areMembersOfSameEnsemble", specification=ISO_19111)
112    boolean areMembersOfSameEnsemble(CoordinateReferenceSystem source, CoordinateReferenceSystem target)
113            throws FactoryException;
114}