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