Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
cspice_ednmpt

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_EDNMPT returns the unique point on an ellipsoid's surface where
   the outward normal direction is a given vector.

I/O


   Given:

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

               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 coordinate system.

               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 coordinate system.

               help, c
                  DOUBLE = Scalar

      normal   a non-zero vector.

               help, normal
                  DOUBLE = Array[3]

               The unique point on the ellipsoid at which `normal' is an
               outward normal vector is sought.

   the call:

      cspice_ednmpt, a, b, c, normal, point

   returns:

      point    the unique point on the ellipsoid at which `normal' is an
               outward normal vector.

               help, point
                  DOUBLE = Array[3]

               `point' is a 3-vector giving the body-fixed coordinates
               of a point on the ellipsoid. In body-fixed coordinates,
               the semi-axes of the ellipsoid are aligned with the X,
               Y, and Z-axes of the coordinate system.

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) Choose a triaxial ellipsoid with three unequal semi-axis
      lengths. Pick several vectors; find the points on the
      ellipsoid where the respective outward normals are parallel to
      those vectors.

      Check the results: at each point, a computed outward normal
      vector should have very small angular separation from the
      input vector. Also, the point should be on the surface of the
      ellipsoid. The ellipsoid can be thought of as a level surface
      of the procedure

                           2        2         2
         f(x, y, z) = (x/a)  + (y/b)  +  (z/c)

      where `a', `b', `c' are the semi-axis lengths of the ellipsoid.
      Specifically, the ellipsoid is the set

         { (x, y, z) : f(x, y, z)  =  1 }

      We can evaluate F at a point to determine whether that point
      is close to the ellipsoid's surface.


      Example code begins here.


      PRO ednmpt_ex1

         ;;
         ;; Initialize the ellipsoid semi-axes.
         ;;
         a = 10.0
         b =  5.0
         c =  2.0

         ;;
         ;; Pick several vectors; find the points
         ;; on the ellipsoid where the respective
         ;; outward normals are parallel to those
         ;; vectors; check the results.
         ;;
         cspice_vpack, 0.0, 0.0, 3.0, xnorml
         cspice_ednmpt, a, b, c, xnorml, point
         cspice_surfnm, a, b, c, point, normal

         print, ' '
         print, format='(A,3F14.8)', 'Semi-axis lengths:   ', a, b, c
         print, format='(A,3F14.8)', 'Input vector:        ', xnorml[0],     $
                                     xnorml[1], xnorml[2]
         print, format='(A,3F14.8)', 'Point:               ', point[0],      $
                                     point[1], point[2]
         print, format='(A,3F14.8)', 'Outward normal:      ', normal[0],     $
                                     normal[1], normal[2]
         print, format='(A,F14.8)', 'Angular error (rad): ',                 $
                                    cspice_vsep( normal, xnorml )
         print, format='(A,F14.8)', 'Off-surface error:   ',                 $
                                    (point[0]/a) ^ 2 + (point[1]/b) ^ 2 +    $
                                    (point[2]/c) ^ 2 - 1
         print, ' '

         cspice_vpack, 15.0, -7.0, 3.0, xnorml
         cspice_ednmpt, a, b, c, xnorml, point
         cspice_surfnm, a, b, c, point, normal

         print, format='(A,3F14.8)', 'Semi-axis lengths:   ', a, b, c
         print, format='(A,3F14.8)', 'Input vector:        ', xnorml[0],     $
                                     xnorml[1], xnorml[2]
         print, format='(A,3F14.8)', 'Point:               ', point[0],      $
                                     point[1], point[2]
         print, format='(A,3F14.8)', 'Outward normal:      ', normal[0],     $
                                     normal[1], normal[2]
         print, format='(A,F14.8)', 'Angular error (rad): ',                 $
                                    cspice_vsep( normal, xnorml )
         print, format='(A,F14.8)', 'Off-surface error:   ',                 $
                                    (point[0]/a) ^ 2 + (point[1]/b) ^ 2 +    $
                                    (point[2]/c) ^ 2 - 1
         print, ' '

         cspice_vpack, 15.0, -7.0, 3.0, xnorml
         cspice_ednmpt, a, b, c, xnorml, point
         cspice_surfnm, a, b, c, point, normal

         print, format='(A,3F14.8)', 'Semi-axis lengths:   ', a, b, c
         print, format='(A,3F14.8)', 'Input vector:        ', xnorml[0],     $
                                     xnorml[1], xnorml[2]
         print, format='(A,3F14.8)', 'Point:               ', point[0],      $
                                     point[1], point[2]
         print, format='(A,3F14.8)', 'Outward normal:      ', normal[0],     $
                                     normal[1], normal[2]
         print, format='(A,F14.8)', 'Angular error (rad): ',                 $
                                    cspice_vsep( normal, xnorml )
         print, format='(A,F14.8)', 'Off-surface error:   ',                 $
                                    (point[0]/a) ^ 2 + (point[1]/b) ^ 2 +    $
                                    (point[2]/c) ^ 2 - 1
         print, ' '

         cspice_vpack, a/2, b/2, c/2, xnorml
         cspice_ednmpt, a, b, c, xnorml, point
         cspice_surfnm, a, b, c, point, normal

         print, format='(A,3F14.8)', 'Semi-axis lengths:   ', a, b, c
         print, format='(A,3F14.8)', 'Input vector:        ', xnorml[0],     $
                                     xnorml[1], xnorml[2]
         print, format='(A,3F14.8)', 'Point:               ', point[0],      $
                                     point[1], point[2]
         print, format='(A,3F14.8)', 'Outward normal:      ', normal[0],     $
                                     normal[1], normal[2]
         print, format='(A,F14.8)', 'Angular error (rad): ',                 $
                                    cspice_vsep( normal, xnorml )
         print, format='(A,F14.8)', 'Off-surface error:   ',                 $
                                    (point[0]/a) ^ 2 + (point[1]/b) ^ 2 +    $
                                    (point[2]/c) ^ 2 - 1
         print, ' '

      END


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


      Semi-axis lengths:      10.00000000    5.00000000    2.00000000
      Input vector:            0.00000000    0.00000000    3.00000000
      Point:                   0.00000000    0.00000000    2.00000000
      Outward normal:          0.00000000    0.00000000    1.00000000
      Angular error (rad):     0.00000000
      Off-surface error:       0.00000000

      Semi-axis lengths:      10.00000000    5.00000000    2.00000000
      Input vector:           15.00000000   -7.00000000    3.00000000
      Point:                   9.73103203   -1.13528707    0.07784826
      Outward normal:          0.89165745   -0.41610681    0.17833149
      Angular error (rad):     0.00000000
      Off-surface error:       0.00000000

      Semi-axis lengths:      10.00000000    5.00000000    2.00000000
      Input vector:           15.00000000   -7.00000000    3.00000000
      Point:                   9.73103203   -1.13528707    0.07784826
      Outward normal:          0.89165745   -0.41610681    0.17833149
      Angular error (rad):     0.00000000
      Off-surface error:       0.00000000

      Semi-axis lengths:      10.00000000    5.00000000    2.00000000
      Input vector:            5.00000000    2.50000000    1.00000000
      Point:                   9.69412864    1.21176608    0.07755303
      Outward normal:          0.88045091    0.44022545    0.17609018
      Angular error (rad):     0.00000000
      Off-surface error:       0.00000000


Particulars


   This routine can be used to determine the distance between an
   ellipsoid and a non-intersecting plane. This distance computation
   supports computation of terminator points on an ellipsoid.

Exceptions


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

   2)  If any of the semi-axis lengths underflows to zero when
       divided by the largest semi-axis length, the error
       SPICE(AXISUNDERFLOW) is signaled by a routine in the call tree
       of this routine.

   3)  If `normal' is the zero vector, the error SPICE(ZEROVECTOR)
       is signaled by a routine in the call tree of this routine.

   4)  If the input pass the above checks but lead to a
       divide-by-zero error or to a computing an invalid argument of
       a fractional exponential expression, the error
       SPICE(DEGENERATECASE) is signaled by a routine in the call
       tree of this routine.

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

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

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

Files


   None.

Restrictions


   None.

Required_Reading


   ICY.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)

Version


   -Icy Version 1.0.0, 09-AUG-2021 (JDR)

Index_Entries


   point on an ellipsoid having given surface normal



Fri Dec 31 18:43:03 2021