Abstract

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

I/O

   Given:

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

               help, a
                  DOUBLE = Scalar

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

               help, b
                  DOUBLE = Scalar

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

               help, c
                  DOUBLE = Scalar

      point    a 3-vector giving the bodyfixed coordinates of a point on the
               ellipsoid.

               help, point
                  DOUBLE = Array[3]

               In bodyfixed coordinates, the semi-axes of the ellipsoid are
               aligned with the X, Y, and Z-axes of the reference frame.

   the call:

      cspice_surfnm, a, b, c, point, normal

   returns:

      normal   the unit vector pointing away from the ellipsoid and normal to
               the ellipsoid at `point'.

               help, normal
                  DOUBLE = Array[3]

Parameters

   None.

Examples

   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Compute the surface normal to an ellipsoid defined by its three
      radii at a given location.

      Example code begins here.


      PRO surfnm_ex1

         ;;
         ;; Define the radii of an ellipsoid.
         ;;
         a  =  1.d
         b  =  2.d
         c  =  3.d

         ;;
         ;; Select a location.
         ;;
         point = [ 0.d, 0.d, 3.d ]

         ;;
         ;; calculate the surface normal to the ellipsoid at 'point'.
         ;;
         cspice_surfnm, a, b, c, point, out_norm
         print, 'Surface normal:'
         print, out_norm

      END


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


      Surface normal:
             0.0000000       0.0000000       1.0000000

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

Exceptions

   1)  If any of the axes are non-positive, the error
       SPICE(BADAXISLENGTH) is signaled by a routine in the call tree
       of this routine.

   2)  If any of the input arguments, `a', `b', `c' or `point', is
       undefined, an error is signaled by the IDL error handling
       system.

   3)  If any of the input arguments, `a', `b', `c' or `point', is
       not of the expected type, or it does not have the expected
       dimensions and size, an error is signaled by the Icy
       interface.

   4)  If the output argument `normal' is not a named variable, an
       error is signaled by the Icy interface.

Files

   None.

Restrictions

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

Required_Reading

   ICY.REQ
   ELLIPSES.REQ

Literature_References

   None.

Author_and_Institution

   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version

   -Icy Version 1.0.1, 01-NOV-2021 (JDR)

       Edited the header to comply with NAIF standard. Added example's problem
       statement and reformatted example's output.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections, and
       completed -Particulars section.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries

   surface normal vector on an ellipsoid