| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.sis.referencing.operation; |
| |
| import java.util.Map; |
| import java.util.List; |
| import java.util.ArrayList; |
| import java.util.Objects; |
| import java.util.Locale; |
| import jakarta.xml.bind.annotation.XmlType; |
| import jakarta.xml.bind.annotation.XmlElement; |
| import jakarta.xml.bind.annotation.XmlRootElement; |
| import org.opengis.util.FactoryException; |
| import org.opengis.referencing.crs.CoordinateReferenceSystem; |
| import org.opengis.referencing.operation.CoordinateOperation; |
| import org.opengis.referencing.operation.ConcatenatedOperation; |
| import org.opengis.referencing.operation.Conversion; |
| import org.opengis.referencing.operation.Transformation; |
| import org.opengis.referencing.operation.MathTransform; |
| import org.opengis.referencing.operation.MathTransformFactory; |
| import org.opengis.referencing.operation.NoninvertibleTransformException; |
| import org.apache.sis.referencing.IdentifiedObjects; |
| import org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory; |
| import org.apache.sis.referencing.factory.InvalidGeodeticParameterException; |
| import org.apache.sis.referencing.privy.PositionalAccuracyConstant; |
| import org.apache.sis.referencing.privy.CoordinateOperations; |
| import org.apache.sis.referencing.privy.ReferencingUtilities; |
| import org.apache.sis.referencing.internal.Resources; |
| import org.apache.sis.util.Utilities; |
| import org.apache.sis.util.ComparisonMode; |
| import org.apache.sis.util.ArgumentChecks; |
| import org.apache.sis.util.collection.Containers; |
| import org.apache.sis.util.privy.UnmodifiableArrayList; |
| import org.apache.sis.util.resources.Errors; |
| import org.apache.sis.io.wkt.Formatter; |
| |
| // Specific to the main and geoapi-3.1 branches: |
| import org.opengis.referencing.operation.SingleOperation; |
| |
| |
| /** |
| * An ordered sequence of two or more single coordinate operations. The sequence of operations is constrained |
| * by the requirement that the source coordinate reference system of step (<var>n</var>+1) must be the same as |
| * the target coordinate reference system of step (<var>n</var>). The source coordinate reference system of the |
| * first step and the target coordinate reference system of the last step are the source and target coordinate |
| * reference system associated with the concatenated operation. |
| * |
| * @author Martin Desruisseaux (IRD, Geomatys) |
| */ |
| @XmlType(name = "ConcatenatedOperationType") |
| @XmlRootElement(name = "ConcatenatedOperation") |
| final class DefaultConcatenatedOperation extends AbstractCoordinateOperation implements ConcatenatedOperation { |
| /** |
| * Serial number for inter-operability with different versions. |
| */ |
| private static final long serialVersionUID = 4199619838029045700L; |
| |
| /** |
| * Optional key for specifying the {@link #transform} value. |
| * This property should generally not be specified, as the constructor builds the transform itself. |
| * It may be useful if the resulting transform is already known and we want to avoid the construction cost. |
| */ |
| public static final String TRANSFORM_KEY = "transform"; |
| |
| /** |
| * The comparison modes to use for determining if two CRS are equal, in preference order. |
| * This is used for determining if an operation need to be inverted. |
| */ |
| private static final ComparisonMode[] CRS_ORDER_CRITERIA = { |
| ComparisonMode.BY_CONTRACT, |
| ComparisonMode.IGNORE_METADATA, |
| ComparisonMode.APPROXIMATE |
| }; |
| |
| /** |
| * The sequence of operations. |
| * |
| * <p><b>Consider this field as final!</b> |
| * This field is modified only at unmarshalling time by {@link #setSteps(CoordinateOperation[])}</p> |
| */ |
| @SuppressWarnings("serial") // Most SIS implementations are serializable. |
| private List<SingleOperation> operations; |
| |
| /** |
| * Constructs a concatenated operation from a set of properties and a |
| * {@linkplain MathTransformFactory math transform factory}. |
| * The properties given in argument follow the same rules as for the |
| * {@linkplain AbstractCoordinateOperation#AbstractCoordinateOperation(Map, CoordinateReferenceSystem, |
| * CoordinateReferenceSystem, CoordinateReferenceSystem, MathTransform) super-class constructor}. |
| * The following table is a reminder of main (not all) properties: |
| * |
| * <table class="sis"> |
| * <caption>Recognized properties (non exhaustive list)</caption> |
| * <tr> |
| * <th>Property name</th> |
| * <th>Value type</th> |
| * <th>Returned by</th> |
| * </tr><tr> |
| * <td>{@value #TRANSFORM_KEY}</td> |
| * <td>{@link MathTransform}</td> |
| * <td>{@link #getMathTransform()}</td> |
| * </tr><tr> |
| * <th colspan="3" class="hsep">Defined in parent class (reminder)</th> |
| * </tr><tr> |
| * <td>{@value org.opengis.referencing.IdentifiedObject#NAME_KEY}</td> |
| * <td>{@link org.opengis.metadata.Identifier} or {@link String}</td> |
| * <td>{@link #getName()}</td> |
| * </tr><tr> |
| * <td>{@value org.opengis.referencing.IdentifiedObject#IDENTIFIERS_KEY}</td> |
| * <td>{@link org.opengis.metadata.Identifier} (optionally as array)</td> |
| * <td>{@link #getIdentifiers()}</td> |
| * </tr><tr> |
| * <td>{@value org.opengis.referencing.operation.CoordinateOperation#COORDINATE_OPERATION_ACCURACY_KEY}</td> |
| * <td>{@link PositionalAccuracy} (optionally as array)</td> |
| * <td>{@link #getCoordinateOperationAccuracy()}</td> |
| * </tr> |
| * </table> |
| * |
| * The {@value #TRANSFORM_KEY} property should generally not be provided, as it is automatically computed. |
| * That property is available for saving computation cost when the concatenated transform is known in advance, |
| * or for overriding the automatic concatenation. |
| * |
| * @param properties the properties to be given to the identified object. |
| * @param operations the sequence of operations. Shall contain at least two operations. |
| * @param mtFactory the math transform factory to use for math transforms concatenation. |
| * @throws FactoryException if this constructor or the factory cannot concatenate the operation steps. |
| */ |
| public DefaultConcatenatedOperation(final Map<String,?> properties, final CoordinateOperation[] operations, |
| final MathTransformFactory mtFactory) throws FactoryException |
| { |
| super(properties); |
| if (operations.length < 2) { |
| throw new InvalidGeodeticParameterException(Errors.forProperties(properties).getString( |
| Errors.Keys.TooFewOccurrences_2, 2, CoordinateOperation.class)); |
| } |
| transform = Containers.property(properties, TRANSFORM_KEY, MathTransform.class); |
| initialize(properties, operations, (transform == null) ? mtFactory : null); |
| checkDimensions(properties); |
| } |
| |
| /** |
| * Initializes the {@link #sourceCRS}, {@link #targetCRS} and {@link #operations} fields. |
| * If the source or target CRS is already non-null (which may happen on JAXB unmarshalling), |
| * leaves that CRS unchanged. |
| * |
| * @param properties the properties specified at construction time, or {@code null} if unknown. |
| * @param operations the operations to concatenate. |
| * @param mtFactory the math transform factory to use, or {@code null} for not performing concatenation. |
| * @throws FactoryException if this constructor or the factory cannot concatenate the operation steps. |
| */ |
| private void initialize(final Map<String,?> properties, |
| final CoordinateOperation[] operations, |
| final MathTransformFactory mtFactory) |
| throws FactoryException |
| { |
| final List<CoordinateOperation> flattened = new ArrayList<>(operations.length); |
| final CoordinateReferenceSystem crs = initialize(properties, operations, flattened, mtFactory, |
| sourceCRS, (sourceCRS == null), (coordinateOperationAccuracy == null)); |
| |
| if (targetCRS == null) { |
| targetCRS = crs; |
| } else if (mtFactory instanceof DefaultMathTransformFactory) { |
| final var dmf = (DefaultMathTransformFactory) mtFactory; |
| final MathTransform t = dmf.createCoordinateSystemChange( |
| crs.getCoordinateSystem(), |
| targetCRS.getCoordinateSystem(), |
| ReferencingUtilities.getEllipsoid(crs)); |
| transform = dmf.createConcatenatedTransform(transform, t); |
| } |
| /* |
| * At this point we should have flattened.size() >= 2, except if some operations |
| * were omitted because their associated math transform were identity operation. |
| */ |
| this.operations = UnmodifiableArrayList.wrap(flattened.toArray(SingleOperation[]::new)); |
| } |
| |
| /** |
| * Performs the part of {@code DefaultConcatenatedOperations} construction that requires an iteration over |
| * the sequence of coordinate operations. This method performs the following processing: |
| * |
| * <ul> |
| * <li>Verify the validity of the {@code operations} argument.</li> |
| * <li>Add the single operations in the {@code flattened} array.</li> |
| * <li>Set the {@link #transform} field to the concatenated transform.</li> |
| * <li>Set the {@link #coordinateOperationAccuracy} field, but only if {@code setAccuracy} is {@code true}.</li> |
| * </ul> |
| * |
| * This method invokes itself recursively if there is nested {@code ConcatenatedOperation} instances |
| * in the given list. This should not happen according ISO 19111 standard, but we try to be safe. |
| * |
| * <h4>How coordinate operation accuracy is determined</h4> |
| * If {@code setAccuracy} is {@code true}, then this method copies accuracy information found in the single |
| * {@link Transformation} instance. This method ignores instances of other kinds for the following reason: |
| * some {@link Conversion} instances declare an accuracy, which is typically close to zero. If a concatenated |
| * operation contains such conversion together with a transformation with unknown accuracy, then we do not want |
| * to declare "0 meter" as the concatenated operation accuracy; it would be a false information. |
| * Another reason is that a concatenated operation typically contains an arbitrary number of conversions, |
| * but only one transformation. So considering only transformations usually means to pickup only one operation |
| * in the given {@code operations} list, which make things clearer. |
| * |
| * <h5>Note</h5> |
| * According ISO 19111, the accuracy attribute is allowed only for transformations. However, this restriction |
| * is not enforced everywhere. For example, the EPSG database declares an accuracy of 0 meter for conversions, |
| * which is conceptually exact. In this class we are departing from strict interpretation of the specification |
| * since we are adding accuracy information to a concatenated operation. This departure should be considered |
| * as a convenience feature only; accuracies are really relevant in transformations only. |
| * |
| * @param properties the properties specified at construction time, or {@code null} if unknown. |
| * @param operations the operations to concatenate. |
| * @param flattened the destination list in which to add the {@code SingleOperation} instances. |
| * @param mtFactory the math transform factory to use, or {@code null} for not performing concatenation. |
| * @param previous target CRS of the step before the first {@code operations} step, or {@code null}. |
| * @param setSource {@code true} for setting the {@link #sourceCRS} on the very first CRS (regardless if null or not). |
| * @param setAccuracy {@code true} for setting the {@link #coordinateOperationAccuracy} field. |
| * @return the last target CRS, regardless if null or not. |
| * @throws FactoryException if the factory cannot concatenate the math transforms. |
| */ |
| private CoordinateReferenceSystem initialize( |
| final Map<String,?> properties, |
| final CoordinateOperation[] operations, |
| final List<CoordinateOperation> flattened, |
| final MathTransformFactory mtFactory, |
| CoordinateReferenceSystem previous, |
| boolean setSource, |
| boolean setAccuracy) throws FactoryException |
| { |
| CoordinateReferenceSystem source; // Source CRS of current iteration. |
| CoordinateReferenceSystem target = null; // Target CRS of current and last iteration. |
| for (int i=0; i<operations.length; i++) { |
| CoordinateOperation op = operations[i]; |
| ArgumentChecks.ensureNonNullElement("operations", i, op); |
| /* |
| * Verify consistency of user argument: for each coordinate operation, the source CRS |
| * should be equal (ignoring metadata) to the target CRS of the previous operation. |
| * An exception to this rule is when source and target CRS need to be swapped. |
| */ |
| source = op.getSourceCRS(); |
| target = op.getTargetCRS(); |
| final boolean inverse = verifyStepChaining(properties, i, previous, source, target); |
| if (inverse) { |
| var t = source; |
| source = target; |
| target = t; |
| // Inverse the operation only if it produces a more natural definition. |
| if (CoordinateOperations.getMethod(op) instanceof InverseOperationMethod) { |
| CoordinateOperation natural = getCachedInverse(op); |
| if (natural != null) op = natural; |
| } |
| } |
| if (setSource) { |
| setSource = false; |
| sourceCRS = source; // Take even if null. |
| } |
| /* |
| * Now that we have verified the CRS chaining, we should be able to concatenate the transforms. |
| * If an operation is a nested `ConcatenatedOperation` (not allowed by ISO 19111, but we try to |
| * be safe), we will first try to use the `ConcatenatedOperation.transform` as a whole. Only if |
| * that concatenated operation does not provide a transform, we will concatenate its components. |
| * Note however that we traverse nested concatenated operations unconditionally at least for |
| * checking its consistency. |
| */ |
| NoninvertibleTransformException cause = null; |
| MathTransform step = op.getMathTransform(); |
| if (step != null && inverse) try { |
| step = step.inverse(); |
| } catch (NoninvertibleTransformException e) { |
| step = null; |
| cause = e; |
| } |
| if (step == null) { |
| // May happen if the operation is a defining operation. |
| throw new InvalidGeodeticParameterException(Resources.format( |
| Resources.Keys.OperationHasNoTransform_2, op.getClass(), op.getName()), cause); |
| } |
| if (op instanceof ConcatenatedOperation) { |
| final var nested = ((ConcatenatedOperation) op).getOperations().toArray(CoordinateOperation[]::new); |
| previous = initialize(properties, nested, flattened, null, previous, false, setAccuracy); |
| } else if (!step.isIdentity()) { |
| // Note: operation (source, target) may be in reverse order, but it should be taken as metadata. |
| flattened.add(op); |
| previous = target; // For next iteration cycle. |
| } |
| if (mtFactory != null) { |
| transform = (transform != null) ? mtFactory.createConcatenatedTransform(transform, step) : step; |
| } |
| /* |
| * Optionally copy the coordinate operation accuracy from the transformation (or from a concatenated |
| * operation on the assumption that its accuracy was computed by the same algorithm as this method). |
| * See javadoc for a rational about why we take only transformations in account. If more than one |
| * transformation is found, clear the collection and abandon the attempt to set the accuracy information. |
| * Instead, the user will get a better result by invoking PositionalAccuracyConstant.getLinearAccuracy(…) |
| * since that method conservatively computes the sum of all linear accuracy. |
| */ |
| if (setAccuracy && (op instanceof Transformation || op instanceof ConcatenatedOperation) |
| && (PositionalAccuracyConstant.getLinearAccuracy(op) != 0)) |
| { |
| if (coordinateOperationAccuracy == null) { |
| coordinateOperationAccuracy = op.getCoordinateOperationAccuracy(); |
| } else { |
| coordinateOperationAccuracy = null; |
| setAccuracy = false; |
| } |
| } |
| } |
| if (!(mtFactory instanceof DefaultMathTransformFactory)) { |
| verifyStepChaining(properties, operations.length, target, targetCRS, null); |
| // Else verification will be done by the caller. |
| } |
| return previous; |
| } |
| |
| /** |
| * Verifies if a step of a concatenated operation can be chained after the previous step. |
| * |
| * @param properties user-specified properties (for the locale of error message), or {@code null} if none. |
| * @param step index of the operation step, used only in case an exception it thrown. |
| * @param previous Target CRS of the previous step. |
| * @param source Source CRS of the current step. |
| * @param target Target CRS of the current step, or {@code null} if none. |
| * @return whether the math transform needs to be inverted. |
| * @throws FactoryException if the current operation cannot be chained after the previous operation. |
| */ |
| static boolean verifyStepChaining( |
| final Map<String,?> properties, final int step, |
| final CoordinateReferenceSystem previous, |
| final CoordinateReferenceSystem source, |
| final CoordinateReferenceSystem target) throws FactoryException |
| { |
| if (previous == null || source == null) { |
| return false; |
| } |
| for (final ComparisonMode mode : CRS_ORDER_CRITERIA) { |
| if (Utilities.deepEquals(previous, source, mode)) return false; |
| if (Utilities.deepEquals(previous, target, mode)) return true; |
| } |
| Resources resources = Resources.forProperties(properties); |
| Locale locale = resources.getLocale(); |
| throw new InvalidGeodeticParameterException(resources.getString( |
| Resources.Keys.MismatchedSourceTargetCRS_3, step, |
| IdentifiedObjects.getDisplayName(previous, locale), |
| IdentifiedObjects.getDisplayName(source, locale))); |
| } |
| |
| /** |
| * Creates a new coordinate operation with the same values as the specified one. |
| * This copy constructor provides a way to convert an arbitrary implementation into a SIS one |
| * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API. |
| * |
| * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p> |
| * |
| * @param operation the coordinate operation to copy. |
| * |
| * @see #castOrCopy(ConcatenatedOperation) |
| */ |
| protected DefaultConcatenatedOperation(final ConcatenatedOperation operation) { |
| super(operation); |
| operations = operation.getOperations(); |
| } |
| |
| /** |
| * Returns a SIS coordinate operation implementation with the values of the given arbitrary implementation. |
| * If the given object is already an instance of {@code DefaultConcatenatedOperation}, then it is returned |
| * unchanged. Otherwise a new {@code DefaultConcatenatedOperation} instance is created using the |
| * {@linkplain #DefaultConcatenatedOperation(ConcatenatedOperation) copy constructor} and returned. |
| * Note that this is a <em>shallow</em> copy operation, |
| * since the other properties contained in the given object are not recursively copied. |
| * |
| * @param object the object to get as a SIS implementation, or {@code null} if none. |
| * @return a SIS implementation containing the values of the given object (may be the |
| * given object itself), or {@code null} if the argument was null. |
| */ |
| public static DefaultConcatenatedOperation castOrCopy(final ConcatenatedOperation object) { |
| return (object == null) || (object instanceof DefaultConcatenatedOperation) |
| ? (DefaultConcatenatedOperation) object : new DefaultConcatenatedOperation(object); |
| } |
| |
| /** |
| * Returns the GeoAPI interface implemented by this class. |
| * The SIS implementation returns {@code ConcatenatedOperation.class}. |
| * |
| * <h4>Note for implementers</h4> |
| * Subclasses usually do not need to override this method since GeoAPI does not define {@code ConcatenatedOperation} |
| * sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their |
| * own set of interfaces. |
| * |
| * @return {@code ConcatenatedOperation.class} or a user-defined sub-interface. |
| */ |
| @Override |
| public Class<? extends ConcatenatedOperation> getInterface() { |
| return ConcatenatedOperation.class; |
| } |
| |
| /** |
| * Returns the sequence of operations that are steps in this concatenated operation. |
| * The sequence can contain {@link org.opengis.referencing.operation.SingleOperation}s |
| * or {@link org.opengis.referencing.operation.PassThroughOperation}s. |
| * |
| * <div class="warning"><b>Upcoming API change</b><br> |
| * This method is conformant to ISO 19111:2003. But the ISO 19111:2007 revision changed the element type |
| * from {@code SingleOperation} to {@link CoordinateOperation}. This change may be applied in GeoAPI 4.0. |
| * This is necessary for supporting usage of {@code PassThroughOperation} with {@link ConcatenatedOperation}. |
| * </div> |
| * |
| * @return the sequence of operations. |
| */ |
| @Override |
| @SuppressWarnings("ReturnOfCollectionOrArrayField") |
| public List<SingleOperation> getOperations() { |
| return operations; |
| } |
| |
| /** |
| * Compares this concatenated operation with the specified object for equality. If the {@code mode} argument |
| * is {@link ComparisonMode#STRICT} or {@link ComparisonMode#BY_CONTRACT BY_CONTRACT}, then all available |
| * properties are compared including the {@linkplain #getDomains() domains} and the accuracy. |
| * |
| * @return {@inheritDoc} |
| */ |
| @Override |
| public boolean equals(final Object object, final ComparisonMode mode) { |
| if (object == this) { |
| return true; // Slight optimization. |
| } |
| if (super.equals(object, mode)) { |
| if (mode == ComparisonMode.STRICT) { |
| return Objects.equals(operations, ((DefaultConcatenatedOperation) object).operations); |
| } else { |
| return Utilities.deepEquals(getOperations(), ((ConcatenatedOperation) object).getOperations(), mode); |
| } |
| } |
| return false; |
| } |
| |
| /** |
| * {@inheritDoc} |
| * |
| * @return {@inheritDoc} |
| */ |
| @Override |
| protected long computeHashCode() { |
| return super.computeHashCode() + 37 * Objects.hashCode(operations); |
| } |
| |
| /** |
| * Formats this coordinate operation in pseudo-WKT. This is specific to Apache SIS since |
| * there is no concatenated operation in the Well Known Text (WKT) version 2 format. |
| * |
| * @param formatter the formatter to use. |
| * @return {@code "ConcatenatedOperation"}. |
| */ |
| @Override |
| protected String formatTo(final Formatter formatter) { |
| super.formatTo(formatter); |
| for (final CoordinateOperation component : operations) { |
| formatter.newLine(); |
| formatter.append(castOrCopy(component)); |
| } |
| formatter.setInvalidWKT(this, null); |
| return "ConcatenatedOperation"; |
| } |
| |
| |
| |
| |
| /* |
| ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ |
| ┃ ┃ |
| ┃ XML support with JAXB ┃ |
| ┃ ┃ |
| ┃ The following methods are invoked by JAXB using reflection (even if ┃ |
| ┃ they are private) or are helpers for other methods invoked by JAXB. ┃ |
| ┃ Those methods can be safely removed if Geographic Markup Language ┃ |
| ┃ (GML) support is not needed. ┃ |
| ┃ ┃ |
| ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ |
| */ |
| |
| /** |
| * Constructs a new object in which every attributes are set to a null value. |
| * <strong>This is not a valid object.</strong> This constructor is strictly |
| * reserved to JAXB, which will assign values to the fields using reflection. |
| */ |
| private DefaultConcatenatedOperation() { |
| operations = List.of(); |
| } |
| |
| /** |
| * Returns the operations to marshal. We use this private methods instead of annotating |
| * {@link #getOperations()} in order to force JAXB to invoke the setter method on unmarshalling. |
| */ |
| @XmlElement(name = "coordOperation", required = true) |
| private CoordinateOperation[] getSteps() { |
| @SuppressWarnings("LocalVariableHidesMemberVariable") |
| final List<? extends CoordinateOperation> operations = getOperations(); |
| return (operations != null) ? operations.toArray(CoordinateOperation[]::new) : null; |
| } |
| |
| /** |
| * Invoked by JAXB for setting the operations. |
| */ |
| private void setSteps(final CoordinateOperation[] steps) throws FactoryException { |
| initialize(null, steps, DefaultMathTransformFactory.provider()); |
| } |
| } |
