Procedure

   inelpl_c ( Intersection of ellipse and plane ) 

   void inelpl_c ( ConstSpiceEllipse  * ellips,
                   ConstSpicePlane    * plane,
                   SpiceInt           * nxpts,
                   SpiceDouble          xpt1[3],
                   SpiceDouble          xpt2[3] )

Abstract

   Find the intersection of an ellipse and a plane.

Required_Reading

   ELLIPSES
   PLANES

Keywords

   ELLIPSE
   GEOMETRY
   MATH

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. The intersection of plane
               and ellipse is sought.

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 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

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.

          #include "SpiceUsr.h"
              .
              .
              .
     /.
     Find the limb of the ellipsoid as seen from the
     point observ. Here a, b, and c are the lengths of
     the semi-axes of the ellipsoid. The limb is
     returned as a SpiceEllipse.
     ./

     edlimb_c ( a, b, c, observ, &limb );

     /.
     The ray direction vector is raydir, so the ray is the
     set of points

        observ  +  t * raydir

     where t is any non-negative real number.

     The `down' vector is just -observ. The vectors
     observ and raydir are spanning vectors for the plane
     we're interested in. We can use psv2pl_c to represent
     this plane by a SPICE plane.
     ./
     psv2pl_c ( observ, observ, raydir, &plane );

     /.
     Find the intersection of the plane defined by observ
     and raydir with the limb.
     ./
     inelpl_c ( limb, plane, nxpts, xpt1, xpt2 );

     /.
     We always expect two intersection points, if the vector
     down is valid.
     ./
     if ( nxpts < 2 )
     {
        [ do something about the error ]
     }

     /.
     Form the vectors from observ to the intersection
     points. Find the angular separation between the
     boresight ray and each vector from observ to the
     intersection points.
     ./
     vsub_c   ( xpt1, observ, vec1 );
     vsub_c   ( xpt2, observ, vec2 );

     sep1 = vsep_c ( vec1, raydir );
     sep2 = vsep_c ( vec2, raydir );

     /.
     The angular separation we're after is the minimum of
     the two separations we've computed.
     ./
     angle = mind_c ( 2, sep1, sep2 );

Restrictions

   None.

Literature_References

   None.

Author_and_Institution

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

Version

   -CSPICE Version 2.1.1, 24-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard.

       Removed non-standard header section "Revisions", moving its
       contents to the relevant entry in -Version section.

   -CSPICE Version 2.1.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.

   -CSPICE 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. In this case,
       if an intersection is found, the number of intersection points
       is set to 1 and both intersection arguments are set equal to
       the ellipse's center.

       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.
       Error handling code has been added to trap errors that had
       been erroneously passed off to lower level routines for
       diagnosis.

   -CSPICE Version 1.0.0, 28-AUG-2001 (NJB)

Index_Entries

   intersection of ellipse and plane