diff options
Diffstat (limited to 'funtools/doc/pod/funimage.pod')
| -rw-r--r-- | funtools/doc/pod/funimage.pod | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/funtools/doc/pod/funimage.pod b/funtools/doc/pod/funimage.pod new file mode 100644 index 0000000..7ec3f93 --- /dev/null +++ b/funtools/doc/pod/funimage.pod @@ -0,0 +1,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 |