XIMAGE is a command-driven program. Each command has associated with it qualifiers and positional arguments. These define values for the arguments used by each XIMAGE command. Qualifiers and positional arguments can be of three different types: numerical, character and logical. Qualifiers are separated by a slash /. Numerical and character qualifiers must be used as follows command/qualifier= where the parameter value or the appropriate alphanumeric string must be given after the symbol "=". Logical qualifiers can be used simply by specifying their name (i.e. command/logical). The name of qualifiers can be abbreviated provided that the abbreviation is unique. To get a list of the available qualifiers for each command type command/?. Positional arguments follow the qualifiers and are typically used to specify a required parameter e.g. command pos1. Commands can be typed on the same line using the symbol ; as a separator. The commands are executed in sequence from left to right.
Commands can be given at the [XIMAGE> prompt or, equivalently, as a command string when XIMAGE is started. The following two examples will produce the same result:
> ximage
[1]XIMAGE>read/fits test.fits
[2]XIMAGE>disp
[3]XIMAGE>exit
> ximage "read/fits test.fits; disp; exit"
In both cases the user runs XIMAGE, reads the image test.fits,
displays it and then returns to the operating system.
The command recall is used to list previous commands. Any command can be reexecuted by typing recall n where n is the command number given in the listing. The alias command is used to rename long command strings to a simple name for the current session. A log file of the session can be created using log file. This will create a text file called file.log. The script file command writes all the commands entered as they are executed into the given file until exit or script none is run. XIMAGE also has access to the readline facility, which allows for command recall through use of the up-arrow key.
Scripts (Macros) can be created in a text file with the extension .xco. They are run by giving the file name preceded by an @ symbol at either the XIMAGE prompt, or at run time (e.g. ximage @my_analysis P1 P2 ). Variables can be passed into the script by using %N% in the script, where N is the number of the parameter on the command line. E.g. the my_analysis script could be:
read/fits %1%
disp
read/fits %2%
disp
Where P1 and P2 are the filenames. If all arguments are not given, the
%N% syntax will not be replaced in the script.
Note: if a startup script like my_analysis encounters an error on
execution, ximage will normally return to the Tcl prompt with an error
message. In some cases this behavior is undesireable. For example, if
a Perl script is executing ximage with a startup script, dropping into
the prompt will bring the automated process to a halt. Add the line
set exit_on_startfail 1 to the ~/.ximagerc file and an error will
cause ximage to exit, returning 1 as the error status. Any valid error
status may be assigned to exit_on_startfail.
The operating system can be accessed from the XIMAGE command line by
using the syscall command (e.g. syscall ls). The pre-4.0 method
used the $ symbol, however that symbol is now used by Tcl to denote
variables. As a shortcut to the syscall command, quote the symbol
with a backslash (e.g. 
ls). Typing syscall with no arguments
will spawn to the operating system command line, without
interrupting the current XIMAGE session. Type exit to return to XIMAGE.
The input files can be read into XIMAGE using the command read_image. The following file formats are supported:
If no file type qualifier is given, the read command assumes FITS format and examines the file to determine whether it is an image or event list. In cases where multiple extensions could result in a valid image, the syntax filename.fits+n or filename.fits[n] should be used to specify the desired extension.
When reading an event file, XIMAGE expects to find EVENT and GTI extensions. However if the GTI extension is not present, the file is still read. The exposure, in this case, is either set to the value of the exposure keyword in the header of the EVENT extension or set to zero if no exposure keywords is found. The exposure may be updated manually with the syntax chheader key=EXPOSURE val=1000 where 1000 is replaced by the desired value.
XIMAGE uses dynamic memory when reading an image or an event file, therefore the maximum size array is limited by the available memory. However, default sizes are set for an image file and an event file. For an image file the default array corresponds to the value of NAXIS1 and NAXIS2 in the FITS file, up to a maximum of 1024x1024 pixels. This maximum can be changed by setting read_image_limitsize (see read_image/size documentation). For event files, the default size depends on mission-specific settings in the mission database. If no default size is set for that mission or the mission is unknown, the resulting image will be 256x256 pixels. The default size can be changed by using the qualifier /size=n, where n is limited by the available memory, and/or by reading the image rebinned using the qualifier /rebin=m. The rebinning factor, m, is usually an integer value, however, a float (real) value may be specified. For example, in the case of Chandra where events have coordinates that are floats, a fractional rebin of 0.5, 0.25, etc. may be used to create images where the pixels correspond to sub-pixels in the original Chandra detector coordinates. If a rebinning is set, XIMAGE will continue to work and display in terms of the original unbinned pixel convention. Non square images can be read by setting the qualifiers /szx and /szy in place of /size.
XIMAGE has the capability of storing up to nine image maps, identified as MAP1-9, and an exposure map for each (EXMAP1-9), provided there is enough available memory to hold them. All maps are capable of storing float (real) or integer data, including both negative and positive values as well as null. The map command is used to copy, move, and free these internal image maps and select the map which commands operate on by default (i.e. the current map). Some commands (e.g. read_image, display) include a qualifier mapid=idstring, where idstring is MAP1-9 or EXMAP1-9, so the map to operate with may be specified independently from what is set as the current map. Special ids are defined which make referring to special maps easier in marith and commands with a mapid qualifier. DIS is the displayed map, CUR is the current map, SAV is the saved map, and prepending EX refers to their associated exposure maps (i.e. EXDIS and EXCUR).
The pre-4.0 method of managing maps with save_image and restore_image is emulated by treating MAP9 as the saved image. Also, at startup MAP1 is set as the current map, and the first image loaded is copied to MAP9. SAV is the recommended id for referring to the saved map, and EXSAV to its associated exposure map. If you choose to take advantage of map slots beyond the current and saved, using save_image and restore_image is not recommended, as this combination can cause confusion. The map copy command is better suited for use with all map slots.
Each map has an associated header, which contains keywords specifying coordinate and other properties of the image, similar to the headers found in FITS files. The header keyword values are assigned upon reading in an image, and are used internally by XIMAGE to display coordinates, do analysis, etc. The command chheader allows for printing these values and/or modifying them. Through typing chheader all the keywords associated with the current map are shown. If only chheader is typed, a subset is listed. All keywords can have their values modified, however only the subset listed by chheader are recommended for modification. The others listed with chheader all are mostly for internal usage.
Each map also has associated WCS information, identified by the WCSID keyword. This WCS data can potentially contain information for many coordinate system frames beyond the standard CRPIX1/2, CRVAL1/2, etc. keywords of the internal header. See wcs command documentation for details.
The read/exposure command will read in an exposure map that is in FITS format. The exposure map must be read in after the corresponding image has been read, and it must have the same binning and size as that image. The map can be displayed using the disp/exp command. The exposure corrected image is displayed using disp/correct.
An exposure map contains in each element the total number of seconds each pixel was exposed. By default it is assumed that the exposure map is already corrected for the vignetting. If it has not, then the vignetting command can be used to apply the correction (for a known instrument).
These are currently only supplied for the EXOSAT CMA. The capability exists to read in a FITS image as a background map, but it requires the appropriate file to be installed in the calibration file directory.
The write command allows images to be written out in a couple of different formats, FITS by default. The current exposure map can also be written using the /exposure_map qualifier. The currently displayed image is written using the /display_map qualifier.
The extract command is used to obtain a spectrum and/or a lightcurve for the selected region or to construct color-color diagrams for detected sources from the detect or search command. This command can be used only with event files. The spectrum format is an ASCII dump containing the number of events per channel. The lightcurves are also ASCII files in QDP format. Both files can be plotted via QDP and are mainly for internal usage. It is recommended that xselect be used to extract these products for analysis with XSPEC or XRONOS.
A sky coordinate grid can be overlayed on the image using grid, and a slice in the x and y planes can be obtained with the slice command. Circular and box regions can be defined and written to an SAOIMAGE type region file using the circle and box commands. The HEASARC database can be directly queried using skymap/db=, where /db= is used to specify the name of a HEASARC database. This is useful to overlay star positions from different catalogs on the current image. Plotting contour levels on top of an image is automatic with the contour/overlay command.
To overlay a contour on top of an image from a different mission, e.g. ROSAT on top of ASCA, no manipulation of the contour map is necessary as the transformation between the two sets of coordinates is automatically calculated. For example:
read/fits/size=800 inst1.fits ! read the 1st instrument image
save_image ! save the image
disp/sav ! display the 1st image
read/fits inst2.fits ! read the 2nd instrument image
smooth ! smooth the 2nd image
cont/overlay ! make a contour plot and overlay it
! on the current image.
grid 0.5 0.5 ! draw a skygrid
Note: the coordinates that will be reported from the cursor will correspond to the image, not the overlayed contour.
If the /xtk device is being used, zooming is not available unless all the maps that have been plotted are present in memory for replotting. They do not need to exist in the exact mapid that they were originally plotted from. Ximage recognizes maps that are exact copies of each other, and if a copy of that displayed map is still in memory it will refer to that one. For example:
read/fits/size=800 inst1.fits ! current map contains inst1.fits
disp ! current map is displayed
save ! current map is saved (current=saved)
read/fits inst2.fits ! current map contains inst2.fits
! and saved is still inst1.fits
smooth ! current map (inst2) is smoothed
cont/overlay ! current map (inst2) is overlayed
! the saved map is recognized as
! a copy of the original displayed map
! when replotting
Note: In the event of an operation which alters an image map, such as smooth, rotate, etc. ximage will recognize that the map is no longer an exact copy, so the map will no longer be available for replotting.
A good rule of thumb is when performing contour overlays, make a copy of the image immediately after it has been displayed. In the simple contour overlay case, use the save_image command, however, if more than two maps are involved, use map copy to copy the displayed map to an unused map slot.
To draw a skygrid use the command grid. The default grid spacing is usually optimal, but can be changed by giving the degree steps e.g. grid 0.5 0.5. If the grid is not optimal use display to redisplay, and then try a new grid. The grid will be drawn using the original coordinate system defined in the input file whether it is equatorial tangent, galactic, or any WCS system. Use the /gal qualifier to draw the grid in galactic coordinates or '/radec' to draw an R.A./Dec grid regardless of the original coordinate system. Use /equinox to set the system's equinox.
There are two commands to convert pixel coordinates to sky positions and vice-a-versa. These are pix[el_to_ra_dec] and ra[_dec_to_pixel]. They can, as with all ximage commands, be abbreviated to make them unique (e.g. pix and ra). Use pix/cur to input the pixel coordinates using the cursor.
Coordinates in ximage are given referenced to the currently set equinox year. The equinox setting can be viewed with the show command, and changed with cey command (e.g. cey 2000). The equinox year can be changed many times during a session.
To draw a slice along the x or y axis then use slice/x or slice/y. The cursor is used to select the range of y or x to sum the image over to make the slice (opposite the axis to which the slice is to be made). For a x slice click the left button to choose two points along the y axis. The middle button can be used to cancel the slice. The /log qualifier will draw the slice on a log scale.
The skymap command reads in a list of star positions and overlays them on the current image. The default will read an ascii file with the first line containing the equinox year (e.g. 1950) and on each following line the RA and DEC in decimal degrees. The /label qualifier will also overlay the names of the objects and the /class will give the classification.
Ximage may also make overlays of catalogs queried from the HEASARC database. This is done as follows:
[3]XIMAGE> skymap/db=rc3/label
This will open a connection to the HEASARC database system at GSFC and will download all objects within the image that are found in the rc3 database into a local file. This is then automatically overlayed on the image. The /label qualifier will cause the objects to be written. The /class qualifier will write the object class as well, if it is known. Useful master databases such as OPTICAL, XRAY, RADIO and ROSID give an overview of the contents of the many individual databases. The URL, http://heasarc.gsfc.nasa.gov/db-perl/W3Browse/w3catindex.pl, from the HEASARC online service lists the available databases.
It is possible to access the HEASARC skyview facility directly from XIMAGE using the skyview command. This will take the coordinates and image size from the current image, and request an image from the specified survey. This is useful for making overlays and identifying X-ray sources. A full list of available surveys can be accessed using skyview/list and the chosen survey accessed by giving the full name with the /survey qualifier (e.g. skyview/survey="digitized sky survey"). After the image is retrieved it must be read back in, and displayed in the usual way. By default, the retrieved file is called skyview.fits, although the name may be set with the file qualifier.
Region selection is possible using box and circle. The regions are selected using the cursor, and are by default inclusive. The /exclude qualifier will create an exclusive region. These write out a region descriptor file that has a format identical to the region descriptor file used by SAOIMAGE (which can also be used to write the region file). The region file can be used to select a part of the image for further analysis. Multiple regions can be built up, to e.g. create an annulus, or exclude part of the image. Each call to these two commands will add the latest selected region to the existing region file. The /new qualifier is used to start a new region selection. The region file is given by default the name of the image, with the extension .reg. Otherwise it can be specified using /regionfile=.
Other commands, such as counts and remove_sources take regionfiles as input. Of course, the format output by the box and circle commands are supported, but also the formats output by the image viewers fv and ds9 are supported. Note, fv and ds9 do not preserve the original detector coordinates of the image, while ximage does, so using regionfiles in image coordinates from those programs will not give the desired results. Use a format that utilizes sky coordinates and the polygon shape for best results.