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_convrt

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


Abstract


   CSPICE_CONVRT performs a conversion from a measurement in
   one unit set to the corresponding measure in another unit
   set.

I/O


   Given:

      x        a number representing a measurement in the units specified by
               `in'.

               help, x
                  DOUBLE = Scalar

      in       the identifier of the units associated with the measurement `x'.

               help, in
                  STRING = Scalar

               Acceptable units are:

                  Angles:                 'RADIANS'
                                          'DEGREES'
                                          'ARCMINUTES'
                                          'ARCSECONDS'
                                          'HOURANGLE'
                                          'MINUTEANGLE'
                                          'SECONDANGLE'

                  Metric Distances:       'M'
                                          'METERS'
                                          'KM'
                                          'KILOMETERS'
                                          'CM'
                                          'CENTIMETERS'
                                          'MM'
                                          'MILLIMETERS'

                  English Distances:      'FEET'
                                          'INCHES'
                                          'YARDS'
                                          'STATUTE_MILES'
                                          'NAUTICAL_MILES'

                  Astrometric Distances:  'AU'
                                          'PARSECS'
                                          'LIGHTSECS'
                                          'LIGHTYEARS' julian lightyears

                  Time:                   'SECONDS'
                                          'MINUTES'
                                          'HOURS'
                                          'DAYS'
                                          'JULIAN_YEARS'
                                          'TROPICAL_YEARS'
                                          'YEARS' (same as julian years)

      out      the identifier of the units desired for the measurement `x'.

               help, out
                  STRING = Scalar

               See the description of `in'.

   the call:

      cspice_convrt, x, in, out, y

   returns:

      y        the input measurement converted to the desired units.

               help, y
                  DOUBLE = Scalar

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) Convert 300 miles (statute miles) to kilometers and determine
      the number of lightyears in a parsec.

      Example code begins here.


      PRO convrt_ex1

         ;;
         ;; Convert 300 miles (statute miles) to kilometers.
         ;;
         dist_sm = 300.d
         cspice_convrt, dist_sm, 'statute_miles', 'km', dist_km
         print, FORMAT='("300 miles in km  :", F16.6)', dist_km

         ;;
         ;; Determine the number of lightyears in a parsec.
         ;;
         one_parsec = 1.d
         cspice_convrt, one_parsec, 'parsecs', 'lightyears', lightyears
         print, FORMAT='("Lightyears/parsec:", F16.6)', lightyears

      END


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


      300 miles in km  :      482.803200
      Lightyears/parsec:        3.261564


Particulars


   This routine converts a measurement x given in units specified by
   in to the equivalent value y in units specified by out.

   If a unit is not recognized, an error message is produced that
   indicates which one was not recognized.

   If input and output units are incompatible (for example angle
   and distance units) and error message will be produced stating
   the requested units and associated types.

Exceptions


   1)  If the input units, output units, or both input and output
       units are not recognized, the error SPICE(UNITSNOTREC) is
       signaled by a routine in the call tree of this routine.

   2)  If the units being converted between are incompatible, the
       error SPICE(INCOMPATIBLEUNITS) is signaled by a routine in the
       call tree of this routine.

   3)  If any of the input arguments, `x', `in' or `out', is
       undefined, an error is signaled by the IDL error handling
       system.

   4)  If any of the input arguments, `x', `in' or `out', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy interface.

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

Files


   None.

Restrictions


   1)  This routine does not do any checking for overflow. The caller
       is required to make sure that the units used for the
       measurement are such that no floating point overflow will
       occur when the conversion is performed.

   2)  Some of the units are not "defined" quantities. In such a case
       a best estimate is provided as of the date of the current
       version of this routine. Those estimated quantities are:

          AU               The astronomical unit. The value was taken
                           from the JPL ephemeris DE125. This value
                           is an approximation and should not be used
                           for high-accuracy work. It agrees with the
                           value used in the JPL planetary ephemeris
                           DE430 (149597870.700 km) at the 100m
                           level.

          TROPICAL_YEARS   The tropical year is the time from equinox
                           to equinox. This varies slightly with
                           time.

          PARSECS          The parsec is the distance to an object
                           whose parallax angle is one arcsecond. Its
                           value is dependent upon the value of the
                           astronomical unit.

Required_Reading


   ICY.REQ

Literature_References


   None.

Author_and_Institution


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

Version


   -Icy Version 1.0.2, 17-JUN-2021 (JDR)

       Edited the header to comply with NAIF standard. Added example's problem
       statement and merged existing code into a single example.

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

       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.1, 11-JAN-2017 (EDW)

       Header update to correspond to current SPICELIB/CSPICE version.

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

Index_Entries


   convert units



Fri Dec 31 18:43:02 2021