--- a/gnv-artifacts/src/main/java/de/intevation/gnv/math/Interpolation2D.java	Thu Apr 08 13:10:39 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/math/Interpolation2D.java	Thu Apr 08 15:24:45 2010 +0000
@@ -10,24 +10,51 @@
 import org.apache.log4j.Logger;
 
 /**
- *  @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
+ * Interpolates along a given line string. This used to generate
+ * "horizontale Schnittprofile".
+ *
+ * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public final class Interpolation2D
 {
     private static Logger log = Logger.getLogger(Interpolation2D.class);
 
+    /**
+     * If the number of input points are over this threshold
+     * some culling strategies are applied to reduce the amount of points.
+     */
     public static final int CULL_POINT_THRESHOLD = Integer.getInteger(
         "gnv.interpolation2d.cull.point.threshold", 1000);
 
+    /**
+     * Numerical stability epsilon.
+     */
     public static final double EPS = 1e-6d;
 
+    /**
+     * Callback to send the interpolated values back to the
+     * caller without building large temporary strcutures.
+     */
     public interface Consumer {
+        /**
+         * Sends an interpolated point back to the called.
+         * The interpolated parameter is stored in the z component.
+         * @param point The interpolated point.
+         * @param success true if interpolation at the point
+         * succeed, else false.
+         */
         void interpolated(Coordinate point, boolean success);
     } // interface Consumer
 
     private Interpolation2D() {
     }
 
+    /**
+     * Calculates the relevant area for a given line string.
+     * @param path The line string.
+     * @param points The sample points.
+     * @return The relevant area.
+     */
     public static final Envelope relevantArea(
         List<? extends Coordinate> path,
         List<? extends Coordinate> points
@@ -35,6 +62,12 @@
         return relevantArea(path, points, CULL_POINT_THRESHOLD);
     }
 
+    /**
+     * Calculates the relevant area for a given bounding box.
+     * @param pathBBox The bounding box.
+     * @param points The sample points.
+     * @return The relevant area.
+     */
     public static final Envelope relevantArea(
         Envelope                   pathBBox,
         List<? extends Coordinate> points
@@ -42,6 +75,14 @@
         return relevantArea(pathBBox, points, CULL_POINT_THRESHOLD);
     }
 
+    /**
+     * Calculates the relevant area for a given bounding box.
+     * @param pathBBox The bounding box.
+     * @param points The sample points.
+     * @param threshold If the number of sample points
+     * are below this threshold no relevant area is calculated.
+     * @return The relevant area.
+     */
     public static final Envelope relevantArea(
         Envelope                   pathBBox,
         List<? extends Coordinate> points,
@@ -54,6 +95,14 @@
                 pointsBoundingBox(points));
     }
 
+    /**
+     * Calculates the relevant area for a given line string.
+     * @param path The line string.
+     * @param points The sample points.
+     * @param threshold If the number of sample points
+     * are below this threshold no relevant area is calculated.
+     * @return The relevant area.
+     */
     public static final Envelope relevantArea(
         List<? extends Coordinate> path,
         List<? extends Coordinate> points,
@@ -66,6 +115,12 @@
                 pointsBoundingBox(points));
     }
 
+    /**
+     * Heuristic function to define a 'relevant area'.
+     * @param pathBBox The bounding box of the line line string.
+     * @param pointsBBox The bounding box of the sample points.
+     * @return The relevant area.
+     */
     public static final Envelope relevantArea(
         Envelope pathBBox,
         Envelope pointsBBox
@@ -90,6 +145,13 @@
         return pathBBox;
     }
 
+    /**
+     * Solves quadratic equation a*x*x + b*x + c = 0.
+     * @param a a-coefficent.
+     * @param b b-coefficent
+     * @param c c-coefficent.
+     * @return the solution of the equation, or null if not solvable.
+     */
     public static final double [] solveQuadratic(
         double a, double b, double c
     ) {
@@ -103,11 +165,22 @@
         return new double [] { a*(b + d), a*(b - d) };
     }
 
+    /**
+     * Return the element of a two element array which
+     * is greater or equal zero.
+     * @param x The two values.
+     * @return The value which is greater or equal zero.
+     */
     public static final double pos(double [] x) {
         return x[0] >= 0 ? x[0] : x[1];
     }
 
 
+    /**
+     * Calculates the bounding box of a given line string.
+     * @param path The line string.
+     * @return The bounding box.
+     */
     public static Envelope pointsBoundingBox(
         List<? extends Coordinate> path
     ) {
@@ -121,6 +194,19 @@
         return area;
     }
 
+    /**
+     * Interpolates linearly a number of coordinates and parameter values along
+     * a given line string path. The results are issued to a consumer.
+     * @param path The line string path.
+     * @param points The sample points.
+     * @param from Start point as a scalar value linear
+     * referenced on the line string.
+     * @param to End point of  as a scalar value linear
+     * referenced on the line string.
+     * @param steps Number of points to be interpolated.
+     * @param metrics The used metric.
+     * @param consumer The callback to retrieve the result points.
+     */
     public static void interpolate(
         List<? extends Coordinate> path,
         List<? extends Point2d>    points,
@@ -225,6 +311,16 @@
         }
     }
 
+    /**
+     * Linear interpolate a value between (x1, y1) and (x2, y2) at
+     * a given x-value.
+     * @param x1 x component of first point.
+     * @param y1 y component of first point.
+     * @param x2 x component of second point.
+     * @param y2 y component of second point.
+     * @param x The x value.
+     * @return The intepolated result.
+     */
     public static final double interpolate(
         double x1, double y1,
         double x2, double y2,
@@ -238,4 +334,4 @@
         return m*x + b;
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
\ No newline at end of file