--------------------------------------------------
Utilities (source found in src/* and src/otcom/*):
--------------------------------------------------

mkfinder
--------

mkfinder is a script which makes a finding chart from the DSS which
has an OPTIC footprint drawn on it.  You invoke mkfinder with three
arguments: an identifier name, RA, and Dec in a colon-separated
format, J2000, e.g.

  mkfinder n2419 07:38:08.5 +38:52:55

It will write several files starting with "Obj_name", and the final
postscript is called "Obj_name.ps".  If you are intending to use
OPTIC for guiding/tracking, it is a very good idea to know where stars
which are bright enough for guiding are located, it can be very
frustrating to do a blind search.


othead
------

The utility othead will look up header information from an otcom image
(not video) file and write it as a single line.  Without an argument
it just dumps out a title line.  Othead can also take a flag "psf"
which causes it to run "videostack" if the image was taken in OT mode
and has a video file.  Vista is then run on the resulting stack of psf
images and othead reports the FWHM of each.  This is a good way to get
a log of which regions were used for guiding and the seeing in each.
Typical usage in a directory where you have written data might be:

  othead > mylog
  foreach i (myprefix.???)
    othead $i psf >> mylog
  end

videostack
----------
Videostack is a utility to read a 3D FITS file, stack all the frames,
and write a 2D FITS file of the resulting average.  It assumes
unsigned short images.  The syntax is

  videostack input_3d_file  output_2d_average  [silent]


fitstile
--------
Fitstile will read a 3D FITS file and write a 2D FITS file which has
the individual frames laid out in a tile, starting at the lower left
and working right and up.  The syntax is

  fitstile  input_3d_file  output_2d_tile  [options]

and options include

  -first  N  first frame to use
  -last   N  last frame to use
  -ntile  N  number of frames to use
  -sky    S  subtract this from final image
  -book      arrange tiles as characters in a book: upper left to lower right 
  -grid      draw grid lines between tiles


videosum
--------

Videosum reads a 3D FITS video file (prefix_vid.nnn) and writes an
output file which is supposed to be identical to the guide star file
(prefix_gs.nnn) already written by otcom.  Good for checking for bugs
in the psf routine and otcom.  Syntax:

  videosum input_3d_file  


videoplay / xoptic
------------------

Videoplay reads a 3D FITS video file and replays it in real time on
the screen.  It can take an additional argument which is taken to be a
frame time for the display in seconds.

  videoplay input_3d_file  [frame_time]

Videoplay, like otcom, forks off a child process which runs the
program xoptic.  This in principle can be on a different machine, but
at present is hardwired to run locally.  Because X is so wonderfully
inefficient at passing data back and forth, xoptic does all the X
display (coded in Xlib for historical reasons and efficiency), and it
receives a fairly compressed data stream from videoplay (or from otcom).


conflat
-------

Conflat is an extremely important utility which convolves an unshifted
(stare mode) flatfield in accordance with the shifts which were
performed for an OT tracked image, and writes a new flatfield which
should flatten the OT tracked image.  The result of OT shifting an
image is that each pixel in the final image has actually been
integrated on a variety of physical pixels.  An exposure during which
OT shifting has taken place normally writes an auxiliary file called

  myprefix_ot.???	- table of where each pixel was integrated

Conflat takes an unshifted, unbinned flatfield and convolves it
according to the data in the '_ot' file so that it agrees with the
OT convolution which took place in the image file.  The basic syntax
is:

  conflat flat_field ot_file out_file

For example, suppose that f.115 was a stare mode flatfield in the same
filter as an OT tracked observation f.087.  You could make a flatfield
for observation 087 by:

  conflat f.115 f_ot.087 flat_115.087

There are a few things you should beware of with the current conflat.

 (a) It assumes that it has short data (not floating point!)
 (b) It assumes that the flatfield format is a standard, unbinned
     readout -- the bias strip must be present.
 (c) It wants data which is less than 32k (which you want as well for
     flatfields) 

These are easy restrictions to lift, but if you get garbage results
from conflat stop and think whether you have written short integer
files or whether you have done some processing on the flatfields which
has subtracted bias or rewritten in floating format.


Vista (source found in ~src/vista and ~src/mongo2k):
----------------------------------------------------

Vista is a handy means of displaying images if nothing else, and it is
used as part of the fgs routine.  Look at the file "Howto.Vista" to
get a sense of how to use it.