1funimage(1) SAORD Documentation funimage(1)
2
6 funimage - create a FITS image from a Funtools data file
7
9 funimage [-a] <iname> <oname> [bitpix=n] funimage [-l] <iname> <oname>
10 <xcol:xdims> <ycol:ydims> <vcol> [bitpix=n] funimage [-p x⎪y] <iname>
11 <oname> [bitpix=n]
12
14 -a # append to existing output file as an image extension
15 -l # input is a list file containing xcol, ycol, value
16 -p [x⎪y] # project along x or y axis to create a 1D image
17
19 funimage creates a primary FITS image from the specified FITS Extension
20 and/or Image Section of a FITS file, or from an Image Section of a non-
21 FITS array, or from a raw event file.
22 The first argument to the program specifies the FITS input image,
24 array, or raw event file to process. If "stdin" is specified, data are
25 read from the standard input. Use Funtools Bracket Notation to specify
26 FITS extensions, image sections, and filters. The second argument is
27 the output FITS file. If "stdout" is specified, the FITS image is
28 written to the standard output. By default, the output pixel values
29 are of the same data type as those of the input file (or type "int"
30 when binning a table), but this can be overridden using an optional
31 third argument of the form:
32 bitpix=n
34 where n is 8,16,32,-32,-64, for unsigned char, short, int, float and
36 double, respectively.
37 If the input data are of type image, the appropriate section is
39 extracted and blocked (based on how the Image Section is specified),
40 and the result is written to the FITS primary image. When an integer
41 image containing the BSCALE and BZERO keywords is converted to float,
42 the pixel values are scaled and the scaling keywords are deleted from
43 the output header. When converting integer scaled data to integer (pos‐
44 sibly of a different size), the pixels are not scaled and the scaling
45 keywords are retained.
46 If the input data is a binary table or raw event file, these are binned
48 into an image, from which a section is extracted and blocked, and writ‐
49 ten to a primary FITS image. In this case, it is necessary to specify
50 the two columns that will be used in the 2D binning. This can be done
51 on the command line using the bincols=(x,y) keyword:
52 funcnts "foo.ev[EVENTS,bincols=(detx,dety)]"
54 The full form of the bincols= specifier is:
56 bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]])
58 where the tlmin, tlmax, and binsiz specifiers determine the image bin‐
60 ning dimensions:
61 dim = (tlmax - tlmin)/binsiz (floating point data)
63 dim = (tlmax - tlmin)/binsiz + 1 (integer data)
64 Using this syntax, it is possible to bin any two columns of a binary
66 table at any bin size. Note that the tlmin, tlmax, and binsiz speci‐
67 fiers can be omitted if TLMIN, TLMAX, and TDBIN header parameters
68 (respectively) are present in the FITS binary table header for the col‐
69 umn in question. Note also that if only one parameter is specified, it
70 is assumed to be tlmax, and tlmin defaults to 1. If two parameters are
71 specified, they are assumed to be tlmin and tlmax. See Binning FITS
72 Binary Tables and Non-FITS Event Files for more information about bin‐
73 ning parameters.
74 By default, a new 2D FITS image file is created and the image is writ‐
76 ten to the primary HDU. If the -a (append) switch is specified, the
77 image is appended to an existing FITS file as an IMAGE extension. (If
78 the output file does not exist, the switch is effectively ignored and
79 the image is written to the primary HDU.) This can be useful in a
80 shell programming environment when processing multiple FITS images that
81 you want to combine into a single final FITS file.
82 funimage also can take input from a table containing columns of x, y,
84 and value (e.g., the output from fundisp -l which displays each image x
85 and y and the number of counts at that position.) When the -l (list)
86 switch is used, the input file is taken to be a FITS or ASCII table
87 containing (at least) three columns that specify the x and y image
88 coordinates and the value of that image pixel. In this case, funimage
89 requires four extra arguments: xcolumn:xdims, ycolumn:ydims, vcolumn
90 and bitpix=n. The x and y col:dim information takes the form:
91 name:dim # values range from 1 to dim
93 name:min:max # values range from min to max
94 name:min:max:binsiz # dimensions scaled by binsize
95 In particular, the min value should be used whenever the minimum coor‐
97 dinate value is something other than one. For example:
98 funimage -l foo.lst foo.fits xcol:0:512 ycol:0:512 value bitpix=-32
100 The list feature also can be used to read unnamed columns from standard
102 input: simply replace the column name with a null string. Note that the
103 dimension information is still required:
104 funimage -l stdin foo.fits "":0:512 "":0:512 "" bitpix=-32
106 240 250 1
107 255 256 2
108 ...
109 ^D
110 The list feature provides a simple way to generate a blank image. If
112 you pass a Column-based Text File to funimage in which the text header
113 contains the required image information, then funimage will correctly
114 make a blank image. For example, consider the following text file
115 (called foo.txt):
116 x:I:1:10 y:I:1:10
118 ------ ------
119 0 0
120 This text file defines two columns, x and y, each of data type 32-bit
122 int and image dimension 10. The command:
123 funimage foo.txt foo.fits bitpix=8
125 will create an empty FITS image called foo.fits containing a 10x10
127 image of unsigned char:
128 fundisp foo.fits
130 1 2 3 4 5 6 7 8 9 10
131 ------ ------ ------ ------ ------ ------ ------ ------ ------ ------
132 10: 0 0 0 0 0 0 0 0 0 0
133 9: 0 0 0 0 0 0 0 0 0 0
134 8: 0 0 0 0 0 0 0 0 0 0
135 7: 0 0 0 0 0 0 0 0 0 0
136 6: 0 0 0 0 0 0 0 0 0 0
137 5: 0 0 0 0 0 0 0 0 0 0
138 4: 0 0 0 0 0 0 0 0 0 0
139 3: 0 0 0 0 0 0 0 0 0 0
140 2: 0 0 0 0 0 0 0 0 0 0
141 1: 1 0 0 0 0 0 0 0 0 0
142 Note that the text file must contain at least one row of data. However,
144 in the present example, event position 0,0 is outside the limits of the
145 image and will be ignored. (You can, of course, use real x,y values to
146 seed the image with data.)
147 Furthermore, you can use the TEXT filter specification to obviate the
149 need for an input text file altogether. The following command will cre‐
150 ate the same 10x10 char image without an actual input file:
151 funimage stdin'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8 < /dev/null
153 or
154 funimage /dev/null'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8
155 You also can use either of these methods to generate a region mask sim‐
157 ply by appending a region inside the filter brackets and specfying
158 mask=all along with the bitpix. For example, the following command will
159 generate a 10x10 char mask using 3 regions:
160 funimage stdin'[TEXT(x:I:10,y:I:10),cir(5,5,4),point(10,1),-cir(5,5,2)]' \
162 foo.fits bitpix=8,mask=all < /dev/null
163 The resulting mask looks like this:
165 fundisp foo.fits
167 1 2 3 4 5 6 7 8 9 10
168 ------ ------ ------ ------ ------ ------ ------ ------ ------ ------
169 10: 0 0 0 0 0 0 0 0 0 0
170 9: 0 0 0 0 0 0 0 0 0 0
171 8: 0 0 1 1 1 1 1 0 0 0
172 7: 0 1 1 1 1 1 1 1 0 0
173 6: 0 1 1 0 0 0 1 1 0 0
174 5: 0 1 1 0 0 0 1 1 0 0
175 4: 0 1 1 0 0 0 1 1 0 0
176 3: 0 1 1 1 1 1 1 1 0 0
177 2: 0 0 1 1 1 1 1 0 0 0
178 1: 0 0 0 0 0 0 0 0 0 2
179 You can use funimage to create 1D image projections along the x or y
181 axis using the -p [x⎪y] switch. This capability works for both images
182 and tables. For example consider a FITS table named ev.fits containing
183 the following rows:
184 X Y
186 -------- --------
187 1 1
188 1 2
189 1 3
190 1 4
191 1 5
192 2 2
193 2 3
194 2 4
195 2 5
196 3 3
197 3 4
198 3 5
199 4 4
200 4 5
201 5 5
202 A corresponding 5x5 image, called dim2.fits, would therefore contain:
204 1 2 3 4 5
206 ---------- ---------- ---------- ---------- ----------
207 5: 1 1 1 1 1
208 4: 1 1 1 1 0
209 3: 1 1 1 0 0
210 2: 1 1 0 0 0
211 1: 1 0 0 0 0
212 A projection along the y axis can be performed on either the table or
214 the image:
215 funimage -p y ev.fits stdout ⎪ fundisp stdin
217 1 2 3 4 5
218 ---------- ---------- ---------- ---------- ----------
219 1: 1 2 3 4 5
220 funimage -p y dim2.fits stdout ⎪ fundisp stdin
222 1 2 3 4 5
223 ---------- ---------- ---------- ---------- ----------
224 1: 1 2 3 4 5
225 Furthermore, you can create a 1D image projection along any column of a
227 table by using the bincols=[column] filter specification and specifying
228 a single column. For example, the following command projects the same
229 1D image along the y axis of a table as use of the -p y switch:
230 funimage ev.fits'[bincols=y]' stdout ⎪ fundisp stdin
232 1 2 3 4 5
233 ---------- ---------- ---------- ---------- ----------
234 1: 1 2 3 4 5
235 Examples:
237 Create a FITS image from a FITS binary table:
239 [sh] funimage test.ev test.fits
241 Display the FITS image generated from a blocked section of FITS binary
243 table:
244 [sh] funimage "test.ev[2:8,3:7,2]" stdout ⎪ fundisp stdin
246 1 2 3
247 --------- --------- ---------
248 1: 20 28 36
249 2: 28 36 44
250
252 See funtools(n) for a list of Funtools help pages
253version 1.4.0 August 15, 2007 funimage(1)