Readme for ckopus.c

June 2020
- ckopus.c V1.0.7 20200725
- added several stations, Addis Ababa, St Petersburg
- add force FOV option


Nov 2019
- -c option to print out  hard coded site data.
- added Altzomoni and UNAM, Swoya, Rikubetsu, Moshiri, Tsukuba


Dec 2018
- Added optical filter decode for FL0


Some caveats and possible causes for errors

velocity
   for os/2 v3 of opus the velocity value in opus was the index to an array of velocity values in Hz
   for 125 it is the floating point value in kHz
   we have a simple check for the '.'
   This works so far mat may fail with some other configuration

aperture
   is read from a string to a float with units of mm

optical filter
   is read as a 1 char string from a multi word string
   this string is editable and may be different at any site!
   on 2 filter wheel systems the combination of positions determines the designation
   we have this for MLO but this needs to be changed for your site.
   see function filterid() in ckopus.c

May 2014
- ckopus.c V1.0.3 20140520
- feature - added Hefei to constans.c,h
- bugfix - changed UTC time offset for LDR from -10 to -12


October 2013
-ckopus.c V1.0.2 20131010
- v1.0.2 first version with sfit4 release January 2014


August 2013
   Included a check for internally determining if a fwd only or fwd/bkd file for 125
      siteflag must be 3 (fwd) or 4(fwd/bkd) but will be changed if the file is the other type


July 2013
    added check for OPUS magic number
    return codes
      1 = cannot open file given
      3 = opened file but not an OPUS file (incorrect magic #)

   added time correction flags
      0 - default no time correction
      1 - empirical value given in -t time to block time
      2 - for 2 file forward / backward scheme (OPUS v3.04 OS/2 ~1996) plus -t time
      3 - forward only fast return plus -t time
      4 - forward / backward one file (IFS125) plus -t time
      5 - forward only fast return plus -t time (use scantime duration value)
      6 - forward only fast return plus -t time (use scantime duration, file time is end of scan)

   these are ways to adjust the the time that I am aware of, its likely not complete
   I don't know if there is a document or map for conversions for all opus versions / IFS models
   so this is a work in progress.  You can view the error file for some details on the offset it
   calculates



25 June 2013 V1.0 --- jwh

Ckopus has many useful features for looking at OPUS file contents, converting spectral
data blocks to other formats and acquiring pertinent data for a database. Type ckopus -?
for a list of features.

In particular it also calculates the solar position given the lat lon and time of measurement.
See the file constant.c (h) to add a new site to the built in sites for lat, lon, UTC offset etc.
The UTC offset can be applied (when the instrument is on local time see option -U) or not.

Time is a tricky issue with OPUS files.  There is consensus that the time of ZPD should be used
for the calculation of the solar zenith angle.  Deriving that time from the OPUS file write
timestamp or a time given in a data block is not so straight forward.  For new instruments
it may be largely settled but for the older instruments and versions of OPUS going back
to V1.4 on OS/2 in the early 1990's it was not clear.  Different groups worked out
procedures appropriate to their needs.

The current version of ckopus does not make any adjustments yet. So beware.

For early opus versions (MLO, OS/2, OPUS v1.4) it was found that the time in the PHAS block was
at zpd at about 2:18 earlier than the EMIS block.  For later OPUS (TAB, OS/2, OPUS V3) all
blocks had the same time stamp (PHAS, SNGC, IFGM) and this held true for MLO 125HR.  Hence it
defaults to the PHAS block.  Other groups calculated the zpd time from the file write timestamp
FWD / BKD number of scans the resolution and scanner velocity.  This relies on the file
write timestamp being preserved.  This can be code in but as yet has not.  I don't believe
these options are conclusive so other options may need to be included.  Then as well some way of
choosing which to employ.  It can be a combination of site and date.

If you have a calculation that you put in or wish to have put in let me know.

-Jim
jamesw@ucar.edu


usage:
               printf( "usage: ckopus -wXXX -nXXX -aXXX -tNNN -s -Ssss -[S|L|B|P|R] -[R|F]ssss file1 file2 ...\n" );
               printf( "where:\n" );
               printf( "   -v print the current version\n" );
               printf( "   -w is west longitude defaults to %.2lf [decimal degrees]\n",site.w_lon );
               printf( "   -n is north latitude defaults to %.2lf [decimal degrees]\n", site.n_lat );
               printf( "   -a is altitude defaults to %.2lf [meters]\n", site.altud );
               printf( "   -t is time offset defaults to %i [seconds]\n", site.sec_offs );
               printf( "   -p use this block for time calculations [TRAN | SGN2 | IFG2 | EMIS | IFGM | PHAS | SNGC] ex. -pSNGC \n" );
               printf( "   -b Bruker time calculation flag\n" );
               printf( "      0 - default no time correction\n" );
               printf( "      1 - empirical value given in -t time to block time\n" );
               printf( "      2 - for 2 file forward / backward scheme (OPUS v3.04 OS/2 ~1996) plus -t time\n" );
               printf( "      3 - forward only fast return plus -t time\n" );
               printf( "      4 - forward / backward one file (IFS125) plus -t time\n" );
               printf( "      5 - forward only fast return plus -t time (use scantime duration value)\n" );
               printf( "      6 - forward only fast return plus -t time (use scantime duration, file time is end of scan)\n" );
               printf( "   -u is UTC time offset defaults to %i [hours]\n", site.utc_offs );
               printf( "   -U apply UTC time offset\n" );
               printf( "   -s swap bytes on opus read defaults to No Swap\n" );
               printf( "   -S set lat lon & alt for [TAB | FL0 | MLO | KPK | PKF | MSA | SGP | TMK]\n" );
               printf( "   -C short listing of file contents\n" );
               printf( "   -L long listing of file contents\n" );
               printf( "   -B list file blocks\n" );
               printf( "   -P list time stamps\n" );
               printf( "   -M make Linefit microwindow files\n" );
               printf( "   -R write 'C' bnr from type     [TRAN | SGN2 | IFG2 | EMIS | IFGM | PHAS | SNGC] ex. -RSNGC \n" );
               printf( "   -F write FORTRAN bnr from type [TRAN | SGN2 | IFG2 | EMIS | IFGM | PHAS | SNGC] ex. -FEMIS \n" );
               printf( "   -T write T15asc file from type [TRAN | SGN2 | IFG2 | EMIS | IFGM | PHAS | SNGC] ex. -TEMIS \n" );
               printf( "   -D one line param list for database to stdout ex. -DEMIS\n" );
               printf( "   -H print database header to stdout\n" );
