ConvertToUnits TCL UTILITIES USER MANUAL ConvertToUnits
SYNOPSIS
Convert a UDF measurement to physical units
PACKAGE
TCLUDF
NAME
ConvertToUnits
USAGE
set rV  ConvertToUnits  Key Ver N Alg V {Src} {SubSrc}]
INPUT DEFINITIONS
Key - The data key associated with the with UDF hierarchy of the opened file from which the measurements were obtained. Key should have been obtained from a call to GetDataKey.
Ver - Version number associated with the open file
N - The iD used when placing data to the the ExDa global variable. This is set in the call to ReadUDF.
Alg - The description of the algorithm used to convert the UDF raw data to the required units. This is obtained in a call to UUunitAlg
V - The array of returned data.
Src - An optional input which specifies the data source. This is defaulted to "" and if not changed the procedure will determine the input source from the Alg input. The possible settings are are:
"" - Use the source specified contained in the Alg input.
SENSOR - Converting a measurement associated with a VIDF sensor definition.
SCAN - Converting a set of indice data associated with a measurement.
MODE - Converting a insrument mode
ANCILLARY - Converting an ancillary measurement associated with a VIDF ancillary data definition.
SubSrc - If the data being converted is ANCILLARY data, this is the VIDF number of the ancillary data set to use. This is defaulted to 0 and can be left as such if Src is set to "" in which case the value is obtained from the Alg definition.
RETURN DEFINITION
The routines returns V(0)
DESCRIPTION
ConvertToUnits converts the raw data obtained in a call to ReadUDF to the units specified in the Alg argument. Data from a single measurement may be converted into multiple units by multiple calls to ConvertToUnits without having to reread the data.
ERRORS
None Generated
C BACKING
No
EXAMPLE(S) 
# RETURN THE X POSITION OF THE IMAGE SATELLITE IN BOTH KM AND Re

# INITIALIZE the UDF common variables

UDFInits

# GET the key for the UDF hierarchy IMAGE IMAGE1 OA ORBIT IMOORBIT

set KeY [GetDataKey IMAGE IMAGE1 OA ORBIT IMOORBIT]

# OPEN the data file containing the time 2001 198 1 0 0

FileOpen $KeY 0 2001 198 1 0 0 2001 198 6 0 0

# POSITION the file pointer to the beginning of the requested time

FilePos $KeY 0 2001 198 1 0 0

# IN the PIDF the Measurement definitions for the X, Y, and Z, spacecraft
#   locations are 0, 1, and 2 under the SENSOR drfinitions.  The UNIT 
#   definition to convert the measurements to km is 2 and to Re 5.
#   The algorithm definitions (2 per sensor) are set below.

set kV $KeY,0
set uX(0) [UUunitAlg $kV 2 0]
set uX(1) [UUunitAlg $kV 5 0]
set uY(0) [UUunitAlg $kV 2 1]
set uY(1) [UUunitAlg $kV 5 1]
set uZ(0) [UUunitAlg $kV 2 2]
set uZ(1) [UUunitAlg $kV 5 2]

# THE format used to print out the data

set FmT "%d %d %d : X %.0f  %.4f   Y %.0f  %.4f   Z %.0f  %.4f" 

# READ five instances of the satellite X,Y,Z positions and print out the
#   results (together the the start time) in both km and Re.

for { set I 0 } { $I < 5 } { incr I } { 
   ReadUDF $KeY 0 OA 0 0 0 
   set Xkm [ConvertToUnits $KeY 0 OA $uX(0) rV]
   set XRe [ConvertToUnits $KeY 0 OA $uX(1) rV]
   ReadUDF $KeY 0 OA 1 0 0 
   set Ykm [ConvertToUnits $KeY 0 OA $uY(0) rV]
   set YRe [ConvertToUnits $KeY 0 OA $uY(1) rV]
   ReadUDF $KeY 0 OA 2 0 1 
   set Zkm [ConvertToUnits $KeY 0 OA $uZ(0) rV]
   set ZRe [ConvertToUnits $KeY 0 OA $uZ(1) rV]

   puts stderr [format $FmT $ExDa(OA,BYR) $ExDa(OA,BDY) $ExDa(OA,BMSEC) \
          $Xkm $XRe $Ykm $YRe $Zkm $ZRe] 
}

>2001 198 3600000 : X -15183  -2.3831   Y -4507  -0.7075   Z 44264  6.9477
>2001 198 3720000 : X -15049  -2.3621   Y -4476  -0.7026   Z 44444  6.9760
>2001 198 3840000 : X -14914  -2.3409   Y -4445  -0.6977   Z 44621  7.0038
>2001 198 3960000 : X -14778  -2.3196   Y -4413  -0.6927   Z 44796  7.0312
>2001 198 4080000 : X -14642  -2.2982   Y -4381  -0.6877   Z 44969  7.0584
Feb 19, 2007