McIDAS Programmer's Manual
Version 2003
[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]
Calibration is the process of converting data values sensed by an instrument to useful, physical quantities such as temperature, radiance and albedo. The McIDAS-X calibration subsystem is designed to:
Thus, you can define your own calibration modules that will allow McIDAS-X applications to view the data that you prescribe.
McIDAS-X has a defined Application Program Interface, including subroutine names, calling sequence and functionality, that all calibration modules must adhere to. This section provides a brief history of how the calibration API was developed and an overview of the applications interface.
In the mid-1980s, the McIDAS-X area-format image file was redesigned to accommodate the ever increasing number of remotely sensed data types. The redesign allowed programmers to add new datasets from a variety of platforms to McIDAS-X without changing the existing software or file format. The new area file format accommodated multibanded, multibyte data along with a variety of ancillary data. The redesign process also provided a general method of storing, navigating and calibrating these data. It defined an API that all navigation and calibration modules would adhere to, and a mechanism for accessing the appropriate module at application runtime. The previous section in this chapter described the navigation system; this section describes the calibration system.
For information about the McIDAS-X area format image file, see Chapter 6, Format of the Data Files. |
The calibration API is defined at several levels. For ADDE applications, the call to mcaget has a parameter to request data to be returned in a specific physical quantity. The calibration process occurs on the data server, and although calibration information is returned, it is usually not needed by the ADDE client application.
The next level down in the API is used by non-ADDE applications and by the ADDE data servers. A call to the araopt function, which sets the area options, will use a calibration module if the physical quantity specified in its UNIT option is different than that stored in the image file (word 53 of the area directory). Subsequent calls to redara, which reads the data, will use the calibration module if needed. This provides the application with calibrated data in a rather transparent and data-independent way.
Below araopt in the API is the subroutine kbprep, which provides the interface to the dynamic calibration modules. Most applications don't call the lower level API functions directly. However, you must understand this lowest API definition to incorporate new calibration modules.
The function names used to access the calibration are listed below:
These are not the names of the functions within the calibration module itself. A mapping is done in kbprep that allows applications to use multiple instances of different calibrations. kbprep builds the name of the module to load, based on the slot number and data type.
The numeric (1, 2 or 3) is the slot number, which allows simultaneous use of up to three different calibration modules. The data type, which is stored in word 52 of the area directory, is needed to construct the name of the module to call. For example, the data type for GOES-8 is GVAR. Thus, the name constructed, using slot number 1, is KB1GVAR, which uses the functions KB1INIGVAR, KB1CALGVAR, and KB1OPTGVAR.
All calibration modules have the same framework. They must conform to the McIDAS-X convention for functionality, names of functions, and types of arguments. This standardization allows applications to make use of these modules in a generic, yet powerful way. It is usually not necessary for applications to have any private knowledge of the data it's working with; the calibration interface provides a means to acquire certain aspects that are common to all.
When naming your calibration module, use this form: kbxtype.dlm, where type is the same four characters in word 52 of the area directory. For example, type could be GVAR, TIRO or AAA.
Each calibration module has identical function names and interface, and performs similar operations. The actual algorithm for calibrating the data is hidden from the application, regardless of the calibration type. All calibration modules contain these three functions:
| Function | Description |
|---|---|
provides additional operations, which are usually queries from the application |
The structure of these functions is designed so that any required ancillary data is passed in as arguments or handled by kbxopt. An exception is the access to the calibration block. Current McIDAS-X calibration modules requiring the calibration block read the block from disk from within kbxcal. A few modules have the capability to receive the calibration block through kbxopt, kbxgvar for example.
All the functions should return either the requested data or an error status. They should never terminate, but rather rely on the exception handling of the application.
Most McIDAS-X calibration modules retrieve necessary parameters from one of these locations:
Some calibration algorithms, such as VISR (GOES 1-byte data) don't require additional parameters, or the amount is fixed and relatively small. The VISR calibration was designed for the original GOES satellites, which transmitted its data as 1-byte values. For the visible (even sensor source numbers), the RAW value is the same as the BRIT, and no conversion is necessary. For the IR (odd sensor source numbers), an option for TEMP (temperature) is available through a lookup table coded in the module.
The calibration of these images are handled in the code without an external data structure.
The calibration parameters stored in the area directory, calibration block, line prefix and disk files are described below.
The MSAT (Meteosat) calibration parameters are stored in the area directory of an area format image file. Although the entire image only has three constant parameters, they change twice per day. SSEC does not recommend that you store parameters in the area directory, since it lacks available words. A calibration block is the preferred location.
The calibration block contains the calibration parameters for:
This block consists of 128 words and is the most common location for storing calibration parameters. The values in this block are used for the entire image file. Sections in the calibration block are defined for AAA and GVAR.
Normally, integers or scaled integers are stored so that moving the data to different platforms is not a problem. However, potential problems exist when storing character data. For example, when accessing files that are not native to the platform, byte flipping may be needed for integers but not character data. The problem arises when deciding how to flip the bytes, since a schema for storing calibration parameters is not defined. Currently, 4-byte words are tested to determine if all the bytes are printable characters. This does not always work for large or scaled integers. Be aware of this situation when developing new calibration modules, if problems seem to be platform-dependent.
For more information about the calibration blocks for AAA and GVAR, see the section titled Image-specific characteristics in the area file description in Chapter 6, Format of the Data Files. |
The prefix part of the data line contains the calibration parameters for:
This is the preferred location for image data, where calibration parameters can change throughout the image. For AAA data, two different channels may alternate through the image; TIRO calibration has a different set of parameters every five lines. Although you can define the documentation and calibration sections for specific data, use only the calibration section to store calibration parameters. The documentation section is not guaranteed to move with some copy commands.
For more information about the line prefix, see the section titled Data block in the area file description in Chapter 6, Format of the Data Files . |
Disk files, which are described earlier in this chapter, are used to store calibration parameters for:
The use of these files is decreasing as the definition of the calibration block is now less restricted. Previously, there was a 128-word limit in the calibration block; thus, storing large lookup tables in a disk file was preferable to including them as DATA statements in the code.
For VAS calibration, the line-to-line variability in the calibration coefficients required that the lookup tables be pregenerated for better performance. The file VASTBLS, which accounts for all possible lookup tables, is over six megabytes.
GMS data is received from the satellite as 1-byte values. For the IR, each value corresponds to a temperature; for the visible, an albedo. Because this table is fixed for GMS-3, and the calibration block was restricted to 128 words, a disk file was chosen to store the calibration information. For GMS-5, the tables are provided in the satellite data stream and are stored in a now-expanded calibration block. The disk file is not needed in this case, and will not be used for any future GMS satellites.
Most calibration modules in McIDAS-X generate lookup tables to convert the stored data to some output physical quantity. This is usually preferred over performing the computation for every input data value. For example, a standard McIDAS-X image frame is about 300,000 pixels. Since most input data is eight or 10 bits per value, performing 256 or 1024 computations to create a lookup table is much more efficient than doing 300,000. These are many byte and word manipulation routing in McIDAS that can help to simplify the code in calibration modules. These can be found in the Conversion Utilities section of Chapter 4.
The table below describes some of the data-specific functions you will use in your calibration modules. These functions pass values through a lookup table for performance and memory considerations.
| Function | Description |
|---|---|
For example, AAA data is sent by the satellite as 10-bit data, but is stored on disk as 15 bits. Rather than generating a lookup table of 32,768 values (for 15 bits), a table of 1024 values is made for the 10-bit data. maaatb does the bit shifting to take the raw 15-bit data to 10-bit, and then passes it into the lookup table.
For more information on conversion utilities, see the section titled Conversion utilities in Chapter 4, McIDAS-X Utilities. |
The sample calibration program named KBXSIN.DLM, which follows, illustrates the structure of a calibration module. It accepts input data, from 0 to 255, and returns values modified by a sine curve. To use this module with existing 1-byte data, run the following McIDAS-X command:
After compiling KBXSIN.DLM and any appropriate applications, McIDAS-X applications can be run against the data.
The three required functions below are present in the sample code. An additional subroutine, maktab, generates the lookup table.
kbxini takes its input, usually from araopt, and copies it to a local buffer, as shown in line 53. It then verifies that the calibration requested is valid; see lines 59 and 60.
kbxcal is usually not called directly from the application, but rather when required by redara. It takes as input:
The calibrated data is returned through the same buffer. kbxcal checks if the lookup table was generated (line 118). If not, a call is made to maktab ( line 119). mpixtb completes the calibration (line 125) by taking the data, passing it through the lookup table, and expanding or packing the bytes.
kbxopt contains additional operations for querying information about the calibration. The KEYS option, shown in lines 182-187, passes a frame directory block to the calibration module; the number and list of physical quantities are returned.
This option was written for the McIDAS-X IMGPROBE command, which lists the stored data values converted to appropriate quantities. The ADDE image directory servers actually use this option to pass the information block to the client application. Because the information returned by KEYS was incomplete, the option INFO (lines 191-202) was added to provide scale factors and units. The input for INFO is:
Most calibration modules contain code to handle stretch tables generated by the SU command. By calling kbxopt with BRKP as the option and the name of the stretch table, the calibration module computes a modified brightness value based on the table.
To identify the sections of code where this is done, find the CALTYP variable, which is held in COMMON/BRKPNT. In ADDE, this function is done in the client application instead of the calibration module. This code will be removed from the calibration modules in the future.
The sample calibration module, KBXSIN.DLM is provided below.
1: INTEGER FUNCTION KBXINI(CIN,COUT,IOPT)
2:
3: *$ Name:
4: *$ kbxini - Initialize for sine modified calibration
5: *$
6: *$ Interface:
7: *$ integer function
8: *$ kbxini( character*4 cin, character*4 cout, integer iopt(*))
9: *$
10: *$ Input:
11: *$ cin - input physical quantity ('TEMP', 'BRIT', 'RAW', etc.)
12: *$ cout - output physical quantity
13: *$ iopt -
14: *$ iopt(1) precision of stored data (1, 2 or 4 bytes)
15: *$ iopt(2) spacing of output data (1, 2 or 4 bytes)
16: *$ iopt(3-5) filled by araopt but should not be used
17: *$
18: *$ Input and Output:
19: *$ none
20: *$
21: *$ Output:
22: *$ none
23: *$
24: *$ Return values:
25: *$ 0 - success
26: *$ -1 - unit conversion not possible
27: *$
28: *$ Remarks:
29: *$ This calibration module will only accept values from 0 to
30: *$ 255 and will return values modified by a sine curve. There
31: *$ is no check for input data out of range.
32: *$
33: *$ Categories:
34: *$ calibration
35:
36: CHARACTER*4 CIN
37: CHARACTER*4 COUT
38: INTEGER IOPT(*)
39:
40: INCLUDE 'areaparm.inc'
41:
42: INTEGER JTYPE
43: INTEGER ISOU
44: INTEGER IDES
45: INTEGER JOPT(NUMAREAOPTIONS)
46: C
47: C--- Store information needed in other functions
48: C
49: COMMON/M0SIN/JTYPE,ISOU,IDES,JOPT
50: C
51: C--- Copy what araopt sent in
52: C
53: CALL MOVW(NUMAREAOPTIONS,IOPT,JOPT)
54:
55: JTYPE=0
56: ISOU=IOPT(1) ! length in bytes of input data
57: IDES=IOPT(2) ! length in bytes to output data
58:
59: IF(CIN.EQ.'RAW'.AND.COUT.EQ.'SIN') JTYPE=1
60: IF(CIN.EQ.'RAW'.AND.COUT.EQ.'BRIT') JTYPE=2
61: C
62: C--- If not one of the 2 cases above is true, error
63: C
64: IF(JTYPE.EQ.0) GO TO 900
65:
66: KBXINI=0
67: RETURN
68:
69: 900 CONTINUE
70: KBXINI = -1
71: RETURN
72: END
73:
74: INTEGER FUNCTION KBXCAL(PREFIX,IDIR,NVAL,IBAND,IBUF)
75: *$ Name:
76: *$ kbxcal - Calibrate data
77: *$
78: *$ Interface:
79: *$ integer function
80: *$ kbxcal( integer prefix(*), integer idir(*), integer nval,
81: *$ integer iband, integer ibuf(*))
82: *$
83: *$ Input:
84: *$ prefix - prefix part of image line (not needed)
85: *$ idir - area directory (not needed)
86: *$ nval - number of values to calibrate
87: *$ iband - band number (not needed)
88: *$
89: *$ Input and Output:
90: *$ ibuf - buffer containing data
91: *$
92: *$ Output:
93: *$ none
94: *$
95: *$ Return values:
96: *$ 0 - success
97: *$ -1 - error (not needed)
98: *$
99: *$ Categories:
100: *$ calibration
101:
102: INTEGER PREFIX(*)
103:
104: INCLUDE 'areaparm.inc'
105:
106: INTEGER JTYPE
107: INTEGER ISOU
108: INTEGER IDES
109: INTEGER JOPT(NUMAREAOPTIONS)
110:
111: INTEGER ITAB(256)
112:
113: COMMON/M0SIN/JTYPE,ISOU,IDES,JOPT
114: DATA IFLAG/0/
115: C
116: C--- If the calibration type changes, remake the lookup table
117: C
118: IF( JTYPE .NE. IFLAG) THEN
119: CALL MAKTAB(JTYPE, ITAB)
120: IFLAG = JTYPE
121: ENDIF
122: C
123: C--- Pass the data IBUF through the lookup table ITAB
124: C
125: CALL MPIXTB(NVAL,ISOU,IDES,IBUF,ITAB)
126:
127: KBXCAL=0
128: RETURN
129: END
130:
131:
132: INTEGER FUNCTION KBXOPT(CFUNC,IIN,IOUT)
133: *$ Name:
134: *$ kbxopt - Additional operations
135: *$
136: *$ Interface:
137: *$ integer function
138: *$ kbxopt( character*4 cfunc, integer iin(*), integer iout(*))
139: *$
140: *$ Input:
141: *$ cfunc - function ('INFO', 'KEYS')
142: *$ iin - for cfunc 'KEYS', iin contains frame directory block
143: *$ for cfunc 'INFO'
144: *$ iin(1) - band number
145: *$ iin(2) - sensor source number
146: *$ iin(3) - calibration type ('GVAR', for example)
147: *$
148: *$ Input and Output:
149: *$ none
150: *$
151: *$ Output:
152: *$ iout - for cfunc 'KEYS'
153: *$ iout(1) - number of physical quantities,'TEMP' etc.
154: *$ iout(2-n) - list of physical quantities
155: *$ iout - for cfunc 'INFO'
156: *$ iout(1) - number of physical quantities,'TEMP' etc.
157: *$ iout(2-n) - list of physical quantities, units,
158: *$ and scale factors
159: *$
160: *$ Return values:
161: *$ 0 - success
162: *$ 1 - invalid function
163: *$
164: *$ Categories:
165: *$ calibration
166:
167: CHARACTER*4 CFUNC
168:
169: INTEGER IIN(*)
170: INTEGER IOUT(*)
171:
172: INCLUDE 'areaparm.inc'
173:
174: INTEGER JTYPE
175: INTEGER ISOU
176: INTEGER IDES
177: INTEGER JOPT(NUMAREAOPTIONS)
178: COMMON/M0SIN/JTYPE,ISOU,IDES,JOPT
179: C
180: C--- KEYS option
181: C
182: IF( CFUNC .EQ. 'KEYS') THEN
183: IOUT(1) = 3 ! Number of types
184: IOUT(2) = LIT('RAW ') ! Physical quantities
185: IOUT(3) = LIT('SIN ')
186: IOUT(4) = LIT('BRIT')
187: ENDIF
188: C
189: C--- INFO option
190: C
191: IF( CFUNC .EQ. 'INFO') THEN
192: IOUT(1) = 3 ! Number of types
193: IOUT(2) = LIT('RAW ') ! Physical quantities
194: IOUT(3) = LIT('SIN ')
195: IOUT(4) = LIT('BRIT')
196: IOUT(5) = LIT(' ') ! Units
197: IOUT(6) = LIT('none')
198: IOUT(7) = LIT(' ')
199: IOUT(8) = 1 ! Scale factors
200: IOUT(9) = 1000
201: IOUT(10)= 1
202: ENDIF
203:
204: RETURN
205: END
206:
207:
208: SUBROUTINE MAKTAB(JTYPE, ITAB)
209: *$ Name:
210: *$ maktab - Make lookup table for sine modified calibration
211: *$
212: *$ Interface:
213: *$ subroutine
214: *$ maktab( integer jtype, integer itab(*))
215: *$
216: *$ Input:
217: *$ jtype - calibration type
218: *$ 1 - sine
219: *$ 2 - grayscale
220: *$
221: *$ Input and Output:
222: *$ none
223: *$
224: *$ Output:
225: *$ itab - lookup table of 256 values
226: *$
227: *$ Remarks:
228: *$ This routine makes a lookup table by computing the sine
229: *$ for all possible values from 0 to 255 (the range of the
230: *$ input data). Rather than computing the sine directly on
231: *$ the values 0 to 255, it is initially scaled to 0 to 10
232: *$ which is approximately 3 sine waves (3 * PI = 10)
233: *$
234: *$ Categories:
235: *$ calibration
236:
237: INTEGER ITAB(*)
238:
239: REAL SINVAL
240: REAL X
241: C
242: C---
243:
244: DO 100 I = 1, 256
245:
246: X = I - 1 ! X goes from 0 to 255
247: X = 10. * (X / 255.) ! Normalize and scale to 3 sine waves
248: SINVAL = SIN(X)
249: C
250: C--- Output sine value
251: C
252: IF (JTYPE .EQ. 1) THEN
253: ITAB(I) = NINT(SINVAL * 1000.) ! Scale sine by 1000
254: C
255: C--- Output grayscale value
256: C
257: ELSE IF (JTYPE .EQ. 2) THEN
258: ITAB(I) = NINT( 127. + 128 * SINVAL) ! Scale to 0 to 255
259: ENDIF
260:
261: 100 CONTINUE
262:
263:
264: RETURN
265: END
[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]