001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-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.Optional;
021import java.util.Collection;
022import java.time.temporal.Temporal;
023import org.opengis.metadata.quality.PositionalAccuracy;
024import org.opengis.referencing.crs.CoordinateReferenceSystem;
025import org.opengis.referencing.ObjectDomain;
026import org.opengis.annotation.UML;
027
028import static org.opengis.annotation.Obligation.*;
029import static org.opengis.annotation.Specification.*;
030
031
032/**
033 * An operation specifying a subset of a coordinate tuple subjected to a specific coordinate operation.
034 * Coordinates in the coordinate tuple other than the subset remain unchanged.
035 * For example, it may be required to transform only the horizontal or only the vertical component of
036 * a compound three-dimensional coordinate reference system (<abbr>CRS</abbr>).
037 * This operation specifies what subset of a coordinate tuple is subject to a requested operation.
038 * It takes the form of referencing another coordinate operation and specifying a sequence of numbers
039 * defining the positions in the coordinate tuple of the coordinates affected by that operation.
040 * The order of the coordinates in a coordinate tuple shall agree with the order of the coordinate system
041 * axes as defined for the associated coordinate system.
042 *
043 * <div class="warning"><b>Upcoming API change</b><br>
044 * This interface is conformant to ISO 19111:2003. But the ISO 19111:2007 revision changed the parent
045 * interface from {@code SingleOperation} to {@link CoordinateOperation}. This change may be applied
046 * in GeoAPI 4.0.
047 * </div>
048 *
049 * @author  OGC Topic 2 (for abstract model and documentation)
050 * @author  Martin Desruisseaux (IRD, Geomatys)
051 * @version 3.1
052 * @since   1.0
053 */
054@UML(identifier="PassThroughOperation", specification=ISO_19111)
055public interface PassThroughOperation extends SingleOperation {
056    /**
057     * Returns the operation to apply on the subset of a coordinate tuple.
058     *
059     * <div class="warning"><b>Upcoming API change</b><br>
060     * This method is conformant to ISO 19111:2003. But the ISO 19111:2007 revision changed the type from
061     * {@code SingleOperation} to {@link CoordinateOperation}. This change may be applied in GeoAPI 4.0.
062     * This is necessary for supporting usage of {@code PassThroughOperation} with {@link ConcatenatedOperation}.
063     * </div>
064     *
065     * @return the operation to apply on the subset of a coordinate tuple.
066     */
067    @UML(identifier="coordOperation", obligation=MANDATORY, specification=ISO_19111)
068    SingleOperation getOperation();
069
070    /**
071     * Returns the positions in a source coordinate tuple of the coordinates affected by this pass-through operation.
072     * Values 0 identifies the first source coordinate, value 1 identifies the second source coordinate, <i>etc.</i>
073     * This is an ordered sequence: coordinates will be given to the {@linkplain #getOperation() operation}
074     * in the same order as the indices returned by this method.
075     *
076     * @return zero-based indices of the modified source coordinates.
077     */
078    @UML(identifier="modifiedCoordinate", obligation=MANDATORY, specification=ISO_19111)
079    int[] getModifiedCoordinates();
080
081    /**
082     * Returns the <abbr>CRS</abbr> to be used for interpolations in a grid.
083     * By default, this is the interpolation <abbr>CRS</abbr> of the {@linkplain #getOperation() operation}.
084     *
085     * @since 3.1
086     */
087    @Override
088    @UML(identifier="interpolationCRS", obligation=OPTIONAL, specification=ISO_19111)
089    default Optional<CoordinateReferenceSystem> getInterpolationCRS() {
090        return getOperation().getInterpolationCRS();
091    }
092
093    /**
094     * Returns the date at which source coordinate tuples are valid.
095     * By default, this is the source epoch of the {@linkplain #getOperation() operation}.
096     *
097     * @since 3.1
098     */
099    @Override
100    @UML(identifier="sourceCoordinateEpoch", obligation=CONDITIONAL, specification=ISO_19111)
101    default Optional<Temporal> getSourceEpoch() {
102        return getOperation().getSourceEpoch();
103    }
104
105    /**
106     * Returns the date at which target coordinate tuples are valid.
107     * By default, this is the target epoch of the {@linkplain #getOperation() operation}.
108     *
109     * @since 3.1
110     */
111    @Override
112    @UML(identifier="targetCoordinateEpoch", obligation=CONDITIONAL, specification=ISO_19111)
113    default Optional<Temporal> getTargetEpoch() {
114        return getOperation().getTargetEpoch();
115    }
116
117    /**
118     * Returns the usage of this <abbr>CRS</abbr>-related object.
119     * By default, this is the domain of the {@linkplain #getOperation() operation}.
120     *
121     * @since 3.1
122     */
123    @Override
124    @UML(identifier="ObjectUsage.domain", obligation=OPTIONAL, specification=ISO_19111)
125    default Collection<ObjectDomain> getDomains() {
126        return getOperation().getDomains();
127    }
128
129    /**
130     * Returns estimate(s) of the impact of this operation on point accuracy.
131     * By default, this is the accuracy of the {@linkplain #getOperation() operation}.
132     */
133    @Override
134    @UML(identifier="coordinateOperationAccuracy", obligation=OPTIONAL, specification=ISO_19111)
135    default Collection<PositionalAccuracy> getCoordinateOperationAccuracy() {
136        return getOperation().getCoordinateOperationAccuracy();
137    }
138}