MicrosphereInterpolatingFunction.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.math3.analysis.interpolation;

  19. import java.util.ArrayList;
  20. import java.util.HashMap;
  21. import java.util.List;
  22. import java.util.Map;

  24. import org.apache.commons.math3.analysis.MultivariateFunction;
  25. import org.apache.commons.math3.exception.DimensionMismatchException;
  26. import org.apache.commons.math3.exception.NoDataException;
  27. import org.apache.commons.math3.exception.NullArgumentException;
  28. import org.apache.commons.math3.linear.ArrayRealVector;
  29. import org.apache.commons.math3.linear.RealVector;
  30. import org.apache.commons.math3.random.UnitSphereRandomVectorGenerator;
  31. import org.apache.commons.math3.util.FastMath;

  33. /**
  34.  * Interpolating function that implements the
  35.  * <a href="http://www.dudziak.com/microsphere.php">Microsphere Projection</a>.
  36.  *
  37.  */
  38. public class MicrosphereInterpolatingFunction
  39.     implements MultivariateFunction {
  40.     /**
  41.      * Space dimension.
  42.      */
  43.     private final int dimension;
  44.     /**
  45.      * Internal accounting data for the interpolation algorithm.
  46.      * Each element of the list corresponds to one surface element of
  47.      * the microsphere.
  48.      */
  49.     private final List<MicrosphereSurfaceElement> microsphere;
  50.     /**
  51.      * Exponent used in the power law that computes the weights of the
  52.      * sample data.
  53.      */
  54.     private final double brightnessExponent;
  55.     /**
  56.      * Sample data.
  57.      */
  58.     private final Map<RealVector, Double> samples;

  60.     /**
  61.      * Class for storing the accounting data needed to perform the
  62.      * microsphere projection.
  63.      */
  64.     private static class MicrosphereSurfaceElement {
  65.         /** Normal vector characterizing a surface element. */
  66.         private final RealVector normal;
  67.         /** Illumination received from the brightest sample. */
  68.         private double brightestIllumination;
  69.         /** Brightest sample. */
  70.         private Map.Entry<RealVector, Double> brightestSample;

  72.         /**
  73.          * @param n Normal vector characterizing a surface element
  74.          * of the microsphere.
  75.          */
  76.         MicrosphereSurfaceElement(double[] n) {
  77.             normal = new ArrayRealVector(n);
  78.         }

  80.         /**
  81.          * Return the normal vector.
  82.          * @return the normal vector
  83.          */
  84.         RealVector normal() {
  85.             return normal;
  86.         }

  88.         /**
  89.          * Reset "illumination" and "sampleIndex".
  90.          */
  91.         void reset() {
  92.             brightestIllumination = 0;
  93.             brightestSample = null;
  94.         }

  96.         /**
  97.          * Store the illumination and index of the brightest sample.
  98.          * @param illuminationFromSample illumination received from sample
  99.          * @param sample current sample illuminating the element
  100.          */
  101.         void store(final double illuminationFromSample,
  102.                    final Map.Entry<RealVector, Double> sample) {
  103.             if (illuminationFromSample > this.brightestIllumination) {
  104.                 this.brightestIllumination = illuminationFromSample;
  105.                 this.brightestSample = sample;
  106.             }
  107.         }

  109.         /**
  110.          * Get the illumination of the element.
  111.          * @return the illumination.
  112.          */
  113.         double illumination() {
  114.             return brightestIllumination;
  115.         }

  117.         /**
  118.          * Get the sample illuminating the element the most.
  119.          * @return the sample.
  120.          */
  121.         Map.Entry<RealVector, Double> sample() {
  122.             return brightestSample;
  123.         }
  124.     }

  126.     /**
  127.      * @param xval Arguments for the interpolation points.
  128.      * {@code xval[i][0]} is the first component of interpolation point
  129.      * {@code i}, {@code xval[i][1]} is the second component, and so on
  130.      * until {@code xval[i][d-1]}, the last component of that interpolation
  131.      * point (where {@code dimension} is thus the dimension of the sampled
  132.      * space).
  133.      * @param yval Values for the interpolation points.
  134.      * @param brightnessExponent Brightness dimming factor.
  135.      * @param microsphereElements Number of surface elements of the
  136.      * microsphere.
  137.      * @param rand Unit vector generator for creating the microsphere.
  138.      * @throws DimensionMismatchException if the lengths of {@code yval} and
  139.      * {@code xval} (equal to {@code n}, the number of interpolation points)
  140.      * do not match, or the the arrays {@code xval[0]} ... {@code xval[n]},
  141.      * have lengths different from {@code dimension}.
  142.      * @throws NoDataException if there an array has zero-length.
  143.      * @throws NullArgumentException if an argument is {@code null}.
  144.      */
  145.     public MicrosphereInterpolatingFunction(double[][] xval,
  146.                                             double[] yval,
  147.                                             int brightnessExponent,
  148.                                             int microsphereElements,
  149.                                             UnitSphereRandomVectorGenerator rand)
  150.         throws DimensionMismatchException,
  151.                NoDataException,
  152.                NullArgumentException {
  153.         if (xval == null ||
  154.             yval == null) {
  155.             throw new NullArgumentException();
  156.         }
  157.         if (xval.length == 0) {
  158.             throw new NoDataException();
  159.         }
  160.         if (xval.length != yval.length) {
  161.             throw new DimensionMismatchException(xval.length, yval.length);
  162.         }
  163.         if (xval[0] == null) {
  164.             throw new NullArgumentException();
  165.         }

  167.         dimension = xval[0].length;
  168.         this.brightnessExponent = brightnessExponent;

  170.         // Copy data samples.
  171.         samples = new HashMap<RealVector, Double>(yval.length);
  172.         for (int i = 0; i < xval.length; ++i) {
  173.             final double[] xvalI = xval[i];
  174.             if (xvalI == null) {
  175.                 throw new NullArgumentException();
  176.             }
  177.             if (xvalI.length != dimension) {
  178.                 throw new DimensionMismatchException(xvalI.length, dimension);
  179.             }

  181.             samples.put(new ArrayRealVector(xvalI), yval[i]);
  182.         }

  184.         microsphere = new ArrayList<MicrosphereSurfaceElement>(microsphereElements);
  185.         // Generate the microsphere, assuming that a fairly large number of
  186.         // randomly generated normals will represent a sphere.
  187.         for (int i = 0; i < microsphereElements; i++) {
  188.             microsphere.add(new MicrosphereSurfaceElement(rand.nextVector()));
  189.         }
  190.     }

  192.     /**
  193.      * @param point Interpolation point.
  194.      * @return the interpolated value.
  195.      * @throws DimensionMismatchException if point dimension does not math sample
  196.      */
  197.     public double value(double[] point) throws DimensionMismatchException {
  198.         final RealVector p = new ArrayRealVector(point);

  200.         // Reset.
  201.         for (MicrosphereSurfaceElement md : microsphere) {
  202.             md.reset();
  203.         }

  205.         // Compute contribution of each sample points to the microsphere elements illumination
  206.         for (Map.Entry<RealVector, Double> sd : samples.entrySet()) {

  208.             // Vector between interpolation point and current sample point.
  209.             final RealVector diff = sd.getKey().subtract(p);
  210.             final double diffNorm = diff.getNorm();

  212.             if (FastMath.abs(diffNorm) < FastMath.ulp(1d)) {
  213.                 // No need to interpolate, as the interpolation point is
  214.                 // actually (very close to) one of the sampled points.
  215.                 return sd.getValue();
  216.             }

  218.             for (MicrosphereSurfaceElement md : microsphere) {
  219.                 final double w = FastMath.pow(diffNorm, -brightnessExponent);
  220.                 md.store(cosAngle(diff, md.normal()) * w, sd);
  221.             }

  223.         }

  225.         // Interpolation calculation.
  226.         double value = 0;
  227.         double totalWeight = 0;
  228.         for (MicrosphereSurfaceElement md : microsphere) {
  229.             final double iV = md.illumination();
  230.             final Map.Entry<RealVector, Double> sd = md.sample();
  231.             if (sd != null) {
  232.                 value += iV * sd.getValue();
  233.                 totalWeight += iV;
  234.             }
  235.         }

  237.         return value / totalWeight;
  238.     }

  240.     /**
  241.      * Compute the cosine of the angle between 2 vectors.
  242.      *
  243.      * @param v Vector.
  244.      * @param w Vector.
  245.      * @return the cosine of the angle between {@code v} and {@code w}.
  246.      */
  247.     private double cosAngle(final RealVector v, final RealVector w) {
  248.         return v.dotProduct(w) / (v.getNorm() * w.getNorm());
  249.     }
  250. }
Created with JaCoCo 0.7.2.201409121644