001 package edu.nrao.sss.math;
002
003 import java.awt.geom.Point2D;
004 import java.util.List;
005
006 /**
007 * An interpolated value calculator.
008 * <p>
009 * This object holds a list of two dimensional points,
010 * <tt>(x<sub>i</sub>, y<sub>i</sub>)</tt>. Its main job is to calculate a
011 * value, <tt>f(x)</tt>, for any <tt>x</tt> between <tt>x<sub>i</sub></tt> and
012 * <tt>x<sub>i+1</sub></tt>, inclusive. This object ensures that its
013 * list is ordered such that <tt>x<sub>i</sub> < x<sub>i+1</sub></tt>,
014 * no matter the order in which a client might send it points on which
015 * to operate. Interpolators are not permitted to hold more than one point
016 * for a given <tt>x</tt> value.</p>
017 * <p>
018 * <b>Version Info:</b>
019 * <table style="margin-left:2em">
020 * <tr><td>$Revision: 568 $</td></tr>
021 * <tr><td>$Date: 2007-04-27 16:53:09 -0600 (Fri, 27 Apr 2007) $</td></tr>
022 * <tr><td>$Author: dharland $</td></tr>
023 * </table></p>
024 *
025 * @author David M. Harland
026 * @since 2007-04-24
027 */
028 public interface Interpolator
029 {
030 /**
031 * Returns a value, <tt>f(x)</tt>, for the given value.
032 * The returned value is calculated based on an interpolation algorithm
033 * provided by concrete implementations of this interface. Some examples
034 * of such algorithms are linear, cubic spline, and polynomial.
035 * <p>
036 * If the value {@code x} is outside the {@link #getDomain() domain} of this
037 * interpolator, and {@link IllegalArgumentException} is thrown.</p>
038 *
039 * @param x the independent variable for which a dependent variable,
040 * <tt>f(x)</tt> is sought.
041 *
042 * @return an interpolated value for <tt>f(x)</tt>.
043 */
044 public double getValueFor(double x);
045
046 /**
047 * Adds a copy of each of the points in the list to this interpolator.
048 * <p>
049 * If any of the new points holds an x-value equal to that of a point already
050 * held by this interpolator, the already-held point is first removed, and
051 * then the new point is added.</p>
052 *
053 * @param points a list of new points to be added to this interpolator.
054 */
055 public void setPoints(List<? extends Point2D> points);
056
057 /**
058 * Adds a copy of {@code newPoint} to this interpolator.
059 * <p>
060 * If this interpolator already contains a point with the same x-value as
061 * {@code newPoint}, that point is first removed and is also the value
062 * returned.</p>
063 *
064 * @param newPoint a point to be added to this interpolator.
065 *
066 * @return the previously held point that has the same x-value as
067 * {@code newPoint}, or <i>null</i> if this interpolator held
068 * no such point.
069 */
070 public Point2D addPoint(Point2D newPoint);
071
072 /**
073 * Removes from this interpolator the point, if any, with an independent
074 * variable equal to {@code xValue}.
075 *
076 * @param xValue the independent variable of the point to be removed.
077 *
078 * @return a point formerly contained by this interpolator having an
079 * independent variable equal to {@code xValue}. If this
080 * interpolator holds no such point, <i>null</i> is returned.
081 */
082 public Point2D removePoint(double xValue);
083
084 /**
085 * Clears all points from this interpolator. Implementations of this
086 * interface may choose to reset other properties as well.
087 */
088 public void clear();
089
090 /**
091 * Returns the number of points held by this interpolator.
092 * @return the number of points held by this interpolator.
093 */
094 public int size();
095
096 /**
097 * Returns a list containing a copy of each point held by this interpolator.
098 * The copies in the returned list will be in the same order as the
099 * actual points held by this interpolator.
100 *
101 * @return a list containing a copy of each point held by this interpolator.
102 */
103 public List<Point2D> getPoints();
104
105 /**
106 * Returns an interval whose endpoints are the smallest and largest
107 * independent ("x") values of the points held by this interpolator.
108 *
109 * @return the domain of the function represented by the points of
110 * this interpolator.
111 */
112 public NumberInterval getDomain();
113 }
114
115 //TODO need new exception class? Java has NumericException or similar?