Procedure

     SURFNM ( Surface normal vector on an ellipsoid )

     SUBROUTINE SURFNM ( A, B, C, POINT, NORMAL )

Abstract

     Compute the outward-pointing, unit normal vector at a point on
     the surface of an ellipsoid.

Required_Reading

     None.

Keywords

     ELLIPSOID
     GEOMETRY

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION   A
     DOUBLE PRECISION   B
     DOUBLE PRECISION   C
     DOUBLE PRECISION   POINT  ( 3 )
     DOUBLE PRECISION   NORMAL ( 3 )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     A          I   Length of the ellipsoid semi-axis along the X-axis.
     B          I   Length of the ellipsoid semi-axis along the Y-axis.
     C          I   Length of the ellipsoid semi-axis along the Z-axis.
     POINT      I   Body-fixed coordinates of a point on the ellipsoid.
     NORMAL     O   Outward pointing unit normal to ellipsoid at POINT.

Detailed_Input

     A        is the length of the semi-axis of the ellipsoid that is
              parallel to the X-axis of the body-fixed reference frame.

     B        is the length of the semi-axis of the ellipsoid that is
              parallel to the Y-axis of the body-fixed reference frame.

     C        is the length of the semi-axis of the ellipsoid that is
              parallel to the Z-axis of the body-fixed reference frame.

     POINT    is a 3-vector giving the bodyfixed coordinates of a point
              on the ellipsoid. In bodyfixed coordinates, the semi-axes
              of the ellipsoid are aligned with the X, Y, and Z-axes of
              the reference frame.

Detailed_Output

     NORMAL   is the unit vector pointing away from the ellipsoid and
              normal to the ellipsoid at POINT.

Parameters

     None.

Exceptions

     1)  If any of the axes are non-positive, the error
         SPICE(BADAXISLENGTH) is signaled.

Files

     None.

Particulars

     This routine computes the outward pointing unit normal vector to
     the ellipsoid having semi-axes of length A, B, and C from the
     point POINT.

Examples

     A typical use of SURFNM would be to find the angle of incidence
     of the light from the sun at a point on the surface of an
     ellipsoid.

     Let Q be a 3-vector representing the rectangular body-fixed
     coordinates of a point on the ellipsoid (we are assuming that
     the axes of the ellipsoid are aligned with the axes of the
     body fixed frame.) Let V be the vector from Q to the sun in
     bodyfixed coordinates. Then the following code fragment could
     be used to compute angle of incidence of sunlight at Q.

        CALL SURFNM   ( A, B, C, Q, NRML )

        INCIDN = VSEP ( V,          NRML )

Restrictions

     1)  It is assumed that the input POINT is indeed on the ellipsoid.
         No checking for this is done.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 1.4.0, 26-OCT-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard. Removed
        unnecessary $Revisions section.

        Updated the documentation to refer to "reference frame" instead
        of "coordinate system" as per NAIF conventions.

    SPICELIB Version 1.3.2, 23-FEB-2016 (NJB)

        Corrected some typos in the header.

    SPICELIB Version 1.3.1, 18-MAY-2010 (BVS)

        Removed "C$" marker from text in the header.

    SPICELIB Version 1.3.0, 02-SEP-2005 (NJB)

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

    SPICELIB Version 1.2.0, 07-AUG-1996 (WLT)

        Added a SAVE statement so that the error message will
        not be lost between separate invocations of the routine.

    SPICELIB Version 1.1.0, 21-JUL-1995 (WLT)

        A typo in the $Examples section was corrected

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (WLT)