Document #LD_008_006_001_00_00_0_19990423 ******************************************************************************** * * * Readme file for the FIRE ACE ER2 MAS Data Sets * * * ******************************************************************************** 1.0 INTRODUCTION This file contains information about the NASA ER2 Moderate Resolution Imaging Spectroradiometer (MODIS) Airborne Simulator (MAS) data sets sample read software and data file for the data set: First ISCCP Regional Experiment Arctic Cloud Experiment (FIRE_ACE_ER2_MAS) The ER2 MAS data files range in size from 8 Mbytes to 1.1 Gbytes. The data files are written in netCDF (Common Data Format). NCSA's (National Center for Supercomputing Applications) HDF (Hierarchical Data Format) libraries with the netCDF extensions are required to build the read software. These libraries can be obtained via anonymous ftp from ftp.ncsa.uiuc.edu (141.142.20.50) or via the World Wide Web at http://hdf.ncsa.uiuc.edu. This readme file includes the following sections: Section 2.0 - describes all sample programs (source files). Section 3.0 - discusses how to create the executable from the C program(s). Section 4.0 - demonstrates how to invoke the run-time executable(s). Section 5.0 - provides general information on the data set. Section 6.0 - provides more detailed implementation notes. If users have questions while using the sample read software, please contact the Langley DAAC Science, User and Data Services (SUDS) office at: NASA Langley Research Center Langley DAAC Science, User and Data Services Office Mail Stop 157D 2 South Wright Street Hampton, VA 23681 USA email: support-asdc@earthdata.nasa.gov telephone: (757) 864-8656 fax: (757) 864-8807 2.0 READ SOFTWARE FILES There are two sample read programs for the ER2_MAS data sets developed by the DAAC. One is in the C programming language and the other is in Interactive Data Language (IDL). The C program has been tested on Sun 4 (OS 4.1.3), Solaris 2.3 and HP UNIX-based workstations. The IDL program was developed and tested on an SGI workstation. Information about IDL can be obtained at the Research Systems, Inc. web site at: http://www.rsinc.com/ There is also Fortran read software. Two files are used to generate the Fortran read software: ace_er2_mas_read_netcdf.f and ace_er2_mas_constant.i. The Fortran read software is available at the Langley DAAC or may be downloaded from the MAS URL at: http://ltpwww.gsfc.nasa.gov/MODIS/MAS/sw.html Also, a viewer for MAS Imagery called SHARP is available at the following URL: http://cimss.ssec.wisc.edu/~gumley/sharp/sharp.html The read software includes: ace_er2_mas_read_netcdf.c - 'C' read software based upon NCSA's "ncdump" utility with major modifications. ace_er2_mas_read_netcdf.f - Fortran based read software ace_er2_mas_constant.i - include file for use with Fortran based read software ace_er2_mas_read_netcdf_idl.pro - IDL read software based on the 'C' read software. The ace_er2_mas_read_netcdf.c program is meant to be an example program provided for the user's convenience. With minor modifications, the program can be compiled and executed on many different platforms. This read software is heavily based upon the NCSA distributed version of the netCDF utility "ncdump". In fact, the program should work for most, if not all, netCDF formatted files. Please see program source code for copyright information. 3.0 CREATING EXECUTABLE FILES The user can build the sample read program from the C or Fortran source files. To build the executable using the C source file at the UNIX commmand line prompt type: cc (or acc) -DNO_HAVE_PROTOTYPES -DNO_STDARG -I/usr/local/hdf/include -o ace_er2_mas_read_netcdf_c ace_er2_mas_read_netcdf.c -L/usr/local/hdf/lib -lmfhdf -ljpeg -ldf -lz /usr/lib/libm.a To build the executable using the Fortran source files for the ER2_MAS data set, type: f77 -DNO_HAVE_PROTOTYPES -DNO_STDARG -I/usr/local/hdf/include -o ace_er2_mas_read_netcdf_f ace_er2_mas_read_netcdf.f ace_er2_mas_constant.i -L/usr/local/hdf/lib -lmfhdf -ljpeg -ldf -lz /usr/lib/libm.a NOTE 1: The -I (include) and -L (library) hdf directory paths may differ on your system. /usr/lib/libm.a should be the path to your system math libraries. NOTE 2: The include file mas_constant.i should be in the working directory. A warning is issued for line 55 of mas_constant.i for an unused variable. This does not effect the use of this program. 4.0 INVOLKING READ SOFTWARE This section illustrates the invocation of the executable file. Currently, the executable ace_er2_mas_read_netcdf_c program does not accept command line arguments. When the program is executed, it requests an input filename. The output file name is automatically created by appending ".rpt" to the input file name. This code assumes that the data and code are located in the working directory. The report file generated will also be written to the working directory. After entering the filename, the user is presented with a parameter selection list. The user can select some of the parameters or all of the parameters to be written into the output file. At this point, the program generates the report file and exits. To begin program execution for the 'C' executable at the UNIX command line prompt, type : ace_er2_mas_read_netcdf_c The idl read software can be compiled and run through the IDL development environment. The idl read software can also be started by compiling and then executing the program. At the UNIX command line prompt, type: idl IDL>.compile ace_er2_mas_read_netcdf_idl.pro IDL>ace_er2_mas_read_netcdf_idl Currently, the executable ace_er2_mas_read_netcdf_f program does not accept command line arguments. When the program is executed, it requests an input filename. An output filename is not automatically created. After entering the filename, the user must input a series of (carriage returns) or n - (no's) for a series of output requests. To begin program execution for the Fortran executable, at the UNIX command line prompt, type: ace_er2_mas_read_netcdf_f A sample of the interactive program execution is provided in Section 6.0. 5.0 DATA SET INFORMATION The data files contain 2 types of data. The "Global" data consist of data that are pertinent to the entire file. Examples of these are the begin_date, end_date and CreationDate. There are varying numbers of Scientific Data Sets (SDSs) in the different data sets. These SDSs contain the recorded variable data. Examples of the type of information are Solar Azimuth Angle, Calibrated Data, and Black Body count. A complete listing is shown in section 6.0. Further information can be retrieved using the ace_er2_mas_read_netcdf_c executable program and entering #6 for the item number to view the DataSetHeader. During validation checking of the FIRE_ACE_ER2_MAS data granules, it was discovered that several of the granules where the flight overlapped a day have the date for the first day with a time for the next day. (e.g., flight 98-064, The flight dates are 05/18-19: In track 16 -- begin_date 19980518 000404 end_date 19980518 002458; The end_date should be 19980519.) The naming convention used for the files includes the starting date of the flight. For the corresponding flight number, see the following table. Flight No. Date 98-077 08 June 1998 98-076 06 June 1998 98-075 04 June 1998 98-074 03 June 1998 98-073 02 June 1998 98-072 01 June 1998 98-071 30 May 1998 98-070 29 May 1998 98-069 27 May 1998 98-068 26 May 1998 98-067 24 May 1998 98-066 22 May 1998 98-065 20 May 1998 98-064 18 May 1998 98-063 13 May 1998 Affected tracks (granules): flight 98-064, flight dates 05/18-19/1998 Track 16: begin_date 19980518 000404 end_date 19980518 002458 Track 17: begin_date 19980518 002534 end_date 19980518 004349 Track 18: begin_date 19980518 004350 end_date 19980518 010211 flight 98-065, flight dates 05/20-21/1998 Track 17: begin_date 19980520 002938 end_date 19980520 004637 flight 98-067, flight dates 05/24-25/1998 Track 12: begin_date 19980524 000005 end_date 19980524 001208 flight 98-068, flight dates 05/26-27/1998 Track 18: begin_date 19980526 000003 end_date 19980526 001331 Track 19: begin_date 19980526 001332 end_date 19980526 002659 Track 20: begin_date 19980526 002722 end_date 19980526 004648 flight 98-069, flight dates 05/27-28/1998 Track 16: begin_date 19980527 002046 end_date 19980527 003025 Track 17: begin_date 19980527 003125 end_date 19980527 004502 Track 18: begin_date 19980527 004503 end_date 19980527 005841 Track 19: begin_date 19980527 005851 end_date 19980527 010058 flight 98-071, flight dates 05/30-31/1998 Track 15: begin_date 19980530 004310 end_date 19980530 005632 Track 16: begin_date 19980530 005633 end_date 19980530 010956 Track 17: begin_date 19980530 010957 end_date 19980530 012319 Track 18: begin_date 19980530 012320 end_date 19980530 013642 Track 19: begin_date 19980530 013643 end_date 19980530 014958 Track 20: begin_date 19980530 015003 end_date 19980530 015526 Track 21: begin_date 19980530 015600 end_date 19980530 015646 flight 98-072, flight dates 06/01-02/1998 Track 16: begin_date 19980601 005947 end_date 19980601 011358 Track 17: begin_date 19980601 011415 end_date 19980601 011926 Track 18: begin_date 19980601 012045 end_date 19980601 012242 Track 19: begin_date 19980601 012301 end_date 19980601 013623 Track 20: begin_date 19980601 013624 end_date 19980601 015035 flight 98-073, flight dates 06/02-03/1998 Track 18: begin_date 19980602 011007 end_date 19980602 011713 Track 19: begin_date 19980602 011728 end_date 19980602 012036 Track 20: begin_date 19980602 012043 end_date 19980602 014215 flight 98-077, flight dates 06/08-09/1998 Track 14:begin_date 19980608 004717 end_date 19980608 005532 Track 15: begin_date 19980608 005547 end_date 19980608 010909 Track 16: begin_date 19980608 010910 end_date 19980608 012232 Track 17: begin_date 19980608 012233 end_date 19980608 013555 Track 18: begin_date 19980608 013556 end_date 19980608 014418 Questions pertaining to the data values contained within these files should be directed to: Paul A. Hubanks MODIS Science Data Support Team Research and Data Systems Corporation NASA Goddard Space Flight Center Greenbelt, MD 20771 Tel: (301) 982-3724 E-mail: hubanks@ltpsun.gsfc.nasa.gov 6.0 IMPLEMENTATION NOTES 6.1 Compiling 'C' program using HDF4.1r1 (tested on Sun 4) acc ace_er2_mas_read_netcd.c -g -I/usr/local/hdf/include -o read_mas_c -L/usr/local/hdf/lib -lmfhdf -ldf -ljpeg -lz /usr/lib/libm.a 6.2 Compiling Fortran program using HDF4.1r1 (for Sun 4) f77 ace_er2_mas_read_netcdf.f -I/usr/local/hdf/include -o read_mas_f -L/usr/local/HDF4.1r1/lib -lmfhdf -ldf -ljpeg -lz /usr/lib/libm.a (for SGI) f77 -64 -mips4 -O -s -o read_mas_f ace_er2_mas_read_netcdf.f -I/usr/local/hdf/include -L/usr/local/HDF4.1r1/lib -lmfhdf -ldf -lz (for HP) f77 -O -o read_mas_f ace_er2_mas_read_netcdf.f -I/usr/local/hdf/include /usr/local/hdf/lib/libmfhdf.a /usr/local/hdf/lib/libdf.a /usr/local/hdf/lib/libjpeg.a /usr/local/hdf/lib/libz.a /usr/lib/libm.a 6.3 Output demonstration of Fortran sample read software. 6.3.1 Sample read software for ace_er2_mas_read_netcdf_f: WARNING: This version fixes a bug in HDF3.3r3 Enter HDF file name : mas_950911s6.01 name=mas_950911s6.01 HDF file id = 393216 # of Global Attributes = 33 # of Scientific Data Sets (SDS"s) = 38 Read Global Attributes ? ( or n ) : ******** GLOBAL ATTRIBUTE ********* Attribute_Name = title Attribute Index = 0 Number_Type = 4 Count = 44 - - - Attribute Value - - - MODIS Airborne Simulator (MAS) Level-1B Data ********************************** Continue ? ( or n ) : ******** GLOBAL ATTRIBUTE ********* Attribute_Name = CreationDate Attribute Index = 1 Number_Type = 4 Count = 18 - - - Attribute Value - - - 10-Aug-96 22:52:34 ********************************** Continue ? ( or n ) : ******** GLOBAL ATTRIBUTE ********* Attribute_Name = ExperimentName Attribute Index = 2 Number_Type = 4 Count = 20 - - - Attribute Value - - - SCAR-B ********************************** Continue ? ( or n ) : . . Output continues in this manner until all GLOBAL ATTRIBUTES are shown. . Read Scientific Data Set"s (SDS"s) ? ( or n) : ************* Scientific Data Set ************** SDS_Name = Left50%ResponseWavelength Index = 0 SDS_ID = 262144 # of Dims = 1 DimSizes = 50 0 0 0 0 Number_Type = 5 Number of Attributes = 1 - - - Sample Data Value - - - 0.626999974 - - - - - - - - - - - - - - - Read SDS attribute string ? ( or n ) : -------- Local Attribute ----------- Attribute_Name = units Attribute Index = 0 Number_Type = 4 Count = 7 - - - Attribute Value - - - microns -------------------------------------- ************************************************ . . Output continues in this manner until all Scientific Data Sets are shown. . ************* Scientific Data Set ************** SDS_Name = CalibratedData Index = 37 SDS_ID = 262181 # of Dims = 3 DimSizes = 716 50 2012 0 0 Number_Type = 22 Number of Attributes = 2 - - - Sample Data Value - - - 474 - - - - - - - - - - - - - - - Read SDS attribute string ? ( or n ) : -------- Local Attribute ----------- Attribute_Name = units Attribute Index = 0 Number_Type = 4 Count = 29 - - - Attribute Value - - - watts/meter2/steradian/micron -------------------------------------- -------- Local Attribute ----------- Attribute_Name = scale_factor Attribute Index = 1 Number_Type = 5 Count = 50 - - - Attribute Value - - - 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.01000 0.01000 0.01000 0.01000 0.01000 0.10000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 -------------------------------------- ************************************************ Continue ? ( or n ) : Dump Descaled Calibrated Radiances ? ( or n) : ************* Scientific Data Set ************** SDS_Name = CalibratedData Index = 37 SDS_ID = 262181 # of Dims = 3 DimSizes = 716 50 2012 0 0 Number_Type = 22 Number of Attributes = 2 -------- Local Attribute ----------- Attribute_Name = units Attribute Index = 0 Number_Type = 4 Count = 29 - - - Attribute Value - - - watts/meter2/steradian/micron -------- Local Attribute ----------- Attribute_Name = scale_factor Attribute Index = 1 Number_Type = 5 Count = 50 - - - Attribute Value - - - 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.10000 0.01000 0.01000 0.01000 0.01000 0.01000 0.10000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.00100 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 0.01000 Enter Pixel(1-716), Record(1- 2012), Channel(1-12) ? 716,2012,12 At Pixel = 716 Record = 2012 For Channel = 12 Stored Value = 611 Scale Factor = 0.010 Calibrated Radiance = 6.1099996567 Another ? ( or n ) : n 6.4 Output demonstration of C sample read software. 6.4.1 Complete list of parameters for ace_er2_mas_read_netcdf.c Item Data Type Label(dimension lengths) ==== ========= ======================== 1 float Left50%ResponseWavelength(50) 2 float Central100%ResponseWavelength(50) 3 float Right50%ResponseWavelength(50) 4 float SolarSpectralIrradiance(50) 5 short AnchorPointIndex(716) 6 char DataSetHeader(13520) 7 long ScanLineCounter(2012) 8 float ScanRate(2012) 9 long GreenwichMeanTime(2012) 10 long MasTime(2012) 11 long GpsTime(2012) 12 short AircraftRollCount(2012) 13 long YearMonthDay(2012) 14 float ScanlineTime(2012) 15 short BlackBody1Temperature(2012 X 50) 16 short BlackBody2Temperature(2012 X 50) 17 short AnalogGain(2012 X 50) 18 short AnalogOffset(2012 X 50) 19 short BlackBody1Counts(2012 X 50) 20 short BlackBody2Counts(2012 X 50) 21 short Head1Counts(2012 X 50) 22 short Head2Counts(2012 X 50) 23 short Head1Temperatures(2012 X 50) 24 short Head2Temperatures(2012 X 50) 25 float CalibrationSlope(2012 X 50) 26 float CalibrationIntercept(2012 X 50) 27 float PixelLatitude(2012 X 716) 28 float PixelLongitude(2012 X 716) 29 float SensorZenithAngle(2012 X 716) 30 float SensorAzimuthAngle(2012 X 716) 31 float SolarZenithAngle(2012 X 716) 32 float SolarAzimuthAngle(2012 X 716) 33 float AircraftLatitude(2012) 34 float AircraftLongitude(2012) 35 float AircraftHeading(2012) 36 float AircraftAltitude(2012) 37 float AircraftPitch(2012) 38 short CalibratedData(2012 X 50 X 716) 6.4.2 Partial output for ace_er2_mas_read_netcdf.c selecting just one parameter with the global data. This program reads the FIRE ASTEX and FIRE CI2 ER2 MAS netCDF data. Please enter Q to Quit or C to continue c Please enter netCDF file name to read: scarbmas_950911s6.01 Report file name is: scarbmas_950911s6.01.rpt Item Data Type Label(dimension lengths) ==== ========= ======================== 1 float Left50%ResponseWavelength(50) 2 float Central100%ResponseWavelength(50) 3 float Right50%ResponseWavelength(50) 4 float SolarSpectralIrradiance(50) 5 short AnchorPointIndex(716) 6 char DataSetHeader(13520) 7 long ScanLineCounter(2012) 8 float ScanRate(2012) 9 long GreenwichMeanTime(2012) 10 long MasTime(2012) 11 long GpsTime(2012) 12 short AircraftRollCount(2012) 13 long YearMonthDay(2012) 14 float ScanlineTime(2012) 15 short BlackBody1Temperature(2012 X 50) Please choose the numbers of the data items you wish to dump Enter -1 to display additional items or zero to end selection process NOTE: if you enter 0 as very first entry, all variables will be displayed 11 0 Would you like the global attributes included in the report? (Y/N)y *** THE OUTPUT FILE FOR THE SELECTION ABOVE**** This is the report file for the scarbmas_950911s6.01 file ****************** START GLOBAL ATTRIBUTE SECTION ****************** title = MODIS Airborne Simulator (MAS) Level-1B Data CreationDate = 10-Aug-96 22:52:34 ExperimentName = SCAR-B FlightDate = 11 September 1995 FlightNumber = 95-170 ClockUsedToProcess = GPS Clock DataSliceNumber = 6 FlightLineNumber = 1 TotalFlightLines = 2 Credits = Liam Gumley/design Paul Hubanks/modify,maintain MASDataUsersGuideSource = MAS World Wide Web site at http://ltpwww.gsfc. nasa.gov/MAS/Home.html VIS/NIRCountSensitivityAdjustment = Yes (See DataSetHeader) SoftwareVersion = Version 5.0 CalibrationVersion = SCAR-B King 1.0 data_set = MAS SCAR-B data_product = straight-line flight tracks geog_flag = c day_night_flag = d granule_version = 5 metadata_version = 5a producer_granule_id = Version 5.0 SCAR-B King 1.0 data_quality = Fair: some noise in IR channels granule_size = 1.8177816e+08f begin_date = 19950912 190750 end_date = 19950912 191313 lat_LL = -9.6660156f lon_LL = -49.119671f lat_UL = -9.6659241f lon_UL = -49.736412f lat_UR = -9.3349609f lon_UR = -49.742195f lat_LR = -9.3339920f lon_LR = -49.126026f ****************** END GLOBAL ATTRIBUTE SECTION ****************** GpsTime 19075000, 19075000, 19075000, 19075000, 19075000, 19075000, 19075100, 19075100, 19075100, 19075100, 19075100, 19075100, 19075100, 19075200, 19075200, 19075200, 19075200, 19075200, 19075200, 19075300, 19075300, 19075300, 19075300, 19075300, 19075300, 19075400, 19075400, 19075400, 19075400, 19075400, 19075400, 19075500, 19075500, 19075500, 19075500, 19075500, 19075500, 19075500, 19075600, 19075600, 19075600, 19075600, 19075600, 19075600, 19075700, 19075700, 19075700, 19075700, 19075700, 19075700, 19075800, 19075800, 19075800, 19075800, 19075800, 19075800, 19075900, 19075900, 19075900, 19075900, 19075900, 19075900, 19075900, 19080000, 19080000, 19080000, 19080000, 19080000, 19080000, 19080100, 19080100, 19080100, 19080100, 19080100, 19080100, 19080200, 19080200, 19080200, 19080200, 19080200, 19080200, 19080300, 19080300, 19080300, 19080300, 19080300, 19080300, 19080300, 19080400, 19080400, 19080400, 19080400, 19080400, 19080400, 19080500, 19080500, 19080500, 19080500, 19080500, 19080500, 19080600, 19080600, 19080600, 19080600, 19080600, 19080600, 19080700, 19080700, 19080700, 19080700, 19080700, 19080700, 19080700, 19080800, 19080800, 19080800, 19080800, 19080800, 19080800, 19080900, 19080900, 19080900, 19080900, 19080900, 19080900, 19081000, 19081000, 19081000, 19081000, 19081000, 19081000, 19081100, 19081100, 19081100, 19081100, 19081100, 19081100, 19081100, 19081200, 19081200, 19081200, 19081200, 19081200, 19081200, 19081300, 19081300, 19081300, 19081300, 19081300, 19081300, 19081400, 19081400, 19081400, 19081400, 19081400, 19081400, 19081400, 19081500, 19081500, 19081500, 19081500, 19081500, 19081500, 19081600, 19081600, 19081600, 19081600, 19081600, 19081600, 19081700, 19081700, 19081700, 19081700, 19081700, 19081700, 19081800, 19081800, 19081800, 19081800, 19081800, 19081800, 19081900, 19081900, 19081900, 19081900, 19081900, 19081900, 19081900, 19082000, 19082000, 19082000, 19082000, 19082000, 19082000, 19082100, 19082100, 19082100, 19082100, 19082100, 19082100, 19082200, 19082200, 19082200, 19082200, 19082200, 19082200, 19082300, 19082300, 19082300, 19082300, 19082300, 19082300, 19082300, 19082400, 19082400, 19082400, 19082400, 19082400, 19082400, 19082500, 19082500, 19082500, 19082500, 19082500, 19082500, 19082600, 19082600, 19082600, 19082600, 19082600, 19082600, 19082600, 19082700, 19082700, 19082700, 19082700, 19082700, 19082700, 19082800, 19082800, 19082800, 19082800, 19082800, 19082800, 19082900, 19082900, 19082900, 19082900, 19082900, 19082900, 19083000, 19083000, 19083000, 19083000, 19083000, 19083000, 19083000, 19083100, 19083100, 19083100, 19083100, 19083100, 19083100, 19083200, 19083200, 19083200, 19083200, 19083200, 19083200, 19083300, 19083300, 19083300, 19083300, 19083300, 19083300, 19083400, 19083400, 19083400, 19083400, 19083400, 19083400, 19083400, 19083500, 19083500, 19083500, 19083500, 19083500, 19083500, 19083600, 19083600, 19083600, 19083600, 19083600, 19083600, 19083700, 19083700, 19083700, 19083700, 19083700, 19083700, 19083800, Updated: