National Aeronautics and Space Administration

Additional scripts for use with XIMAGE

Ximage 4.2 and later natively supports the full range of WCS encodings, including the CD matrix convention. This script, however, allows the user to convert a CD matrix representation to an analagous CDELT/CROTA representation.

This script uses the "pget" task to retrieve the CD matrix keywords (i.e. CD1_1, CD1_2, CD2_1, CD2_2) and calculates analogous values for CDELT1, CDELT2, and CROTA2.

The following options are available:

       -h - Prints help file
       -d - Debug

       the following flags require arguments
       -i - input FITS file
       -t - template file (optional output)
       -a - tolerance angle (Default 0.001)

By default the calculated keywords are simply printed out, however the syntax "cdelrot.pl -t header.txt" will output a template file for use with fmodhead which will rename the CD matrix and add the CDELT and CROTA keywords.

The conversion is not exact. There is a tolerance angle which, if exceeded, will cause the calculation to fail. By default, the angle is 0.001 degrees, although the "-a" flag may be used to alter this value.

The script, reggen.pl, generates region files from a text file containing columns for position and size in detector coordinates, and creates an XIMAGE script which runs commands for each. Position and size columns need not be specified for SEARCH and EXCESS output from XIMAGE. Those files will be automatically identified and the proper columns read.

The following options are available:

       -h - prints the help
       -c - write circle regions instead of default boxes

       the following flags require arguments
       -p - position columns "x,y" (Default = 1,2)
       -s - size column [half-width for box, radius for circle] (Default = 3)
       -i - input text file
       -d - region file directory
       -o - output script file (Default=reggen.xco)
            Will contain a line for each region, based on the macro settings
       -m - macro [form: @script or command] (Default = counts)
            script should contain %1% where regionfile is to be inserted
            for script the line written is "@script [regionfile]"
            for command the line written is "command/reg=[regionfile]"

For example, the command:

      reggen.pl -d xsregions -m @sumone.xco -i output.xs -o sumall.xco

Valid commands for the "-m" option include any command with the REGIONFILE option, such as REMOVE_SOURCES and COUNTS. For operations involving more than one command, use a script with %1% in place of the region file. If the string begins with an "@" symbol, a script is assumed. For example, listed below is the example script, sumone.xco:

read/regionfile=%1% rp200008.evt
sum
save

It is recommended that you always use the "-d" option to specify a directory, as reggen.pl generates many region files which can clutter your current directory. Attempting to reuse the same directory, however, will cause the script to fail. Remove the existing directory before usage, as reggen.pl will not overwrite it.

The script, vpcgen.pl, generates a viewport configuration file for a configuration of NxM viewports (i.e. N viewports wide and M viewports high) to use with ximage's viewport command. The minimum amount of info needed by this script is the dimensions of the configuration (e.g. 2x2). By default a /GIF device is assumed, which has dimensions of 850x680. The dimensions of some PGPLOT graphic devices, such as /XW, vary from system to system. To find the actual dimensions, display an image in ximage with the device and run the command 'viewport/devsz'.

The following options are available:

       -h - print help
       -c - turn on chat (for debugging)

       the following flags require arguments
       -v - viewport configuration (NxM or N,M)
       -d - device size in pixels  (NxM or N,M) Default=850x680
       -s - image size in pixels (NxM or N,M) square images are
            assumed by default
       -m - minimum margin from edge in device pixels
       -o - output viewport configuration file (Default=NxM.vpc)

Usage examples:

Generate 2x2.vpc viewport configuration file for /GIF device

      vpcgen.pl -v 2x2

Generate 3x2.vpc viewport configuration file for /XW device (812x642 in this case) intended for images read with szx=300/szy=200

      vpcgen.pl -v 3x2 -d 812x642 -s 300x200

In XIMAGE, use the syntax VIEWPORT [viewport file] to set the viewport configuration. Note that the 3.0 version of XIMAGE has a limit of 10 total viewports. The limit was increased to 1000 for the 3.01 release.

The viewport files installed with ximage have precedence. If the file generated by this script has a name coincident with the installed viewport files, you must rename it or specify its full path.