Procedure

     INCNSG ( Intersection of cone and line segment )

     SUBROUTINE INCNSG ( APEX,   AXIS,  ANGLE, ENDPT1,
    .                    ENDPT2, NXPTS, XPT1,  XPT2   )

Abstract

     Compute the points of intersection of a specified nappe of a cone
     and a line segment.

Required_Reading

     None.

Keywords

     CONE
     GEOMETRY
     INTERSECTION
     LINE
     MATH
     SEGMENT

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION      APEX   ( 3 )
     DOUBLE PRECISION      AXIS   ( 3 )
     DOUBLE PRECISION      ANGLE
     DOUBLE PRECISION      ENDPT1 ( 3 )
     DOUBLE PRECISION      ENDPT2 ( 3 )
     INTEGER               NXPTS
     DOUBLE PRECISION      XPT1   ( 3 )
     DOUBLE PRECISION      XPT2   ( 3 )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     APEX       I   Apex of cone.
     AXIS       I   Axis of cone.
     ANGLE      I   Angle of cone.
     ENDPT1,
     ENDPT2     I   Endpoints of line segment.
     NXPTS      O   Number of intersection points.
     XPT1       O   First intersection point, if it exists.
     XPT2       O   Second intersection point, if it exists.

Detailed_Input

     APEX     is the apex (tip) of the cone. In this routine's
              documentation, we'll consider the cone to be a
              semi-infinite pyramid with circular cross-section. In
              some contexts, this object is called one "nappe" of
              the complete cone.

     AXIS     is an axis vector of the cone.

     ANGLE    is the angular separation from AXIS of the rays
              comprising the cone. Let the notation

                 < A, B >

              denote the dot product of vectors A and B, and let

                 ||A||

              denote the norm of vector A. Then the cone is the set
              of points

                           X-APEX       AXIS
                 { X:  < ----------,  -------- >  =  cos(ANGLE) }
                         ||X-APEX||   ||AXIS||


     ENDPT1,
     ENDPT2   are endpoints of a line segment. These points
              must be distinct.

Detailed_Output

     NXPTS    is the number of points of intersection of the input
              line segment and cone.

     XPT1     is the point of intersection of the segment and cone
              that is closest to ENDPT1, if an intersection exists.
              If there are no intersections, XPT1 is undefined.

     XPT2     is the point of intersection of the segment and cone
              that is farthest from ENDPT1, if two points of
              intersection exist. If there are not two
              intersections, XPT2 is undefined.

Parameters

     None.

Exceptions

     1)  If AXIS is the zero vector, the error SPICE(ZEROVECTOR)
         is signaled.

     2)  If ANGLE is less than zero, the error SPICE(INVALIDANGLE)
         is signaled.

     3)  If ENDPT1 and ENDPT2 coincide, the error
         SPICE(ENDPOINTSMATCH) is signaled.

Files

     None.

Particulars

     This routine is used by the SPICELIB DSK subsystem. In
     particular, it is used to determine whether a ray contacts a
     latitude boundary of a volume element in either planetocentric
     latitudinal or planetodetic coordinates.

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 intersection of a line segment and cone in
        a simple case for which the results can easily be checked.

        Let the apex of the cone be at the origin. Let the axis
        of the cone lie on the +X axis. Let the angle of the cone
        be 45 degrees. Let the line segment have endpoints

           ENDPT1 = ( 1,   -2, sqrt(3)/2 )
           ENDPT2 = ( 1,    2, sqrt(3)/2 )

        We expect there to be two points of intersection:

           XPT1   = ( 1, -1/2, sqrt(3)/2 )
           XPT2   = ( 1,  1/2, sqrt(3)/2 )


        Example code begins here.


              PROGRAM INCNSG_EX1
              IMPLICIT NONE
        C
        C     SPICELIB functions
        C
              DOUBLE PRECISION      RPD
        C
        C     Local parameters
        C
              CHARACTER*(*)         FMT1
              PARAMETER           ( FMT1 = '(A,3F13.8)' )

              CHARACTER*(*)         FMT2
              PARAMETER           ( FMT2 = '(A,I2)' )
        C
        C     Local variables
        C
              DOUBLE PRECISION      ANGLE
              DOUBLE PRECISION      APEX   ( 3 )
              DOUBLE PRECISION      AXIS   ( 3 )
              DOUBLE PRECISION      ENDPT1 ( 3 )
              DOUBLE PRECISION      ENDPT2 ( 3 )
              DOUBLE PRECISION      SQ3
              DOUBLE PRECISION      XPT1   ( 3 )
              DOUBLE PRECISION      XPT2   ( 3 )

              INTEGER               NXPTS

        C
        C     Set up the cone's geometric attributes.
        C
              CALL VPACK ( 0.D0, 0.D0, 0.D0, APEX )
              CALL VPACK ( 1.D0, 0.D0, 0.D0, AXIS )

              ANGLE = 45.D0 * RPD()
        C
        C     Initialize the line segment's endpoints.
        C
              SQ3 = SQRT( 3.D0  )

              CALL VPACK ( 1.D0, -2.D0, SQ3/2, ENDPT1 )
              CALL VPACK ( 1.D0,  2.D0, SQ3/2, ENDPT2 )
        C
        C     Find the points of intersection.
        C
              CALL INCNSG ( APEX,   AXIS,  ANGLE, ENDPT1,
             .              ENDPT2, NXPTS, XPT1,  XPT2   )

              WRITE (*,*) ' '
              WRITE (*,FMT1) 'Apex:        ', APEX
              WRITE (*,FMT1) 'Axis:        ', AXIS
              WRITE (*,FMT1) 'Angle (deg): ', ANGLE/RPD()
              WRITE (*,FMT1) 'Endpoint 1:  ', ENDPT1
              WRITE (*,FMT1) 'Endpoint 2:  ', ENDPT2
              WRITE (*,*) ' '
              WRITE (*,FMT2) 'Number of intersection points: ',
             .            NXPTS
              WRITE (*,*) ' '
              WRITE (*,FMT1) 'Point 1:    ', XPT1
              WRITE (*,FMT1) 'Point 2:    ', XPT2
              WRITE (*,*) ' '

              END


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


        Apex:           0.00000000   0.00000000   0.00000000
        Axis:           1.00000000   0.00000000   0.00000000
        Angle (deg):   45.00000000
        Endpoint 1:     1.00000000  -2.00000000   0.86602540
        Endpoint 2:     1.00000000   2.00000000   0.86602540

        Number of intersection points:  2

        Point 1:       1.00000000  -0.50000000   0.86602540
        Point 2:       1.00000000   0.50000000   0.86602540

Restrictions

     1)  This routine is designed to avoid arithmetic overflow in
         normal cases, such as those in which the line segment is
         nearly parallel to the cone. However, it is possible to cause
         arithmetic overflow by using input vectors with extremely
         large magnitudes.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 1.0.1, 06-JUL-2021 (JDR)

        Edited the header to comply with NAIF standard.

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