OMEGA software (IDL version)
release SOFT01
september 2004

unzipping SOFT01.ZIP will create a new subdirectory, SOFT01, so that
new releases (SOFT02, soft03...) will not erase previous versions
(this can be useful for comparing the results of the different updates). 

So as to use the new version, the user should copy the content of SOFT01 
to the OMEGA working directory, from where IDL should be started.

IMPORTANT ! The first thing a user should do after unzipping a new
software release and copying the contents to the working directory 
is to modify the file:
         omega_path
in the working directory (from which IDL is run)
replacing the first line with the path to the directory
where the user puts data files (.QUB), and the second line
with the path to the directory where the user puts the geometry files (.NAV)

An OMEGA observation corresponds to data obtained with the same observation
parameters (scan length, integration time for the VIS and IR channels, 
downtrack summing, compression). There are in general several OMEGA 
observations for the same orbit, as the scan length is changed depending
on the spacecraft altitude so as to best match the sampling rate and
the drift velocity on the surface.

The OMEGA data files and geometry files are named from the corresponding
OMEGA observation: ORBNNNN_S where NNNN is the orbit number (format I4.4)
and S is the rank of the OMEGA observation on that orbit (starting with 0).
The extensions are .QUB for the data, .NAV for the geometry
example: ORB0018_1.QUB and ORB0018_1.NAV correspond to the second 
observation on orbit 18 (scan length: 32 pixels). 

The main procedure for reading level 1b OMEGA data is readomega.pro

After entering IDL and typing ".run readomega", one has simply to enter 
the name of the requested OMEGA observation in answer to the query

example:

IDL (enter)
.run readomega (enter)
OMEGA observation:
ORB0097_4 (enter) 

readomega first checks that obsname.QUB exists in the directory
indicated by the path for data files in "omega_path". 

If the cube is not found, it prints "file OMEGA_PATH_DATA/obsname.QUB 
not found, and goes back to the query. Otherwise, readomega reads the
pds cube, then it look fors the corresponding geometry cube 
obsname.NAV in the directory indicated by the path for geometry files 
in the "omega_path" file. If there is no such file, it prints: 
"no corresponding NAV cube". If the NAV file exists, readomega reads 
the geometry cube. 

the resulting variables are:

idat(npix,352,nscan): integer 16 bits, raw OMEGA data
      npix: 16, 32, 64 or 128 pixels
      nscans: number of scans in the cube
      the 352 wavelengths are in the following order:
      IR C (128 values), then IR L (128 values), then Visible (96 values)

wvl(352) OMEGA wavelengths (file 'lambda_0304.dat'). these wavelengths
      are valid at the center of the IR and VIS field. The wavelength
      range changes only slightly across the field of view, in particular
      in the IR.

jdat(npix, 352, nscan): floating point, OMEGA data physical units 
      (W/m2/steradian/m)
      the last 35 spectels of the VIS channel show a second order
      contribution. There is still a mismatch between the VIS and IR C
      at 0.95 m, which is being investigated. The L channel (128:255)
      shows variations in terms of internal calibration signal, which
      do not correlate simply with DN levels from Mars or Phobos

note: the last 4 scans (16 pixels), 2 scans (32 pixels)
      or 1 scan (64, 128 pixels) of idat and jdat
      have only IR data (spectels 0 to 255)

