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] You need to specify a fits image file for this program to work. Everything else is optional. A brief description of them are listed below: -h help Prints out a usage-help message, much like this section. -s scale for output image, where 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 -n Negate the image -q quality factor. Defines the jpeg encoding quality Valid range: 0-100, default value: 100, which means best quality and largest file-size. -d Write jpeg file to this specified directory. Will create it if needed. Default is to write jpeg in the same directory of fits image file -r : 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 -z Resize/Scale output image by . Eg: 0.5 Shrink output to half of input 2.0 Magnify output to double the size Allowed range: 0.01 to 4.0 NOTE: Zooming will be carried out after all other operations, before writing out jpeg image fits2jpeg uses a bilinear interpolation based algorithm to scale the image. Allowed range: 0.01 to 4.0 NOTE: Anything outside the allowed range will be clipped to this range. Output will be written to .jpg. For eg., fits2jpeg 30dor.fits writes output to jpeg file 30dor.jpg Wild card entries allowed in . For eg: *.fits, m31*.fits ngc???.fits etc. 3.1 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. v. fits2jpeg -s equalize -r 200: -d/path/to/mydir NGS253*.fits Reads all fits files in the present directory that matches the filename patterm, performs a histogram equalization, drops pixel values below 200 and write out all the corresponding jpeg files to directory /path/to/mydir Will create the destination directory tree if it does not exist. 3.1. Sequence of operations --------------------------- Here is the sequence of operations, after reading the fits file: i. clip the image to user specified pixel limits, if it was requested ii. Squeeze image pixel values to jpeg limits (0 - 255) iii. image scaling function, default being linear pixel scale iv. Negate the image, if requested v. Image zoom - magnify or shrink the image vi. Write out jpeg file 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 Last modified: 10 July 2012