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

Procedure
Abstract
Required_Reading
Keywords
Declarations
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version

Procedure

      CONVRT ( Convert Units )
 
      SUBROUTINE CONVRT ( X, IN, OUT, Y )
 

Abstract

      Take a measurement X, the units associated with
      X, and units to which X should be converted; return Y ---
      the value of the measurement in the output units.

Required_Reading

     None.

Keywords

     CONVERSION, UNITS

Declarations

 
      DOUBLE PRECISION X
      CHARACTER*(*)    IN
      CHARACTER*(*)    OUT
      DOUBLE PRECISION Y
 

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  -------------------------------------------------
     X          I   Number representing a measurement in some units.
     IN         I   The units in which X is measured.
     OUT        I   Desired units for the measurement.
     Y          O   The measurement in the desired units.

Detailed_Input

     X          is a number representing a measurement in the units
                specified by IN.

     IN         represents the units associated with a measurement X.
                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        represents the units desired for the measurement X.
                See the description of IN.

Detailed_Output

     Y          is the input measurement converted to the desired
                units.

Parameters

     None.

Exceptions

     1) If the input units, output units, or both input and
        output units are not recognized, the error
        SPICE(UNITSNOTREC) is signaled.

     2) If the units being converted between are incompatible, the
        error SPICE(INCOMPATIBLEUNITS) is signaled.

Files

     None.

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.

Examples

     To convert 1 meter to statute miles and feet you could

        CALL CONVRT ( 1.0D0, 'METERS',        'STATUTE_MILES', MILES )
        CALL CONVRT ( MILES, 'STATUTE_MILES', 'FEET',          FEET  )

     or

        CALL CONVRT ( 1.0D0, 'METERS', 'STATUTE_MILES', MILES )
        CALL CONVRT ( 1.0D0, 'METERS', 'FEET',          FEET  )

Restrictions

     You should make sure that your units are appropriate for the
     measurement. This routine does not do any checking for over-
     flow. Something like

        CALL ( 10.0D22, 'LIGHTYEARS', 'MM', Y )

     will cause a floating point overflow.

     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:

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

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

         1 PARSEC --- is dependent upon the value of the astronomical
                      unit.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman    (JPL)
     C.A. Curzon     (JPL)
     H.A. Neilan     (JPL)
     W.M. Owen       (JPL)
     W.L. Taber      (JPL)
     I.M. Underwood  (JPL)

Version

    SPICELIB Version 2.0.0, 12-MAY-2015 (NJB)

        Added support for full names of metric distance units. Added
        support for the abbreviation 'M' indicating meters.
     
    SPICELIB Version 1.0.2, 01-JUL-2014 (NJB)

        Updated the description of the AU in the Restrictions
        section.

    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 (CAC) (WMO) (WLT) (IMU)
Wed Apr  5 17:46:10 2017