
================================================================================

SPICA_READ_1A_CMD program DOCUMENTATION:

================================================================================

This documentation file is only dedicated for the SPICA_READ_1A_CMD program, 
which read the SPICAM/V 1A UV/IR data in command line.
The spica_read_1A_cmd program reads any 1A files, and permits to display 
some data sample, parameters and information.


BUILDING SPICA_READ_1A_CMD
================================================================================

The builded CFITSIO library must be located at the same level than the "src" 
directory. To build the library, please take a look at the cfitsio/README file.
The CFITSIO library can be download at this adress: 
http://heasarc.gsfc.nasa.gov/fitsio/

The GCC libm and libnsl libraries must be also available on the user system.
The user should use GCC to build the program.

To build the SPICA_READ_1A program on Unix systems, follow those 3 steps:

 >  ./configure [--prefix=/target/installation/path]
 >  make          (or  'make shared')
 >  make install  (optional, user must have write permission on /usr/local/bin/)


USING SPICA_READ_1A
================================================================================

The call line is:
 > spica_read_1a_cmd [full_1A_file_path] [options] [sample]

-	[full_1A_file_path]: The full path and filename of the 1A file to read
-	[options]: display options (see below)

Example:
 > /src/./spica_read_1a --version 
   ==> should display version number of the program
 > /src/./spica_read_1a SPICAM/V_1A_FITS_FILE --info 
   ==> should display inforfmation of the observation

DOCUMENTATION
================================================================================

----------------------------------
UV OPTIONS:

-c [sample], --cleandata=[sample]:
Display following columns:
1-Band number
2-Spectrum number (or records)
3-Pixel number
4-Flag value (from FLAG sub-structure) 
5-intensity value 
 (from CLEANDATA sub-structure )

-i, --info: 
Display content of INFO sub-structure

-g, --geoinfo: 
Display content of GEOINFO sub-structure

--georec=[sample]: 
Display content of GEO.RECORD sub-structure

--geosc=[sample]: 
Display content of GEO.SPACECRAFT sub-structure

--geoband1=[sample]: 
Display content of GEO.BAND1 sub-structure

--geoband2=[sample]: 
Display content of GEO.BAND2 sub-structure

--geoband3=[sample]: 
Display content of GEO.BAND3 sub-structure

--geoband4=[sample]: 
Display content of GEO.BAND4 sub-structure

--geoband5=[sample]: 
Display content of GEO.BAND5 sub-structure

--geocoord=[sample]: 
Display content of GEO.COORDINATES sub-structure

--geotransm=[sample]: 
Display content of GEO.TRANSMATRIX sub-structure

--geolose=[sample]: 
Display content of GEO.LOSE sub-structure

-n, --nomask:
The flag mask will not be applied on the primary data

-m, --minimum: 
Display the minimum value of the data,
-c or -r must be defined with [sample] (minimum on the data sample) 
or without (minimum on all data)

-M, --maximum: 
Display the maximum value of the data, 
-c or -r must be defined with [sample] (maximum on the data sample)
or without (maximum on all data)

-p, --parameters: 
Display content of PARAMETERS, except all temperatures fields sub-structure

-r [sample], --rawdata=[sample]: 
Display:
1-Band number
2-Spectrum number (or records),
3-Pixel number
4-Flag value (from FLAG sub-structure) 
5-intensity value 
  (from RAWDATA sub-structure)

-t [sample], --temperatures=[sample]:
Display content of PARAMETERS sub-structure, only for temperatures fields

-v, --verbose: verbose mode


-	[sample]:
For -c or -r option, [sample] is a 3 dimension array defined as 
[Npixels, NRecords(septrum), NBands]

Example:
to display pixel nb. 500, on the spectrum 100, on band 2: [500,100,2]
to display pixel from nb. 500 to 520, on the spectrum 100, 
  on band 2 to 5: [500:520,100,2:3]
to display pixel from nb. 500 to 520, all spectrum 100, 
  on band 2 to 5: [500:520,*,2:3]

For other options, [sample] is a 1 dimension array defined as 
[NRecords(septrum)]

----------------------------------
IR OPTIONS (TODO):
-i, --info: print content of INFO sub-structure of the main 
    spica_struct_1a structure
-v, --verbose: verbose mode

================================================================================

--------------------------------------------------------------------------------
Nicolas Chapron
CNRS | LATMOS - Laboratoire Atmospheres, Milieux, Observations Spatiales.
11 boulevard d'Alembert
78280 Guyancourt
France
Tel. 33-(0) 1 80 28 50 57
Email. nicolas.chapron@latmos.ipsl.fr
--------------------------------------------------------------------------------


