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
-------

 Usage: fits2jpeg [options] <fits_file>

 Options are:

    -h help

    -s <scale_type>
       scale for output image, where <scale_type> can be:
         linear         Linear scale, default
         sqroot         for square root scale
         square         for quadratic scale
         cubic          for cubic scale
         log            for log scale
         normalize      for linear histogram stretch
         equalize       for histogram equalization

    -r <min>:<max>
       Clip output image to min-max range. Eg:
         0:100          Use only values in the range 0-100
         100:0          Same as above, but negative image
           :10          Clip everything above 10
         10:            Clip everything below 10

    -n
       Negate the image.

    -q <value>
       jpeg quality factor. Defines the jpeg encoding quality
       Valid range: 0-100, default value: 100, which is for
       best quality (and largest file size).

    -z <zoomfactor>
       Resize/Scale output image by <zoomfactor>. Eg:
         0.5            Shrink output to half of input
         2.0            Magnify output to double the size


  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 log 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 -n ngc4151.fits
     Converts ngc4151.fits to ngc4151.jpg, negative image.

iv.  fits2jpeg -s square -n -r 10:2000 m31.fits
     Write out m31.jpg, after square scaling of flux/intensity,
     negate image and clip pixel values in the range 10 to 2000
     units.


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: 10 July 2012