convrt_c |
Table of contents
Procedureconvrt_c ( Convert Units ) void convrt_c ( SpiceDouble x, ConstSpiceChar * in, ConstSpiceChar * out, SpiceDouble * y ) AbstractTake 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_ReadingNone. KeywordsCONVERSION UNITS Brief_I/OVARIABLE 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_Inputx 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: "METERS" "M" "KILOMETERS" "KM" "CENTIMETERS" "CM" "MILLIMETERS" "MM" 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) The case of the string in is not significant. out represents the units desired for the measurement x. See the description of in. The case of the string out is not significant. Detailed_Outputy is the input measurement converted to the desired units. ParametersNone. Exceptions1) 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 `in' or `out' input string pointers is null, the error SPICE(NULLPOINTER) is signaled. 4) If any of the `in' or `out' input strings has zero length, the error SPICE(EMPTYSTRING) is signaled. FilesNone. ParticularsThis 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. ExamplesThe numerical results shown for this example may differ across platforms. The results depend on the SPICE kernels used as input, the compiler and supporting libraries, 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. /. Program convrt_ex1 ./ #include <stdio.h> #include "SpiceUsr.h" int main( ) { /. Local variables. ./ SpiceDouble distsm; SpiceDouble onpars; SpiceDouble result; /. Convert 300 miles (statute miles) to kilometers. ./ distsm = 300.0; convrt_c ( distsm, "statute_miles", "km", &result ); printf ( "300 miles in km : %16.6f\n", result ); /. Determine the number of lightyears in a parsec. ./ onpars = 1.0; convrt_c ( onpars, "PARSECS", "LIGHTYEARS", &result ); printf ( "Lightyears/parsec: %16.6f\n", result ); return ( 0 ); } When this program was executed on a Mac/Intel/cc/64-bit platform, the output was: 300 miles in km : 482.803200 Lightyears/parsec: 3.261564 Restrictions1) 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. Literature_ReferencesNone. Author_and_InstitutionN.J. Bachman (JPL) C.A. Curzon (JPL) J. Diaz del Rio (ODC Space) H.A. Neilan (JPL) W.M. Owen (JPL) W.L. Taber (JPL) I.M. Underwood (JPL) Version-CSPICE Version 2.0.1, 13-AUG-2021 (JDR) Edited the header to comply with NAIF standard. Added complete code example. -CSPICE Version 2.0.0, 13-MAY-2016 (NJB) Updated to support expanded names of metric distance units, as well as to support the abbreviation "M" indicating meters. -CSPICE Version 1.0.0, 17-MAY-1999 (NJB) (CAC) (HAN) (WMO) (WLT) (IMU) Index_Entriesconvert units |
Fri Dec 31 18:41:03 2021