README file for CADS/UVS fits2jpeg software
-------------------------------------------


0. FEATURES
-----------
fits2jpeg is a tiny program to read FITS Images and convert them
to jpeg, which is more popular. This software supports various
type of intensity scaling and image enhancements. fits2jpeg do not
support coordinate axes overlay. fits2jpeg supports batch mode
operations - for instance, converting several fits files to jpeg
at once.


1. BUILD/INSTALL
----------------

Pre-requisites:

 a) CFITSIO
    CFITSIO is a library and headers to read and write FITS files.
    If you do not have cfitsio installed, get it from:

    http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html

 b) JPEGLIB
    jpeg library and headers. libjpeg is installed by default on most
    platforms, but we need the header files too. Once you have cfitsio
    and jpeglib installed, you may proceed with compiling jpeg2fits.
    Follow these 4 steps:


  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.

     If cfitsio library and header files are not in the standard path,
     then you may need to pass on the following argument to configure:

        --with-cfitsio=path/to/cfitsio

         Script will search fitsio header files in:
             1. path/to/cfitsio
             2. path/to/cfitsio/include
             3. path/to/cfitsio/include/cfitsio

        and library (libcfitsio.so or libcfitsio.a) in
             1. path/to/cfitsio
             2. path/to/cfitsio/lib
             3. path/to/cfitsio/lib64


     Similarly, for jpeglib (incase configure failed to detect it)

              --with-jpeglib=/path/to/jpeglib

     Running `configure' takes a few seconds. While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Type `make install' to install the programs and any data files and
     documentation. By default, the binary is copied to /usr/local/bin.
     You may change this destination by passing on the following
     argument to configure:

             --prefix=/your/chosen/destination

     Which would result in the binary in /your/chosen/destination/bin
     You may need to ensure that in $PATH to run the program.

  4. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.

You may read more about configure script and others in the accompanying
file named `INSTALL.txt'.


2.USAGE
-------

  fits2jpeg [options] <fits_file>

  Options are:
    -h help

    -s <scale_type>
       scale for output image intensity. Valid arguments are:

         linear         for linear scaling, default
         sqroot         for square root scale
         square         for quadratic scale
         cubic          for cubic scale
         log            for log scale

    -e <operation>
       Imaghe enhancement operations. Valid arguments are:

         equalize       perform histogram equalization
         normalize      perform a linear contrast stretch
                        (use cutoffs at 1% and 99% for image data)

  Output will be written to <fits_file_root>.jpg. For eg.,

    fits2jpeg 30dor.fits

  writes output to jpeg file 30dor.jpg

  Wild card entries allowed in <fits_file>. For eg: *.fits,
  m31*.fits ngc???.fits etc.

  More examples:

  i. fits2jpeg -s cubic sirius.fits
     will write out sirius.jpg, flux/intensity in log scale

 ii. fits2jpeg -s sqroot *.fits
     Converts all fits files in the directory to jpegs, with
     square-root scaling of flux/intensity - Good for very
     high dynamic range images

iii. fits2jpeg -e normalize ngc4151.fits
     Converts ngc4151.fits to ngc4151.jpg, contrast stretched.

NOTE: You can perform scaling + enhancing on an image. Scaling will
      always be performed first. In most cases combining these two
      would lead to un-usable images :)


3. DOCUMENTATION
----------------
An extensive coverage of how this program works along with line
by line account of the happenings within the code, are dealt with
in the user manual, which is yet to be written :(


4. LICENSE: GPL [See the file COPYING.txt for details]
-----------


5. DISCLAIMER
-------------
You may encounter bugs in this software. If you do, please
report them. Your bug reports are valuable contributions,
since they allow us to notice and fix problems on
machines/platforms we don't have, and/or remained un-noticed.


6. REPORTING BUGS
-----------------
You can register with the cads bug reporting tool:
http://cads.iiap.res.in/bugzilla/
and file a bug report.

If you are too lazy, drop in an email to: cads_AT_iiap.res.in

Either way, please include as many details as possible.

-----------------------------------------------------------
Reks, 28 June 2012 <reks_at_iiap.res.in>
      Last modified: 28 June 2012