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         You need to specify a fits image file <fits_file> for this program to
  84         work. Everything else is optional. A brief description of them are
  85         listed below:
  86
  87     -h help
  88        Prints out a usage-help message, much like this section.
  89
  90     -s <scale_type>
  91        scale for output image, where <scale_type> can be:
  92          linear         Linear scale, default
  93          sqroot         for square root scale
  94          square         for quadratic scale
  95          cubic          for cubic scale
  96          log            for log scale
  97          normalize      for linear histogram stretch
  98          equalize       for histogram equalization
  99
 100     -n
 101        Negate the image
 102
 103     -q <value>
 104        quality factor. Defines the jpeg encoding quality
 105        Valid range: 0-100, default value: 100, which means
 106        best quality and largest file-size.
 107
 108     -d <path/to/output/directory>
 109        Write jpeg file to this specified directory. Will
 110        create it if needed. Default is to write jpeg in the
 111        same directory of fits image file
 112
 113     -r <min>:<max>
 114        Clip output image to min-max range. Eg:
 115          0:100          Use only values in the range 0-100
 116          100:0          Same as above, but negative image
 117            :10          Clip everything above 10
 118          10:            Clip everything below 10
 119
 120     -z <zoomfactor>
 121        Resize/Scale output image by <zoomfactor>. Eg:
 122          0.5            Shrink output to half of input
 123          2.0            Magnify output to double the size
 124                         Allowed range: 0.01 to 4.0
 125        NOTE: Zooming will be carried out after all other
 126              operations, before writing out jpeg image
 127
 128        fits2jpeg uses a bilinear interpolation based algorithm
 129        to scale the image. Allowed range: 0.01 to 4.0
 130        NOTE: Anything outside the allowed range will be clipped
 131              to this range.
 132
 133   Output will be written to <fits_file_root>.jpg. For eg.,
 134
 135     fits2jpeg 30dor.fits
 136
 137   writes output to jpeg file 30dor.jpg
 138
 139   Wild card entries allowed in <fits_file>. For eg: *.fits, m31*.fits
 140   ngc???.fits etc.
 141
 142
 143 3.1 Examples:
 144 -------------
 145   i. fits2jpeg -s log sirius.fits
 146
 147      will write out sirius.jpg, flux/intensity in log scale
 148
 149  ii. fits2jpeg -s sqroot *.fits
 150
 151      Converts all fits files in the directory to jpegs, with square-root scaling
 152      of flux/intensity - Good for very high dynamic range images
 153
 154 iii. fits2jpeg -n ngc4151.fits
 155
 156      Converts ngc4151.fits to ngc4151.jpg, negative image.
 157
 158  iv. fits2jpeg -s square -n -r 10:2000 m31.fits
 159
 160      Write out m31.jpg, after square scaling of flux/intensity, negate image and
 161      clip pixel values in the range 10 to 2000 units.
 162
 163   v. fits2jpeg -s equalize -r 200: -d/path/to/mydir NGS253*.fits
 164
 165      Reads all fits files in the present directory that matches the filename
 166      patterm, performs a histogram equalization, drops pixel values below 200
 167      and write out all the corresponding jpeg files to directory /path/to/mydir
 168      Will create the destination directory tree if it does not exist.
 169
 170
 171 3.1. Sequence of operations
 172 ---------------------------
 173 Here is the sequence of operations, after reading the fits file:
 174
 175      i. clip the image to user specified pixel limits, if it was requested
 176     ii. Squeeze image pixel values to jpeg limits (0 - 255)
 177    iii. image scaling function, default being linear pixel scale
 178     iv. Negate the image, if requested
 179      v. Image zoom - magnify or shrink the image
 180     vi. Write out jpeg file
 181
 182
 183 3. DOCUMENTATION
 184 ----------------
 185 An extensive coverage of how this program works along with line by line account
 186 of the happenings within the code, are dealt with in the user manual, which is
 187 yet to be written :(
 188
 189
 190 4. LICENSE: GPL [See the file COPYING.txt for details]
 191 -----------
 192
 193
 194 5. DISCLAIMER
 195 -------------
 196 You may encounter bugs in this software. If you do, please report them. Your bug
 197 reports are valuable contributions, since they allow us to notice and fix
 198 problems on machines/platforms we don't have, and/or remained un-noticed.
 199
 200
 201 6. REPORTING BUGS
 202 -----------------
 203 You can register with the cads bug reporting tool:
 204 http://cads.iiap.res.in/bugzilla/
 205 and file a bug report.
 206
 207 If you are too lazy, drop in an email to: cads_AT_iiap.res.in
 208
 209 Either way, please include as many details as possible.
 210
 211
 212 -----------------------------------------------------------
 213 Reks, 28 June 2012 <reks_at_iiap.res.in>
 214       Last modified: 10 July 2012