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