001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.math4.analysis.interpolation;
018
019import org.apache.commons.math4.exception.DimensionMismatchException;
020import org.apache.commons.math4.exception.NoDataException;
021import org.apache.commons.math4.exception.NonMonotonicSequenceException;
022import org.apache.commons.math4.exception.NumberIsTooSmallException;
023import org.apache.commons.math4.util.MathArrays;
024
025/**
026 * Generates a {@link BicubicInterpolatingFunction bicubic interpolating
027 * function}.
028 * <p>
029 *  Caveat: Because the interpolation scheme requires that derivatives be
030 *  specified at the sample points, those are approximated with finite
031 *  differences (using the 2-points symmetric formulae).
032 *  Since their values are undefined at the borders of the provided
033 *  interpolation ranges, the interpolated values will be wrong at the
034 *  edges of the patch.
035 *  The {@code interpolate} method will return a function that overrides
036 *  {@link BicubicInterpolatingFunction#isValidPoint(double,double)} to
037 *  indicate points where the interpolation will be inaccurate.
038 * </p>
039 *
040 * @since 3.4
041 */
042public class BicubicInterpolator
043    implements BivariateGridInterpolator {
044    /**
045     * {@inheritDoc}
046     */
047    @Override
048    public BicubicInterpolatingFunction interpolate(final double[] xval,
049                                                    final double[] yval,
050                                                    final double[][] fval)
051        throws NoDataException, DimensionMismatchException,
052               NonMonotonicSequenceException, NumberIsTooSmallException {
053        if (xval.length == 0 || yval.length == 0 || fval.length == 0) {
054            throw new NoDataException();
055        }
056        if (xval.length != fval.length) {
057            throw new DimensionMismatchException(xval.length, fval.length);
058        }
059
060        MathArrays.checkOrder(xval);
061        MathArrays.checkOrder(yval);
062
063        final int xLen = xval.length;
064        final int yLen = yval.length;
065
066        // Approximation to the partial derivatives using finite differences.
067        final double[][] dFdX = new double[xLen][yLen];
068        final double[][] dFdY = new double[xLen][yLen];
069        final double[][] d2FdXdY = new double[xLen][yLen];
070        for (int i = 1; i < xLen - 1; i++) {
071            final int nI = i + 1;
072            final int pI = i - 1;
073
074            final double nX = xval[nI];
075            final double pX = xval[pI];
076
077            final double deltaX = nX - pX;
078
079            for (int j = 1; j < yLen - 1; j++) {
080                final int nJ = j + 1;
081                final int pJ = j - 1;
082
083                final double nY = yval[nJ];
084                final double pY = yval[pJ];
085
086                final double deltaY = nY - pY;
087
088                dFdX[i][j] = (fval[nI][j] - fval[pI][j]) / deltaX;
089                dFdY[i][j] = (fval[i][nJ] - fval[i][pJ]) / deltaY;
090
091                final double deltaXY = deltaX * deltaY;
092
093                d2FdXdY[i][j] = (fval[nI][nJ] - fval[nI][pJ] - fval[pI][nJ] + fval[pI][pJ]) / deltaXY;
094            }
095        }
096
097        // Create the interpolating function.
098        return new BicubicInterpolatingFunction(xval, yval, fval,
099                                                dFdX, dFdY, d2FdXdY) {
100            /** {@inheritDoc} */
101            @Override
102            public boolean isValidPoint(double x, double y) {
103                if (x < xval[1] ||
104                    x > xval[xval.length - 2] ||
105                    y < yval[1] ||
106                    y > yval[yval.length - 2]) {
107                    return false;
108                } else {
109                    return true;
110                }
111            }
112        };
113    }
114}