Procedure

     PLTVOL ( Compute volume of plate model )

     DOUBLE PRECISION FUNCTION PLTVOL ( NV, VRTCES, NP, PLATES )

Abstract

     Compute the volume of a three-dimensional region bounded by a
     collection of triangular plates.

Required_Reading

     DSK

Keywords

     DSK
     GEOMETRY
     MATH
     TOPOGRAPHY

Declarations

     IMPLICIT NONE

     INTEGER               NV
     DOUBLE PRECISION      VRTCES ( 3, NV )
     INTEGER               NP
     INTEGER               PLATES ( 3, NP )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     NV         I   Number of vertices.
     VRTCES     I   Array of vertices.
     NP         I   Number of triangular plates.
     PLATES     I   Array of plates.

     The function returns the volume of the spatial region bounded
     by the plates.

Detailed_Input

     NV       is the number of vertices comprising the plate
              model.

     VRTCES   is an array containing the plate model's vertices.
              Elements

                 VRTCES( 1, I )
                 VRTCES( 2, I )
                 VRTCES( 3, I )

              are, respectively, the X, Y, and Z components of
              the Ith vertex.

              This routine doesn't associate units with the
              vertices.


     NP       is the number of triangular plates comprising the
              plate model.

     PLATES   is an array containing 3-tuples of integers
              representing the model's plates. The elements of
              PLATES are vertex indices. The vertex indices are
              1-based: vertices have indices ranging from 1 to
              NV. The elements

                 PLATES( 1, I )
                 PLATES( 2, I )
                 PLATES( 3, I )

              are, respectively, the indices of the vertices
              comprising the Ith plate.

              Note that the order of the vertices of a plate is
              significant: the vertices must be ordered in the
              positive (counterclockwise) sense with respect to
              the outward normal direction associated with the
              plate. In other words, if V1, V2, V3 are the
              vertices of a plate, then

                 ( V2 - V1 )  x  ( V3 - V2 )

              points in the outward normal direction. Here
              "x" denotes the vector cross product operator.

Detailed_Output

     The function returns the volume of the spatial region bounded
     by the plates.

     If the components of the vertex array have length unit L, then the
     output volume has units

         3
        L

Parameters

     None.

Exceptions

     1)  The input plate model must define a spatial region with
         a boundary. This routine does not check the inputs to
         verify this condition. See the $Restrictions section below.

     2)  If the number of vertices is less than 4, the error
         SPICE(TOOFEWVERTICES) is signaled.

     3)  If the number of plates is less than 4, the error
         SPICE(TOOFEWPLATES) is signaled.

     4)  If any plate contains a vertex index outside of the range

            [1, NV]

         the error SPICE(INDEXOUTOFRANGE) is signaled.

Files

     None.

Particulars

     This routine computes the volume of a spatial region bounded by
     a set of triangular plates. If the plate set does not actually
     form the boundary of a spatial region, the result of this routine
     is invalid.

     Examples:

        Valid inputs
        ------------
        Tetrahedron
        Box
        Tiled ellipsoid
        Two disjoint boxes

        Invalid inputs
        --------------
        Single plate
        Tiled ellipsoid with one plate removed
        Two boxes with intersection having positive volume

Examples

     The numerical results shown for this example may differ across
     platforms. The results depend on the SPICE kernels used as input
     (if any), the compiler and supporting libraries, and the machine
     specific arithmetic implementation.


     1) Compute the volume of the pyramid defined by the four
        triangular plates whose vertices are the 3-element
        subsets of the set of vectors

           ( 0, 0, 0 )
           ( 1, 0, 0 )
           ( 0, 1, 0 )
           ( 0, 0, 1 )


        Example code begins here.


        C
        C     Compute the volume of a plate model representing the
        C     pyramid with one vertex at the origin and the other
        C     vertices coinciding with the standard basis vectors.
        C
              PROGRAM PLTVOL_EX1
              IMPLICIT NONE

        C
        C     SPICELIB functions
        C
              DOUBLE PRECISION      PLTVOL
        C
        C     Local parameters
        C
              INTEGER               NVERT
              PARAMETER           ( NVERT  = 4 )

              INTEGER               NPLATE
              PARAMETER           ( NPLATE = 4 )
        C
        C     Local variables
        C
              DOUBLE PRECISION      VRTCES ( 3, NVERT  )
              DOUBLE PRECISION      VOL

              INTEGER               PLATES ( 3, NPLATE )

        C
        C     Let the notation
        C
        C        < A, B >
        C
        C     denote the dot product of vectors A and B.
        C
        C     The plates defined below lie in the following planes,
        C     respectively:
        C
        C        Plate 1:    { P :  < P, (-1,  0,  0) > = 0 }
        C        Plate 2:    { P :  < P, ( 0, -1,  0) > = 0 }
        C        Plate 3:    { P :  < P, ( 0,  0, -1) > = 0 }
        C        Plate 4:    { P :  < P, ( 1,  1,  1) > = 1 }
        C
              DATA                  PLATES /    1,     4,     3,
             .                                  1,     2,     4,
             .                                  1,     3,     2,
             .                                  2,     3,     4 /

              DATA                  VRTCES / 0.D0,  0.D0,  0.D0,
             .                               1.D0,  0.D0,  0.D0,
             .                               0.D0,  1.D0,  0.D0,
             .                               0.D0,  0.D0,  1.D0 /


              VOL = PLTVOL ( NVERT, VRTCES, NPLATE, PLATES )

              WRITE (*,*) 'Expected volume =    1/6'
              WRITE (*,*) 'Computed volume = ', VOL

              END


        When this program was executed on a Mac/Intel/gfortran/64-bit
        platform, the output was:


         Expected volume =    1/6
         Computed volume =   0.16666666666666666

Restrictions

     1)  The plate collection must describe a surface and enclose a
         volume such that the divergence theorem (see [1]) is
         applicable.

Literature_References

     [1]  T. Apostol, "Calculus, Vol. II," John Wiley & Sons, 1969.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)

Version

    SPICELIB Version 1.0.1, 08-JUL-2020 (JDR)

        Edited the header to comply with NAIF standard. Added DSK to
        $Required_Reading. Updated code example comments.

    SPICELIB Version 1.0.0, 24-OCT-2016 (NJB)

        Based on original 11-FEB-2011