Procedure

     INELPL ( Intersection of ellipse and plane )

     SUBROUTINE INELPL ( ELLIPS, PLANE, NXPTS, XPT1, XPT2 )

Abstract

     Find the intersection of an ellipse and a plane.

Required_Reading

     ELLIPSES
     PLANES

Keywords

     ELLIPSE
     GEOMETRY
     MATH

Declarations

     IMPLICIT NONE

     INTEGER               UBEL
     PARAMETER           ( UBEL = 9 )

     INTEGER               UBPL
     PARAMETER           ( UBPL = 4 )

     DOUBLE PRECISION      ELLIPS ( UBEL )
     DOUBLE PRECISION      PLANE  ( UBPL )
     INTEGER               NXPTS
     DOUBLE PRECISION      XPT1   ( 3 )
     DOUBLE PRECISION      XPT2   ( 3 )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     ELLIPS     I   A SPICE ellipse.
     PLANE      I   A SPICE plane.
     NXPTS      O   Number of intersection points of plane and ellipse.
     XPT1,
     XPT2       O   Intersection points.

Detailed_Input

     ELLIPS   is a SPICE ellipse. The ellipse is allowed to
              be degenerate: one or both semi-axes may have
              zero length.

     PLANE    is a SPICE plane.

Detailed_Output

     NXPTS    is the number of points of intersection of the
              geometric plane and ellipse represented by PLANE
              and ELLIPS. NXPTS may take the values 0, 1, 2 or
              -1. The value -1 indicates that the ellipse
              consists of more than one point and lies in the
              plane, so the number of intersection points is
              infinite.

              When the ellipse consists of a single point and
              lies in the plane, NXPTS is set to 1.

     XPT1,
     XPT2     are the points of intersection of the input plane
              and ellipse. If there is only one intersection
              point, both XPT1 and XPT2 contain that point. If
              the number of intersection points is zero or
              infinite, the contents of XPT1 and XPT2 are
              undefined.

Parameters

     None.

Exceptions

     1)  If the input plane is invalid, the error SPICE(INVALIDPLANE)
         is signaled. The input plane must be a SPICE plane: the normal
         vector must be non-zero and the constant must be non-negative.

     2)  If the input ellipse has non-orthogonal axes, the error
         SPICE(INVALIDELLIPSE) is signaled.

     3)  The input ellipse is allowed to be a line segment or a point;
         these cases are not considered to be errors. If the ellipse
         consists of a single point and lies in the plane, the number
         of intersection points is set to 1 (rather than -1) and
         the output arguments XPT1 and XPT2 are assigned the value
         of the ellipse's center.

Files

     None.

Particulars

     This routine computes the intersection set of a non-degenerate
     plane with a possibly degenerate ellipse. The ellipse is allowed
     to consist of a line segment or a point.

     A plane may intersect an ellipse in 0, 1, 2, or infinitely many
     points. For there to be an infinite set of intersection points,
     the ellipse must lie in the plane and consist of more than one
     point.

Examples

     1)  If we want to find the angle of some ray above the limb of an
         ellipsoid, where the angle is measured in a plane containing
         the ray and a `down' vector, we can follow the procedure
         given below. We assume the ray does not intersect the
         ellipsoid. The result we seek is called ANGLE, imaginatively
         enough.

         We assume that all vectors are given in body-fixed
         coordinates.

            C
            C     Find the limb of the ellipsoid as seen from the
            C     point OBSERV. Here A, B, and C are the lengths of
            C     the semi-axes of the ellipsoid.
            C
                  CALL EDLIMB ( A, B, C, OBSERV, LIMB )

            C
            C     The ray direction vector is RAYDIR, so the ray is the
            C     set of points
            C
            C        OBSERV  +  t * RAYDIR
            C
            C     where t is any non-negative real number.
            C
            C     The `down' vector is just -OBSERV. The vectors
            C     OBSERV and RAYDIR are spanning vectors for the plane
            C     we're interested in. We can use PSV2PL to represent
            C     this plane by a SPICE plane.
            C
                  CALL PSV2PL ( OBSERV, OBSERV, RAYDIR, PLANE )

            C
            C     Find the intersection of the plane defined by OBSERV
            C     and RAYDIR with the limb.
            C
                  CALL INELPL ( LIMB, PLANE, NXPTS, XPT1, XPT2 )

            C
            C     We always expect two intersection points, if DOWN
            C     is valid.
            C
                  IF ( NXPTS .LT. 2 ) THEN

                     [ do something about the error ]

                  ENDIF

            C
            C     Form the vectors from OBSERV to the intersection
            C     points. Find the angular separation between the
            C     boresight ray and each vector from OBSERV to the
            C     intersection points.
            C
                  CALL VSUB   ( XPT1, OBSERV, VEC1 )
                  CALL VSUB   ( XPT2, OBSERV, VEC2 )

                  SEP1 = VSEP ( VEC1, RAYDIR )
                  SEP2 = VSEP ( VEC2, RAYDIR )

            C
            C     The angular separation we're after is the minimum of
            C     the two separations we've computed.
            C
                  ANGLE = MIN ( SEP1, SEP2 )

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 3.1.0, 24-AUG-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 3.0.0, 07-OCT-2011 (NJB)

        Relaxed ellipse semi-axes orthogonality test limit
        SEPLIM from 1.D-12 TO 1.D-9 radians. The angular
        separation of the axes of the input ellipse must not
        differ from pi/2 radians by more than this limit.

    SPICELIB Version 2.0.0, 14-JAN-2008 (NJB)

        Bug fix: the routine's specification and behavior have been
        updated so the routine now returns a meaningful result for the
        case of an ellipse consisting of a single point.

        Bug fix: in the degenerate case where the input ellipse is a
        line segment of positive length, and this segment intersects
        the plane, the number of intersection points is set to 1
        rather than 2.

        Invalid input planes and ellipses are now diagnosed.

    SPICELIB Version 1.2.0, 25-AUG-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VSUB call.

    SPICELIB Version 1.1.0, 24-MAR-1992 (NJB) (WLT)

        Output arguments XPT1, XPT2 are now correctly declared
        with length 3. Comment section for permuted index source
        lines was added following the header.

    SPICELIB Version 1.0.0, 02-NOV-1990 (NJB)