There is calibration data at the beginning of each cube for the visible
channel, at the beginning of the ORBNNNN_0.QUB cubes for the IR channels
The number of calibration scans depend on the pixel length (16 to 128)
and the summation (1, 2 or 4 for 128 pixel modes)

      for every cube, the first scan (128 pixels x 4), 3 scans (128 x 2) 
      7 scans (128 x 1), 14 scans (64 pixels), 
      28 scans (32 pixels), 56 scans (16 pixels) of the visible channel
      (256 and above) correspond to an internal calibration

      for cubes with names NNNN_0 (first cube in a sequence), the first
      6 scans (128 x 4), 12 scans (128 x 2), 24 scans (128 x 1)
      48 scans (64 pixels), 96 scans (32 pixels) or 192 scans (16 pixels)
      correspond to an internal calibration (closed shutter, lamp on
      at 6 different levels, in order 0,4,3,2,1,0

specmars(352): floating point, solar spectrum at the distance of Mars
      at the time of observations. jdat(i,*,n)/specmars(*) provides 
      the I/F values for the spectral range dominated by reflected 
      sunlight. It is meaningless for the spectral range dominated
      by thermal emission (usually above 3.5 m)

sdat0(352,nscan): 
       0:256 contains the corresponding IR dark
       raw data: sdat0(0:255,n)-idat(i,0:255,n)
       this can be useful when there are problems
       with the IR (digital saturation of the dark, detector saturation) 

       detector saturation in the IR (only observed in the C channel
       with 5 msec integration time) can be checked by plotting:
       sdat0(0:127,n)-idat(i,0:127,n). If there is a plateau at values
       close to 300 DN around spectel 41 (the highest DN level), these
       values are saturated.

       Perturbations of the dark are most prominent with 16 pixels, 
       5 msec integration time at high DN levels from channels 20 to 50.
       A simple way to check for such effects is to plot sdat0(41,*)  
       (dark level for spectel 41, the highest DN level
       in the signal). If it is not nearly constant, and there is a dip 
       when the signal is high, the dark is perturbed. A non perturbed
       dark needs then to be recovered from a region of the cube with
       lower signal values (or another cube from the same orbit). 
       The proper level of the data can then be recovered by:
 
       idat(i,0:127,n)=idat -sdat0 (0:127,n) + sdat0 (0:127, unperturbed)

sdat1(npix,7,nscan):
       housekeeping data as defined in the EAICD

exposure (float(3)): integration times for the IR (C channel), 
       the IR (L channel) and the VIS channel. The integration time
       is the same for IR C and IR L in all foreseen OMEGA modes.
       It can be either 2.5 msec or 5 msec. the visible integration
       time is in general set as 50 msec.
    
       there are two photometric functions (352 values per files):
          mtfYYMM_25.dat (2.5 msec, release of year YY, month MM)
          mtfYYMM_50.dat ( 50 msec, release of year YY, month MM) 

       The readomega procedure selects the proper exposure time 
       for the IR and for the visible. In the present release, it uses the 
       mtf040324_25.dat nad mtf040324_50.dat files. It also takes into account
       the summation by two internal to the VIS channel for 128 pixel modes

IMPORTANT REMARK: new releases of the photometric function are likely to
       be necessary as the knowledge of the intrument improves.
       with this software release, relative variations of 5% or more
       between spectra are considered reliable. Smaller variations can
       be related to linearity effects, and should be considered with
       caution, in particular if they correlated with I/F (linearity). 
       The confidence on the absolute radiometric calibration is 
       at the 15% level. Two sets of photometric functions (040319 and 
       040324) are given so as to provide an estimate of the remaining
       uncertainties. The 040324 set is used when computing jdat

bits_per_pixel : number of bits per pixel from data compression

summation : number of downtrack summations (only for modes with 128 pixels)
       this parameter can be 1.0, 2.0 or 4.0, in which case both idat
       and sdat0 have values can be a factor of 2 or 4 higher than
       in the nominal situation (summation 1.0). This factor is taken
       care of when computing jdat
      
The corresponding auxiliary pds cube ORBNNNN_X.NAV is read by readomega
if available (otherwise the user gets a "no corresponding geometry file"
message

products:

geocube: geometry cube with as many samples and lines as idat,
         and 51 bands. The definitions of each band are:
   0:   scan value (in DN) for each pixel
   1:   information on the time (hr:min:sec:msec)
   2:   incidence on the ellipsoid  (unit: 0.0001)
   3:   emergence from the ellipsoid (unit: 0.0001)
   4:   incidence wrt the local gravity field (atmospheric science)
   5:   emergence wrt the local gravity field
   6,7 : longitude and latitude of the center of the IR C pixel (0.0001)
   8,9,10: incidence, emergence, phase for the IR C pixel (unit: 0.0001)
   11 : distance in m
   12 : altitude (MOLA - ellipsoid) in m
        if > 65.535 km: altitude above the surface + 65536 m
        (for limb observations)
   13-16: longitudes of the corners of the IFOV (unit: 0.0001)
   17-20: latitudes of the corners of the IFOV (unit: 0.0001)
   21-35: same as 6-20 for the IR L pixel
   36-50: same as 6-20 for the Visible pixel

More details are given in the EAICD

dmars : sun - mars distance, in AU
specmars (352 values) : solar spectrum at OMEGA wavelengths at
        the heliocentric distance of Mars during observations
longi : longitude in  of all OMEGA pixels (C channel)
lati : latitude in  of all OMEGA pixels (C channel)
alt : MOLA altitude, in km, for all pixels in the cube (C channel)

IMPORTANT NOTE
   The geocube data set is very useful to obtain a first estimate
   of the region imaged by each OMEGA cube. Given the remaining uncertainties
   on position and attitude restitution, the observed variations in
   alignment of the C and L channel (from 1 to 3 pixels), and the 
   registration problems between spectels, the positionning error is 
   estimated as 3 mrad or better for most cubes. A specific effort using
   other data sets (in particular comparing the CO2 band strength with
   MOLA altimetry) is required if one requires a better positioning.
