README.txt

   1
   2
   3 README file for CADS/UVS fits2jpeg software
   4 -------------------------------------------
   5
   6
   7 0. FEATURES
   8 -----------
   9 fits2jpeg is a tiny program to read FITS Images and convert them to jpeg, which
  10 is more popular. This software supports various type of intensity scaling and
  11 image enhancements. fits2jpeg do not support coordinate axes overlay. fits2jpeg
  12 supports batch mode operations - for instance, converting several fits files to
  13 jpeg at once.
  14
  15
  16 1. BUILD/INSTALL
  17 ----------------
  18
  19 Pre-requisites:
  20
  21  a) CFITSIO
  22     CFITSIO is a library and headers to read and write FITS files.
  23     If you do not have cfitsio installed, get it from:
  24
  25     http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html
  26
  27  b) JPEGLIB
  28     jpeg library and headers. libjpeg is installed by default on most platforms,
  29     but we need the header files too. Once you have cfitsio and jpeglib
  30     installed, you may proceed with compiling jpeg2fits.
  31
  32     Follow these 4 steps:
  33
  34
  35   1. `cd' to the directory containing the package's source code and type
  36      `./configure' to configure the package for your system.
  37
  38      If cfitsio library and header files are not in the standard path,
  39      then you may need to pass on the following argument to configure:
  40
  41         --with-cfitsio=path/to/cfitsio
  42
  43          Script will search fitsio header files in:
  44              1. path/to/cfitsio
  45              2. path/to/cfitsio/include
  46              3. path/to/cfitsio/include/cfitsio
  47
  48         and library (libcfitsio.so or libcfitsio.a) in
  49              1. path/to/cfitsio
  50              2. path/to/cfitsio/lib
  51              3. path/to/cfitsio/lib64
  52
  53
  54      Similarly, for jpeglib (incase configure failed to detect it)
  55
  56               --with-jpeglib=/path/to/jpeglib
  57
  58      Running `configure' takes a few seconds. While running, it prints some
  59      messages telling which features it is checking for.
  60
  61   2. Type `make' to compile the package.
  62
  63   3. Type `make install' to install the programs and any data files and
  64      documentation. By default, the binary is copied to /usr/local/bin. You may
  65      change this destination by passing on the following argument to configure:
  66
  67              --prefix=/your/chosen/destination
  68
  69      Which would result in the binary in /your/chosen/destination/bin
  70      You may need to ensure that in $PATH to run the program.
  71
  72   4. You can remove the program binaries and object files from the source code
  73      directory by typing `make clean'.
  74
  75 You may read more about configure script and others in the accompanying file
  76 named `INSTALL.txt'.
  77
  78
  79 2.USAGE
  80 -------
  81
  82  Usage: fits2jpeg [options] <fits_file>
  83
  84  Options are:
  85
  86     -h help
  87
  88     -s <scale_type>
  89        scale for output image, where <scale_type> can be:
  90          linear         Linear scale, default
  91          sqroot         for square root scale
  92          square         for quadratic scale
  93          cubic          for cubic scale
  94          log            for log scale
  95          normalize      for linear histogram stretch
  96          equalize       for histogram equalization
  97
  98     -r <min>:<max>
  99        Clip output image to min-max range. Eg:
 100          0:100          Use only values in the range 0-100
 101          100:0          Same as above, but negative image
 102            :10          Clip everything above 10
 103          10:            Clip everything below 10
 104
 105     -n
 106        Negate the image.
 107
 108     -q <value>
 109        jpeg quality factor. Defines the jpeg encoding quality
 110        Valid range: 0-100, default value: 100, which is for
 111        best quality (and largest file size).
 112
 113     -z <zoomfactor>
 114        Resize/Scale output image by <zoomfactor>. Eg:
 115          0.5            Shrink output to half of input
 116          2.0            Magnify output to double the size
 117
 118        fits2jpeg uses a bilinear interpolation based algorithm
 119        to scale the image. Allowed range: 0.01 to 4.0
 120        NOTE: Anything outside the allowed range will be clipped
 121
 122   Output will be written to <fits_file_root>.jpg. For eg.,
 123
 124     fits2jpeg 30dor.fits
 125
 126   writes output to jpeg file 30dor.jpg
 127
 128   Wild card entries allowed in <fits_file>. For eg: *.fits, m31*.fits
 129   ngc???.fits etc.
 130
 131   More examples:
 132
 133   i. fits2jpeg -s log sirius.fits
 134      will write out sirius.jpg, flux/intensity in log scale
 135
 136  ii. fits2jpeg -s sqroot *.fits
 137      Converts all fits files in the directory to jpegs, with
 138      square-root scaling of flux/intensity - Good for very
 139      high dynamic range images
 140
 141 iii. fits2jpeg -n ngc4151.fits
 142      Converts ngc4151.fits to ngc4151.jpg, negative image.
 143
 144 iv.  fits2jpeg -s square -n -r 10:2000 m31.fits
 145      Write out m31.jpg, after square scaling of flux/intensity,
 146      negate image and clip pixel values in the range 10 to 2000
 147      units.
 148
 149
 150 3.1. Sequence of operations
 151 ---------------------------
 152 Here is the sequence of operations, after reading the fits file:
 153
 154      i. clip the image to user specified pixel limits, if it was requested
 155     ii. Squeeze image pixel values to jpeg limits (0 - 255)
 156    iii. image scaling function, default being linear pixel scale
 157     iv. Negate the image, if requested
 158      v. Image zoom - magnify or shrink the image
 159     vi. Write out jpeg file
 160
 161 3. DOCUMENTATION
 162 ----------------
 163 An extensive coverage of how this program works along with line by line account
 164 of the happenings within the code, are dealt with in the user manual, which is
 165 yet to be written :(
 166
 167
 168 4. LICENSE: GPL [See the file COPYING.txt for details]
 169 -----------
 170
 171
 172 5. DISCLAIMER
 173 -------------
 174 You may encounter bugs in this software. If you do, please report them. Your bug
 175 reports are valuable contributions, since they allow us to notice and fix
 176 problems on machines/platforms we don't have, and/or remained un-noticed.
 177
 178
 179 6. REPORTING BUGS
 180 -----------------
 181 You can register with the cads bug reporting tool:
 182 http://cads.iiap.res.in/bugzilla/
 183 and file a bug report.
 184
 185 If you are too lazy, drop in an email to: cads_AT_iiap.res.in
 186
 187 Either way, please include as many details as possible.
 188
 189
 190 -----------------------------------------------------------
 191 Reks, 28 June 2012 <reks_at_iiap.res.in>
 192       Last modified: 10 July 2012