3 README file for CADS/UVS fits2jpeg software
4 -------------------------------------------
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.
16 1. BUILD/INSTALL
17 ----------------
19 Pre-requisites:
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:
25 http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html
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.
32 Follow these 4 steps:
35 1. `cd' to the directory containing the package's source code and type
36 `./configure' to configure the package for your system.
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:
41 --with-cfitsio=path/to/cfitsio
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
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
54 Similarly, for jpeglib (incase configure failed to detect it)
56 --with-jpeglib=/path/to/jpeglib
58 Running `configure' takes a few seconds. While running, it prints some
59 messages telling which features it is checking for.
61 2. Type `make' to compile the package.
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:
67 --prefix=/your/chosen/destination
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.
72 4. You can remove the program binaries and object files from the source code
73 directory by typing `make clean'.
75 You may read more about configure script and others in the accompanying file
76 named `INSTALL.txt'.
79 2.USAGE
80 -------
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:
87 -h help
88 Prints out a usage-help message, much like this section.
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
100 -n
101 Negate the image
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.
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
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
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
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.
133 Output will be written to <fits_file_root>.jpg. For eg.,
135 fits2jpeg 30dor.fits
137 writes output to jpeg file 30dor.jpg
139 Wild card entries allowed in <fits_file>. For eg: *.fits, m31*.fits
140 ngc???.fits etc.
143 3.1 Examples:
144 -------------
145 i. fits2jpeg -s log sirius.fits
147 will write out sirius.jpg, flux/intensity in log scale
149 ii. fits2jpeg -s sqroot *.fits
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
154 iii. fits2jpeg -n ngc4151.fits
156 Converts ngc4151.fits to ngc4151.jpg, negative image.
158 iv. fits2jpeg -s square -n -r 10:2000 m31.fits
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.
163 v. fits2jpeg -s equalize -r 200: -d/path/to/mydir NGS253*.fits
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.
171 3.1. Sequence of operations
172 ---------------------------
173 Here is the sequence of operations, after reading the fits file:
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
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 :(
190 4. LICENSE: GPL [See the file COPYING.txt for details]
191 -----------
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.
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.
207 If you are too lazy, drop in an email to: cads_AT_iiap.res.in
209 Either way, please include as many details as possible.
212 -----------------------------------------------------------
213 Reks, 28 June 2012 <reks_at_iiap.res.in>
214 Last modified: 10 July 2012