001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-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
020
021/**
022 * Transforms one-dimensional coordinate points.
023 * {@link CoordinateOperation#getMathTransform()} may return instance of this
024 * interface when source and destination coordinate systems are both one dimensional.
025 * {@code MathTransform1D} extends {@link MathTransform} by adding a simple method
026 * transforming a value without the overhead of creating data array.
027 *
028 * @departure extension
029 *   This interface is not part of the OGC specification. It has been added as a complement
030 *   of {@code MathTransform2D} and because the 1D case provides opportunities for optimization
031 *   through a {@code transform} method accepting a single {@code double} primitive type.
032 *
033 * @author  Martin Desruisseaux (IRD, Geomatys)
034 * @version 3.1
035 * @since   1.0
036 */
037public interface MathTransform1D extends MathTransform {
038    /**
039     * Returns the number of dimensions of input points, which shall be 1.
040     *
041     * @return always 1.
042     */
043    @Override
044    default int getSourceDimensions() {
045        return 1;
046    }
047
048    /**
049     * Returns the number of dimensions of output points, which shall be 1.
050     *
051     * @return always 1.
052     */
053    @Override
054    default int getTargetDimensions() {
055        return 1;
056    }
057
058    /**
059     * Transforms the specified value.
060     *
061     * @param  value  the value to transform.
062     * @return the transformed value.
063     * @throws TransformException if the value cannot be transformed.
064     */
065    double transform(double value) throws TransformException;
066
067    /**
068     * Gets the derivative of this function at a value. The derivative is the
069     * 1×1 matrix of the non-translating portion of the approximate affine
070     * map at the value.
071     *
072     * @param  value  the value where to evaluate the derivative.
073     * @return the derivative at the specified point.
074     * @throws TransformException if the derivative cannot be evaluated at the specified point.
075     */
076    double derivative(double value) throws TransformException;
077
078    /**
079     * Returns the inverse transform of this object.
080     *
081     * @return the inverse transform.
082     * @throws NoninvertibleTransformException if the transform cannot be inverted.
083     */
084    @Override
085    default MathTransform1D inverse() throws NoninvertibleTransformException {
086        if (isIdentity()) {
087            return this;
088        }
089        throw new NoninvertibleTransformException();
090    }
091}