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.math3.analysis.interpolation;
018
019import org.apache.commons.math3.analysis.MultivariateFunction;
020import org.apache.commons.math3.exception.NotPositiveException;
021import org.apache.commons.math3.exception.NotStrictlyPositiveException;
022import org.apache.commons.math3.exception.NoDataException;
023import org.apache.commons.math3.exception.DimensionMismatchException;
024import org.apache.commons.math3.exception.NullArgumentException;
025import org.apache.commons.math3.random.UnitSphereRandomVectorGenerator;
026
027/**
028 * Interpolator that implements the algorithm described in
029 * <em>William Dudziak</em>'s
030 * <a href="http://www.dudziak.com/microsphere.pdf">MS thesis</a>.
031 *
032 * @since 2.1
033 * @deprecated Code will be removed in 4.0.  Use {@link InterpolatingMicrosphere}
034 * and {@link MicrosphereProjectionInterpolator} instead.
035 */
036@Deprecated
037public class MicrosphereInterpolator
038    implements MultivariateInterpolator {
039    /**
040     * Default number of surface elements that composes the microsphere.
041     */
042    public static final int DEFAULT_MICROSPHERE_ELEMENTS = 2000;
043    /**
044     * Default exponent used the weights calculation.
045     */
046    public static final int DEFAULT_BRIGHTNESS_EXPONENT = 2;
047    /**
048     * Number of surface elements of the microsphere.
049     */
050    private final int microsphereElements;
051    /**
052     * Exponent used in the power law that computes the weights of the
053     * sample data.
054     */
055    private final int brightnessExponent;
056
057    /**
058     * Create a microsphere interpolator with default settings.
059     * Calling this constructor is equivalent to call {@link
060     * #MicrosphereInterpolator(int, int)
061     * MicrosphereInterpolator(MicrosphereInterpolator.DEFAULT_MICROSPHERE_ELEMENTS,
062     * MicrosphereInterpolator.DEFAULT_BRIGHTNESS_EXPONENT)}.
063     */
064    public MicrosphereInterpolator() {
065        this(DEFAULT_MICROSPHERE_ELEMENTS, DEFAULT_BRIGHTNESS_EXPONENT);
066    }
067
068    /** Create a microsphere interpolator.
069     * @param elements Number of surface elements of the microsphere.
070     * @param exponent Exponent used in the power law that computes the
071     * weights (distance dimming factor) of the sample data.
072     * @throws NotPositiveException if {@code exponent < 0}.
073     * @throws NotStrictlyPositiveException if {@code elements <= 0}.
074     */
075    public MicrosphereInterpolator(final int elements,
076                                   final int exponent)
077        throws NotPositiveException,
078               NotStrictlyPositiveException {
079        if (exponent < 0) {
080            throw new NotPositiveException(exponent);
081        }
082        if (elements <= 0) {
083            throw new NotStrictlyPositiveException(elements);
084        }
085
086        microsphereElements = elements;
087        brightnessExponent = exponent;
088    }
089
090    /**
091     * {@inheritDoc}
092     */
093    public MultivariateFunction interpolate(final double[][] xval,
094                                            final double[] yval)
095        throws DimensionMismatchException,
096               NoDataException,
097               NullArgumentException {
098        final UnitSphereRandomVectorGenerator rand
099            = new UnitSphereRandomVectorGenerator(xval[0].length);
100        return new MicrosphereInterpolatingFunction(xval, yval,
101                                                    brightnessExponent,
102                                                    microsphereElements,
103                                                    rand);
104    }
105}