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
  10 to jpeg, which is more popular. This software supports various
  11 type of intensity scaling and image enhancements. fits2jpeg do not
  12 support coordinate axes overlay. fits2jpeg supports batch mode
  13 operations - for instance, converting several fits files to jpeg
  14 at once.
  15
  16
  17 1. BUILD/INSTALL
  18 ----------------
  19
  20 Pre-requisites:
  21
  22  a) CFITSIO
  23     CFITSIO is a library and headers to read and write FITS files.
  24     If you do not have cfitsio installed, get it from:
  25
  26     http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html
  27
  28  b) JPEGLIB
  29     jpeg library and headers. libjpeg is installed by default on most
  30     platforms, but we need the header files too. Once you have cfitsio
  31     and jpeglib installed, you may proceed with compiling jpeg2fits.
  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.
  65      You may change this destination by passing on the following
  66      argument to configure:
  67
  68              --prefix=/your/chosen/destination
  69
  70      Which would result in the binary in /your/chosen/destination/bin
  71      You may need to ensure that in $PATH to run the program.
  72
  73   4. You can remove the program binaries and object files from the
  74      source code directory by typing `make clean'.
  75
  76 You may read more about configure script and others in the accompanying
  77 file named `INSTALL.txt'.
  78
  79
  80 2.USAGE
  81 -------
  82
  83  Usage: fits2jpeg [options] <fits_file>
  84
  85  Options are:
  86
  87     -h help
  88
  89     -s <scale_type>
  90        scale for output image, where <scale_type> can be:
  91          linear         Linear scale, default
  92          sqroot         for square root scale
  93          square         for quadratic scale
  94          cubic          for cubic scale
  95          log            for log scale
  96          normalize      for linear histogram stretch
  97          equalize       for histogram equalization
  98
  99     -r <min>:<max>
 100        Clip output image to min-max range. Eg:
 101          0:100          Use only values in the range 0-100
 102          100:0          Same as above, but negative image
 103            :10          Clip everything above 10
 104          10:            Clip everything below 10
 105
 106     -n
 107        Negate the image.
 108
 109     -q <value>
 110        jpeg quality factor. Defines the jpeg encoding quality
 111        Valid range: 0-100, default value: 100, which is for
 112        best quality (and largest file size).
 113
 114     -z <zoomfactor>
 115        Resize/Scale output image by <zoomfactor>. Eg:
 116          0.5            Shrink output to half of input
 117          2.0            Magnify output to double the size
 118
 119
 120   Output will be written to <fits_file_root>.jpg. For eg.,
 121
 122     fits2jpeg 30dor.fits
 123
 124   writes output to jpeg file 30dor.jpg
 125
 126   Wild card entries allowed in <fits_file>. For eg: *.fits,
 127   m31*.fits ngc???.fits etc.
 128
 129   More examples:
 130
 131   i. fits2jpeg -s log sirius.fits
 132      will write out sirius.jpg, flux/intensity in log scale
 133
 134  ii. fits2jpeg -s sqroot *.fits
 135      Converts all fits files in the directory to jpegs, with
 136      square-root scaling of flux/intensity - Good for very
 137      high dynamic range images
 138
 139 iii. fits2jpeg -n ngc4151.fits
 140      Converts ngc4151.fits to ngc4151.jpg, negative image.
 141
 142 iv.  fits2jpeg -s square -n -r 10:2000 m31.fits
 143      Write out m31.jpg, after square scaling of flux/intensity,
 144      negate image and clip pixel values in the range 10 to 2000
 145      units.
 146
 147
 148 3. DOCUMENTATION
 149 ----------------
 150 An extensive coverage of how this program works along with line
 151 by line account of the happenings within the code, are dealt with
 152 in the user manual, which is yet to be written :(
 153
 154
 155 4. LICENSE: GPL [See the file COPYING.txt for details]
 156 -----------
 157
 158
 159 5. DISCLAIMER
 160 -------------
 161 You may encounter bugs in this software. If you do, please
 162 report them. Your bug reports are valuable contributions,
 163 since they allow us to notice and fix problems on
 164 machines/platforms we don't have, and/or remained un-noticed.
 165
 166
 167 6. REPORTING BUGS
 168 -----------------
 169 You can register with the cads bug reporting tool:
 170 http://cads.iiap.res.in/bugzilla/
 171 and file a bug report.
 172
 173 If you are too lazy, drop in an email to: cads_AT_iiap.res.in
 174
 175 Either way, please include as many details as possible.
 176
 177 -----------------------------------------------------------
 178 Reks, 28 June 2012 <reks_at_iiap.res.in>
 179       Last modified: 10 July 2012