Class SurfaceIntegral

java.lang.Object
org.bzdev.geom.SurfaceIntegral

public class SurfaceIntegral extends Object
Class providing surface integrals.

A scalar field f can be integrated over a surface S: $\int_S f dA$. Similarly a vector field v can be integrated over S: $\int_S \mathbf{v \cdot n} dA$. The constructors provide the scalar or vector fields as functions of (x, y, z), plus a degree for a polynomial approximation to these fields at the surface. This degree is used to compute the number of points used in the numerical integration. The methods integrate(SurfaceIterator), integrate(Shape3D), integrate(Shape3D,Transform3D), or integrate(Shape3D,Transform3D,int) will perform the integration for a specified surface.

The implementation uses Gauss-Legendre quadrature.

  • Constructor Details

    • SurfaceIntegral

      public SurfaceIntegral(int n, RealValuedFunctThreeOps sf)
      Constructor for the surface integral of a scalar field.
      Parameters:
      n - maximum value for the sum i+j+k of the exponents of terms xiyjzk for a polynomial in x, y and z that provides an adequate approximation to the scalar field over a surface patch
      sf - the scalar field as a function of x, y, and z
    • SurfaceIntegral

      public SurfaceIntegral(int n, RealValuedFunctThreeOps sf, int limit)
      Constructor for the surface integral of a scalar field with a flatness parameter.

      A flatness parameter determines if fewer points can be used for a numerical integration using Gauss-Legendre quadrature at the expense of some reduction in accuracy for the case of a cubic Bézier triangle or cubic Bézier patch (the surface integral is represented as a sum over patches). Consider the 16 control points for a cubic Bézier patch:

       P03 P13 P23 P33
       P02 P12 P22 P32
       P01 P11 P21 P31
       P00 P10 P20 P30
       
      If the patch is planar with the coordinates at each point linear in u and v, the intermediate control points will lie along lines connecting the corners and will be at locations 1/3 and 2/3 of the distance between each pair of corners. In the usual case in which the cubic Bézier patch is not planar, the flatness parameter is used to determine if the surface is close to planar. The criteria are as follows:
      • For each corner, construct a line vector from the corner to an adjacent control point (both along the edges and a diagonal) and from that corner and the opposite corner along the same edge and the same diagonal. If the absolute value of the tangent of the angle between these two vectors exceeds the flatness parameter, the test fails.
      • For each corner, construct a line vector from the corner to an adjacent control point (both along the edges and a diagonal) and from that corner and the opposite corner along the same edge and the same diagonal. Compute the lengths of these two lines. If ratio of the length of the line to an adjacent point to the length of the line to the opposite corner differs from 1/3 by more than the flatness limit, the test fails.
      • For each corner, construct a line vector from the corner to an adjacent control point (both along the edges and a diagonal) and from that corner and the opposite corner along the same edge and the same diagonal. Compute the lengths of these two lines. If the dot product of these two vectors is negative, the test fails.
      A similar set of tests is done for cubic B&ecute;zier triangles.

      The use of a flatness parameter can reduce running times for some computations noticeably with only a minor impact on accuracy. Please see SurfaceIntegral(int,RealValuedFunctThreeOps,RealValuedFunctThreeOps,RealValuedFunctThreeOps,double) for an example showing running times.

      Parameters:
      n - maximum value for the sum i+j+k of the exponents of terms xiyjzk for a polynomial in x, y and z that provides an adequate approximation to the scalar field over a surface patch
      sf - the scalar field as a function of x, y, and z
      limit - the flatness limit
    • SurfaceIntegral

      public SurfaceIntegral(int n, RealValuedFunctThreeOps xf, RealValuedFunctThreeOps yf, RealValuedFunctThreeOps zf)
      Constructor for the surface integral of a vector field.
      Parameters:
      n - maximum value for the sum i+j+k of the exponents of terms xiyjzk for a polynomial in x, y and z that provides an adequate approximation to a component of the vector field over a surface patch
      xf - the X component of the vector field as a function of x, y, and z
      yf - the Y component of the vector field as a function of x, y, and z
      zf - the Z component of the vector field as a function of x, y, and z
    • SurfaceIntegral

      public SurfaceIntegral(int n, RealValuedFunctThreeOps xf, RealValuedFunctThreeOps yf, RealValuedFunctThreeOps zf, double limit)
      Constructor for the surface integral of a vector field with a flatness parameter.

      A flatness parameter determines if fewer points can be used for a numerical integration using Gauss-Legendre quadrature at the expense of some reduction in accuracy for the case of a cubic Bézier triangle or cubic Bézier patch (the surface integral is represented as a sum over patches). Consider the 16 control points for a cubic Bézier patch:

       P03 P13 P23 P33
       P02 P12 P22 P32
       P01 P11 P21 P31
       P00 P10 P20 P30
       
      If the patch is planar with the coordinates at each point linear in u and v, the intermediate control points will lie along lines connecting the corners and will be at locations 1/3 and 2/3 of the distance between each pair of corners. In the usual case in which the cubic Bézier patch is not planar, the flatness parameter is used to determine if the surface is close to planar. The criteria are as follows:
      • For each corner, construct a line vector from the corner to an adjacent control point (both along the edges and a diagonal) and from that corner and the opposite corner along the same edge and the same diagonal. If the absolute value of the tangent of the angle between these two vectors exceeds the flatness parameter, the test fails.
      • For each corner, construct a line vector from the corner to an adjacent control point (both along the edges and a diagonal) and from that corner and the opposite corner along the same edge and the same diagonal. Compute the lengths of these two lines. If ratio of the length of the line to an adjacent point to the length of the line to the opposite corner differs from 1/3 by more than the flatness limit, the test fails.
      • For each corner, construct a line vector from the corner to an adjacent control point (both along the edges and a diagonal) and from that corner and the opposite corner along the same edge and the same diagonal. Compute the lengths of these two lines. If the dot product of these two vectors is negative, the test fails.
      A similar set of tests is done for cubic B&ecute;zier triangles.

      The use of a flatness parameter can reduce running times for some computations noticeably with only a minor impact on accuracy. For example, for a sphere constructed by joining two B&ecute;zier grids with a total of 3200 patches, each covering a small portion of the sphere, a center of mass computation's running time was reduced from 673 ms to 422 ms. Similarly, a computation of moments about the center of mass was reduced from 1.07 seconds to 606 ms. The flatness test took 8.2 milliseconds, and thus contributes very little to the total running time. The flatness parameter for these tests was 0.5. When printed with a "%g" format that by default displays 5 digits past the decimal point, the diagonal elements for the moments printed the same for both cases. The off-diagonal elements differed in the value before the decimal point, but the exponent was 1017 times smaller (and for a perfect sphere, should be zero).

      Parameters:
      n - maximum value for the sum i+j+k of the exponents of terms xiyjzk for a polynomial in x, y and z that provides an adequate approximation to a component of the vector field over a surface patch
      xf - the X component of the vector field as a function of x, y, and z
      yf - the Y component of the vector field as a function of x, y, and z
      zf - the Z component of the vector field as a function of x, y, and z
      limit - the flatness limit
  • Method Details

    • integrate

      public double integrate(SurfaceIterator si) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a surface iterator.
      Parameters:
      si - the surface iterator
      Returns:
      the surface integral
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
    • integrate

      public double integrate(SurfaceIterator si, boolean parallel, int size) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a surface iterator, specifying if the integral should be done in parallel.
      Parameters:
      si - the surface iterator
      parallel - true if the integral should be done in parallel; false if it should be done sequentially
      size - the number of surface elements that the iterator provides
      Returns:
      the surface integral
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
    • integrate

      public double integrate(Shape3D surface) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a 3D shape.
      Parameters:
      surface - the surface over which the integral is performed
      Returns:
      the value of the surface integral
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
    • integrate

      public double integrate(Shape3D surface, boolean parallel) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a 3D shape, specifying if the integral should be done in parallel.
      Parameters:
      surface - the surface over which the integral is performed
      parallel - true if the integral should be done in parallel; false if it should be done sequentially
      Returns:
      the value of the surface integral
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
    • integrate

      public double integrate(Shape3D surface, Transform3D transform) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a 3D shape modified by a transform. The actual surface is not modified.
      Parameters:
      surface - the surface
      transform - the transform to apply to the surface
      Returns:
      the value of the surface integral over the transformed surface
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
      See Also:
    • integrate

      public double integrate(Shape3D surface, Transform3D transform, boolean parallel, int size) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a 3D shape modified by a transform, specifying if the integral should be done in parallel. The actual surface is not modified.
      Parameters:
      surface - the surface
      transform - the transform to apply to the surface
      parallel - true if the integral should be done in parallel; false if it should be done sequentially
      size - an estimate of the number of elements (triangles and cubic patches) comprising the surface
      Returns:
      the value of the surface integral over the transformed surface
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
      See Also:
    • integrate

      public double integrate(Shape3D surface, Transform3D transform, int level) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a 3D shape modified by a transform, splitting each triangle or patch. Providing a level is useful when the transform is not an affine transform. The actual surface is not modified.
      Parameters:
      surface - the surface
      transform - the transform to apply to the surface
      level - The number of partitioning levels (each level splits each patch or triangle into quarters)
      Returns:
      the value of the surface integral over the transformed surface
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
      See Also:
    • integrate

      public double integrate(Shape3D surface, Transform3D transform, int level, boolean parallel, int size) throws IllegalArgumentException
      Perform a surface integral with the surface specified by a 3D shape modified by a transform, splitting each triangle or patch, specifying if the integral should be done in parallel. Providing a level is useful when the transform is not an affine transform. The actual surface is not modified.
      Parameters:
      surface - the surface
      transform - the transform to apply to the surface
      level - The number of partitioning levels (each level splits each patch or triangle into quarters)
      parallel - true if the integral should be done in parallel; false if it should be done sequentially
      size - an estimate of the number of elements (triangles and cubic patches) comprising the surface
      Returns:
      the value of the surface integral over the transformed surface
      Throws:
      IllegalArgumentException - the surface should have been oriented to integrate a vector field
      See Also: