|
ENVISAT IDL General Purpose Tools |
Last modified: Wed Dec 05 10:45:17 2001.
NAME:
MPH OBJECT
PURPOSE:
mph object and related methods
CATEGORY:
INPUT/OUTPUT
METHODS:
mymph=obj_new('mph'[,filename]) ; creation of the object
res=mymph->isInit() ; returns 1 if object has been properly initialized and filled (creation and read ok)
mymph->change_prdname,/AUXILIARY ; updates PRODUCT keyword according to the SPH data (SENSING_START, _STOP etc.)
res=mymph->read([filename]) ; reads of a mph from a file
res=mymph->getStruct(KEYWORD=keyword,INDEX=index) ; returns the structure associated to the given keyword (taken from the MPH keywords) or keyword index ( i.e. line number)
status=mph->UpdateMPH(/AUXILIARY) ; updates a MPH for auxiliary product
The keyword structure holds the following tags:
VALUE - pointer adressing the data
FORMAT - string specifying the format to be used when re-writting the data
UNIT - string specifying the unit that appears at the end of the line
res=mymph->getValue(KEYWORD=keyword,INDEX=index) ; returns the value associated with the keyword (taken from the MPH keywords)
For a MERIS products the following keywords are accepted:
FILENAME
PRODUCT
PRODUCT_ID
PROC_STAGE
REF_DOC
ACQUISITION_STATION
PROC_CENTER
PROC_TIME
SOFTWARE_VER
SENSING_START
SENSING_STOP
PHASE
CYCLE
REL_ORBIT
ABS_ORBIT
STATE_VECTOR_TIME
DELTA_UT1
X_POSITION
Y_POSITION
Z_POSITION
X_VELOCITY
Y_VELOCITY
Z_VELOCITY
VECTOR_SOURCE
UTC_SBT_TIME
SAT_BINARY_TIME
CLOCK_STEP
LEAP_UTC
LEAP_SIGN
LEAP_ERR
PRODUCT_ERR
TOT_SIZE
SPH_SIZE
NUM_DSD
DSD_SIZE
NUM_DATA_SETS
res=mymph->getMPHVector() ; returns a string vector w/ all the lines of the MPH
res=mymph->write(filename) ; writes MPH to a file
OUTPUTS:
status - Upon successful completion, a NULL value is returned,
otherwise a problem has occured.
SIDE EFFECTS:
Not known
RESTRICTIONS:
None
EXAMPLE:
mph=obj_new('mph')
res=mph->Read(filename)
res=mph->getMPHVector()
sensing_start=mph->getValue(KEYWORD='SENSING_START')
sensing_stop=mph->getValue(KEYWORD='SENSING_STOP')
obj_destroy, mph
void=DIALOG_MESSAGE(res,TITLE='Content of MPH:')
mph=obj_new('mph')
status=mph->Read(prdfile)
status=mph->UpdateMPH(/AUXILIARY)
status=mph->write(prdfile,/UPDATE)
obj_destroy, mph
MODIFICATION HISTORY:
written by Christophe Ngo Van Duc - June 2001 - chr@acri-st.fr
ACRI S.A.
(See $IDL_LOCAL\Products\mph__define.pro)
NAME:
RD_PROD
PURPOSE:
Retrieves data from any ENVISAT product
CATEGORY:
INPUT/OUTPUT
CALLING SEQUENCE:
struct_name=RD_PROD(KEY=key, $
FILENAME=filename,RECORDS=records, $
DATABASE_DIR=database_dir,$
/NODATA,/IMPLICIT_SCALE,/ALLFIELDS,/VERBOSE)
INPUTS:
None
OPTIONAL INPUTS:
KEY - string (1-4 char.) array specifying parameter to retrieve
FILENAME - product filename
RECORDS - integer array of record # (from 0) to retrieve
If not set than all records are retrieved.
A negative record number will be reset to 0.
A record number greater than the number of
records stored in the product -1 (or
n_records-1) will be reset to n_records-1 .
DATABASE_DIR - sets the DATABASE_DIR environment variable
index_#.txa files must be under DATABASE_DIR
obsolete if IDL_LOCAL is set
VERBOSE - if set then executes in verbose mode
ALLFIELDS - if set then all fields specified by the
KEY array are loaded and no dialog_message
box is displayed for the user to select
the fields to retrieve
KEYWORD PARAMETERS:
NODATA - if set, data is not retrieved from the product
file and "data" tag is not created
IMPLICIT_SCALE - if set then implicit scaling factor (the one
appearing in the structure) is used, BEWARE when using
this feature that the output data type will no longer
reflect the file data coding (e.g integers are systematically
translated to floating or double values).
OUTPUTS:
structure holding the following tags :
KEY - 4-letter string specifying
parameter address in product file
FILENAME - data product file from which data has
been retrieved
COMMENT - comment retrieved from index_#.txa config. file
SCALING - implicit scaling factor
only used if /IMPLICIT_SCALE is set
PARAMSIZE - table size in bytes
CODING_TYPE - coding (integer) used in product file
UNIT - units of retrieved parameter
DIMS - integer array specifying dimensions of parameter
OFFSET_FIRST - long integer specifying offset of first record
OFFSET_INCR - byte increment between two consecutive records
N_RECORDS - number of records in the product
RECORDS - pointer pointing to long integer array holding
retrieved record numbers (starting from 0)
DATA - pointer pointing to data array
This tag is not created if /NODATA was set.
In the IODD, contrary to IDL,
the indice that changes the fastest
is the last one ; therefore, if you want to
download a table with severall
records that is descibed in the IODD
as being of size (15*10*25) with 16
records, the table that will be
created under IDL will be of size [25,10,15,16]
OPTIONAL OUTPUTS:
None
COMMON BLOCKS:
None
SIDE EFFECTS:
Unknown
RESTRICTIONS:
As some unsigned types did not exist in version 5.1 of IDL it
is preferable to use version 5.2 instead (like for
retrieveing L2 normalized water leaving reflectances that are
coded as unsigned short integers)
PROCEDURE:
This function interfaces w/ an IDL program that reads the index_#.txa
file of the parameter specified by its "key" and retrieves from the
SPH of the product file the byte offsets wrt the begining of the
file for all records of the parameter.
These informations are then sent back to the IDL routine that
optionaly retrieves the data from the product file.
EXAMPLE:
filename='../data/atmosphere.12.03.prd'
rho_R=rd_prod(key="PA00",filename=filename,/nodata)
filename="/megs_aux/products/pp_atmosphere/atmosphere.11.00.prd"
rho_R=rd_prod(key="PA00",filename=filename,/nodata)
rho_R=rd_prod(key="PA00",filename=filename,records=[0])
rho_R=rd_prod(key="PA00",filename=filename,records=[3])
rho_R=rd_prod(key="PA00",filename=filename,records=[3,6,9])
rho_R=rd_prod(key="PA00",filename=filename)
database_dir="/megs/megs.4.1/resources/databases"
rho_R=rd_prod(key="PA00",filename=filename,DATABASE_DIR=database_dir)
MODIFICATION HISTORY:
written by Vincent Fournier-Sicre - June 1999 - vfs@acri.fr
ACRI S.A.
20 Sep 1999 - vfs - modification done to suppress error
message :
% Program caused arithmetic error:
Floating illegal operand
03 July 2000 - OFFSET tag replaced by RECORDS tag
03 July 2000 - creation of tags OFFSET_FIRST, OFFSET_INCR,and N_RECORDS
03 July 2000 - all dimensioning variables are now stored as
unsigned long integers
23 June 2000 - vfs - added VERBOSE option
22 June 2000 - vfs - added "temporary" in struct=CREATE_STRUCT(struct,'data',temporary(data))
21 July 1999 - vfs - routine may now read any type of variable
before, routine could only read floating
point data
12 Sep. 2000 - vfs - suppression of the MEGS_HOME KEYWORD
returns error code if FILENAME or KEY or not given
returns error code if IDL_LOCAL
env. variable is not set
26 Oct. 2000 - corrected typos in documentation
19 Jan. 2001 - vfs - uses FILE_TEST for file existence testing
STILL2DO:
define a maximum number of records allowed to be retrieved
(i.e. 400000)
(See $IDL_LOCAL\Products\rd_prod.pro)
NAME:
SPH Object
PURPOSE:
sph object and related methods
CATEGORY:
INPUT/OUTPUT
METHODS:
mysph=obj_new('sph'[,filename]) ; creates an SPH object
res=mysph->isInit() ; returns 1 if the object has been correctly initialized and filled (creation and read ok)
res=mysph->read([filename]) ; reads a sph from a file
res=mysph->getStruct(KEYWORD=keyword,INDEX=index) ; returns the structure with the given keyword (or corresponding index)
res=mysph->ProdSize(sph_size) ; returns the product size given the SPH size
The keyword structure holds the following tags:
VALUE - pointer adressing the data
FORMAT - string specifying the format to be used when re-writting the data
UNIT - string specifying the unit that appears at the end of the line
res=mysph->getValue(KEYWORD=keyword,INDEX=index) ; returns the value associated with the keyword (or corresponding index)
For a L1b/L2 MERIS products the following keywords are accepted:
SPH_DESCRIPTOR
STRIPLINE_CONTINUITY_INDICATOR
SLICE_POSITION
NUM_SLICES
FIRST_LINE_TIME
LAST_LINE_TIME
FIRST_FIRST_LAT
FIRST_FIRST_LONG
FIRST_MID_LAT
FIRST_MID_LONG
FIRST_LAST_LAT
FIRST_LAST_LONG
LAST_FIRST_LAT
LAST_FIRST_LONG
LAST_MID_LAT
LAST_MID_LONG
LAST_LAST_LAT
LAST_LAST_LONG
TRANS_ERR_FLAG
FORMAT_ERR_FLAG
DATABASE_FLAG
COARSE_ERR_FLAG
ECMWF_TYPE
NUM_TRANS_ERR
NUM_FORMAT_ERR
TRANS_ERR_THRESH
FORMAT_ERR_THRESH
NUM_BANDS
BAND_WAVELEN
INST_FOV
PROC_MODE
OFFSET_COMP
LINE_TIME_INTERVAL
LINE_LENGTH
LINES_PER_TIE_PT
SAMPLES_PER_TIE_PT
COLUMN_SPACING
For a L0 MERIS products the following keywords are accepted:
START_LAT
START_LONG
STOP_LAT
STOP_LONG
SAT_TRACK
ISP_ERRORS_SIGNIFICANT
MISSING_ISPS_SIGNIFICANT
ISP_DISCARDED_SIGNIFICANT
RS_SIGNIFICANT
NUM_ERROR_ISPS
ERROR_ISPS_THRESH
NUM_MISSING_ISPS
MISSING_ISPS_THRESH
NUM_DISCARDED_ISPS
DISCARDED_ISPS_THRESH
NUM_RS_ISPS
RS_THRESH
TX_RX_POLAR
SWATH
res=mysph->getSPHVector() ; returns a string vector specifying the entire SPH
res=mysph->getDSD(INDEX=index) ; returns a structure for the DSD specified by the index
a DSD structure holds the following tags:
DS_NAME - string holding Data Set name '
DS_TYPE - string specifying Data Set Type ('A' for ADS, 'G' for GADS, 'M' for MDS)
FILENAME - string holding DSD filename field '...
DS_OFFSET - long integer specifying offset of first record from beginning of file
DS_SIZE - long integer specifying Data Set size in bytes
NUM_DSR - long integer specifying Number of Records for this MDS 2
DSR_SIZE - long integer specifying Data Set size for a single record
res=mysph->setDSD(DSD,index) ; stores the modified DSD structure in the SPH object (index specifies the DSD number to store)
res=mysph->getDSDVector() ; returns a vector of DSD structures
res=mysph->UpdateDSD(level,TIE_PTS=nbtie,RESOLUTION=resolution,FLAGS=flags) ; updates the DSD object with the proper number of tie-points
Update all the size. The variable flags is a boolean vector specifying if the corresponding MDS holds records or not.
res=mysph->write(filename,/APPEND,/UPDATE) ; writes SPH to a file
OUTPUTS:
status - Upon successful completion, a NULL value is returned,
otherwise a problem has occured.
SIDE EFFECTS:
Not known
RESTRICTIONS:
None
EXAMPLE:
mph=obj_new('mph')
res=mph->Read(filename)
sph_size=mph->getValue(KEYWORD='SPH_SIZE')
obj_destroy, mph
prod_size=mysph->ProdSize(sph_size)
status=mph->setValue('TOT_SIZE',prod_size)
res=mph->Write(filename)
sph=obj_new('sph')
res=sph->Read(filename)
res=sph->getSPHVector()
;removing SPH DSDs part
tmp=strpos(res,'DS_NAME')
index=where(tmp EQ 0,count)
IF count GT 0 THEN res=res[0:index[0]-1]
void=DIALOG_MESSAGE(res,TITLE='Content of SPH (DSDs excluded):')
dsd=mysph->getDSD(INDEX=3)
dsd.NUM_DSR=17
res=mysph->setDSD(dsd,3)
dsd=sph->getDSDVector()
obj_destroy, sph
MODIFICATION HISTORY:
written by Christophe Ngo Van Duc - June 2001 - chr@acri-st.fr
ACRI S.A.
(See $IDL_LOCAL\Products\sph__define.pro)
NAME:
WR_PROD
PURPOSE:
writes data into an ENVISAT product (measurement or auxiliary)
CATEGORY:
INPUT/OUTPUT
CALLING SEQUENCE:
status=WR_PROD(data,KEY=key,FILENAME=filename,DATABASE_DIR=database_dir)
INPUTS:
data - array, pointer or array of structures similar to rd_prod output
OPTIONAL INPUTS:
KEY - array of parameter keys (e.g. ['PA00','P202'])
this keyword is ignored if passed data is a structure
FILENAME - product file where data will be transfered
DATABASE_DIR - sets the DATABASE_DIR environment variable
index_#.txa files must be under DATABASE_DIR
obsolete if IDL_LOCAL is set
RECORDS - integer vector specifying the records to write
KEYWORD PARAMETERS:
None
OUTPUTS:
status - Upon successful completion, a NULL value is returned,
otherwise a problem has occured.
OPTIONAL OUTPUTS:
None
COMMON BLOCKS:
None
SIDE EFFECTS:
Not known
RESTRICTIONS:
1) The tables that are passed to this function needs to be exactly
identical in type and dimensions to the table that are stored in
the product, no 'casting' or 'resizing' is performed within this
function.
2) This function is only applicable to parameters stored in the
binary part of a product file; therefore the MPH nor the SPH may
be updated w/ this function - use the MPH and SPH methods to
update them.
PROCEDURE:
Dimension/type of input data array is checked to be in agreement
with destination field. Once this is performed data is copied
at proper offset.
EXAMPLE:
infile='/megs_test/lb/Bomem/MER_AOP_130999'
outfile='/megs_aux/products/pr_ocean_aerosol/oceanaero.tmp.prd'
key='R800'
database_dir='/megs/megs.4.3/resources/databases/'
;reading data from inputfile
struct1=rd_prod(KEY=key,filename=infile,DATABASE_DIR=database_dir)
;copying data to outputfile
status=wr_prod(struct1.data,KEY=key,FILENAME=outfile,DATABASE_DIR=database_dir)
IF status EQ 0 THEN BEGIN
;re-reading data from outputfile
struct2=rd_prod(KEY=key,filename=outfile,DATABASE_DIR=database_dir)
;checking that table has not been corrupted
print,min(struct2.data-struct1.data),max(struct2.data-struct1.data)
ENDIF ELSE BEGIN
print,'problems occured while writing data to output file'
ENDELSE
MODIFICATION HISTORY:
written by Vincent Fournier-Sicre - October 1999 - vfs@acri.fr
ACRI S.A.
12 Sep. 2000 - suppression of the MEGS_HOME keyword
26 Oct. 2000 - corrected to be compatible w/ RD_PROD
(offset tag had been suppressed)
(See $IDL_LOCAL\Products\wr_prod.pro)