1 XIMAGE
2 Introduction
3 Overview
 
XIMAGE is a multi-mission X-ray image display and analysis program. It
is designed to be instrument independent and to support the analysis of
data from any X-ray imaging detector provided that the proper
calibration files are available. Currently XIMAGE supports the detailed
analysis of EXOSAT CMA, Einstein HRI and IPC, ROSAT PSPC and HRI, ASCA
GIS and SIS, BeppoSAX MECS and LECS data.  It also supports some basic
analysis of optical, infrared and radio images.
The following functions are provided:
---
 * reading in of images and event files
 * image rebinning, smoothing, and display
 * source detect, and statistical analysis
 * source removal
 * correction for vignetting, exposure, background and point spread function
 * image mosaics
 * contour plots and overlays
 * sky grids and pixel-coordinate conversions
 * changing equinox
 * x/y image slices
 * generation of a point spread function
 * circular and box region selection
 * extraction of spectra and lightcurves from event data
---
The display and graphic capabilities of XIMAGE are based on the
`PGPLOT` graphic package, which supports most terminals and
workstations. The programs, `saoimage` and `POWplot` can also be
spawned to display images and select regions.
 
While XIMAGE is a multimission package, it must first "know" about the
calibration information associated with a mission in order to be able to make
a detailed image analysis. Some XIMAGE functions are mission independent (e.g.
display), but others are not (e.g. source detect). XIMAGE will read in images
from an unknown mission, but the user should beware trying to make a detailed
analysis. A warning will be issued if the mission is unknown. A list of known
missions can be obtained by giving the command `chmdb/list`. Adding new
missions usually requires either adding new files and/or adding new calls and
relinking XIMAGE.
 
3 History
 
XIMAGE is based on original routines developed as part of the EXOSAT
interactive image analysis system. These routines have been restructured
and assembled as part of a multimission command driven interactive
software package running as part of the XANADU infrastructure.
 
3 Calibration_Information
 
Performing image analysis requires the following calibration items to be
known:
---
 * the vignetting function - the radial dependence of the telescope effective
area;
 
 * the point spread function (PSF) - the blurring of the image caused by its
intrinsic angular resolution;
 
 * the exposure map - the number of seconds each pixel in the image was
exposed; and
 
 * a background map - the particle background counting rate in each pixel.
---
The first two are critical for XIMAGE to produce any useful results. The
vignetting can be provided as an image map, or as a function. In the latter
case the XIMAGE code must be relinked. The PSF can be derived from within
XIMAGE, and read in as a file. The exposure map is optional, and if it is not
available then it is assumed the image exposure is uniform. This is usually
acceptable for detectors without any obstructing structures (e.g. the EXOSAT
CMA), but will lead to errors if there are window supports (e.g. the ROSAT
PSPC). The background map is also optional, and is only necessary in the case
where there is significant variation in the particle background across the
detector.
 
The vignetting function and the PSF can be energy dependent
(e.g. the ROSAT PSPC), and care must be taken to ensure that they match the
energy band of the image.
 
3 Caveat_Emptor
 
XIMAGE is written by astronomers, for astronomers. This
has the advantage that its requirements are driven by real needs, and
so it tends to do things in the most natural way and usually very
efficiently. While every effort has been made to get things right, the
user should always make an attempt to "understand" what ximage is doing
to produce the given results.
 
3 Installation
 
The XIMAGE package can be obtained for several platforms
including Dec-OSF, SunOS, and Linux. Compressed tar files can be obtained at
`http://heasarc.gsfc.nasa.gov/lheasoft/` or write to
`xanprob@legacy.gsfc.nasa.gov`.
 
3 Reporting_problems
 
Any problems in obtaining or installing XIMAGE should be reported to
`xanprob@legacy.gsfc.nasa.gov`. Any questions or problems with
XIMAGE or requests to add additional instruments should be
directed to `Lorella.Angelini-1@nasa.gov` or
`Charles.A.Padgett@nasa.gov`.
 
2 Getting_Started
 
XIMAGE is run directly from the operating system prompt by typing
`ximage`.  The user will receive the prompt `[XIMAGE>`. This is the
main command line of XIMAGE.  To get the list of commands type `?`
and/or `??`.  Typing `?` or `keywords` will print a short list of
keywords (or subjects) each grouping a number of related ximage
commands. Entering one of these keywords will print a short summary for
each command in that group.  Typing `??` will print a short summary for
all available commands.  Typing `help` followed by the command name
(e.g. `help display`) will provide a more detailed description of each
command.  General help is available by calling the `help` command with
no arguments.  In help, type the first few characters of the topic
followed by `<cr>` to get info on it.  Use `<cr>` to back up a level.
`Ctrl-D` exits help.
 
3 Command
4 Syntax
 
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.
 
4 Command_Line
 
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.
 
4 Scripts
 
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`.
 
4 Spawning
 
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.
 
3 Data
4 Reading
 
The input files can be read into XIMAGE using the command `read_image`.
The following file formats are supported:
---
 * a FITS image (`read/fits filename`),
 
 * a FITS photon event list (`read/rfits filename`),
 
 * an EXOSAT format image (`read/exo filename`),
---
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`.
 
4 Internal_Data_Storage
 
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.
 
4 Exposure_Maps
 
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).
 
4 Background_Maps
 
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.
 
4 Writing
 
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.
 
4 Extract
 
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.
 
3 Coordinates_and_Overlays
 
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.
 
4 Contour_Overlays
 
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.
 
4 Grid
 
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.
 
4 Pixel_Coordinate_Conversions
 
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.
 
4 Equinox_Year
 
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.
 
4 Slice
 
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.
 
4 Skymap
 
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.
 
4 Skyview
 
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.
 
4 Regions
 
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.
 
2 Plot_Images
3 Displaying
 
Three different displays are available to plot an image, one
interactive and two via external programs. The interactive display uses
PGPLOT as the plotting package.  All the commands that plot or query
the display use these built-in PGPLOT routines. The command `display`
plots the image on the plotting device, while the command `contour`
provides a contour plot.  The plot device may be set using the `cpd`
command (e.g. `cpd /xw`). XIMAGE supports many different plot devices,
although the primary devices are Tk (`/xtk`) for GUI interactive usage,
providing zoom, recenter, and color adjustment capabilities, X-windows
(`/xw`) for simple interactive usage, GIF (`/gif`) for web-ready
output, and Postscript (`/ps` or `/cps`) for printer output.  The image
is displayed with a histogram equalization scaling and a default color
table.  The `cct` command changes the color table and `cct ?` lists the
available color tables.  On PseudoColor devices, they can be cycled through
with the `cct/loop` command. For devices with limited colors or without
image display capability a contour plot can be made with the `contour`
command.  The image should be smoothed beforehand using the `smooth`
command.
 
The external programs to display an image are `saoimage` and `POWplot`,
useful for panning and zooming of the image. To run these external
programs, XIMAGE writes out an intermediate FITS file containing what
is currently in memory.  SAOIMAGE is run by typing `saoimage` at the
ximage command line, while POWplot is available through the `powplot`
command.  When saoimage or POWplot are used as image display , it is
not possible to overlay grids and/or return values from the image in
XIMAGE.
 
4 Tk_Details
 
The `/xtk` device provides more capabilities than the standard PGPLOT
devices.  Moving the mouse over a plot continually updates the tracking
information at the right side of the window with sky, galactic, detector
and image coordinates, as well as the value of the pixel the mouse is
positioned over.  Clicking on a plot with the left mouse button
zooms in by a factor of 2, recentering at the clicked point.  The middle
button simply recenters the plot with no change in zoom, while the right
button zooms out by a factor of 2, also recentering at the clicked point.
The `Zoom In` and `Zoom Out` buttons also zoom by a factor of 2, however
the current plot center is unchanged.  The `Replot` button returns the plot
to its original state with a zoom factor of 1.  The current zoom factor
is displayed under these buttons.  When multiple viewports are defined,
the area between the zoom buttons and color table sliders will contain
a representation of the defined viewports, called the viewport selector.
The box outlined in blue represents the current viewport which mouseover
coordinates and plotting commands apply to.  To switch the current
viewport click its associated box in the viewport selector.  The
brightness and contrast of the color table may also be adjusted with
the scales at the lower right of the window.  The `Reset` button
returns the color table to the default values of 0.5 for brightness
and 1.0 for contrast.
 
The `File` menu contains a `Print...` option which can be used to
output the current plot to a PostScript file, a GIF file, or directly
to a printer.  Note: It is important that all the image maps originally
used to make the plot are still present at print time, as everything
must be redrawn.  The device will present a warning when this is not
the case.  Continuing despite the warning, will cause the output to
be missing some plot elements.  A better approach in this case would
be to use the `Screen Grab...` option which simply captures the plot
as it appears on the screen.
 
The `Edit` menu allows the user to selectively add a sky
coordinate grid to the current image with the `Show Grid` checkbox
or add a scale defining which intensity levels are assigned
to which colors in the image with the `Show Scale` checkbox.
Unchecking the box removes the plot element.
 
 
3 Color
4 Levels
 
The number of colors that are plotted in an image depends on the
number of levels.  The default number of levels (n) is 16, however, it
may be changed through the `levels/num=[n]` command.  The number of
colors used in an image is one more than the number of levels (n+1).
To increase the color resolution, the number of levels must be
increased.
 
4 Color_Tables
 
When displaying an image through the `display` command, the intensity
levels are mapped into a default color table.  This may be changed
using the `cct [color table]` command, providing the device allows
color table changes, e.g. GIF and PseudoColor Xwindow devices. To plot
with a new color table on devices which don't allow color table
changes, such as Postscript and TrueColor Xwindow devices, the desired
color table must be set before the `display` command is called. To set
a color table use the command `cct/set [color table]`.  All subsequent
displays will use that color table, until either another color table
is chosen or the command `cct/reset` is executed.  Available color
tables are listed with the `cct ?` command.
 
4 User-Defined_Tables
 
Color tables are defined as ASCII files containing a list of RGB values
with a line per color, each having three numbers ranging in value from
0 to 1.  A color table file does not need to contain the exact number
of used colors, as the colors will be interpolated or ignored depending
on how many are needed.  Custom color tables may be input by giving the
filename with the `cct` command  , e.g. `cct/set mycolors.tab`.
 
4 Brightness_and_Contrast
 
The appearance of the specified color table may be further modified by
varying brightness and contrast settings. These are qualifiers of the
`cct` command and may be set as  `cct/contrast=n` and
`cct/brightness=m`. The effects of these adjustments on the color table
can clearly be seen if a `scale` is plotted.  Brightness (m) can go
from 0.0 to 1.0, with a default of 0.5.  Increasing the brightness
effectively shifts the color scale to the left making the upper end of
the scale, which is usually composed of brighter colors more dominant,
while lowering the brightness shifts it to the right having the
opposite effect.  Contrast (n) has a default value of 1.0.  Increasing
contrast effectively compresses the color scale, while decreasing it
stretches the color scale.  The most stretched out the scale can get is
at 0.0 where the scale is all one color.  As the contrast goes
negative, the direction of the scale is reversed, also affecting the
directional sense of the set brightness.  If the image is displayed on
an interactive device, such as a PseudoColor Xwindow, the `cct/cursor`
command can be used to experiment with various combinations for
brightness and contrast.  On the Tk device (`/xtk`), the adjustment
scales at the lower right can be used to modify the brightness and
contrast.
 
4 Reserved_Colors
 
Color table changes only affect the image itself, not the color of the
image frame or the device background.  The color indices 0 through 15
are reserved colors and are independent from the color table setting.
The device background is index 0 and the device foreground (used for
image title and frame) is index 1. The defaults for the background and
foreground colors are device-dependent. For example, Postscript files
have a white background and a black foreground, while XWindow devices
are the opposite.  The remaining reserved colors are defined by PGPLOT
defaults and are recommended for use with any XIMAGE command that
has `/color` qualifier. To view these reserved colors, list them
with `colors` or plot them to an open device with `colors/plot`.
If the default colors set for indices 0-15 are unsuitable, they may
be altered also through the `colors` command.
 
3 Image_Placement
 
4 Split_screen
 
Images can be placed side by side for comparison purposes using
`disp/left` and `disp/right/overlay`. The currently active window
is the last one displayed.
 
----------------------------------------------------------------------------
read/fits im1.fits            ! read the 1st image
display/left                  ! display the 1st image
grid                          ! overlay the sky grid
read/fits im2.fits            ! read the 2nd image
disp/right/overlay            ! display the two side by side
grid                          ! overlay the sky grid
----------------------------------------------------------------------------
 
Note: The left and right qualifiers are now emulated using a viewport file,
1lef1rig.  It is recommended that the user begin a new page by plotting on
the left side first.
 
4 Viewports
 
The exact position and size of the image on the screen can be
controlled by defining a viewport.  Viewport coordinates number the
device from 0 to 1 from left to right, and 0 to 1 from bottom to top.
A viewport is defined by four values, v1 (the left edge), v2 (the right
edge), v3 (the bottom edge), and v4 (the top edge).  These may be
specified in the `display` or `contour` commands using the `v1-4`
qualifiers or may be specified for all subsequent `display` and
`contour` commands issued within a XIMAGE session with the `viewport`
command.
 
----------------------------------------------------------------------------
 
    v1   v2
     !    !
 v4->|----|<-v4
     |VIEW|
     |PORT|
 v3->|----|<-v3
     ^    ^
    v1   v2
 
----------------------------------------------------------------------------
 
The image will be plotted as the largest size that will fit within the
viewport boundaries.  If one dimension of the viewport is larger than
the other, the image will be centered in the larger dimension and will
exactly fill the smaller dimension.  Most devices are larger in one
direction than the other, while viewport coordinates always map both
directions from 0 to 1. Consequently, viewport coordinates that may
appear square, such as `v1=0.5/v2=0.9/v3=0.5/v4=0.9`, are in fact
rectangular.
 
When displaying multiple images on a plotting device, setting up the
necessary viewports becomes cumbersome.  Viewport configuration files
can make this process easier.  A viewport configuration file is an
ASCII list of viewport definitions given one per each line.  Viewport
configurations are set through the `viewport filename` command.  For
each image displayed, a new viewport from the list is used until the
end is reached, then a new device is opened and the sequence repeats
from the first viewport. There are already made viewport configuration
files these are:
 
----------------------------------------------------------------------------
   1+2           (One image on left, 2 on right)
   1+2gif        (One image on left, 2 on right for a gif device)
   1in1botlef    (One image inset into large image's bottom-left corner)
   1in1botrig    (One image inset into large image's bottom-right corner)
   1in1toplef    (One image inset into large image's top-left corner)
   1in1toprig    (One image inset into large image's top-right corner)
   1lef1rig      (One image left, one right with labelling)
   2x1           (Two images side by side)
   2x2           (4 images in a square)
   2x2gif        (4 images in a square for a gif device)
   3diag         (3 images going left to right diagonally downward)
   3x1           (3 images in a row left to right)
   3x2           (6 images 3 on top 3 on the bottom)
   3x2gif        (6 images 3 top and 3 bottom for a gif device)
   3x3           (9 images 3 on top 3 in center 3 on the bottom)
   3x3gif        (9 images 3 on top 3 in center 3 on the bottom for gif)
----------------------------------------------------------------------------
 
(to get the list use the syntax `viewport ?`). Most installed configuration
files are optimized for square images plotted on Postscript and Xwindow
devices. Those with `gif` in their name, however, are optimized for the
GIF device.  This `optimization` takes into account the aspect ratio of
the device to get the precise layout desired.
 
4 User-Defined_Configurations
 
The `viewport` command will also accept user-defined viewport
configuration files. These are text files with a line for each viewport,
consisting of the v1-v4 values separated by spaces.  To form precise
viewport configurations, it may be necessary to know the exact size of
the plotting device.  The command `viewport/devsz` will provide this
information for the currently open device.
 
4 Viewport_Configuration_Example
 
For example, the installed configuration, 2x1, is defined in the
file, 2x1.vpc:
 
----------------------------------------------------------------------------
!  Viewport configuration file (2x1)
!
!        -------------
!        |     |     |
!        |  1  |  2  |
!        |     |     |
!        -------------
!
!v1  v2  v3  v4
!-- --- --- ---
0.1 0.5 0.2 0.8
0.5 0.9 0.2 0.8
----------------------------------------------------------------------------
 
Start using this configuration by executing the command
`viewport 2x1`.  To see which viewport number will be displayed next,
use the `show` command.  The following line shows the viewport
configuration file currently in use:
 
----------------------------------------------------------------------------
  Viewport                  : 2x1 - 1
----------------------------------------------------------------------------
 
The number following the dash (-) represents the viewport number
in the file.  If you `display` or `contour` at this point the image
will be displayed in square #1 represented in the ASCII grid above.
Using `show` again:
 
----------------------------------------------------------------------------
  Viewport                  : 2x1 - 2
----------------------------------------------------------------------------
 
The next `display` or `contour` will plot the image in square #2,
leaving the image already plotted in #1 on the device.
 
Note: The `/overlay` qualifier should be omitted unless you wish the
`contour` to be overlayed on top of the currently displayed image,
rather than in the next viewport.
 
When the last viewport in the the configuration is reached, a new
plotting device page will be opened and the numbering will begin again
at 1.
 
XIMAGE will continue in this mode until the viewport is changed or
`viewport/reset` is executed to erase any viewport settings.
 
2 Source_analysis
 
There are several XIMAGE commands to make a detailed analysis of the
image. These include:
---
 
 * `BACKGROUND` - estimate the background.
 
 * `EXCESS`     - list the image excesses using a sliding box.
 
 * `SEARCH`     - use the output list from `excess` to determine
                  the good sources. It uses PSF and vignetting to estimate
                  source significance. (Background+Excess+Search = Detect)
 
 * `DETECT`     - a sliding cell source detection algorithm, using the PSF and
                  vignetting to estimate source significance and statistics.
 
 * `REMOVE`     - remove sources from an image.
 
 * `COUNTS`     - calculate the source counts in a given region
 
 * `SOSTA`      - calculate the source counting rates and statistics correcting
                  for vignetting, point spread function and exposure
 
 * `PSF`        - generate the point spread function and compare it to the
                  predicted psf.
---
All these commands but `counts` are very mission dependent and require the
available calibration information.
 
3 Background
 
The BACKGROUND command estimates the background in the image. The method used
divides the image into equal boxes to estimate the local background intensity.
The event distribution in each box is checked for spatial uniformity and
consistency with the expected statistical distribution (Poisson or Gaussian,
depending on image type). If inconsistency between the observed and expected
distribution is found the box is rejected. The distribution of the average
background values in all boxes is then compared to a Gaussian distribution
with mean equal to the mean of all the background values found. All boxes
where the background level is more than three standard deviations away from
the mean are rejected. If more than 80% of the boxes are rejected the
background routine stops and an error message is generated. The value of the
background intensity returned is the average of the values measured in all
accepted boxes. A P(D) can be obtained using the
`background/npd=n/box=m/plot`. The output is written to the file `pd.qdp`.
 
3 Sosta
 
The SOSTA command can be used to determine the count rate in a box
region.  SOSTA counts the number of events within a specified box,
corrects those counts for vignetting, exposure and the point spread
function to give the source intensity and its statistical significance.
If the significance is less than `1.e-3` an upper limit is
automatically calculated.  The simplest way to use SOSTA is with the
cursor, its default mode. SOSTA will then use a box that corresponds
to 66% of the encircled energy function (EEF), and will use a
background from a region surrounding the source, outside the 98% EEF
boundary.
 
The background can be estimated using several different methods, specified
by the user. These are:
---
 * The background is estimated from a region within two boxes centered on the
source using the option `/INNER_RADIUS` and `/OUTER_RADIUS` to specify the
half-sizes of the two boxes. This is the default.
 
 * The background is taken from any specified part of the image using
`/BOX_BACKGROUND`;
 
 * The background intensity can be given using the qualifier
`/BACKGROUND_LEVEL`. In this case the background statistical error is
assumed to be zero.
---
The uncertainty in the count rate returned by SOSTA is purely statistical i.e.
does not include systematic errors. SOSTA will estimate the optimum box size
to maximize the signal to noise ratio. This is given at the end of each run.
By using the option `/OPTIMIZE` then SOSTA will go around a second time, and
use the optimum box size to calculate the optimum source statistics.
 
The psf correction that is calculated can be weighted by an exposure map if
the `/EXPOWGT` qualifier is given.
 
3 Counts
 
The COUNTS command sums the total number of counts specified either
as a box with the cursor or within a region file.  Complicated regions
composed of any of the major shapes, such as box, circle, and polygon, may
be input via a region file. The COUNTS command does not apply any
correction to the total counts nor does it subtract the background.
 
3 Detect
 
The DETECT command locates point sources in the current image by means of a
sliding-cell method. The average background intensity is estimated using the
method described previously. The position and intensity of each detected
source are calculated in a box whose size maximizes the signal-to-noise ratio.
If the source is not pointlike the estimated count rate is in general
inaccurate and likely to be under-estimated. A good estimate of the intensity
of extended sources can be obtained with command `COUNTS`.
 
Corrections to the net counts are applied if the proper calibration
information are available for that instrument. The corrections applied
are dead times, vignetting and psf (the fraction of the source counts
that fall outside the box where the net counts are estimated).  Count
rate errors include both statistical and systematic uncertainties added
quadratically. To minimize the number of spurious sources detected the
threshold used by `detect` is somewhat conservative. Consequently, some
sources with intensity just above the image background can be missed.
In order to allow `detect` to obtain a sufficiently good estimate of
the background only images of size 128x128 pixels or larger should be
used.  Maximum accuracy is obtained running `detect` on full resolution
images.
 
For crowded fields, or for fields with bright sources the qualifier
`/bright`. This will make a weighted mean of each excess, and
optimizing the psf. Consequently it can take much longer to run.
For crowded images, e.g. ROSAT PSPC, it may be necessary to "tweak" the
detection parameters to avoid false detections. The `/thr_scal` and
`/source_box` qualifiers are particularly useful. The `/thr_scal` scales
the threshold for excesses to be detected. This can be increased
by modest amounts for ROSAT PSPC deep fields e.g. 1.2 or 1.3. The
`/source_box` qualifier determines the size of the box used, in detector
coordinates. For the ROSAT PSPC the default is 80, and it can be
increased to 160 to reduce confusion.
 
The functionality of the detect command may also be accessed by
executing the `background`, `excess`, and `search` commands in
succession.  Running the process in pieces allows for finer control of
each step. For example, the background calculation may be tweaked, the
output of each step can be written out and/or read in, and the image
may be altered between steps.
 
3 Remove
 
Sources, or other features can be removed from an image using the command
`REMOVE`. This can be done by:
---
 * using the cursor to mark one or more box regions (`/CURSOR`)
 
 * specifying a region file to remove (`/REGIONFILE`)
 
 * entering the pixels coordinates of each box (`/XMIN`,`/YMIN`, etc)
 
 * using the sources found in the previous run of `DETECT` or `SEARCH`.
---
The latter mode is useful for checking how good the detect run was. For a
crowded region the sequence `DETECT;REMOVE/DETECT;DETECT;REMOVE/DETECT`
can be used to clean the image of all sources.
The removed area is filled with the average background value or by
either an constant input value.
 
3 Extract
 
The `extract` command can be used to generate spectra and lightcurves
from an input event file. The default is to use the region file
generated by the `box` and `circle` commands. A new region file name is
input using `/region=file`.  Output spectra(`/engfile=`) and
lightcurves(`/qdpfile=`) are in ASCII format.  These products can be
transform in FITS files and use within XSPEC and XRONOS.  A direct way
to get a spectrum and a lightcurve is using XSELECT.
 
The ASCII spectrum can be used within XIMAGE to calculate the energy
dependence of the PSF for a given source with the command
`psf/engfile=`.  If the extracted spectrum can be used as a
representative of a number of sources to calculate the energy-dependent
PSF, set the ENGFILE keyword in the mdb equal to the extracted
spectrum. Then the `psf` command will automatically use the value in
ENGFILE.
 
The `extract` command is also useful to
generate color-color diagrams for all the sources detected
in the field of view with the `detect` or `search` command.
 
4 Color-Color_Diagrams
 
The command `extract/detect/plot_color` will generate a color-color
diagram for all sources detected with `detect` or `search` command.
This is useful for identifying very soft or very hard sources in the
field. The default channel boundaries can be changed using the
`/C1=/C2=/C3=/C4=` qualifiers, or set ahead in the Mission database
using the command `chmdb` (i.e. set the EXCHAN key as `C1,C2,C3,C4`).
An output QDP format filename containing the results is written with a
default of the `eventfile.col`, where `eventfile` is the input event
filename. A new name is given with the qualifier `colorfile=`.  The
colors calculated correspond to the following ratios:  (C4-C3)/(C3-C2)
and (C2-C1)/(C3-C2).  The qualifier `cl3file=` outputs the color-color
results with additional columns, which contain the mean channel for
each of the channel ranges.
 
3 PSF
 
Calculates differential and integral Point Spread Function, PSF. It also
compares the observed and the expected PSF provided the latter is given.
 
The `psf` command accumulates all the counts within annuli of
increasing radii. Each annulus increases by one pixel. Rebin the image
to change the step size.  The results are written to a ASCII file
(QDP-compatible) and plotted.  The differential PSF is given as a
surface brightness (counts/s/sq arc min) and the integral as the
Encircled Energy Function, EEF.  The expected values for a pointlike
source are also written to the QDP file and displayed. An accurate
estimate of the image background is required, and is obtained using the
`background` command. The cursor can be used to specify the source
centroid, and the outer ring `psf/cursor`. The `psf` command can be
used to extract the surface brightness profile of extended sources, for
further analysis outside XIMAGE.
 
Typically, PSF depends on offaxis and energy, and the mathematical
description can be provided via a subroutine.  If no routine are
available for a specific mission, the offaxis dependence of the PSF can
be derived within XIMAGE with the `/multpsffile=` qualifier.
This writes a PSF file which can be set as the PSFFILE
key with the `chmdb` command, so `detect` and `sosta` use it for
subsequent analysis. The file created using the qualifier `multpsffile=`
can contain multiple columns representing the PSF at different offaxis
angles.
 
If an exposure map is available, exposure map weighting can be included
in the calculation with the `/expowgt` option. Each annulus is weighted
by the total exposure in that annlulus, normalized to the maximum
exposure contained within the outer radius of the largest annulus.
 
If the expected PSF is energy-dependent, the `psf/engfile=` allows to
input a spectrum which will be used to calculate the observed PSF
weighted for that spectrum.  The `extract/engfile=` command generates
the spectral file to input in `psf/engfile=`.  If no spectrum is input,
then the PSF is calculated at a single energy (1 keV is the default).
The single energy is used to speed up `detect` and `sosta`.  Currently,
energy-dependent PSF routines are available within XIMAGE for ROSAT,
ASCA, and BeppoSAX.
 
The following is an example of how to make a PSF for the ROSAT PSPC. This
procedure is more complex because the PSF is energy dependent, so a spectrum
must first be accumulated.
 
For ROSAT PSPC only:
---------------------------------------------------------------------
read/rfits/xpix=5000/ypix=5000 rp500012.fits  ! make an image from the
                                              ! events file.
disp                                          ! display it
circle                                        ! define a source region
extract/engfile=eng_rosat.dat                 ! extract a spectrum
psf/engfile=eng_rosat.dat/cur                 ! use spectrum to calc psf
---------------------------------------------------------------------
 
For all instruments (for non-PSPC first read in the image):
---------------------------------------------------------------------
back/opt                                      ! optimum background
psf/cur/back=1.0e-03                          ! calculate the psf
---------------------------------------------------------------------
 
2 Mosaics
 
XIMAGE can be used to take several images from a part of the sky and
make a mosaic.
3 Without_Exposure_Maps
 
The sequence of commands to do this are:
----------------------------------------------------------------------------
read/fits/size=800 file1.fits    ! read the first image into a 800x800 array
save_image                       ! save the image
read/fits/size=800 file2.fits    ! read the second image
sum_image                        ! sum the 1st and 2nd images
save_image                       ! save the summed image
read/fits/size=800 file3.fits    ! read the third image
sum_image                        ! sum the 3rd with the saved image
save_image                       ! save the mosaic
disp                             ! display the mosaiced image
grid 0.5 0.5                     ! draw a skygrid in 0.5 degree steps
disp/exp                         ! display the exposure map
disp/cor                         ! display the exposure corrected image
write/fits mosaic.fits           ! write the mosaic to a fits file
----------------------------------------------------------------------------
Its usually best to start with the central image of the mosaic when
if possible. The exposure for each image is kept track of within XIMAGE,
assuming the entire region has been equally exposed. This may not be accurate,
especially for those cases where the active area of the image does not match
that of the entire image. Where ever possible an exposure map must be read in.
 
DETECT and SOSTA will not give the correct results if the summed images come
from different pointing directions. They will be unable to make any correction
for off-axis vignetting and psf changes, since they reference to the detector
coordinates of the last image that was read in.
 
3 With_Exposure_Maps
 
When making a mosaic, it is best to read in an exposure map for each image.
The exposure map must be read in after the image. The following example
repeats the mosaic described above, but includes an exposure map.
----------------------------------------------------------------------------
read/fits/size=800 file1.fits    ! read the first image into a 800x800 array
read/fits/exp/size=800 exp1.fits ! read the first exposure map (optional)
save_image                       ! save the exposure map
read/fits file2.fits             ! read the second image
read/fits/exp exp2.fits          ! read the second exposure map
sum_image                        ! sum the 1st and 2nd images
save_image                       ! save the summed image
read/fits file3.fits             ! read the third image
read/fits/exp exp3.fits          !
sum_image                        ! sum the 3rd with the saved image
save_image                       ! save the mosaic
disp                             ! display the mosaiced image
grid 0.5 0.5                     ! draw a skygrid in 0.5 degree steps
disp/exp                         ! display the exposure map
disp/cor                         ! display the exposure corrected image
write/fits mosaic.fits           ! write the mosaic to a fits file
write/fits/exp mosaic_exp.fits   ! write the exposure
----------------------------------------------------------------------------
 
 
2 Commands
3 alias
alias - rename a command string
------------------------------------------------------------------------
alias [name] [command_string]
------------------------------------------------------------------------
 
Rename a command string to an alias name. `name` specifies the new
name, command_string is that to be renamed. The command string is
exactly as it would be given on the command line.
 
From session to session, aliases are not saved.  In order to retain
an alias definition from one session to the next, edit or create
~/.ximagerc to contain alias commands which will be executed at
each startup.
 
4 Examples
 
alias ls "syscall ls"   ! alias ls to run the ls command in the shell
 
3 background
background - calculate average image background
------------------------------------------------------------------------
background[/qualifiers]
------------------------------------------------------------------------
 
The method used consists in dividing the image in n equal small square
boxes where the local background intensity is estimated. The event
distribution in each box is checked for spatial uniformity and
consistency with the expected statistical distribution (Poisson).  If
inconsistency between the observed and expected distribution is found
the box is rejected. The distribution of the average background values
in all boxes is then compared to a Gaussian distribution with mean
equal to the mean of all the background values found. All boxes where
the background level is more than `sigmult` (default=3.0) standard
deviations away from the mean are rejected. If more than 80% of the
boxes are rejected the background routine stops and an error message is
generated.  The value of the background intensity returned is the
average of the values measured in all accepted boxes.
 
The default box size used in the calculation ranges between 1/8 of the image
size up to a maximum of 64 pixels. The minimum box size is 8 pixels.
The qualifier `box_size` allows to input an arbitrary value, while the
qualifier `optimize` determines the best box size to have the smaller
background rate.
 
Changing the chatter to 20 or higher (command `chatter 20 20 `) and using the
`background/draw`, all the boxes, in which the image has been divided,
will be drawn and numbered on the display. The rejected boxes will be colored,
and the reason why they have been rejected will be printed on the screen.
If the rejection of boxes is not satisfactory, it is recommended, for a given
box size, to use the qualifiers `bxhprob`, `sigmult`, `barylim`.
 
Some commands, such as excess, smooth, remove_sources, and psf may
require the calculation of the background.  The results of the last
execution of the background command is used by default in these commands
However, if the background command has not been executed or
`background/reset` has been run, these commands may calculate the
background with their own default parameters.
When a new image is read or restore from memory, the previous
calculation of background is cleared from memory.
 
4 /draw_rej_back_boxes
background/draw_rej_back_boxes
 
Display all background boxes which have NOT been used for the
estimation of the background. If the chatter is higher than 20, all the
boxes will be drawn but only the rejected boxes will have a color different
from white.
 
4 /box_size
background/box_size=n
 
Defines the size (in image pixels) of the boxes where the image
background is estimated. Recommended background box sizes are powers of
two, such as 16, 32, 64, and 128.
 
4 /optimize
background/optimize
 
Go through a range of background boxes and determine the optimum box
size to give a minimum background counting rate.
 
4 /barylim
background/barylim=x
 
This box rejection criteria checks a box's spatial uniformity by
calculating the barycenter of the box based on the pixel weights.  If
the barycenter deviates from the physical center of the box by more
than `x` it is rejected.  The units for `x` are such that 1.0 is the
width of the box.  The default value is 0.35.
At high chatter the boxes rejected by this criteria are identified by
the message `barycenter greater than x from the center`.
 
This rejects boxes that contain 'excess counts' away from the center.
This is the second rejection criteria used, and it is applied on the
residual boxes after the first rejection criteria.
 
4 /bxhprob
background/bxhprob=x
 
This box rejection criteria compares the population of the left half of the
box with the right half and the top half with the bottom half using a
chi-square test.  The value `x` is the minimum acceptable probability.
For example, 1.0 is the most restrictive.  The default value for
bxhprob is 0.0, which never rejects a box.
At high chatter the boxes rejected by this criteria are identified by
the message `Box half max prob > x `.
This is the first rejection criterion used in established to good background
boxes.
 
4 /sigmult=x
background/sigmult=x
 
The final rejection criteria for background boxes calculates the
distribution of the average background values in all the remaining
boxes and compares them to a Gaussian distribution with mean equal to
the mean of all the background values found.  All boxes where the
background level is more than `x` standard deviations away from the
mean are rejected.  The default value is 3.0. Using lower value
for x will force to reject more boxes.
At high chatter the boxes rejected by this criteria are identified by
the message `Background too far from avg`.
 
4 /outfile
background/outfile=filename
 
The results of the background command are saved as text into a file.
 
4 /infile
background/infile=filename
 
The results of the background command are read in from a text file
generated by using the `outfile` qualifier. This is useful to avoid a
re-run of the background calculation on the same image.
 
 
4 /flat_value
background/flat_value=x
 
The background results are set to `x`, a constant value.
The value of `x` is in units of count for original pixel, e.g.
it is the background value of the unbinned image.
 
4 /reset
background/reset
 
The background results are erased, as if the background calculation was
never performed.  Commands requiring a background calculation will
either perform the calculation internally or fail with an error.
 
4 /npd
background/npd=n
 
A count distribution, P(D), is obtained from the residual boxes
used to calculate the background. The qualifier `npd=n` is the number
of count intervals (bins) into which the distribution is divided.
This qualifier has only effect if used in conjunction with `/plot_pd` to get
a plot of the distribution or with `/file_pd=[filename]` to write
out the distribution.
 
4 /plot_pd
background/plot_pd
 
This calculates, plots and writes out the distribution, P(D), of count
intervals for the residuals boxes used in the background calculation.
The number of bin for the distribution can be input using the qualifier
`/npd=n`, otherwise a default of 8 is used.
The P(D) distribution is written to a file by default named `pd.qdp`.
Different output filename can be selected with `/file_pd=[filename]`.
 
4 /file_pd
background/file_pd=[filename]
 
This calculates and writes out in the `filename` the distribution,
P(D), of counts interval for
the residual boxes used to determine the background.
The default number of bin for the distribution is 8. The qualifier
`/npd=n` allows to change the default number to `n`.
 
4 Examples
background/opt                ! calculate the optimum background
 
background/box=32             ! calculate the average image background
                              ! using square boxes of size=32 image pixels.
 
background/draw               ! use the default box size and draw the
                              ! boxes that have been rejected
 
background/npd=20/plot        ! do a P(D), count distribution in 20 bins
                              ! ct bins and plot the result
 
3 bglevels
bglevels - calculate background levels
-----------------------------------------------------------------------
  bglevels[/qualifiers]
-----------------------------------------------------------------------
 
Primarily for internal use by `contour/statistic`.
Calculates levels based on background calculation.
If the background command has been executed, that background is used,
otherwise the background command is run automatically with no options.
Calling `bglevels` with no options is equivalent to
`bglevels/sigma_levels="2 3 4 6 9 12 18 35 100"`
 
4 /background
bglevels/background=[value]
 
Set flat background value to use in levels calculation.  Note:
background is in units of cnts/image-pixel.
 
4 /mult_levels
contour/statistic/mult_levels=[levels list]
 
Calculates contour levels such that
`cont_levels = mult_levels*background`
 
4 /sigma_levels
contour/statistic/sigma_levels=[levels list]
 
Calculates contour levels such that
`cont_levels = background + sigma_levels*sqrt(background)`
Note: if background is less than 20, a poisson upper limit
approximation is used.
 
 
3 boxreg
boxreg - select a box region
-----------------------------------------------------------------------
  boxreg[/qualifiers] [regionfile]
-----------------------------------------------------------------------
 
A box shaped region is selected using the cursor. The results of the
selection are written to a region file. A box region is defined as
         (x-center, y-center, x-size, y-size)
where x-center and y-center are the box center and x-size and y-size
the size in the X and Y dimension. This is compatible with the
SAOimage definition. The X, Y and size values are in original unbinned pixel
coordinates even if the image has been rebinned.
The default region filename is the same name as the image file, with the
extension `.reg`. A different region filename can be specified using the
`/regionfile` qualifier.
The regions are by default inclusive. The `/exclusive` qualifier will
create an exclusive region. Each new region selection is added to the
region file, unless the `/new` qualifier is given. This applies to all
region selections, including `circlereg`.
 
4 /excluded
boxreg/excluded
 
The selected region will be excluded.
 
4 /regionfile
boxreg/regionfile=filename
 
Specify the name of the region file. Otherwise the default will be the
image name with a `reg` extension. The filename may also be specified after
the qualifiers.
 
4 /new
boxreg/new
 
Start a new region definition. If `/new` is not specified, then regions
will be added to the existing file.
 
4 /displayonly
boxreg/displayonly
 
Draw the contents of a region file on the current image
 
4 /color
boxreg/color=n
 
Set the color for the drawn regions.  By default, included regions are
green and excluded regions are red.  The value set for `/color` is
inherited by the excluded region unless `/excolor` is set.
 
4 /excolor
boxreg/excolor=n
 
Set the color for the excluded regions.
 
4 /lstyle
boxreg/lstyle=n
 
Set the style of the line used to draw regions: 1 (solid line),
2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
By default, all regions are drawn with a solid line.  The value set for
`/style` is inherited by the excluded region unless `/exlstyle` is set.
 
4 /exlstyle
boxreg/exlstyle=n
 
Set the style of the line used to draw excluded regions:
1 (solid line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted),
5 (dash-dot-dot-dot).
 
4 /lwidth
boxreg/lwidth=n
 
Set the width of the line used to draw regions. By default, all regions
are drawn with a line width of 1.  The value set for `/lwidth` is
inherited by excluded regions unless `/exlwidth` is set.
 
4 /exlwidth
boxreg/exlwidth=n
 
Set the width of the line used to draw excluded regions.
 
4 Examples
box/new hello.reg           ! select a box region, writing it into
                            ! hello.reg, creating a new file or
                            ! overwriting an existing one
 
box/disp/color=7/exlstyle=4 ! draw the default region file in yellow,
                            ! where the included regions are solid
                            ! lines and excluded are dotted lines
 
3 cct
cct - change color table
-----------------------------------------------------------------------
  cct[/qualifiers] [table name]
-----------------------------------------------------------------------
 
Can change color table for the currently displayed image, or through
`/set` can set the color table for the next image to be displayed.  A
question mark in place of the table name gives the list of all
available tables.  The current state of the color tables can be seen
with the show command.
 
4 /set
cct/set [table name]
 
Sets `table name` to be the default color table when next image is displayed.
If `table name` is not given the current color table will be set as default.
To revert the `/set` effect use `/reset`
Current brightness and contrast settings are also applied.
 
4 /reset
cct/reset
 
Revert to original startup color table for current and following
images.
 
4 /brightness
cct/brightness=x
 
Set brightness of displayed color table.  The default is 0.5 with
available values ranging from 0.0 to 1.0.
If a `scale` is displayed, the colors will appear to shift to the right
if the brightness is lower than 0.5 (darkening the image) and the colors
will shift to the left for brightness higher than 0.5 (lightening the image).
 
4 /contrast
cct/contrast=x
 
Set contrast of displayed color table.  The default is 1.0 but can have
a wide range of values. If a `scale` is displayed, the colors will appear to
compress for higher contrast values (bright spots get brighter and dark spots
get darker) and spread out for lower contrast values.
A negative value flips the direction of the color table.
 
4 /reverse
cct/reverse
 
Sets brightness=1-brightness and contrast=-contrast, reversing the
sense of the color table.
 
4 /bcreset
cct/bcreset
 
Resets the brightness and contrast to their standard values.
 
4 /cursor
cct/cursor
 
Try out various combinations of brightness and contrast by clicking
with the left button.  The image center corresponds to the standard
brightness/contrast values, with brightness increasing from left to
right across the image and contrast increasing from bottom to top.
Clicking the center button resets the brightness and contrast to their
standard values.  Clicking the right button ends the cursor mode.
 
4 /loop
cct/loop
 
Loop through each of the installed color tables.
 
4 /no_break
cct/no_break
 
Go through each color table without stopping.  Used only in conjunction
with `/loop` qualifier.
 
4 /user_col
cct/user_col [filename]
 
Specify user color table from a user-supplied file.  The color
table is an ascii file with the columns (R, B, G). The values for each
color should range from 0 to 1.  In general, this qualifier is not
necessary as local files matching the filename will automatically be
used.  If, however, there is an ambiguity between an installed color table
and a user-supplied table, the installed table is assumed.  This
qualifier forces XIMAGE to use the user-supplied version.
 
4 /outfile
cct/outfile=[filename]
 
Write the color values currently being used to display the image into a
file.  These values include the effects of the current contrast and
brightness settings, as well as any color interpolating done by
PGPLOT.
 
4 Examples
cct/con=1.2 bb      ! load the bb color table with a slightly tweaked
                    ! contrast for the current image
 
cct/set invgray     ! set the invgray table as the default for
                    ! future images, which is useful for plotting
                    ! to Postscript devices
 
cct ?               ! lists all available color tables
 
cct/loop            ! loop through all the available color tables
 
3 centroid
centroid - calculate centroid
-----------------------------------------------------------------------
  centroid[/qualifiers]
-----------------------------------------------------------------------
 
It calculates the centroid for a given area (box).
The area can be selected via cursor or specifying the qualifiers
`/xpix`, `/ypix` and `/boxradius`.
Centroid first calculates the first guess for the centroid, using
2 possible methods, and after uses this best guess for the final calculation.
The first guess for the centroid is obtained via a subsequent
rebinned by 2 of the selected area until the location of maximum is the same
as the last rebin. The alternative method, using the qualifier `/hist`,
determines as first best guess, the X and Y maximum for the distributions
obtained by summing the counts in the pixels along the X and Y directions.
The first best guess for the centroid is used as new center for the final
centroid calculation. This is achieved by interactively re-evaluating the
barycenter in boxes reduced by 80% each time from the original selected
area.  At each step if the barycenter is the same as the box center, the
box size is reduced, however if the barycenter differs, the barycenter
is recalculated using the last barycenter as the box center.
An alternate method for performing the last step of the centroid calculation,
selected through the `/deriv` option, uses the derivative of partial sums
method.
 
4 /xpix
centroid/xpix=x
 
Define the x coordinate of box center in original pixel coordinates.
To use with `ypix=y`.
 
4 /ypix
centroid/ypix=y
Define the y coordinate of box center in original pixel coordinates.
To use with `/xpix=x`.
 
4 /boxradius
centroid/boxradius=r
 
Define the half-width of the box in arcmin.
 
4 /pixboxrad
centroid/pixboxrad=r
 
Define the half-width of the box in detector pixels.
 
4 /cursor
centroid/cursor
 
Define center and size of box with mouse.  If `/boxrad` or `/xpix`
and `/ypix` have been entered, only the selections for the
unspecified parameters will be necessary.
 
4 /hist
centroid/hist
 
It calculates the first best guess of the centroid using the X and Y maximum
of histograms obtained by summing the counts in the pixels along the X and Y
directions. This first best guess location for the centroid is used to
calculate the final value.
 
4 /deriv
centroid/deriv
 
Use derivative of partial sums method.  Within a square centered on the
location of the maximum, the centroid is computed as the value at which
the derivatives of the partial sums of the input image over (y,x) with
respect to (x,y) = 0.
 
4 /symbol
centroid/symbol=n
 
Set or change the symbol for the centroid location plotted on the image
display.  The default value is 5, and corresponds to an `X`.
The available symbols are those from pgplot and can be viewed
from the ximage web page.
 
4 /csize
centroid/csize=x
 
Set the character size of the symbol. Standard character size is 1.0.
 
4 /color
centroid/color=n
 
Set the color used to plot the box and symbol.
 
4 /lwidth
centroid/lwidth=n
 
Set the width of the lines used to draw the box and symbol.  The
default value is 2.
 
4 Example
centroid/box=1.5/cur        !  Calculate centroid for box with
                            !  half-width of 1.5 arcmin and center
                            !  selected by cursor, plotting the result
 
3 cey
cey - change the equinox
-----------------------------------------------------------------------
  cey [equinox]
-----------------------------------------------------------------------
 
Set or change the current ximage equinox.
All commands dealing with celestial coordinates calculate, expect and/or
return coordinates using the equinox set by this command (e.g.
`detect`, `read`, `ra_dec_to_pixel`, and `pixel_to_ra_dec`).
The command `show` reports the current value set and in use for
the equinox. The alias of cey is the command `equinox`.
The equinox setting is preserved between ximage sessions.
 
4 Example
cey 2000                   ! Change the equinox year to 2000
 
3 chheader
chheader - change header information
-----------------------------------------------------------------------
  chheader[/qualifiers] [template]
-----------------------------------------------------------------------
 
Modify or show the header information for the current image in memory.
The header of the image or event file read is kept in memory using a
FITS structure. The content of the header information is described below.
Typing `chheader all` all the keywords associated with the current map
are shown. Typing `chheader` only a subset is listed.
All keywords can have their values modified, however it is recommended
to change only the keyword values listed by `chheader`. The others
listed with `chheader all` are mostly for internal usage.
 
4 /show
chheader/show
 
Prints the current values for the specified header, listing those
keywords specified in the `template`.
 
4 /template
chheader/template=[template_name]
 
Sets the template which defines the keywords to be shown. The template file
contains a subset of keyword available in the header. This is maily for internal
usage. If a `?` is given, the available templates will be listed.
 
4 /mapid
chheader/mapid=[string]
 
Selects the header to be modified or displayed.  By default the mapid
is MAP, which corresponds to the header for the current image map.
EXMAP corresponds to the current exposure map, MAPSV to the saved map,
EXMAPSV to the saved exposure map, and BGMAP to the background map.
 
4 /key
chheader/key=[keyname]
 
Sets the keyname whose value is being modified.  To see a list of
"safely" editable keynames, run the chheader with no arguments.
Note: Changes to coordinate keywords will not take effect unless
`wcs upwcs` is also run, updating the internal wcs information.
 
4 /value
chheader/value=[keyval]
 
Sets the value for the key defined by the `/key` qualifier.
 
4 Examples
chh                            ! Show "safely" editable header keywords
 
chh all                        ! Show all header keywords, whether
                               ! they are "safe" to edit or not
 
chh/key=telescop/val=rosat     ! Set the telescop and instrume
chh/key=instrume/val=pspc      ! to rosat/pspc
 
3 chmdb
chmdb - change mission information
-----------------------------------------------------------------------
  chmdb[/qualifiers] [input_mdbfile]
-----------------------------------------------------------------------
 
Modify or show default information defined for known missions.  If no
qualifiers are given, the information for the mission of the loaded
image is displayed.  The information for a single mission may also be
shown by specifying only the `/telescop`, `/instrume`, and `/detnam`.
In general, if `/detnam` is blank it need not be specified.
 
4 /list
chmdb/list
 
Lists all the currently defined missions.
 
4 /showall
chmdb/showall
 
Displays the mission information for all defined missions.
 
4 /telescop
chmdb/telescop=[string]
 
Defines the telescope to be displayed, modified, or copied.
 
4 /instrume
chmdb/instrume=[string]
 
Defines the instrument to be displayed, modified, or copied.
 
4 /detnam
chmdb/detnam=[string]
 
Defines the name of the detector to be displayed, modified, or copied.
 
4 /add
chmdb/add
 
Add a new mission specified with `/telescop`, `/instrume`, and `/detnam`.
 
4 /key
chmdb/key=[keyname]
 
Sets the keyname to be modified.
 
4 /value
chmdb/value=[keyval]
 
Sets the value for the key defined by the `/key` qualifier and the
mission specified with `/telescop`, `/instrume`, and `/detnam`.  If the
mission is not specified, the currently loaded mission is assumed.
 
4 /copy
chmdb/copy
 
Copy info for mission specified with `/telescop`, `/instrume`, and `/detnam`
to mission specified with `/totelescop`, `/toinstrume`, and `/todetnam`.
If `/telescop`, `/instrume`, and `/detnam` are not specified, the
currently loaded mission is assumed.  If "to"-mission exists, it is
overwritten. If it doesn't exist it is added.
 
4 /totelescop
chmdb/totelescop=[string]
 
Defines the telescope for the information to be copied to.  Only used
with `/copy` qualifier.
 
4 /toinstrume
chmdb/toinstrume=[string]
 
Defines the instrument for the information to be copied to.  Only used
with `/copy` qualifier.
 
4 /todetnam
chmdb/todetnam=[string]
 
Defines the name of the detector for the information to be copied to.
Only used with `/copy` qualifier.
 
4 /reset
chmdb/reset
 
Remove any changes to the mission information by reloading the
installed mission info file.
 
4 /infile
chmdb/infile=[filename]
 
Specify a mission information file to be input.  By default, new
missions are added and existing missions are updated.  With the
`/replace` qualifier, existing information is deleted, and only the
missions and values listed in the file are loaded.  An input file may
also be specified as the last argument of the command.
 
4 /replace
chmdb/replace
 
Replace the current mission information with the contents of the
specified input file.
 
4 /outfile
chmdb/outfile=[filename]
 
Write the currently loaded mission information into a file.
 
4 Examples
 
chmdb                                  ! Display mission info for
                                       ! current mission
 
chmdb/tel=rosat/inst=pspc              ! Display mission info for
                                       ! one mission
 
chmdb/key=defszx/val=1024              ! Set default size for currently
                                       ! loaded mission
 
chmdb/out=custom.mdb                   ! Write out all mission info
 
chmdb/tel=rosat/inst=pspc/out=pspc.mdb ! Write out mission info for
                                       ! one mission
 
chmdb/replace custom.mdb               ! Replace mission info with
                                       ! custom file
 
chmdb/copy/totel=dumtel/toinst=duminst ! Copy the mission info for the
                                       ! current mission to new or
                                       ! existing mission dumtel:duminst
 
3 circlereg
circlereg - select a circular region
-----------------------------------------------------------------------
  circlereg[/qualifiers] [regionfile]
-----------------------------------------------------------------------
 
A circular region is selected using the cursor. The results of the
selection are written to a region file. A circle region is defined as
         (x-center, y-center, rad)
where x-center and y-center are the X and Y coordinates of the circle
center and rad is the radius of the circle. This is compatible with the
SAOimage definition. The X, Y and the radius values are in original
unbinned pixel coordinates even if the image has been rebinned.
The default region filename is the same name as the image file, with the
extension `.reg`. A different region filename can be specified using the
`/regionfile` qualifier.
The regions are by default inclusive. The `/exclusive` qualifier will
create an exclusive region. Each new region selection is added to the
region file, unless the `/new` qualifier is given. This applies to all
region selections, including `boxreg`.
 
4 /excluded
circlereg/excluded
 
The selected region will be excluded.
 
4 /regionfile
circlereg/regionfile=[filename]
 
Specify the name of the region file. Otherwise the default will be the
image name with a `reg` extension. The filename may also be specified after
the qualifiers.
 
4 /new
circlereg/new
 
Start a new region definition. If `/new` is not specified, then regions
will be added to the existing file.
 
4 /displayonly
circlereg/displayonly
 
Draw the contents of a region file on the current image
 
4 /color
circlereg/color=n
 
Set the color index for the drawn regions.  By default, included
regions are green and excluded regions are red.  The value set for
`/color` is inherited by the excluded region unless `/excolor` is set.
 
4 /excolor
circlereg/excolor=n
 
Set the color index for the excluded regions.
 
4 /lstyle
circlereg/lstyle=n
 
Set the style of the line used to draw regions: 1 (solid line),
2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
By default, all regions are drawn with a solid line.  The value set for
`/lstyle` is inherited by the excluded region unless `/exlstyle` is set.
 
4 /exlstyle
circlereg/exlstyle=n
 
Set the style of the line used to draw excluded regions:
1 (solid line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted),
5 (dash-dot-dot-dot).
 
4 /lwidth
circlereg/lwidth=n
 
Set the width of the line used to draw regions. By default, all regions
are drawn with a line width of 1.  The value set for `/lwidth` is
inherited by excluded regions unless `/exlwidth` is set.
 
4 /exlwidth
circlereg/exlwidth=n
 
Set the width of the line used to draw excluded regions.
 
4 Examples
circle/excluded              ! make an excluded circle region selection
 
circle/new fred.reg          ! select a circle region, writing it
                             ! over fred.reg, a new or existing file
 
circle/file=fred.reg/disp    ! display the region file fred.reg
 
3 close_pg_window
close_pg_window - close the pgplot device
-----------------------------------------------------------------------
  close_pg_window
-----------------------------------------------------------------------
 
Close the current pgplot device.  Useful for closing a displayed image
or finishing a file.  When using a file-based device, such as a GIF or
Postscript file, the file remains open so that labels, scales, etc. may
be plotted.  The file is not ready to use in other programs while it
remains open.  If another image is displayed or XIMAGE is quit, the
file is automatically closed.  This command allows the user to force a
close, so that the file may be viewed or printed immediately.
 
4 Example
 
close_pg              ! close the current window
 
3 colors
colors - display and modify available colors
-----------------------------------------------------------------------
  colors[/qualifiers]
-----------------------------------------------------------------------
 
This command is used to display and modify colors available to use
with commands that have the `color` qualifier, such as in the `label`
command.  Standard colors range from 0 to 15 and they are reserved
colors. e.g. do not change based on the color table set with the `cct`
command.  These reserved colors may be changed by this command, using
the qualifier `/set` in conjunction with one of the following
qualifiers `/copycolor`, `/rgbcolor`, `/namecolor`, and `/swapcolor`.
Color indices greater than 15 are associated with the image color table
and cannot by modified on an individual basis.
 
 
4 /plot
colors/plot
 
Plot a color legend on an open device on the right side of the viewport.
 
4 /clear
colors/clear
 
Clear the color legend from open device, by drawing a box the same
color as the background color over it.
 
4 /reset
colors/reset
 
Reset standard colors back to their original values.
 
4 /setcolor
colors/setcolor=n
 
Set the color index to modify.  Valid values are 0 to 15.
This qualifier has effect only if used in conjunction with one
of the following qualifiers `/copycolor`, `/rgbcolor`, `/namecolor`,
and `/swapcolor`.
 
4 /copycolor
colors/copycolor=n
 
Set the color index to copy from.  Any defined color index is valid,
even those which correspond to image color table.  The `/plot` qualifier
shows the color index mappings for all available colors.
This qualifier has effect only if used in conjunction with `/set`.
 
4 /rgbcolor
colors/rgbcolor=r,g,b
 
Set RGB value to assign to `setcolor` with a comma-delimited list of
values in the range 0.0 to 1.0.
This qualifier has effect only if used in conjunction with `/set`.
 
4 /namecolor
colors/namecolor=[colorname]
 
The name of the color to assign to `setcolor`.  Color names are defined
through an rgb file specified through the PGPLOT_RGB variable.  If this
variable is not set, only black and white are supported.
This qualifier has effect only if used in conjunction with `/set`.
 
4 /swapcolor
colors/swapcolor=n
 
The color index with which to swap.  Valid values are 0 to 15.
This qualifier has effect only if used in conjunction with `/set`.
 
4 /null
colors/null=n
 
The color index used to draw null pixels.  By default, this is
set to the first color of the current color table, 16, usually black.
The current value is printed in the `show` command under "Null pixel
color."
 
4 Examples
color/set=0/swap=1       !  Swap the colors for index 0 and 1
color/set=0/name=black   !  Set color 0 to black
color/set=1/rgb=1,0.5,0  !  Set color 1 to orange
color/set=5/copy=25      !  Copy color 25 into color 5
 
3 contour
contour - display iso-intensity contour levels
-----------------------------------------------------------------------
  contour[/qualifiers] [mapid]
-----------------------------------------------------------------------
 
This command draws a contour plot. By default the contours are calculated
using an image histogram divided in 10 levels, but user can specify the
number of histogram levels with the qualifier `/no_of_cont_levels`.
The option `/first_contour_drawn` defines the first (lowest) level to
display and by default the lowest 5 levels are not displayed.
The contours can be calculated also using a linear, logarithmic or
square-root scale (qualifier `/linear`, `/log`, `/sqrt` respectively).
Arbitrary iso-intensity values can be input via a file in the
command `levels` and used within contour specifying `contours/loaded`.
It is recommended to smooth and/or rebin the image before calculating contours.
This command can be used to overlay contours over an image already plotted
onto the display.  If the contour's coordinates differ from the
underlying image, a transformation will be automatically calculated to
align the contours with the image.
 
4 /mapid
contour/mapid=[idstring]
 
Plot contours for a specified map. Without this qualifier, the current
map is plotted.
 
4 /linear
contour/linear
 
Contouring image with linear scale histogram
 
4 /log
contour/log
 
Contouring image with logarithmic histogram
 
4 /histo
contour/histo
 
Contouring image using histogram equalization to define levels. This is
the default option for command `contour`.
 
4 /sqrt
contour/sqrt
 
Contouring image with square root scaled histogram.
 
4 /loaded
contour/loaded
 
Contouring image with current levels.  Use `levels/show` to see
current levels.
 
4 /div_map
contour/div_map
 
Contours calculated on the map ratio obtained dividing the current image
by the saved image.
 
4 /div_saved
contour/div_saved
 
Contours calculated on the map ratio obtained dividing the saved image
by the current image.
 
4 /sub_map
contour/sub_map
 
Contours calculated on the image obtained from the current minus the saved
image. If the result is a negative number, it will reset it to zero.
 
4 /exposure_map
contour/exposure_map
 
Exposure map contours are plotted.
 
4 /saved_image
contour/saved_image
 
Saved image contours are plotted.
 
4 /correct_exposure
contour/correct_exposure
 
Contours calculated on the current map corrected by the exposure map.
 
4 /noframe
contour/noframe
 
The contours are plotted without axis label frame. This qualifier is
useful when the contours plot are overlayed (see `/overlay`) on a
pre-display image.
 
4 /nobox
contour/nobox
 
The contours are plotted without a bounding box. This qualifier is
useful when the contours plot are overlayed (see `/overlay`) on a
pre-display image. Nobox implies noframe.
 
4 /font
contour/font=[fontname]
 
Sets the font of the title and axis labels.  Use `font=?` to see
available fonts.
 
4 /csize
contour/csize=x
 
Sets the character size of the title and axis labels.  Standard
character size is 1.0.
 
4 /no_of_cont_levels
contour/no_of_cont_levels=nn
 
This defines the number of contour levels, nn, to be used.
 
4 /first_contour_drawn
contour/first_contour_drawn=nn
 
This defines the number of the lower contour used for display.
 
4 /color
contour/color=n
 
The color index to be used in plotting the contours.
 
4 /lwidth
contour/lwidth=n
 
The width of the contour lines.  Possible values range from thinnest of
1 up to 201.
 
4 /lstyle
contour/lstyle=n
 
The style of the contour lines: 1 (solid line), 2 (dashed), 3
(dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
 
4 /overlay
contour/overlay
 
The contour plot is overlayed to the pre-displayed image. The default
is that the contour plot is drawn on a new Pgplot page.
 
4 /nocoortrf
contour/nocoortrf
 
If the overlay qualifier is used to place a contour on top of an
image, the default behavior is to rotate, resize and recenter
the contour map to match the coordinates of the underlying image.
If, however, this behavior is not desired, the nocoortrf qualifier
can be used to plot the contour as it is with no transformation.
 
4 /left
contour/left
 
This qualifier plots the contour lines on the lefthand side of the
screen. Subsequent interactions with the Pgplot screen will act on the
lefthand side.  If a contour plot is already displayed on the righthand
side of the screen, a second contour plot can be displayed on the
lefthand side with the `/overlay` qualifier, which prevents Pgplot from
starting a new page.
 
4 /right
contour/right
 
This qualifier plots the contour lines on the righthand side of the
screen. Subsequent interactions with the Pgplot screen will act on the
righthand side.  If a contour plot is already displayed on the lefthand
side of the screen, a second contour plot can be displayed on the
righthand side with the `/overlay` qualifier, which prevents Pgplot from
starting a new page.
 
4 /v1/v2/v3/v4
contour/v1=x/v2=x/v3=x/v4=x
 
Specify the viewport where the contour plot is displayed.  Viewport
coordinates number the entire device from 0.0 at the left to 1.0 at the
right and 0.0 at the bottom to 1.0 at the top.  The parameter `/v1`
corresponds to the left side of the viewport, `/v2` to the right, `/v3`
to the bottom, and `/v4` to the top.  The `viewport` command may also
be used prior to plotting to set the viewport, however if these values
are set in this command, they will override the values set through the
`viewport` command.
 
4 /statistic
contour/statistic
 
Calculates contour levels based on background calculation.
If the background command has been executed, that background is used,
otherwise the background command is run automatically with no options.
Using this qualifier alone is equivalent to
`contour/statistic/sigma_levels="2 3 4 6 9 12 18 35 100"`
 
4 /background
contour/statistic/background=[value]
 
Set flat background value to use in levels calculation.  Note:
background is in units of cnts/image-pixel.
 
4 /mult_levels
contour/statistic/mult_levels=[levels list]
 
Calculates contour levels such that `cont_levels = mult_levels*background`
 
4 /sigma_levels
contour/statistic/sigma_levels=[levels list]
 
Calculates contour levels such that
`cont_levels = background + sigma_levels*sqrt(background)`
Note: if background is less than 20, a poisson upper limit
approximation is used.
 
4 Examples
 
contour/no_of_cont_levels=20/first_contour=4   ! generate a contour plot with
                                               ! 20 levels, and level 4 to
                                               ! level 20
 
contour/no_of=20/first=4/overlay/col=5         ! same as before but also
                                               ! overlay the contour on the
                                               ! previous image using color 5
 
contour/stat/sig={2 3 4 5 10}                  ! calculate and plot
                                               ! five contour levels
                                               ! based on sigma values
 
contour/map=3                                  ! Plot contour for MAP3
 
 
3 coord
coord - coordinate conversions
-----------------------------------------------------------------------
  coord[/qualifiers]
-----------------------------------------------------------------------
 
This command quietly performs coordinate conversions based on
the input qualifiers and saves results in Tcl array, coord.
Intended primarily for usage in scripts.
 
Output array:
---
 * $coord(system) - Sky coordinate system of original image (e.g. FK5, GALACTIC)
 * $coord(xsky), $coord(ysky) - Sky coordinates of original image
 * $coord(xsfmt), $coord(ysfmt) - Sky coordinates formatted for printing
 * $coord(xpix), $coord(ypix) - Detector coordinates
 * $coord(ximg), $coord(yimg) - Image coordinates
 * $coord(ra),$coord(dec) - Sky coordinates always expressed in RA/Dec
 * $coord(equinox) - Equinox of RA/Dec
 * $coord(lii),$coord(bii) - Galactic coordinates
 * $coord(value) - Pixel value at that point
---
 
4 /mapid
coord/mapid=[idstring]
 
Specify the map for which the coordinate conversion applies.
 
4 /cursor
coord/cursor
 
Select point to convert with mouse.
 
4 /xpix/ypix
coord/xpix=[value]/ypix=[value]
 
Specify point to convert in detector coordinates.
 
4 /xsky/ysky
coord/ysky=[value]/ysky=[value]
 
Specify point to convert in sky coordinates of original image.
Acceptable coordinate syntaxes include: ddd.ddd, dd:mm:ss.s, dd mm ss.s
 
4 /ra/dec
coord/ra=[value]/dec=[value]
 
Aliases for xsky/ysky.
 
4 /equinox
coord/equinox=[value]
 
Specify equinox of input sky coordinates.
 
4 /ximg/yimg
coord/ximg=[value]/yimg=[value]
 
Specify point to convert in image coordinates.
 
4 /Examples
coord/xpix=7000/ypix=8000  ! Sets coord array with detector
                           ! location in various coord systems
 
3 ccorr
ccorr - coordinate correction based guide sources
-----------------------------------------------------------------------
  ccorr[/qualifiers] [filename]
-----------------------------------------------------------------------
 
This command takes an RA and Dec list representing guide sources and
plots them on the existing image.  The user then interactively selects
(i.e. left-clicks)
a plotted source and its visual counterpart in the image, repeating this
at least three times with different sources.  Clicking the right mouse
button ends selections and a correction is made to the internal keywords
of the image based on the input.
 
It is recommended that a visual inspection of the image be made to
observe the general problem with the image coordinates.  For example,
all are shifted in a particular direction.  Then, a small number of key
guide sources distributed throughout the image with distinct image
counterparts should be chosen.  In order to improve precision, it is
possible to zoom the image in and out during the selection process
while using the /xtk device.  Pressing and holding the Shift key
at any time during the selection of sources
temporarily restores the usual behavior of the /xtk device
(i.e. right-click zooms in, middle-click recenters, and
left-click zooms out).  Once the desired guide source is in view,
click the left button on or near a plotted source. A line will be anchored
to the point.  Then, click the left button on the source in the image.
Repeat this for at least three sources, then click the right button
anywhere on the image to indicate that all selections have been made.
If at any point, a mistake is made, the center button can be used
to forget the last entered point.
 
4 /filename
ccorr/filename=[file location]
 
A text file containing RA and Dec of guide sources in the first and
second column, delimited by spaces.  For example, each line can be of
the form "ddd.ddd ddd.ddd" or "hh:mm:ss.s dd:mm:ss.s".
 
4 /ralist/declist
ccorr/ralist=[list]/declist=[list]
 
Instead of a file, RA and Dec of guide sources may be given as Tcl
lists.  The `rdarray` command may be used to read any file format into a
Tcl array of lists.
 
4 /norot
ccorr/norot
 
Restrict the fitting algorithm to keep the rotation fixed, allowing only
a translational correction.   By default, x and y offset as well as
rotation may be varied to perform the fit.
 
4 /disponly
ccorr/disponly
 
Plot the guide sources without doing the correction.  This useful for
plotting the new location of the guide sources after a correction has
been made.
 
4 /color
ccorr/color=n
 
Set the color used to draw the guide sources. The index of each color
can be found by plotting a color legend with the `colors` command.
 
4 /csize
ccorr/csize=x
 
Set the character size for the guide source label.  By default this is
set to 0, meaning that no label is printed.
 
4 /symbol
ccorr/symbol=n
 
Set the symbol style used to plot the guide sources.
 
4 /symcsize
ccorr/symcsize=x
 
Set the character size of the symbol used to plot the guide sources.
The default value is 0.9.  Values more than 2.0 will tend to be too large.
 
4 /symlwidth
ccorr/symlwidth=x
 
Set the line width of the symbol used to plot the guide sources.
The default value is 1.
 
4 /savefile
ccorr/savefile=[file location]
 
Write a file containing the source selections used in the correction
for later re-use with the `matchfile` qualifier.
 
4 /matchfile
ccorr/matchfile=[file location]
 
Read in a file written with the `savefile` qualifer, to re-execute
the same correction.
 
4 Examples
ccorr radec_list.txt                  !  Correct based on sources in file
ccorr/save=select.txt radec_list.txt  !  Save results of correction
ccorr/match=select.txt                !  Re-run prior correction
 
 
 
3 counts
counts - sum counts in a given area
-----------------------------------------------------------------------
  counts[/qualifiers] [regionfile]
-----------------------------------------------------------------------
 
This command sums counts in a given area. By default this area is a box
if selected via a cursor or defined by the qualifiers
`/xmin/xmax/ymin/ymax`. More complicated area can be specified using a
region file created via the `circle` or `box` commands.
The region file may be input with the `/regionfile` qualifier.
By default `counts` uses the cursor.
 
4 /regionfile
counts/regionfile=[filename]
 
Sum the counts within the area defined by a region file.
A region file may also be specified as the last argument of the command.
 
4 /xmin/xmax/ymin/ymax
counts/xmin=x/xmax=x/ymin=x/ymax=x
 
Sum the counts within the box defined by the minimum and
maximum x and y values in original detector coordinates.
 
4 /noplot
counts/noplot
 
By default the selected region is plotted on the screen.  This qualifier
turns off the plotting.
 
4 /color
counts/color=n
 
The color index to be used in plotting the counted region.
 
4 /lwidth
counts/lwidth=n
 
The width of the line used to draw the counted region.  Possible values
range from thinnest of 1 up to 201.
 
4 /lstyle
counts/lstyle=n
 
The style of the line used to draw the counted region: 1 (solid line),
2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
 
4 /Examples
counts                    ! Select box with cursor to sum
 
counts inner.reg          ! Sum counts in `inner.reg` region
 
3 cpd
cpd - change plot device
-----------------------------------------------------------------------
  cpd[/leaveopen] [device-name]
-----------------------------------------------------------------------
 
This command defines the device where all graphic output is directed.
cpd ? gives a list of all available devices.  The specified device
is preserved between ximage sessions.
 
4 /leaveopen
cpd/leaveopen
 
Leave /xtk device open when changing device.  Primarily for internal
use by the /xtk device's Print... option.
 
4 Examples
 
cpd /xw              ! change the current plot device to X-Windows
 
cpd test.ps/ps       ! direct the graphic output to the
                     ! postscript file test.ps
 
cpd /gif             ! direct the graphic output to the
                       GIF file pgplot.gif
 
3 crop
crop - crop image
-----------------------------------------------------------------------
  crop[/qualifiers]
-----------------------------------------------------------------------
 
This command creates a new image based on a portion of the existing image.
Cropping occurs only on existing pixel boundaries with no resampling.
 
4 /inmap
crop/inmap=[idstring]
 
Specify image map to crop.  The current map is used by default.
 
4 /outmap
crop/outmap=[idstring]
 
Specify where the cropped image is to be written.  If no outmap is
given, the inmap location is assumed and the original input map will
be overwritten.  If outmap is specified and differs from inmap, the original
input map will remain untouched and the cropped image will be written to
the outmap location.
 
4 /xpix/ypix
crop/xpix=[value]/ypix=[value]
 
Center the cropped area at xpix, ypix in original pixel coordinates.
Note: a size must also be specified.
 
4 /xsky/ysky
crop/xsky=[value]/ysky=[value]
 
Center the cropped area at xsky, ysky in the sky coordinates of the
original image.  Input must be in decimal format. Note: a size must
also be specified.
 
4 /ra/dec
crop/ra=[value]/dec=[value]
 
Alias for xsky, ysky, except the R.A. value can be specified
either as ra="hh mm ss" (hour minute and second) or ra=deg.ddd (in
degrees), the declination can be specified either as dec="deg mm ss"
or dec=deg.ddd (in degrees). Note: a size must also be specified.
 
4 /equinox
crop/equinox=n
 
Specify the equinox if the requested image center is given in
sky coordinates. By default the current XIMAGE equinox (defined with the
`cey` command) is assumed.
 
4 /size
crop/size=n
 
Specify the size of the cropped area in image pixels.
If an odd number is given for the size, size-1 will be used.
 
The value set through this qualifier is assumed for both the x and y
directions.  If a non-square image is desired, use the `/szx` and
`/szy` qualifiers.
 
4 /szx/szy
crop/szx=n/szy=n
 
These qualifiers are identical to the `/size` qualifier except they
specify the image size in the x and y direction independently.
 
4 /Examples
crop                       ! Select box with cursor to crop
 
crop/xp=256/yp=256/size=50 ! Crop image with center at 256,256 and
                           ! size 50x50
 
3 curve
curve - draw curve between two sky positions
-----------------------------------------------------------------------
  curve[/qualifiers]
-----------------------------------------------------------------------
 
This command draws the path of shortest distance (i.e. a geodesic curve)
between two sky positions.
 
4 /curve
curve/x1sky=[value]/y1sky=[value]/x2sky=[value]/y2sky=[value]
 
Specify the sky positions x1sky,y1sky and x2sky,y2sky to connect
with a geodesic curve.  The values must be given in decimal notation.
 
4 /color
curve/color=n
 
Set the color index for curve.
 
4 /lwidth
curve/lwidth=n
 
The width of the line used to draw the curve.  Possible
values range from thinnest of 1 up to 201.
 
4 /lstyle
curve/lstyle=n
 
The style of the line used to draw the curve: 1 (solid
line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5
(dash-dot-dot-dot).
 
3 detect
detect - source detection
-----------------------------------------------------------------------
  detect[/qualifiers]
-----------------------------------------------------------------------
 
Locates point sources in the current image using a sliding-cell method.
The average background intensity is estimated in several small square boxes
uniformly located within the image (see `background` command for a more
detailed description). The position and intensity of each detected source
are calculated in a box whose size maximizes the signal-to-noise ratio.
If the source is not pointlike the estimated count rate is in general
inaccurate and likely to be under-estimated. A good estimate of the
intensity of extended sources can be obtained with command `COUNTS`.
 
Corrections to the net counts are applied if the proper calibration information
are available for that instrument. The corrections applied are dead times,
vignetting and psf (the fraction of the source counts that fall outside the box
where the net counts are estimated).
Count rate errors include both statistical and systematic uncertainties added
quadratically. To minimize the number of spurious sources detected the
threshold used by `detect` is somewhat conservative. Consequently, some
sources with intensity just above the image background can be missed.
In order to allow `detect` to obtain a sufficiently good estimate of
the background only images of size 128x128 pixels or larger should be
used. Maximum accuracy is obtained running `detect` on full resolution
images.
 
The functionality of the detect command may also be accessed by
executing the `background`, `excess`, and `search` commands in
succession.  Running the process in pieces allows for finer control of
each step. For example, the background calculation may be tweaked, the
output of each step can be written out and/or read in, and the image
may be altered between steps.
 
4 /draw_rej_back_boxes
detect/draw_rej_back_boxes
 
This displays all background boxes which have NOT been used for the
estimation of the background. Different colors correspond to different
reasons for rejection.
 
4 /back_box_size
detect/back_box_size=m
 
Defines the size (in image pixels) of the boxes where the image
background is estimated. Recommended background box sizes are powers of
two, such as 16, 32, 64, and 128.
 
4 /flat_value
detect/flat_value=x
 
Set the background to a constant. By default the background is
calculating with the same method in the `background` command.
 
4 /source_box_size
detect/source_box_size=n
 
This defines the size (in original detector pixels) of the search cell.
The default value of the search cell size depends on the instrument PSF
and on the image pixel size. Try increasing it to reduce confusion.
 
4 /bright
detect/bright
 
Do not merge the excesses before optimizing the box centroid. This is
slower, but can be better for crowded fields and fields containing bright
sources.
 
4 /plot_excesses
detect/plot_excesses
 
Plot the excesses. This is a useful diagnostic if things go wrong.
 
4 /prob_limit
detect/prob_limit=x
 
Change the background probability limit from the default value
(`1E-04`).
 
4 /snr_threshold
detect/snr_threshold=x
 
Change the signal to noise acceptance threshold from its default value
of 2.
 
4 /thr_scaling
detect/thr_scaling=x
 
Scale the threshold for detecting source excesses. Try increasing it to
1.1 or 1.2 or 1.3 to reduce problems with fluctuations from extended
emission.
 
4 /nolabel
detect/nolabel
 
Omit the number label when plotting the detected source boxes.
 
4 /color
detect/color=n
 
Set the color index for the detected source boxes and labels.
 
4 /lwidth
detect/lwidth=n
 
The width of the line used to draw the detected source boxes.  Possible
values range from thinnest of 1 up to 201.
 
4 /lstyle
detect/lstyle=n
 
The style of the line used to draw the detected source boxes: 1 (solid
line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5
(dash-dot-dot-dot).
 
4 /font
detect/font=[fontname]
 
Sets the font of the detected source labels.  Use `font=?` to see
available fonts.
 
4 /filedet
detect/filedet=[filename]
 
Specify an output filename containing the detect results.
The default value is the input filename with extension `.det`.
The output file from detect is plain ascii.
 
4 /fitsdet
detect/fitsdet=[filename]
 
Specify an output FITS file containing the detect results.
By default no FITS file is written, only the ascii `.det` file.
If no extension is provided in the filename, `.fits` will be appended.
The detect results are written to a FITS table with the following column
names: SRCRATE, SRCRATE_ERR, X, Y, VIGNET, RA, DEC, ERRRAD, HBOXSIZE,
PROB, and SNR.
 
 
4 Examples
detect              ! Search for all point sources using the default values.
 
detect/source=10    ! Search for point sources using a search cell size of
                    ! 10 original pixels
 
detect/draw_rej     ! Draw the background boxes that have been rejected to
                    ! be drawn onto the image (if this has been displayed).
                    ! All other parameters are set to default values.
 
detect/back=32      ! Estimate the image background using boxes of size 32
                    ! image pixels. All other parameters are set to default
                    ! values.
 
3 display
display - display the current image
-----------------------------------------------------------------------
  display[/qualifiers] [mapid]
-----------------------------------------------------------------------
 
Display an image on the plotting device via PGPLOT. The default number
of colors used is 16, but this can be adjusted with the `levels/number`
command. A grayscale image is plotted if the plot device does not support
colors. To determine the color levels by default a histogram of the image
is calculated. Other scaling are linear (`/lin`), logarithmic (`/log`),
or  square-root (`/sqrt`). Several color tables are available via
the command `cct`.
Arbitrary images location can be defined via the `viewport` command, or
using the `/v1 /v2 /v3 /v4 `  qualifiers. To plot on the left or on the
right of the screen use the qualifiers `/left` and `/right`.
 
4 /mapid
display/mapid=[idstring]
 
Plot image for a specified map. Without this qualifier, the current
map is plotted.
 
4 /linear
display/linear
 
Display image with linear scale for color levels.
 
4 /log
display/log
 
Display image with logarithmic scale for color levels.
 
4 /histo
display/histo
 
Display image using histogram equalization to define color levels. This
is the default option for the `display` command.
 
4 /sqrt
display/sqrt
 
Display image with square root scaling for color levels.
 
4 /minlevel
display/minlevel=x
 
Sets the value of the lowest level.  Scaling begins after this value.
 
4 /maxlevel
display/maxlevel=x
 
Sets the value of the highest level.  Scaling ends before this value.
 
4 /loaded
display/loaded
 
Display image using current levels.  Use `levels/show` command
to see current levels.
 
4 /correct_exposure
display/correct_exposure
 
Display the image corrected for the exposure map.
 
4 /exposure_map
display/exposure_map
 
Display the exposure map.
 
4 /div_map
display/div_map
 
Display the current image divided by the saved image.
 
4 /div_saved
display/div_saved
 
Display the saved image divided by the current image.
 
4 /saved_image
display/saved_image
 
Display the saved image.
 
4 /sub_map
display/sub_map
 
Display the current image minus the saved image. Any pixels resulting
in a negative number will reset to zero.
 
4 /noframe
display/noframe
 
Suppress the display of the image's axis label frame.  Only the image
and title are displayed.
 
4 /nobox
display/nobox
 
Suppress the display of bounding box around the image.  Only the image
and title are displayed. Nobox implies noframe.
 
4 /font
display/font=[fontname]
 
Sets the font of the title and axis labels.  Use `font=?` to see
available fonts.
 
4 /csize
display/csize=x
 
Sets the character size of the title and axis labels.  Standard
character size is 1.0.
 
4 /overlay
display/overlay
 
This qualifier allow to have multiple images  plotted on the same
page. If an image has been previously displayed on one side of the
screen,e.g. left, specifying this qualifier in combination with
the opposite qualifier, e.g. `/right/overlay`, allows the images
to appear on the same page.  See `/left` and `/right` for usage.
Each execution of the `display` command starts a new Pgplot page
unless this qualifier is specified or a viewport configuration has been
set with the `viewport` command.
 
4 /left
display/left
 
This qualifier displays the image on the lefthand side of the screen.
Subsequent interactions with the Pgplot screen will act on the lefthand
side.  If an image is already displayed on the righthand side of the
screen, a second image can be displayed on the lefthand side with the
`/overlay` qualifier, which prevents Pgplot from starting a new page.
 
4 /right
display/right
 
This qualifier displays the image on the righthand side of the
screen. Subsequent interactions with the Pgplot screen will act on the
righthand side.  If an image is already displayed on the lefthand
side of the screen, a second image can be displayed on the
righthand side with the `/overlay` qualifier, which prevents Pgplot from
starting a new page.
 
4 /v1/v2/v3/v4
display/v1=x/v2=x/v3=x/v4=x
 
Specify the viewport where the image is displayed.  Viewport
coordinates number the entire device from 0.0 at the left to 1.0 at the
right and 0.0 at the bottom to 1.0 at the top.  The parameter `/v1`
corresponds to the left side of the viewport, `/v2` to the right, `/v3`
to the bottom, and `/v4` to the top.  The `viewport` command may also be
used prior to plotting to set the viewport, however if these values are
set in this command, they will override the values set through the
`viewport` command.
 
4 /spectrogram
display/spectrogram
 
Display images which contain spectra obtained at different time and
formatted as an image array. This option only affects the labeling of
the image frame.
 
4 Examples
 
disp               ! display an image with a histogram
 
disp/log           ! display an image with log scaling
 
disp/exp           ! display the exposure map
 
disp/lin           ! display with a linear scaling
 
disp/left          ! display an image on the left
disp/right/overlay ! display an image on the right, and keep the previous
                   ! image
 
disp/v1=0.317/v2=0.617/v3=0.4/v4=0.7 ! display into a specific area of the
                                     ! the screen
 
disp/map=3         ! display image for MAP3
 
3 draw
draw - draw shapes
-----------------------------------------------------------------------
  draw[/qualifiers] [shape parameters]
-----------------------------------------------------------------------
 
Draw shapes specified with detector coordinates on the
currently displayed plot.
 
4 /arrow
draw/arrow [x1] [y1] [x2] [y2]
 
Draw an arrow from (x1,y1) pointing to (x2,y2).
 
4 /oarrow
draw/oarrow [x1] [y1] [x2] [y2]
 
Draw an arrow with an outline arrowhead from (x1,y1) pointing to (x2,y2).
 
4 /circle
draw/circle [x] [y] [r]
 
Draw circle with center (x,y) and radius r in detector coordinates.
 
4 /box
draw/box [xcen] [ycen] [xwid] [ywid] [angle]
 
Draw box with center (xcen,ycen) and dimensions xwid by ywid in
detector coordinates, rotated by angle degrees.
 
4 /polygon
draw/polygon [x1] [y1] ... [xn] [yn]
 
Draw polygon by connecting points x1,y1 through xn,yn in detector
coordinates.  The last point also connects to the first point.
 
4 /line
draw/line [x1] [y1] ... [xn] [yn]
 
Draw line by connecting points x1,y1 through xn,yn in detector
coordinates.  Unlike polygon, the last point does not connect to
the first point.
 
4 /color
draw/color=[n]
 
Specify color index used to draw shape.
 
4 /lwidth
draw/lwidth=[n]
 
Specify line width used to draw shape.
 
4 /lstyle
draw/lstyle=[n]
 
Specify line style used to draw shape: 1 (solid line),
2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
 
4 Example
draw/circ 1000 1000 20      ! Draw circle centered at (1000,1000)
                            ! with radius of 20
 
3 excess
excess - find excesses
-----------------------------------------------------------------------
  excess[/qualifiers]
-----------------------------------------------------------------------
 
Searches the image for excesses. The excesses are found comparing
the counts in the search box with the background counts.
The `background` command needs to be run before using `excess`.
The commands, `background`, `excess`, and `search` run in succession
are functionally equivalent to executing the `detect` command.
 
4 /source_box_size
excess/source_box_size=n
 
This defines the size (in original detector pixels) of the search cell.
The default value of the search cell size depends on the instrument PSF
and on the image pixel size. Try increasing it to reduce confusion.
 
4 /bright
excess/bright
 
Do not merge the excesses before optimizing the box centroid. This is
slower, but can be better for crowded fields and fields containing bright
sources.
 
4 /plot_excesses
excess/plot_excesses
 
Plot the excesses. This is a useful diagnostic if things go wrong.
 
4 /thr_scaling
excess/thr_scaling=x
 
Scale the threshold for detecting source excesses. Try increasing it to
1.1 or 1.2 or 1.3 to reduce problems with fluctuations from extended
emission.
 
4 /outfile
excess/outfile=filename
 
The results of the excess command are saved as text into a file.
 
4 /infile
excess/infile=filename
 
The results of the excess command are read in from a text file
generated by using the outfile qualifier.
 
4 Example
back                ! Search for point sources using a search cell size of
excess/source=10    ! 10 original pixels
search
 
3 exit
exit - quit
 
Return to the operating system. A `$` can be used to spawn to the operating
system without losing the current session.
 
You can exit from XIMAGE also by typing `quit` or `bye`
 
3 extract
extract - extract a spectrum or lightcurve
-----------------------------------------------------------------------
extract[/qualifiers] [event_filename]
-----------------------------------------------------------------------
 
The `extract` command extracts a spectrum and/or a lightcurve
for the selected region or constructs a color-color diagrams for
detected sources from the `detect` or `search` command. This command
can be used only with event files.
 
A spectrum or a lightcurve can be extracted using the qualifiers
`/engfile` and `/qdpfile`, respectively, from a region given via the
qualifier `/regionfile`.  The region file can be created using saoimage
or from XIMAGE using the `circ` and `box` commands. If it is created
within XIMAGE the pixel values are those corresponding to the
unrebinned image.  If instead it is created within saoimage the pixel
values are those corresponding to a rebinned image. The region given to
the `extract` commands needs to be in original (unrebinned) pixels.
 
The spectra are ASCII files containing the number of events per
channel.  The lightcurves are also ASCII files. Both files can be
plotted via QDP and are mainly for internal usage.  The ASCII spectrum
is used internally to calculate the energy dependence of the psf via
the command `PSF`.  A direct way to get a spectrum and a lightcurve is
using XSELECT.
 
The extract command also calculates a set of hardness/softness ratios
for sources included in the previous run of detect. This is possible
using `extract/detect`.These color-color results are written in a
output file.
 
4 /c1/c2/c3/c4
extract/c1=n/c2=n/c3=n/c4=n
 
Specify the channels to be used to generate hardness and softness
ratios.  Hardness ratio is (c3-c4/c2-c3). Softness ratio is
(c1-c2/c2-c3).  Default values for channels are taken from the EXCHAN
keyword in the mission information database.
 
4 /detect
extract/detect
 
Use the positions from a previous run of detect and generate the
hardness and softness ratios for each source.
 
4 /colorfile
extract/detect/colorfile=[filename]
 
The name of the output file with the HR and SR data. The default is
the input filename.col. Use `/plot_color` to plot a color-color diagram.
 
4 /cl3file
extract/detect/cl3file=[filename]
 
The name of the output file with the HR and SR data. The default is the
input filename.cl3. Use `/plot_color` to plot a color-color diagram.
Same as colorfile, except it outputs the color-color results with
additional columns, which contain the mean channel for each of the
channel ranges.
 
4 /plot_color
extract/plot_color/detect
 
Plot a color-color diagram for all the detected sources.
 
4 /qdpfile
extract/qdpfile=[filename]
 
Extract a lightcurve and write to a file in QDP format.
 
4 /regionfile
extract/region=[filename]
 
Enter an SAOIMAGE style region file. If not specified the regionfile
name is equal to the events file .reg.
If filename begins with a `@` this cues the entered file to be
treated as a list of regionfiles which define sources
for which hardness and softness ratios will be generated.
 
4 /windowfile
extract/windowfile=[filename]
 
Enter a XRONOS style timing window file.
 
4 /eminqdp
extract/eminqdp=n
 
Specifies the minimum pha channels to use when constructing
a lightcurve (i.e. `/qdpfile`).
 
4 /emaxqdp
extract/emaxqdp=m
 
Specifies the maximum pha channels to use when constructing
a lightcurve (i.e. `/qdpfile`).
 
4 /variability
extract/variability
 
Calculate a statistical variability test for detected sources. Values
greater than 100 are probably variable.
 
4 /ecol
extract/ecol=[colname]
 
When making a color-color diagram it will default to use the PI (pulse
invariant) channel. The ecol qualifier will set the column name to use
instead.
 
4 /psf_pha
extract/psf_pha
 
The qualifier `/psf_pha` is obsolete. See `/engfile`.
 
4 /engfile
extract/engfile=[filename]
 
Extract a spectrum and write an ASCII pha file, which
can be used by the command `psf/engfile=`.
 
4 Examples
 
extract/reg=agn.reg rp200123.fits     ! Extract a spectrum from the rosat
                                      ! style fits file
 
extract/detect/plot                   ! plot a color-color diagram for
                                      ! all the detected sources
 
3 finding_chart
finding_chart - query STScI DSS for image
-----------------------------------------------------------------------
  finding_chart[/qualifiers]
-----------------------------------------------------------------------
 
Query online STSci Digitized Sky Survey for image centered on selected
point with a width in arcmin designated by `/field_width` (2 arcmin by
default).  The resulting image will be saved to a file named `st.fits`.
 
4 /cursor
finding_chart/cursor
 
Use cursor to select center of field.  By default the user is
interactively asked for the x and y of the center in original
detector pixels.
 
4 /field_width
finding_chart/field_width=x
 
The width of the field being queried in arcminutes.  By default the
value is 2.0 arcmin.
 
4 Example
 
find/field=5/cur   !  Return a 5 arcmin field centered at the
                   !  position selected with the mouse
 
3 flip
flip - flips image array
-----------------------------------------------------------------------
  flip[/qualifiers]
-----------------------------------------------------------------------
 
This command performs simple manipulations on the current image.
Unlike the `rotate` command, individual pixels are preserved, only
their order is changed.
 
4 /horizontal
flip/horizontal
 
Flips image horizontally, as if the image were rotated on an axis
positioned through the image's center going from top to bottom.
 
4 /vertical
flip/vertical
 
Flips image vertically, as if the image were rotated on an axis
positioned through the image's center going from left to right.
 
4 /+90
flip/+90
 
Rotates image by exactly 90 degrees in the clockwise direction, the
upper right corner becomes the lower right and the upper left becomes
the upper right.
 
4 /-90
flip/-90
 
Rotates image by exactly 90 degrees in the counterclockwise direction,
the upper right corner becomes the upper left and the upper left
becomes the lower left.
 
3 free_saved
free_saved - free the saved image
-----------------------------------------------------------------------
  free_saved
-----------------------------------------------------------------------
 
In tight memory situations, images saved with the `save_image` command
or the first image in an XIMAGE session, which is automatically saved,
can be freed with this command.
 
Note, `free_saved` actually runs `map free sav` The command is provided
mainly for backwards compatibility with existing scripts. If the `map`
command is used directly, the continued use of `free_saved` is not
recommended.
 
3 gencolor
gencolor - generate color image from event file
-----------------------------------------------------------------------
  gencolor[/qualifiers] [infile]
-----------------------------------------------------------------------
 
Takes event file, and based on the mission, extracts images for three
ranges of energy, representing red, green and blue.  Then, these images
are fed into the external program mkcolor, that generates an encoded
color image.  This image is read into ximage and displayed.
 
4 /infile
gencolor/infile=[file]
 
Sets the event file to be read in.  In `displayonly` mode,
however, this qualifier is used to set the encoded color image
to be read in for display.
 
4 /outfile
gencolor/outfile=[image file]
 
Sets the name of the encoded color output image, which is "gencolor.img" by
default.
 
4 /jpgfile
gencolor/jpgfile=[graphic file]
 
Sets the name of output jpg graphic file into which the color output image
is converted.  If a base of color encoding greater than 6 is selected,
jpgfile is automatically set to "gencolor.jpg".  If, however, this
qualifier is set by the user, a graphic file is generated with that name
regardless of the base setting.
 
4 /chanlist
gencolor/chanlist=[channel list]
 
If the default settings for a particular mission are not preferable,
the channel ranges may be set explicitly with this qualifier.  The
channel list takes the form: {rminch rmaxch gminch gmaxch bminch bmaxch}
 
4 /displayonly
gencolor/displayonly
 
If this qualifier is specified, an existing encoded color image is
displayed with the proper color table and levels.
 
4 /xpix/ypix
gencolor/xpix=[x]/ypi=[y]
 
Extract images centered on this x,y location in original pixel coordinates.
 
4 /ra/dec
gencolor/ra=[RA]/dec=[Dec]
 
Extract images centered on this location in sky coordinates.  The
values can be specified either as "hh mm ss"/"deg mm ss" or deg.ddd (in
degrees).  The current XIMAGE equinox is assumed.  The command `show`
lists the current XIMAGE equinox, and the command `cey` changes the
current XIMAGE equinox.
 
4 /size
gencolor/size=n
 
Extract images with the set size in pixels.  XIMAGE only deals in
images of even size.  If an odd number is given for the size, the next
highest even number is used.  If the size is given as a negative value,
then it defines the size of the image in arc minutes.  Be warned that
it will round this number to the closest even pixel.
 
The value set through this qualifier is assumed for both the x and y
directions.  If a non-square image is desired, use the `/szx` and
`/szy` qualifiers.
 
4 /szx/szy
gencolor/szx=[i]/szy=[j]
 
These qualifiers perform the same function as `/size`, except the
extracted image need not be square.
 
4 /rebin
gencolor/rebin=[n]
 
Extract images rebinned by a factor of n. n is 1 or a
multiple of 2 (the default is 1).
 
4 /ecol
gencolor/ecol=[column name]
 
Set the energy column to which `chanlist` refers.
 
4 /cutmode
gencolor/cutmode=[HIST|LINEAR|LOG|MAXCOL]
 
Set the method by which mkcolor uses to cut and scale the intensities.
If the cutmode is HISTogram, a histogram equalization is used to assign
intensity values.  If the cutmode is LINEAR, the values will be scaled
linearly from [rgb]min to [rgb]max.  If the cutmode is LOG, the values
will be scaled logarithmically from [rgb]min to [rgb]max. If a MAXCOL
cutmode is used, the maximum value for an individual pixel from the
three component images is used as the maximum intensity, and the other
two colors are scaled relative to the that maximum and [rgb]min.
 
4 /rmin/rmax
gencolor/rmin=[value]/rmax=[value]
 
Set the minimum and maximum value to use from the red image in the
final encoded color image.  The default values are the min and max
of the red image.
 
4 /gmin/gmax
gencolor/gmin=[value]/gmax=[value]
 
Set the minimum and maximum value to use from the green image in the
final encoded color image.  The default values are the min and max
of the green image.
 
4 /bmin/bmax
gencolor/bmin=[value]/bmax=[value]
 
Set the minimum and maximum value to use from the blue image in the
final encoded color image.  The default values are the min and max
of the blue image.
 
4 /base
gencolor/base=[n]
 
Base of color encoding.  For example, the default value of 6 assigns
the pixels in each component image (red, green, and blue) a value
from 0 to 5.  Recommended base values are 4 and 6 for displaying within
ximage, and 8 for generating a jpg file.
 
 
4 Examples
 
gencol/xpix=6000/ypix=6000  file.evt       ! center image on (6000,6000)
                                           ! generate and display in color
 
gencol/chan={10 40 41 90 91 202} file.evt  ! override default channels
 
3 grid
grid - overlay a sky coordinate grid
-----------------------------------------------------------------------
  grid[/qualifiers] [dalpha] [ddelta]
-----------------------------------------------------------------------
 
Draw a grid in the sky coordinates of the original image over the
displayed image. The default will plot a preassigned grid
spacing. This can be changed by specifying `dalpha` and `ddelta` in
degrees.  If the primary coordinate frame has been changed with the
'wcs/frameid=n' command, the grid will reflect the specified frame.
 
Note: The grid command is implemented using the Starlink AST library.
The default behavior of the grid command may be tweaked to a great
degree by setting the 'grid_astoptions' variable to a comma-delimited
list of AST options.  For example, the following forces the axis labelling
to inside the frame and plots the numeric labels in red (color index 2):
 
set grid_astoptions "Labelling=interior,Color(NumLab)=2"
 
For a full list see the Attributes section of the AST Plot documentation:
 
`http://www.starlink.ac.uk/~dsb/ast/sun211.htx/node553.html`
 
Ximage uses the following plot defaults:
Grid=1 Border=1 Edge(1)=top Edge(2)=right TextLab=0 DrawTitle=0
MinTickLen=0
 
4 /radec
grid/radec
 
Draw the grid in equatorial (R.A./Dec) coordinates.
 
4 /galactic
grid/galactic
 
Draw the grid in galactic coordinates.
 
4 /equinox
grid/equinox=[value]
 
Set the equinox of plotted coordinate system.
 
4 /abbrev
grid/abbrev
 
Abbreviate grid line labels to display only changing portions of the
coordinate.  For example, if the Declination of a field of view ranges
from 23 40'00" to 24 10'00", the degree position will only be written once
for each unique value (e.g. 23 40'00", 50'00", 24 00'00", 10'00").
 
4 /csize
grid/csize=x
 
Set the character size of the grid line labels displayed by this command.
Standard character size is 0.75.
 
4 /color
grid/color=n
 
Specify the color index to be used for the grid.
 
4 /lwidth
grid/lwidth=n
 
Specify the width of the lines used to draw the grid.
 
4 /lstyle
grid/lstyle=n
 
Specify the style of the lines used to draw the grid: 1 (solid line), 2
(dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
 
4 /ticks_only
grid/ticks_only
 
This will plot only tick marks on the frame of the image, corresponding
to `dalpha` and `ddelta.`  If not specified a full grid across the
image is plotted.
 
4 /labcolor
grid/labcolor=n
 
Specify the color index to be used for the numeric grid labels.
 
4 /nolabel
grid/nolabel
 
Turn off plotting of numeric grid labels, drawing only grid lines.
 
4 Examples
grid                          ! draw a grid with the default steps in
                              ! in celestial coordinates
 
grid 0.5 0.5                  ! draw a grid in 0.5 deg ra and dec steps
 
grid/gal                      ! draw a grid in galactic coordinates
 
3 header
header - display header summary
-------------------------------------------------------------------------
  header[/qualifiers]
-------------------------------------------------------------------------
 
Lists part of the header information in a pre-set format.  All header
information may be viewed through the `chheader` command.
 
4 /mapid
header/mapid=[string]
 
Selects the header to be displayed.  By default the mapid
is MAP, which corresponds to the header for the current image map.
EXMAP corresponds to the current exposure map, MAPSV to the saved map,
EXMAPSV to the saved exposure map, and BGMAP to the background map.
 
3 help
help - ximage help
-----------------------------------------------------------------------
  help  [command name]
-----------------------------------------------------------------------
 
Help will describe in detail each XIMAGE command. In help, type the
first few characters of the topic followed by `<cr>` to get info on
it.  Use `<cr>` to back up a level. `Ctrl-D` exits help.
 
4 Example
 
help detect           ! show detailed information about command `detect`
 
3 hotspot
hotspot - show position of EXOSAT CMA hot spot
-----------------------------------------------------------------------
 hotspot[/qualifiers]
-----------------------------------------------------------------------
 
Shows the position of the CMA hot spot on a pre-displayed image. This
command only works for EXOSAT LE-1 or LE-2 images that have not been
rotated. The qualifiers for `hotspot` merely affect the appearance of
the plotted symbol and label.  See the `label` command for details.
 
4 Example
hotspot            ! A small circle is drawn around the expected position
                   ! of the CMA hot spot.
 
3 iminfo
iminfo - text overlay
-----------------------------------------------------------------------
 iminfo[/qualifiers] [string]
-----------------------------------------------------------------------
 
Overlay information onto a pre-displayed image. In its default
mode `iminfo` includes image orientation, instrumentation name, exposure
time and image scale.  If only a string is given, that string will be
displayed in place of the `iminfo` command's text information.
 
4 /textonly
iminfo/textonly
 
Display only the default text information,
i.e. the instrumentation name, field name, and exposure time.
 
4 /scale
iminfo/scale
 
Display only the bar indicating the image scale, labeled with the sky
coordinate value it represents.
 
4 /compass
iminfo/compass
 
Display only the compass which indicates the image orientation.
 
4 /short
iminfo/short
 
Display the image orientation compass and the image scale.
 
4 /widscale
iminfo/widscale=x
 
Specify the width of the bar indicating the image scale in sky
coordinates.  Entered value is interpretted in arcmin.
 
4 /xpix
iminfo/xpix=x
 
Specify the x pixel location of where to write the information.
The x value must be given in original pixel coordinates.
 
4 /ypix
iminfo/ypix=x
 
Specify the y pixel location of where to write the information.
The y value must be given in original pixel coordinates.
 
4 /cursor
iminfo/cursor
 
Select the location where position the information on the display.
For `/scale`, `/compass`, and `short` the information will be plotted
centered at the selected point.  For `/textonly` and `string`,
the selected point corresponds to the left/bottom point of the
first line of text.
 
4 /color
iminfo/color=n
 
Set the color index used to draw the scale, compass, and text.
 
4 /csize
iminfo/csize=x
 
Set the character size of the text displayed by this command.
Standard character size is 1.0.
 
4 /lwidth
iminfo/lwidth=n
 
Set the width of the lines used to draw the scale, compass and text.
 
4 /font
iminfo/font=[fontname]
 
Set the font of the text displayed by this command.  Use `font=?` to see
available fonts.
 
4 Examples
 
iminfo                       ! write the default info
 
iminfo "text string"         ! write "text string" in upper left hand corner
 
iminfo/scale/cur             ! display an image scale centered on the
                             ! clicked point
 
3 label
label - write labels on the image
-----------------------------------------------------------------------
 label[/qualifiers] [text]
-----------------------------------------------------------------------
 
This command allows you to write labels anywhere on the display, with any size.
The `/xpix` and `/ypix` qualifiers give the label location in pixel coordinates
as labeled in the image frame, the `/vx=x/vy=x` qualifiers give the
label location in viewport coordinates, and the `/ra=x/dec=x` qualifiers
give the label location in sky coordinates.  If the label has spaces,
the `text` must be included in double quotes,  e.g.  "write this here".
A symbol can also be written using the `/symbol` qualifier.
 
4 /xpix/ypix
label/xpix=x/ypix=x
 
Define the location of the label in original pixel coordinates (i.e.
the coordinates that the image frame is labeled with).
 
4 /vx/vy
label/vx=x/vy=x
 
Define the location of the label in viewport coordinates, which number
the entire device from 0.0 at the left to 1.0 at the right and 0.0 at
the bottom to 1.0 at the top.
 
4 /ra/dec
label/ra=x/dec=x
 
Define the location of the label in sky coordinates.
 
4 /cursor
label/cursor
 
Define the label location as a point selected by the mouse.
 
4 /color
label/color=n
 
Set the color used to draw the label. The index of each color can be
found by plotting a color legend with the `colors` command.
 
4 /csize
label/csize=x
 
Set the character size for the label text.  Standard character size is 1.0.
 
4 /font
label/font=[fontname]
 
Set the font of the label text.  Use `font=?` to see available fonts.
 
4 /just
label/just=[left|center|right]
 
Set the justification of label text.  Possible values are left, right,
and center.
 
4 /angle
label/angle=x
 
Set the angle in degrees of the label text.  The standard orientation of
the text is at zero degrees.  Positive angle values rotate the text
counterclockwise.
 
4 /symbol
label/symbol=n
 
Plot a symbol on the screen. The value n defines different symbols.  The
center of the symbol is plotted at the given coordinate.
 
4 /symcolor
label/symcolor=n
 
Set the color index used to plot the symbol.
 
4 /symcsize
label/symcsize=x
 
Set the character size of the symbol from the default value of 1.0.
Values more than 2.0 will tend to be too large.
 
4 /symlwidth
label/symlwidth=n
 
Set the width of the lines used to draw the symbol.
 
4 /clip
label/clip
 
Turn on clipping, so labels outside viewport are not plotted.
 
4 /text
label/text=string
 
Set the label text.  If no symbol is given, the lower left corner
of the text will be plotted at the given coordinate.  In some cases
it may be necessary to use this qualifier to define the label text,
as there can be an ambiguity if the label matches a qualifier or
its abbreviation.
 
 
4 Examples
 
label/x=128/y=128 "<-- 4U 1822-37"      ! Write this label
 
label/x=128/y=128/text=X                ! Write ambiguous label
 
3 levels
levels - manipulate intensity levels
-----------------------------------------------------------------------
  levels[/qualifiers] [filename]
-----------------------------------------------------------------------
 
List and manipulate intensity levels. If no qualifiers are given, the levels
used to display last the current image are printed to the screen.
Note that the intensity levels are listed only after the `display` or `contour`
command have been used, since they are calculated by default within these
commands. User defined levels may be input using the qualifier `/file`
which is an ascii file containing one level per row.  The number of
levels is preserved between ximage sessions.
 
4 /number
levels/number=n
 
Set number of intensity levels to use when displaying images.
 
4 /reset
levels/reset
 
Reset number of intensity levels to default of 16.
 
4 /show
levels/show
 
List intensity levels for currently displayed image.  This is the
default action if no qualifiers are given.
 
4 /file
levels/file=[filename]
 
Specify a levels file for saving or loading.  A levels file may also be
specified as the last argument of the command.
This qualifier must be used in conjunction with the qualifiers `/save` or
`/load`.
 
4 /save
levels/save
 
Save current intensity levels to a file.
To be used with the qualifier `/file=[filename]`.
 
4 /load
levels/load
 
Load intensity levels from a file. To be used with the qualifier
`/file=[filename]`. These user defined levels are applied by the
`display` or `contour` commands using the syntax `display/loaded`
or `contour/loaded`.
 
4 /histo
levels/histo
 
Calculate levels based on histogram equalization.
 
4 /linear
levels/linear
 
Calculate levels based on linear scaling.
 
4 /log
levels/log
 
Calculate levels based on logarithmic scaling.
 
4 /sqrt
levels/sqrt
 
Calculate levels based on square-root scaling.
 
4 /minlevel
levels/minlevel=[value]
 
Set minimum level in levels calculation.
 
4 /maxlevel
levels/maxlevel=[value]
 
Set maximum level in levels calculation.
 
4 /list
levels/list=[levels list]
 
Set levels through use of list. Syntax example: "1 2 3 4" or {1 2 3 4}
 
4 Examples
 
levels/num=64             ! Set the number of intensity levels to 64 for
                          ! future images that are displayed
 
levels/load saved.lev     ! Load levels from file `saved.lev`
 
 
3 log
log - open a log file
-----------------------------------------------------------------------
  log [filename]
-----------------------------------------------------------------------
 
Write a log file containing the screen output generated by XIMAGE.
 
The option `filename` specifies the name of the log file; the file
extension is .log. If no filename is specified then the default of
ximage.log is used.
 
A log file will be closed if:
---
 * a new log file name is specified (this will open a new log file);
 
 * the filename is given as "none";
 
 * or XIMAGE is exited.
---
The log files are in plain ASCII text.
 
4 Example
 
log results              ! open a log file called results.log
 
 
3 map
map - manipulate image maps
-----------------------------------------------------------------------
  map[/qualifiers] [mapid]
-----------------------------------------------------------------------
 
If given no qualifiers or arguments, prints a description of the
currently loaded image maps to screen, including the filename,
size, rebinning factor, center, and codes which represent
map-altering operations performed in XIMAGE.  Also, the current map
and displayed map are indicated.
 
If a mapid with no qualifiers is given, the current map, the map
which commands operate on by default, is set to that mapid.
Note that the full id for a map is MAP1-9 for
image maps and EXMAP1-9 for associated exposure maps.  These
may be shortened to 1-9 and EX1-9, respectively.
 
4 /copy
map/copy [frommap] [tomap]
 
Copy the contents of [frommap] to the [tomap] position, overwriting
anything that may have been there.
 
4 /move
map/move [frommap] [tomap]
 
Move the contents of [frommap] to the [tomap] position, overwriting
anything that may have been there, and then freeing the memory occupied
by the original [frommap].
 
4 /free
map/free [mapid]
 
Free the memory occupied by [mapid].
 
4 /isequal
map/isequal [mapid] [mapid]
 
Returns 1 if mapids are equal, 0 otherwise.  Useful in Tcl scripting for
determining whether CUR (current map) and DIS (display map) are the same
map as MAP1, etc.  For example, in a Tcl if statement
`if [map isequal map1 dis] { do something }`
 
4 /gettmp
map/gettmp
 
Returns temporary mapid independent of slots MAP1 to MAP9.  Useful in
Tcl scripting when a mapid is needed, but the danger of overwriting
one of the existing map slots must be avoided.  For example,
`set newmap [map gettmp]` then perform some action with temporary map
and release it with `map free $newmap`.
 
4 Examples
 
map                          !  Lists the current status of all maps
map 3                        !  Sets the current map to MAP3
map/copy 1 2                 !  Copies MAP1 to MAP2
map/move 2 1                 !  Moves MAP2 to MAP1
map/free exmap3              !  Frees the memory occupied by EXMAP3
 
 
3 marith
marith - perform arithmetic with image maps
-----------------------------------------------------------------------
  marith[/qualifiers] [expression]
-----------------------------------------------------------------------
 
The marith command allows the user to perform arithmetic on stored
image maps.  Valid operations are `+`,`-`,`/`,`*`,`int()`, and
`float()`.  The `+`,`-`,`/`,`*` operators may have only two arguments,
one of which must be an image map, specified by the full id for an
image map (MAP1-9) or an associated exposure map (EXMAP1-9), and the
other argument may be a numeric constant or another map.  MAP1-9 may
not be shortened to 1-9 in the expression, as the parser has no way of
differentiating between an integer constant and a map shortened to its
numeric id.  The int and float functions may only take a map as an
argument.  Note that this command is currently limited to one
operation.
 
 
The results of the operation are stored in the current map.
Alternately, the output map may be stored in the map specified with
marith's `mapout` qualifier.  For example,
`marith/mapout=map3 map1+map2` behaves in the following arithmetic
sense: map3=map1+map2
 
 
The map output from marith will have an integer or float type depending
on the arguments and operations used to create it.  The `/` and
`float()` operations will always result in a float type.  The `int()`
operation will always result in an integer type.  The `+`, `-`, and
`*` operations will result in an integer type if both of their arguments
are integers, otherwise a float type will result.
 
 
When only one map is involved in an operation, all header information
is copied from that map into the output map.  The DATAMIN/MAX keywords
are updated after the map arithmetic is performed.  Consequently, the
coordinates of the output image are identical to the input map.  When
two image maps are involved, the first image map of an operation is
assumed as the output image map's header, unless overridden with the
hdrid qualifier.   Image maps with rotation, centering and/or size
different from the output image will be transformed to match its
coordinates. Note: In the transformation, a Monte Carlo distribution of
the pixel values is done. The total number of counts is preserved.
 
 
The user may also set explicit coordinates for the output image
independent of any existing header.  Use the crota qualifier for
rotation, which is specified in degrees and assumes the convention
where crota=0 when celestial north is up.  Use the ra, dec, and
(optionally) equinox qualifiers to specify the output image map's
center.
 
 
The output map inherits its size from the larger of the two
input maps.  The user may specify the desired output size with the size
qualifier, or if a nonsquare output image is desired, the szx and szy
qualifiers are available.
 
 
When summing images with associated exposure maps, their exposure maps
will also be combined.  Other operations between maps with associated
exposure maps will result in an output map with no exposure map.
 
 
4 /mapout
marith/mapout=[mapid]
 
Set the map location where the results of the operation should be
stored, overwriting anything that exists in that location.
 
4 /hdrid
marith/hdrid=[mapid]
 
Set the map whose header should be copied into the final image map,
inheriting the center, rotation, etc. of the indicated hdrid.  The
necessary offset, rotation, etc. will be applied to the maps to
yield an image with proper coordinates.
 
4 /expr
marith/expr=[expression]
 
Specify the mathematical expression used to calculate the resulting
image map.  Valid operations include: +,-,*,/,int(),float()
 
4 /crota
marith/crota=[value]
 
Specify the rotation of the resulting image map
 
4 /ra/dec/equinox
marith/ra=[value]/dec=[value]/equinox=[value]
 
Specify the center of the resulting image map in sky coordinates.
If equinox is not specified, the current equinox, defined by the cey
command, is used.
 
4 /size
marith/size=n
 
Specify the size of the resulting image map.
The value set through this qualifier is assumed for both the x and y
directions.  If a non-square image is desired, use the `/szx` and
`/szy` qualifiers.
 
4 /szx/szy
marith/szx=n/szy=m
 
Specify the size of the resulting image map, where the size in x
doesn't have to be the same as the size in y.
 
4 Examples
 
marith int(map2)              !  Truncate MAP2, store in current
marith/map=1 int(map1)        !  Truncate MAP1, overwriting itself
marith/map=3 map1+map2        !  Add MAP1 and MAP2, store in MAP3
marith/map=3/hdr=2 map1+map2  !  Same as above, except use MAP2 coords
 
3 moper
moper - perform mathematical operation between image maps
-----------------------------------------------------------------------
  moper[/qualifiers] [mapid] [mapid]
-----------------------------------------------------------------------
 
The moper command performs elementary operations between image maps
with no consideration for matching sky coordinates.  If two images are
operated on they must be of identical size.  This command is primarily
intended for internal use by marith.
 
4 /mapout
moper/mapout=[mapid]
 
Set the map location where the results of the operation should be
stored, overwriting anything that exists in that location.  If mapout
is not set, the output image will be written to the current map.
 
4 /hdrid
moper/hdrid=[mapid]
 
Set the map whose header should be copied into the final image map,
inheriting the center, rotation, etc. of the indicated hdrid.
By default, operations with one map argument copy the header from the
that map and operations with two map arguments copy the header from the
first map given.
 
4 /add
moper/add [arg1] [arg2]
 
Add images together. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
 
4 /sub
moper/sub [arg1] [arg2]
 
Substract images. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
 
4 /mult
moper/mult [arg1] [arg2]
 
Multiply images. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
 
4 /div
moper/div [arg1] [arg2]
 
Divide images. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
 
4 /int
moper/int [mapid]
 
Truncate values in image to integer value.
 
4 /float
moper/float [mapid]
 
Set values in image to float (i.e. real) values.
 
4 /procname
moper/procname=[name]
 
Define a Tcl proc to operate on each value in the image.  The proc must
take one argument (the original image value) and return the new image
value. For example:
 
-----------------------------------------------------------------------
proc negzero {value} {
   if { $value < 0. } { return 0. }
   return $value
}
-----------------------------------------------------------------------
 
The command `moper mopproc=negzero map1` will set all negative values in
map1 to zero.
 
 
3 offset
offset - calculate offset
-----------------------------------------------------------------------
  offset[/qualifiers]
-----------------------------------------------------------------------
 
Given two points in the current image, calculate the offset between
them in sky coordinates.
 
4 /cursor
offset/cursor
 
Specify two points by clicking the mouse on the current plot.
 
4 /ra1/dec1/ra2/dec2
offset/ra1=hms/dec1=dms/ra2=hms/dec2=dms
 
Specify the RA/Dec for two points as part of the command line.
The RA can be given as either decimal degrees or as hr, mn, sec.
In the latter case it must be included in double quotes
(e.g. /ra="12 23 12.1") The Dec can be given as either
decimal degrees or as degrees, minutes and seconds. In the latter case
it must be included in double quotes (e.g. /dec="50 31 10.1")
 
4 /x1pix/y1pix/x2pix/y2pix
offset/x1pix=x1/y1pix=y1/x2pix=x2/y2pix=y2
 
Specify the coordinates for two points in detector coordinates.
 
4 /plot
offset/plot
 
Plot both points.  By default, nothing is plotted.
 
4 /symbol
offset/symbol=n
 
Set the symbol used in plotting both points.
 
4 /csize
offset/csize=x
 
Set the character size of the symbol. Standard character size is 1.0.
 
4 /color
offset/color=n
 
Set the color used to plot the symbol.
 
4 /lwidth
offset/lwidth=n
 
Set the width of the lines used to draw the symbol.
 
4 Examples
 
off/cur                             ! Use the mouse to find the offset
off/x1=6270/y1=1973/x2=1112/y2=1985 ! Use x,ypix coords
 
 
3 pcontour
pcontour - core contour plotting
-----------------------------------------------------------------------
  pcontour[/qualifiers]
-----------------------------------------------------------------------
 
Core contour plotting routine.  Primarily for internal use by
contour.  See contour for description of following qualifiers:
csize, font, noframe, nobox, overlay, color, lwidth,
lstyle, first_contour_drawn
 
4 /nolabel
pcontour/nolabel
 
Turns off labelling of X/Y axis
 
4 /trf
pcontour/trf=[transformation matrix]
 
Transformation used to draw contours, so coordinates align with
underlying image in overlay case. Formatted as six element list
(e.g. {0 1 0 0 0 1} for no transformation).
 
4 /fromwcs
pcontour/fromwcs=[wcsid]
 
Transformation used to draw the contours assumes the starting
coordinates are those associated with the specified wcsid.
If not defined, the wcsid associated with the mapid being plotted
is used.
 
4 /towcs
pcontour/towcs=[wcsid]
 
Transformation used to draw the contours assumes the final
coordinates are those associated with the specified wcsid.
If not defined, the wcsid associated with the mapid being
overlayed on is used.
 
4 /refresh/xmin/xmax/ymin/ymax
pcontour/refresh/xmin=[n]/xmax=[n]/ymin=[n]/ymax=[n]
 
Plots contours for portion of map defined by array indices.
Primarily for internal use by the zooming and recentering
capabilities of /xtk device.
 
3 pimage
pimage - core image plotting
-----------------------------------------------------------------------
  pimage[/qualifiers]
-----------------------------------------------------------------------
 
Core image plotting routine.  Primarily for internal use by
display.  See display for description of following qualifiers:
csize, font, noframe, nobox, overlay, color, lwidth, lstyle
 
4 /nolabel
pimage/nolabel
 
Turns off labelling of X/Y axis
 
4 /refresh/xmin/xmax/ymin/ymax
pimage/refresh/xmin=[n]/xmax=[n]/ymin=[n]/ymax=[n]
 
Plots image for portion of map defined by array indices.
Primarily for internal use by the zooming and recentering
capabilities of /xtk device.
 
 
3 pixel_to_ra_dec
pixel_to_ra_dec - convert pixel to sky coordinates
-----------------------------------------------------------------------
  pixel_to_ra_dec[/qualifiers]
-----------------------------------------------------------------------
 
Converts a specified pixel position in the current image to RA and DEC.
If `/cur` is not specified, then XIMAGE will ask for X and Y pixel
coordinates.
 
4 /xpix
pixel_to_ra_dec/xpix=x
 
Specify the X coordinate of the pixel position
 
4 /ypix
pixel_to_ra_dec/ypix=x
 
Specify the Y coordinate of the pixel position
 
4 /cursor
pixel_to_ra_dec/cursor
 
The pixel position is specified using cursor.
 
4 /symbol
pixel_to_ra_dec/symbol=n
 
Set the symbol used to plot the position.
 
4 /color
pixel_to_ra_dec/color=n
 
Set the color used to draw the symbol.
 
4 /csize
pixel_to_ra_dec/csize=x
 
Set the character size of the symbol.
 
4 /lwidth
pixel_to_ra_dec/lwidth=n
 
Set the width of the lines used to draw the symbol.
 
4 Example
 
pixel_to_ra_dec/cur           ! Input the position using the cursor.
 
 
3 powplot
powplot - start POWplot viewer
-----------------------------------------------------------------------
  powplot[/qualifiers] [filename]
-----------------------------------------------------------------------
This command writes a temporary FITS file and spawns POWplot
to view it.
It is important to note that any region files written from POWplot will not
correct for any rebinning made within XIMAGE. The XIMAGE `circ` and
`box` commands do not suffer from this problem.
To read POWplot regions back into XIMAGE, the region values need to be
multiplied by the XIMAGE rebinning factor and the reference pixel value
as reported within XIMAGE needs to be added.
 
4 /filename
powplot/filename=[filename]
 
Set the name of the temporary file, which is `pow_temp.img` by default.
The temporary file may also be specified as the last argument of the
command.
 
4 /template
powplot/template=[templatename]
 
Set the template used to write header keywords.  Use `template=?` to
see available templates. The default is sufficient in most cases.
 
4 Example
 
powplot                 !  displays currently loaded image in POWplot
 
3 prarray
prarray - print Tcl array to screen or file
-----------------------------------------------------------------------
  prarray[/qualifiers] [array name]
-----------------------------------------------------------------------
 
This command prints the values contained in a Tcl array to the screen
or to a file.  A related command, `rdarray` exists for
reading text files into an array.
 
4 /varname
prarray/varname=[variable name]
 
Sets the variable name of the array that is to be printed.
 
4 /filename
prarray/filename=[file location]
 
Sets the output text file location.   The command will write
values to the screen by default, unless `filename` is set.
 
4 /noheader
prarray/noheader
 
By default the screen output lists the array name and the column names
above the column values, and file output lists the column names in a
command line preceded by a "#".  When this option is set, only the column
values are printed.
 
4 /comments
prarray/comments=[comment string]
 
The string specified with this qualifier will be printed to
file preceded by a "#" to indicate a comment. To specify multiple lines
insert a "\n" character in the comment string.
 
4 /order
prarray/order=[column list]
 
The order that the array values are printed out may be altered by
setting this option to a comma-delimited list of column names.
For example, suppose the array `inarray` contains a `dec` and `ra`
column.  In order to display `ra` before `dec`, use `order=ra,dec`.
To see what column names are available in the array, use the command
`array names inarray`.
 
4 /index
prarray/index
 
This qualifier may be used to print a column which doesn't exist in the
array, corresponding to the index number in the list.  Tcl uses a
0-index system, so it will begin with 0.
 
4 /iplus
prarray/iplus
 
This qualifier may be used to print a column which doesn't exist in the
array, corresponding to the index number plus one in the list.  Tcl uses a
0-index system, but in some cases one may want to start with 1 by using
the `iplus` option.
 
4 Examples
 
prarray/iplus inarray         ! Print `inarray` to the screen with numbers
prarray/file=out.txt inarray  ! Write `inarray` to the file out.txt
 
3 psf
psf - estimate the point spread function
-----------------------------------------------------------------------
  psf[/qualifiers]
-----------------------------------------------------------------------
 
Calculates differential and integral Point Spread Function and plots
them onto the currently defined graphic device. The expected PSF for a
pointlike source is also calculated and displayed. This command needs
an accurate estimate of the image background.  The `psf` command uses
as background value the results of the previously run `background`
command, but it can be overridden with the `/back` qualifier.
By default the command calculates counts within an annulus which is
incremented by one pixel per iteration.
 
4 /back
psf/back=x
 
Enter the image background in units of `cts/original-pixel`.
 
4 /energy
psf/energy=x
 
The expected PSFs for different detectors are derived in XIMAGE using,
when available, the 'theoretical' algorithms usually derived from
ground or inflight calibration data. Dependent on the detector
the expected PSF can be energy dependent.  This qualifier allows
to specify the  single 'interesting' energy value (in keV, the default
value is 1.0). The expected PSF is plotted together with the measured PSF.
 
4 /engfile
psf/engfile=[filename]
 
This qualifier may be used to input a spectrum to evaluate the energy
dependence of the psf, instead of a single value. The appropriate
file can be derived using `extract/engfile` for a specific regionfile.
The energy dependent psf is calculated only if XIMAGE has a valid
routine for that mission.
 
4 /expowgt
psf/expowgt
 
When this qualifier is given, the psf calculation will use the exposure map
to weight the psf function. The weights are calculated as the total
exposure contained with each psf annulus, normalized by the total exposure
contained within the given radius. If there is not a current exposure map
for the current image map, this is an error.
 
4 /pileup
psf/pileup
 
When this qualifier is given, the psf calculation assumes the center of
the source is piled-up.  The extent of the piled-up region is determined
by including all annuli that contain zero counts starting from the
center.  The next non-zero annulus is also included in the piled-up
region to account for the edge of the region.  The remainder of the
source is used to scale the theoretical psf for comparison with the
actual distribution.
 
4 /radius
psf/radius
 
Give the outer radius in arcminutes.
 
4 /box
psf/box
 
Use boxes, instead of annuli.  Concentric boxes are plotted on the image.
 
4 /cursor
psf/cursor
 
Enter the position of the centroid and outer radius using the cursor.
 
4 /xpix/ypix
psf/xpix=x/ypix=y
 
Specify the x and y coordinate for the center of the box position.
 
4 /calfilegen
psf/calfilegen
 
The `/calfilegen` qualifier is obsolete.  See `/multpsffile`.
 
4 /multpsffile
psf/multpsffile=[filename]
 
Write the psf to the specified file.  If the file already exists,
append the results as another column in the file.  This can be used as
'calibration' file within XIMAGE by setting PSFFILE in the mission
database for use by detect, sosta or even psf.
 
4 /fileplot
psf/fileplot=[filename]
 
Write the psf results to the specified ASCII file.  If not specified,
the result is written to `psf.qdp` by default.
 
4 /print
psf/print
 
Write to the screen the quantities calculated for each step.
 
4 /color
psf/color=n
 
Set the color used to plot the concentric boxes of the `/box` qualifier.
 
4 /lstyle
psf/lstyle=n
 
Set the line style used to plot the concentric boxes of the `/box`
qualifier: 1 (solid line), 2 (dashed), 3 (dot-dash-dot-dash), 4
(dotted), 5 (dash-dot-dot-dot).
 
4 /lwidth
psf/lwidth=n
 
Set the line width used to plot the concentric boxes of the `/box`
qualifier.
 
4 /noplot
psf/noplot
 
Suppress automatic plotting of psf in QDP, allowing for script-driven
sessions to continue without user intervention.
 
4 Examples
 
psf/cur/back=2.3e-03         ! calculate the psf for a position specified
                             ! by the cursor and setting the background.
psf/cur/back=2.3e-03/rad=6   ! calculate the psf for a 6 arc min rad
 
3 ra_dec_to_pixel
ra_dec_to_pixel - sky to detector coordinates
-----------------------------------------------------------------------
  ra_dec_to_pixel[/qualifiers]
-----------------------------------------------------------------------
 
Converts RA and Dec into the image pixel coordinates.
If the image is displayed, a crosshair symbol is drawn at the corresponding
position. Coordinates may be input via the qualifiers `/ra` and `/dec` or
by answering RA/Dec prompts. Input coordinates are assumed to be in the
current equinox set with the `cey` command.  The input ra, dec, and
equinox are saved between ximage sessions.  This saved position is
available as a default at the RA/Dec prompts.  Press return without
entering a value to accept the default.
 
4 /ra
ra_dec_to_pixel/ra=hms
 
Give the RA as part of the command line. The RA can be given as either
decimal degrees or as hr, mn, sec. Acceptable formats include:
12 23 12.1, 12:23:12.1, 12h23m12.1s In the space-delimited case the
value must be included in double quotes (e.g. ra="12 23 12.1")
 
4 /dec
ra_dec_to_pixel/dec=dms
 
Give the Dec as part of the command line. The Dec can be given as either
decimal degrees or as degrees, minutes and seconds.  Acceptable formats
include: 12 23 12.1, 12:23:12.1  In the space-delimited case the value
must be included in double quotes (e.g. dec="12 23 12.1")
 
4 /circle
ra_dec_to_pixel/circle=x
 
Draw a circle with a radius in arcsec around the given position. Useful
for drawing error circles.
 
4 /symbol
ra_dec_to_pixel/symbol=n
 
Set the symbol plotted at the centroid location.  The default value is
8, a circle with crosshairs.
 
4 /csize
ra_dec_to_pixel/csize=x
 
Set the character size of the symbol. Standard character size is 1.0.
 
4 /color
ra_dec_to_pixel/color=n
 
Set the color used to plot the symbol or circle.
 
4 /lwidth
ra_dec_to_pixel/lwidth=n
 
Set the width of the lines used to draw the symbol or circle.
 
4 /lstyle
ra_dec_to_pixel/lstyle=n
 
The style of the line used to draw the circle: 1 (solid
line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5
(dash-dot-dot-dot).
 
4 Examples
 
ra                                 ! Enter the RA and Dec from a prompt
ra/circle=600.0                    ! Draw a 600 arc sec radius circle centered
                                   ! at the given ra and dec
ra/dec="-61 12 1.0"/ra="11 45 2.1" ! Give the RA and Dec on the command line
 
3 rdarray
rdarray - read text file into Tcl array
-----------------------------------------------------------------------
  rdarray[/qualifiers] [filename]
-----------------------------------------------------------------------
 
This command reads a text file containing columns of values into a Tcl
array.  Text files can come in many formats, so the command is
flexible to support them.  A related command, `prarray` exists for
writing arrays to screen or back to a file.
 
4 /filename
rdarray/filename=[file location]
 
Sets the input text file location.  The file must contain columns of
values, using a consistent delimiter.  The number of values in each
column must be equal.  Lines beginning with "#" or "!" are interpretted
as comments.
 
4 /varname
rdarray/varname=[variable name]
 
Sets the variable name of the array that the file is read into.
By default, this is set to `inarray`.
 
4 /delim
rdarray/delim=[character]
 
Sets the delimiter used to parse each line of the text file.  Quoting
the character is recommended (e.g. `delim="|"`)  By default, whitespace
is used as the delimiter.
 
4 /readhead
rdarray/readhead
 
If set, the first non-comment line will be used as the column names.
 
If the text file looks like this:
----------------------------------------------------------------------
|name          |ra         |dec        |pmag |
|GSC 1800-01800|03 46 54.36|+24 06 43.2|14.01|
|GSC 1800-01684|03 46 58.92|+24 05 21.3|11.67|
|GSC 1800-02109|03 47 02.50|+24 09 00.0|14.30|
|GSC 1800-01790|03 46 56.80|+24 08 57.8|13.50|
----------------------------------------------------------------------
 
The array is created:
----------------------------------------------------------------------
$inarray(name) => {{GSC 1800-01800} {GSC 1800-01684} {GSC 1800-02109}
                  {GSC 1800-01790}}
$inarray(ra)   => {{03 46 54.36} {03 46 58.92} {03 47 02.50} {03 46 56.80}}
$inarray(dec)  => {{+24 06 43.2} {+24 05 21.3} {+24 09 00.0} {+24 08 57.8}}
$inarray(pmag) => {14.01 11.67 14.30 13.50}
----------------------------------------------------------------------
 
If `readhead` is not set and `headers` is not used to define column
names, numbers beginning with 1 through the number of columns will be
used as the column names.
 
4 /headers
rdarray/headers=[header list]
 
If column names are not in the text file, they may be assigned with this
qualifier by giving a comma-delimited list of values  (e.g.
`headers=name,ra,dec,pmag`).  If `headers` is not used and `readhead` is
not set, numbers beginning with 1 through the number of columns will be
used as the column names.
 
4 /columns
rdarray/columns=[column list]
 
This qualifier may be used to limit the columns which are actually saved
in the array by giving a comma-delimited list of column names.
In the `readhead` example, if only RA and Dec values are desired, use
`columns=ra,dec`.
 
4 /expr
rdarray/expr=[regular expression]
 
Sets a regular expression used to match every line of the text file.
If `matchlist` is not set the effective behavior is to ignore every line
that matches the expression.  For example, a file may use a % as the
first character of a comment line.  In that case expr="^%" would match
all lines beginning with a percent sign and ignore them.  A regular
expression may also have submatches saved if `matchlist` is set.  See
`matchlist` for details.
 
4 /matchlist
rdarray/matchlist=[variable list]
 
If the regular expression set with `expr` contains sub-expressions
surrounded by parentheses, each sub-expression in order will be assigned
to variables given in the `matchlist`.  For example, given the following
file:
----------------------------------------------------------------------
DATE: May 23, 2002
name          ,ra         ,dec        ,pmag
GSC 1800-01800,03 46 54.36,+24 06 43.2,14.01
GSC 1800-01684,03 46 58.92,+24 05 21.3,11.67
GSC 1800-02109,03 47 02.50,+24 09 00.0,14.30
GSC 1800-01790,03 46 56.80,+24 08 57.8,13.50
----------------------------------------------------------------------
 
The following command:
----------------------------------------------------------------------
rdarray delim="," readhead {expr=^DATE: ([a-zA-Z]+) ([0-9]+), ([0-9]+)}
        matchlist=month,day,year
----------------------------------------------------------------------
will assign `May` to the month variable, `23`
to the day variable and `2002` to the year variable.  Note: The use of
square brackets in the expression can be misinterpretted as Tcl command
evaluations if the entire qualifier is not surrounded by curly brackets.
If more than one line matches the expression, the matching will be
appended to the variables making them lists of values.
 
4 /sublist
rdarray/sublist=[list of expr/substitution pairs]
 
The `sublist` option may be used to alter the lines of the text file
before delimiter-based processing occurs.  The list must have an even
number of elements, the first contains the expression to match and the
second contains the substitution, the third contains the next
expression and the fourth contains the corresponding substitution and
so on.  For example, suppose the text file contains a special string
corresponding to a null value, `NULL` or `INDEF`, and for your purposes `0`
is more appropriate.  The following command would perform the
substitution:  `rdarray {sublist={INDEF|NULL} {0}} file.txt`  Note, when
specifying lists, enclosing the entire qualifier in curly brackets may
be necessary.  The syntax, `rdarray sublist=[list {INDEF|NULL} {0}]`
will also work.
 
 
If the expression contains sub-expressions surrounded
by parentheses, the substitution may contain references to those
sub-matches in the form of a backslash followed by the sub-match number.
For example, suppose the file contains RA and Dec as
follows:
----------------------------------------------------------------------
00 47 10.984   -11 53 18.92
00 47 09.153   -11 52 52.70
00 46 58.055   -11 50 36.60
00 47 00.064   -11 52 49.89
00 46 56.044   -11 54 32.13
----------------------------------------------------------------------
The default behavior is to give each number its own column, clearly not
the desired result.  The `sublist` option can help you merge these based
on a pattern:
----------------------------------------------------------------------
rdarray {sub={([+-]*[0-9]+) ([0-5][0-9]) ([0-5][0-9]\.[0-9]+)} {\1:\2:\3}}
        file.txt
----------------------------------------------------------------------
The parser will then see:
----------------------------------------------------------------------
00:47:10.984   -11:53:18.92
00:47:09.153   -11:52:52.70
00:46:58.055   -11:50:36.60
00:47:00.064   -11:52:49.89
00:46:56.044   -11:54:32.13
----------------------------------------------------------------------
A colon has been inserted between the numbers making up the coordinates,
grouping them together.
 
4 Example
rdarray var=src file.txt  ! Read space-delimited file into `src` variable
 
3 read_image
read_image - read an image or events files
-----------------------------------------------------------------------
  read_image[/qualifiers] [filename]
-----------------------------------------------------------------------
 
Read an image into the current map.  If no file type is specified,
a FITS file is assumed, and various checks are made to identify it as
either an image or event file.  The only non-FITS type supported is
EXOSAT, a binary machine-dependent format indicated by the `/exosat`
qualifier.
 
Whether specified with the `file` qualifier or as an argument
to the command, any FITS file given as a filename may use the
extended filename syntax briefly described on this page:
 
`http://heasarc.gsfc.nasa.gov/docs/software/fitsio/filters.html`
 
A common usage, for example, is to filter out events with certain
energies, filename.evt[EVENTS][PHA > 5].  The Tcl environment
used by ximage, however, interprets square brackets [] as commands
within commands.  In order to prevent expansion by Tcl, use curly
braces to quote the filename.  For example,
`read {filename.evt[EVENTS][PHA > 5]}`
 
4 /mapid
read/mapid=[idstring]
 
Read image into specified map.  Without this qualifier, the default
is to read into current map.
 
4 /exposure_map
read/exposure_map
 
The `/exposure_map` qualifier indicates the image contains an exposure
map and loads it into the exposure map arrays. It can be displayed
using the `disp/exp` command.
 
4 /exosat
read/exosat
 
File is an image in EXOSAT format. This is machine specific.
 
4 /fits
read/fits
 
File is an image in FITS format.
 
4 /rfits
read/rfits
 
File is in FITS photon event format.
 
4 /xpix
read/xpix=x
 
Load an image centered on this x location in original pixel coordinates.
Requires the `/ypix` qualifier to also be set.
 
4 /ypix
read/ypix=x
 
Load an image centered on this y location in original pixel coordinates.
Requires the `/xpix` qualifier to also be set.
 
4 /ra
read/ra=[value]
 
Load an image centered on the specified RA. The value can be specified
either as ra="hh mm ss" (hour minute and second) or ra=deg.ddd (in
degrees).  The current XIMAGE equinox is assumed, unless the `/equinox`
qualifier is set. The command `show` lists the current XIMAGE equinox,
and the command `cey` changes the current XIMAGE equinox.
 
4 /dec
read/dec=[value]
 
Load an image centered on the specified Dec. The value can be specified
either as dec="deg mm ss" or dec=deg.ddd (in degrees).  The current
XIMAGE equinox is assumed, unless the `/equinox` qualifier is set. The
command `show` list the current XIMAGE equinox, and the command `cey`
change the current XIMAGE equinox).
 
4 /equinox
read/equinox=n
 
To specify the equinox if the requested image center is given using
`/ra` and `/dec`. By default the current XIMAGE equinox is assumed.
 
4 /size
read/size=n
 
This qualifier specifies the image size in pixels. XIMAGE only deals in
images of even size.  If an odd number is given for the size, the next
highest even number is used.  If the size is given as a negative value,
then it defines the size of the image in arc minutes.  This is useful
when overlaying or comparing two images. Be warned that it will round
this number to the closest even pixel.
 
When a fits image is read in and no size is specified, the size of
the image (NAXIS1/2) is used.  By default, however, a fits image
is limited to 1024x1024.  This default limit can be changed by setting
the 'read_image_limitsize' variable.  A value of zero is interpretted
as setting no limit for the image size.  For example, if
`set read_image_limitsize 0` is entered in the ~/.ximagerc file,
a 2048x2048 fits image will be read into ximage in its entirety.
 
The value set through this qualifier is assumed for both the x and y
directions.  If a non-square image is desired, use the `/szx` and
`/szy` qualifiers.
 
4 /szx
read/szx=n
 
This qualifier is identical to the `/size` qualifier except it
specifies the image size in the x direction.  Use with `/szy` to define
the image size.
 
4 /szy
read/szy=n
 
This qualifier is identical to the `/size` qualifier except it
specifies the image size in the y direction.  Use with `/szx` to define
the image size.
 
4 /rebin
read/rebin=n
 
As the image is read into memory it is rebinned by n bins. n is usually
1 or a multiple of 2 (the default is 1).  If the input file is an event
list, it is possible to use float values.
For example, `rebin=0.5` divides each original pixel in
half in each dimension, redistributing the events among
the new sub-pixels. If an event falls exactly on a horizonal pixel
boundary, it will be counted in the pixel above.  If it falls on a
vertical pixel boundary, it will be counted in the pixel to the right
of the event coordinate.
 
If used in conjunction with the 'exposure_map' option, the rebinned
pixels are averaged rather than summed.
 
4 /bscale
read/bscale=x
 
Apply a scaling to the read in image.
 
4 /bzero
read/bzero=x
 
Add an offset to the read in image.
 
4 /detector
read/detector
 
Allow to accumulate an image using the content of the DETX, DETY columns.
 
4 /expr
read/expr=[expression]
 
A boolean expression used to filter rows in an event file.  Every event
for which the expression is false will be excluded.  The expressions are
identical to the row-filtering mechanism provided by FTOOLS through
CFITSIO.  Run the ftool `fhelp rowfilter` for documentation.
 
4 /xcol
read/xcol=[column_name]
 
Accumulate an image using the column specified by this qualifier for the
x coordinate.
 
4 /ycol
read/ycol=[column_name]
 
Accumulate an image using the column specified by this qualifier for the
y coordinate.
 
4 /zcol
read/zcol=[column_name]
 
Accumulate an image by piling the value in the `zcol` column for
each event onto the pixel it falls in.  When `/zcol` is not specified
the default is to simply add one to a pixel for each event which falls
in it.
 
4 /ecol
read/ecol=[column_name]
 
Set name of energy column to read in.  Generally used in association
with the `/emin` and `/emax` qualifiers.  For most known missions there
is already a defined energy column.  In those cases, this qualifier will
override the value set in the mission information database.
 
4 /emin
read/emin=n
 
The minimum energy channel to accept from the energy column defined in
the mission info database or through the `/ecol` qualifier.
 
4 /emax
read/emax=n
 
The maximum energy channel to accept from the energy column defined in
the mission info database or through the `/ecol` qualifier.
 
4 /tcol
read/tcol=[column_name]
 
Set name of time column to read in.  Generally used in association
with the `/tmin` and `/tmax` qualifiers.  The default is TIME, but
this qualifier will override that value.
 
4 /tmin
read/tmin=x
 
The minimum time accepted.  The time value should be given in the same
format used in the time column of the fits file.
 
4 /tmax
read/tmax=x
 
The maximum time accepted.  The time value should be given in the same
format used in the time column of the fits file.
 
4 /gtiext
read/gtiext=[gtiext]
 
When reading a FITS event file, the default is to use the first
extension with a name containing 'GTI' to filter events. The
treatment of the GTI extensions within the event file being read can
be specified with this option.  Possible expressions include an
extension number (e.g. 3), extension name (e.g. GTI1), extension name
pattern (e.g. GTI*), or any of these combined with an OR/AND function
(e.g.  OR(GTI1,GTI2) ).  If an OR/AND function is specified, and the
expression matches multiple extensions (e.g. AND(GTI*) matches
GTI1,GTI2,GTI3) all matching extensions will be combined together.
Otherwise, only the first matching extension will be used as a filter
on the events.
 
An extension name pattern can contain any of the
following wildcards: '*' will match any sequence of characters
(including zero characters), '?' will match any single character, and
'#' will match one or more contiguous digits.
 
In some cases, there are mission-specific default settings (see
'chmdb' command) for GTIEXT.  If this option is set, these defaults
are overridden.
 
4 /gtifile
read/gtifile=[gtifile]
 
The GTI extension contained in the file specified by this qualifier
constrain which time intervals events must fall in to be accepted.
If `/gtimode` is not specified, the GTIs specified by the `/gtifile`
qualifier substitute for the GTIs in the event file being read.  An explicit
extension number may be specified.  For example, fitsfile.fits[2] or
fitsfile.fits+2 are both valid methods.
 
Multiple GTI files may be combined using an AND/OR function either
with a comma-delimited list of files (e.g. AND(a.gti,b.gti) ) or by
providing a text file listing all the files using the '@' syntax (e.g.
OR(@gtifile.list) ).
 
4 /gtimode
read/gtimode=[and|or|sub|none]
 
This qualifier determines how the GTI extension(s) of the read in event
file, determined by the `/gtiext` qualifier, interacts with the GTIs
specified through the `/gtifile` qualifier. The `and` mode logically
ands the intervals together, resulting in a set of intervals such that
only the times where both sets have good times are present.  The `or`
mode logically ors the intervals together, resulting in a set of
intervals such that the times where either set has a good
time is represented.  The `sub` mode substitutes the `/gtifile`
intervals, throwing out the ones in the file being read.  The `none`
mode ignores all GTI constraints, effectively assuming all events fall
in a good time.
 
4 /image_number
read/image_number=n
 
Specify which image of a 3D cube to read.  Each integer, from 1 to the
depth of the cube represents a separate 2D slice of the data.  If this
is not specified, the top slice of a cube (n=1) will be read in.
 
4 /file
read/file=filename
 
Allow to specify the filename of the image or event list using a qualifier
instead of specifying the filename on the command line.
 
4 /regionfile
read/regionfile=filename
 
Specify a spatial region file.  The circle or box region file can be
created using the command `circle` and/or `box`.  If no size and
centering is specified, the bounds of the region will be used.
Prior to version 4.2 the region bounds had no effect on size and
centering.  To restore that behavior, enter the line
`set read_image_regcenoff 1` in the ~/.ximagerc file.
 
4 /time_image
read/time_image
 
The `/time_image` qualifier generates a time variability map by
calculating the time chi-square distribution in a pixel.  Chi-square
values are stored in each pixel scaled from 0-200, values greater than
100 mean the source is probably variable.  It's important to make sure
there are a sufficient number of photons per bin, by heavily rebinning
the image. To use this option the event file must be time ordered.
 
4 /color_image
read/color_image
 
The `/color_image` qualifier generates a color weighted image by using
the PI or a PHA column in an event list. In each pixel the energy
information is summed and weighted by the number of photons.  The
resulting image is scaled from 0-100.
 
4 /unknown
read/unknown
 
Treat image as from an unknown mission, ignoring any mission-specific
settings.  For example, the original pixel coordinates will be unknown
and XIMAGE will have to display straight image coordinates.
 
4 Examples
 
read/size=512/xpix=6000/ypix=6000        ! center image on (6000,6000)
                                         ! with an image size of 512x512
 
read/xcol=dx/ycol=dy                     ! use `dx` and `dy` columns
                                         ! to construct image
 
read/ecol=pi/emin=24/emax=224            ! exclude events where `pi`
                                         ! column is outside 24-224
 
3 rebin
rebin - rebin the current image
-----------------------------------------------------------------------
   rebin[/qualifiers] factor
-----------------------------------------------------------------------
 
The current image is rebinned by the number of bins specified by the
`factor` parameter.  The `/mode` parameter can be used to apply some
slight smoothing, or do rebinning for mosaics.
 
4 /mode
rebin/mode=n
 
If n=0, the new pixel values are obtained by averaging pixels involved
in the rebinning (e.g. rebin=2, 4 pixels).  The image and pixel size
remains the same.  If n=1, which is the default, "normal" rebinning is
done.  The image and pixel size change by the rebinning factor.  If
n=2, the pixel size changes, but the image size remains the same,
shrinking the image in the frame.  This mode is useful for image
mosaics.
 
------------------------------------------------------------------------
                 mode =0  rebinning with slight smoothing
                 mode =1  normal rebinning, the default
                 mode =2  rebinning for image mosaics
------------------------------------------------------------------------
 
4 /rebinning_fact
rebin/rebinning_fact=m
 
Used to specify the rebinning factor. The command `rebin/reb=2`
is equivalent to `rebin 2`.  Note: The rebin factor must be an integer
value.  Use the `remap` command if a non-integer rebin is desired.
 
4 Example
 
rebin 8             ! rebin the image by a factor of 8
 
3 recall
recall - recall past command
-----------------------------------------------------------------------
  recall[/qualifiers] [n]
-----------------------------------------------------------------------
 
The command `recall` is used to list previous commands.  The global
Tcl variable, htyshow, determines the default number of commands to
list.  Initially this is set to 20, however it may be redefined by
the user.  Any command can be reexecuted by typing `recall n` where n
is the command number given in the listing.
 
The history of commands is preserved between sessions of Ximage by
storing them in a file at '~/ximage.hty'.  The name of this file can
be changed by setting the 'ximage_history_file' variable in
'~/.ximagerc'.  No history file is written if this variable is set to
an empty string.  For example:
 
set ximage_history_file ""
 
4 /max
recall/max
 
Specify the maximum number of commands to list.  Note, this number
only applies to the current command listing.  If `max` is not specified,
the value set in the Tcl global variable htyshow is always used.
 
4 Examples
 
recall/max=100             ! display last 100 commands
 
recall 242                 ! run command number 242
 
3 remap
remap - remap image to new coordinates
-----------------------------------------------------------------------
  remap[/qualifiers]
-----------------------------------------------------------------------
 
The remap command maps an existing image to new coordinate system,
distributing (or resampling) the original pixels into the new pixel
grid.
 
The default resampling method is CONSERVE, which redistributes the
values in the original image pixels based on the fractional area
intersecting the new pixel, conserving the total value.  Integer values
are redistributed using probabilities to preserve Poissionian
characteristics.  This pixel resampling method is the most rigorous and
hence the slowest by a large margin.
 
The remaining pixel resampling methods are directly implemented in the
Starlink AST library (method descriptions excerpted from astResample
docs).  Note: The `params` qualifier is a list of
parameters that may be used to tweak the operation of some remap methods.
See the description of each method for the definition of `params` in
that context.
 
NEAREST: The value of the input pixel with the nearest center to the
interpolation point is used. This is very quick to execute and will
preserve single-pixel features in the data, but may displace them by up
to half their width along each dimension. It often gives a good cosmetic
result, so is useful for quick-look processing, but is unsuitable if
accurate geometrical transformation is required.
 
LINEAR: Uses linear interpolation between the nearest neighboring pixels
in the input grid. It is superior to the nearest-pixel scheme (above) in
not displacing features in the data, yet it still executes fairly rapidly.
It cannot introduce oscillations, however, it does introduce some spatial
smoothing which varies according to the distance of the interpolation
point from the neighboring pixels. This can degrade the shape of sharp
features in the data in a position-dependent way.
 
BLOCKAVE: Takes an average of all the pixels on the input grid in a
cube centered on the interpolation point. The number of pixels in the
cube is determined by the value of `params`,
which gives the number of pixels in each dimension on either side
of the central point. Hence a block of (2 * params) pixels in each
dimension of the input grid will be examined to determine the value
of the output pixel.  This scheme is suitable where the output grid
is much coarser than the input grid; if the ratio of pixel sizes is R
then a suitable value of `params` may be R/2.
 
The remaining pixel resampling methods are based on a 1-dimensional
interpolation kernel.  The `params` qualifier may be given a single value
(e.g. `params=1`) or two values in a Tcl list (e.g. `params={1 1}`).
The first or only value should be used to specify how many pixels are
to contribute to the interpolated result on either side of the
interpolation point in each dimension (the nearest integer value is
used). Execution time increases rapidly with this number. Typically,
a value of 2 is appropriate and the minimum value used will be 1
(i.e. two pixels altogether, one on either side of the interpolation
point). A value of zero or less may be given to indicate that a
suitable number of pixels should be calculated automatically.  If a list
is given, the second value has a definition which varies based on the
resampling method (see below).  If no `params` value is defined, zero is
assumed for all parameters.
 
SINC: Uses a sinc(pi*x) kernel, where x is the pixel offset from the
interpolation point and sinc(z)=sin(z)/z. In practice it is not useful
for astronomical data.  It is merely provided for completeness.
 
SINCSINC: Uses an improved kernel, of the form sinc(pi*x).sinc(k*pi*x),
with k a constant, out to the point where sinc(k*pi*x) goes to zero, and
zero beyond. The second sinc() factor provides an "envelope" which
gradually rolls off the normal sinc(pi*x) kernel at large offsets. The
width of this envelope is specified by giving the number of pixels
offset at which it goes to zero by means of the second value in the
`params` list, which should be at least 1.0 (in addition, setting
the first value in the `params` list to zero will select the number of
contributing pixels so as to utilize the full width of the kernel, out
to where it reaches zero). The case given by `params={2 2}` is typically
a good choice and is sometimes known as the Lanczos kernel. This is a
valuable general-purpose interpolation scheme, intermediate in its
visual effect on images between the NEAREST and LINEAR schemes. Although
the kernel is slightly oscillatory, ringing is adequately suppressed if
the data are well sampled.
 
SINCCOS: Uses a kernel of the form sinc(pi*x).cos(k*pi*x),
with k a constant, out to the point where cos(k*pi*x) goes to zero, and
zero beyond. As above, the cos() factor provides an envelope which
gradually rolls off the sinc() kernel at large offsets. The width of
this envelope is specified by giving the number of pixels offset at
which it goes to zero by means of the second value in the `params` list,
which should be at least 1.0 (in addition, setting the first value in
the `params` list to zero will select the number of contributing pixels
so as to utilize the full width of the kernel, out to where it reaches zero).
This scheme gives similar results to the SINCSINC scheme, which it
resembles.
 
SINCGAUSS: Uses a kernel of the form sinc(pi*x).exp(-k*x*x),
with k a positive constant. Here, the sinc() kernel is rolled off using
a Gaussian envelope which is specified by giving its full-width at
half-maximum (FWHM) by means of the second value of the `params` list,
which should be at least 0.1 (in addition, setting the first value of
the `params` list  to zero will select the number of contributing pixels
so as to utilize the width of the kernel out to where the envelope declines
to 1% of its maximum value). On astronomical images, good results are
often obtained by approximately matching the FWHM of the envelope function,
given by the second value of the `params` list, to the point spread function
of the input data. However, there does not seem to be any theoretical
reason for this.
 
4 /method/params
remap/method=[name]/params=[value(s)]
 
Method and parameter definitions are detailed in command description
above.  Set `method=?` to list available remap methods.
The default remap method and params may be altered from
their usual values (i.e. method=CONSERVE with no params) by setting the
Tcl variables `remap_method` and `remap_params`.  For example,
running `set remap_method SINCSINC; set remap_params {2 2}` before using
remap or inserting these commands in the ~/.ximagerc will set the
default to the Lanczos kernel mentioned above.
 
4 /inmap
remap/inmap=[idstring]
 
Specify input map to be remapped.  The default value is the current map.
 
4 /outmap
remap/outmap=[idstring]
 
Specify where to save the resulting map.  The default behavior is to use
the inmap value, overwriting the input map.
 
4 /coorid
remap/coorid=[idstring]
 
Specify the coordinates to remap into.  If a mapid is given, the wcsid
associated with the map will be used.  A wcsid may also be given.
 
4 /rotangle
remap/rotangle=[value]
 
Rotate the image grid of the input map about the center by the given
number of degrees.  The resulting image will effectively be rotated
in a counter-clockwise direction for positive values.
 
4 /xsky/ysky
remap/xsky=[value]/ysky=[value]
 
Specify the center of the remapped image in sky coordinates of the
original image.
 
4 /ra/dec
remap/ra=[value]/dec=[value]
 
Aliases for xsky/ysky, except they will also accept "hh mm ss.sss" and
"dd mm ss.sss" formats.
 
4 /equinox
remap/equinox=[value]
 
Specify the equinox if the remapped image center is given in
sky coordinates. By default the current XIMAGE equinox (defined with the
`cey` command) is assumed.
 
4 /size
remap/size=n
 
Specify the size of the remapped image.  The value set through this
qualifier is assumed for both the x and y directions.  If a non-square
image is desired, use the `/szx` and `/szy` qualifiers.
 
4 /szx/szy
remap/szx=n/szy=n
 
These qualifiers are identical to the `/size` qualifier except they
specify the image size in the x and y direction independently.
 
4 /rebin
remap/rebin=[value]
 
Rebin the original image by the given factor.  The rebin factor may be a
real or integer value.  For example, `rebin=0.5` divides each pixel in
half in each dimension, redistributing the pixel values amoung the new
sub-pixels.
 
4 Examples
 
remap/coor=sav             ! Remap current map to the coordinates
                           ! of the saved map
 
remap/xp=128/yp=128/out=2  ! Recenter map at 128,128 saving result in MAP2
 
3 remove_sources
remove_sources - remove sources
-----------------------------------------------------------------------
  remove_sources[/qualifiers]
-----------------------------------------------------------------------
 
This can be used to remove sources or unwanted features from the image
(such as hot spots or events caused by cosmic rays).
The area to remove may be defined via the cursor or by a region file
or through the `x/y_min/max` qualifiers. All the sources found with
`detect` or `search` may be removed using the special qualifier `/detect`.
By default `remove` calculates a standard background and replaces the
removed area with this value. A more customized background value
can be estimated using the `background` command and its qualifier
prior running `remove`. The output of `background` is automatically used
by `remove`.
Alternatively the pixels in the removed area may be replaced with a
constant value set through the `/constant` qualifier.
 
4 /cursor
remove/cursor
 
Specify the area to be removed by clicking the two opposite corners of
a rectangular box.
 
4 /nsources
remove/nsources=n
 
Loop through the removal process n times.  This option is only useful
with the `/cursor` qualifier.
 
4 /xmin/xmax/ymin/ymax
remove/xmin=x/xmax=x/ymin=x/ymax=x
 
Remove the box defined by the minimum and maximum x and y values in
original detector coordinates.
 
4 /detect_sources
remove/detect_sources
 
Remove all the sources found in the last run of the `detect` or
`search` commands.
 
4 /regionfile
remove/regionfile=[filename]
 
Remove area defined in a region file.
 
4 /constant
remove/constant=x
 
Replace the removed regions with a constant value, rather than the
average value from the `background` command.  A special null value
may be specified with the usage `remove/const=null`.
 
4 Examples
 
remove/cursor/nsources=5   ! remove 5 regions defined by the cursor
 
remove/detect              ! remove the sources found by detect
 
3 rescale
rescale - rescale the current image
-----------------------------------------------------------------------
  rescale[/qualifiers]
-----------------------------------------------------------------------
 
Rescale multiply, add or divide the current image for either a constant
value or a vector.
The vector can be input as an ascii file, containing one or more columns,
where each column has the same number of elements in the x or y directions
of the image.
 
4 /multiply
rescale/multiply
 
Specifies that the scaling factors is multiplicative. The value of
each pixels in the current image are multiplied by a constant or a
vector.  This is the default scaling method.
 
4 /divide
rescale/divide
 
Specifies that the scaling factor is used to divide each pixel of the
image by a constant or a vector.
 
4 /add
rescale/add
 
Specifies that the scaling is additive. A constant is added to the value
of the pixels in the current image.  This option may not be used in
conjunction with `/file_vector`.
 
4 /scaling_factor
rescale/scaling_factor=x
 
Set the scaling factor to constant value.
 
4 /to_exposure
rescale/to_exposure=x
 
Set scaling factor to be x/exposure where the exposure is taken from the
header of the current image (i.e. scaling_factor = to_exposure/image
exposure time) and applied to the image using one of the arithmetic
qualifiers. The qualifier `/scaling_factor` has not effect is `/to_exposure`
is in use.
 
4 /file_vector
rescale/file_vector=[filename]
 
Perform rescaling by using vector from a file. If the file contain
multiple columns the qualifier `/column` set the column number
to use. The qualifiers `/x_direction` or `/y_direction`
define which direction is used to perform the vector arithmetic.
 
4 /column
rescale/column=n
 
Set the column number to use from the `/file_vector` file as the
rescaling vector.
 
4 /x_direction
rescale/x_direction
 
Perform the vector arithmetic in the x direction.
 
4 /y_direction
rescale/y_direction
 
Perform the vector arithmetic in the y direction.
 
4 /min_fraction
rescale/min_fraction=x
 
Minimum fraction to use in rescaling image.  Only applicable
when dividing by a vector.  If the reciprocal of the vector value is
less than `/min_fraction`, pixels in that position are zeroed out.
 
4 Examples
 
rescale/scal=10                ! every pixel value in the current image
                               ! is multiplied by a factor 10.
 
rescale/add/scal=25            ! 25 is added to every pixel value
                               ! in the current image.
 
rescale/file=slice.cut/col=2/x ! multiply the values in the 2nd
                               ! column of slice.cut along the
                               ! x direction of the image
 
3 resize
resize - change the pixels size of the current image
-----------------------------------------------------------------------
  resize/[qualifiers]
-----------------------------------------------------------------------
 
This command allows to size the pixel up to a maximum of twice the original
value. This is useful when two images from different detectors need to be
summed but the pixel scale for the two images is different.
 
4 /pixel_size
resize/pixel_size=x
 
Specify the value of the new pixel size in arcseconds.
 
4 Examples
 
resize/pixel_size=10           ! the pixel size will be change from the
                               ! original value to 10 arcsecs.
 
3 restore_image
restore_image - restore the saved image
-----------------------------------------------------------------------
  restore_image
-----------------------------------------------------------------------
 
Copy the saved image to the current image, along with its associated
exposure map.  The first image in an XIMAGE session is automatically
saved.  The current image can be saved with the `save_image` command.  In
tight memory situations, saved images can be freed with the `free_saved`
command.
 
Note, `restore_image` actually runs `map copy sav cur` The command is
provided mainly for backwards compatibility with existing scripts. If
the `map` command is used directly, the continued use of `save_image`
and `restore_image` is not recommended.
 
 
4 Example
 
restore_image                  ! restore the saved image
 
3 rotate
rotate - rotate the current image
-----------------------------------------------------------------------
  rotate[/qualifiers]
-----------------------------------------------------------------------
 
This routine properly rotates sparse arrays such as X-ray images. In
order to preserve the poissonian nature of the background a Monte Carlo
redistribution of some events is carried out. The total number of
photons is strictly conserved. This operation is however
`irreversible`, that is, a rotation of +x degrees, followed by a
rotation of -x degrees will produce an image that although closely
resembles the original one, it is not identical. For this reason it is
advisable to keep to a minimum the number of rotations performed on one
image.
 
4 /roll_angle
rotate/roll_angle=dms
 
This qualifier can be used to specify the roll angle at which to rotate
the image. The default angle is -90, corresponding to North up and East
to the left.  Angle may be entered as degrees or in "dd mm ss.s"
format.
 
4 Example
 
rotate/roll_angle=-20.1           ! Rotates the current image to a roll
                                  ! angle of -20.1 degrees
 
3 saoimage
saoimage - Start the SAOIMAGE display package
-----------------------------------------------------------------------
  saoimage[/qualifiers] [filename]
-----------------------------------------------------------------------
 
SAOIMAGE is a general image display program developed by Michael
VanHilst at the Smithsonian Astrophysical Observatory.  This command
writes a temporary FITS file and spawns SAOIMAGE to view it.  It is
important to note that any region files written from SAOIMAGE will not
correct for any rebinning made within XIMAGE. The XIMAGE `circ` and
`box` commands do not suffer from this problem.
To read saoimage regions back into XIMAGE, the region values need to be
multiplied by the XIMAGE rebinning factor and the reference pixel value
as reported within XIMAGE needs to be added.
 
4 /filename
saoimage/filename=[filename]
 
Set the name of the temporary file, which is `sao_temp.img` by default.
The temporary file may also be specified as the last argument of the
command.
 
4 /template
saoimage/template=[templatename]
 
Set the template used to write header keywords.  Use `template=?` to
see available templates. The default is sufficient in most cases.
 
4 Example
 
saoimage                 !  displays currently loaded image in saoimage
 
 
3 save_image
save_image - save the current image in memory
-----------------------------------------------------------------------
  save_image
-----------------------------------------------------------------------
 
Copy the current image and exposure map to a save area in memory. They
are restored using the `restore_image` command. The first image opened
in an XIMAGE session is automatically saved.  In tight memory
situations, saved images can be freed with the `free_saved` command.
 
Note, `save_image` actually runs `map copy cur sav` The command is
provided mainly for backwards compatibility with existing scripts. If
the `map` command is used directly, the continued use of `save_image`
and `restore_image` is not recommended.
 
4 Example
 
save_image                   ! save the current image and exposure map
 
3 scale
scale - plot color scale
-----------------------------------------------------------------------
  scale[/qualifiers]
-----------------------------------------------------------------------
Each color in a displayed image corresponds to an intensity level.  This
command plots a color scale, which shows the relationship between them.
For a complete list of intensity levels, use the `levels/show` command.
 
4 /no_of_divisions
scale/no_of_divisions=n
 
Set the number of divisions to divide up the scale for labeling.
 
4 /top
scale/top
 
Plot scale along top of image.
 
4 /bottom
scale/bottom
 
Plot scale along bottom of image, which is the default.
 
4 /left
scale/left
 
Plot scale along left side of image.
 
4 /right
scale/right
 
Plot scale along right side of image.
 
4 /vertical
scale/vertical
 
Force the scale be plotted in the vertical direction of the screen.
Identical to `/right` qualifier.  Kept for backwards compatibility.
 
4 /thickness
scale/thickness=x
 
Thickness of color scale measured in units of the current character
size.  For example, 1.0 corresponds to the height of an 'h' or 't' as
currently set.  Default is 0.7.
 
4 /margin
scale/margin=x
 
Distance between image edge and nearest edge of color scale measured in
units of the current character size.
 
4 /spacing
scale/spacing=x
 
Spacing between intensity level text and scale itself measured in units
of the current character size.  Default is 0.5.
 
4 /lwidth
scale/lwidth=n
 
The width of the lines surrounding and dividing the scale.  Possible
values range from thinnest of 1 up to 201.
 
4 /csize
scale/csize=x
 
Sets the character size of the scale labels.  Standard character size
is 1.0.
 
4 /font
scale/font=[fontname]
 
Sets the font of the scale labels.  Use `font=?` to see available fonts.
 
4 /label
scale/label=[string]
 
Write a string to label the color scale.
 
4 /curvp
scale/curvp
 
This qualifier only has an effect if a viewport configuration is being
used.  The default is to plot the scale with respect to all the
viewports in the configuration as a whole.  If this qualifier is
specified, the labeling is done with respect to only the current
viewport.
 
4 Examples
 
scale             ! display the color scale at the image's bottom
scale/right       ! display the color scale along the image's right side
 
3 screengrab
screengrab - capture /xtk plot
-----------------------------------------------------------------------
  screengrab[/qualifiers] [outfile]
-----------------------------------------------------------------------
 
Capture the current plot shown in the /xtk device.  Used by the /xtk
device's Screen Grab... option, although it may be used to automate
screen grabs with the `/convert` qualifier.
 
4 /xv
screengrab/xv
 
Performs screen capture of /xtk plot, then crops with xv.  Graphic
must be saved from xv.  Note: pgplot.xwd is created.
 
4 /display
screengrab/display
 
Performs screen capture of /xtk plot, then crops with ImageMagick
display.  Graphic must be saved from display.  Note: pgplot.xwd
is created.
 
4 /convert
screengrab/convert
 
Performs screen capture of /xtk plot, then crops with ImageMagick
convert.  Saved as pgplot.gif by default.  Note: pgplot.xwd is removed.
 
4 /outfile
screengrab/convert/outfile=[filename]
 
Specifies the filename for ImageMagick convert to write.  Convert
uses the filename's extension to determine the final graphic format
that is output.
 
4 Examples
 
screengrab/xv                ! Grabs and crops in xv
screengrab/convert grab.jpg  ! Grabs and crops with convert to jpg
 
 
3 script
script - write a command script
-----------------------------------------------------------------------
 script [filename]
-----------------------------------------------------------------------
 
Open a script file where all XIMAGE commands are written. This command is
useful to create macros including a set of commands that have to be
executed several times. The option `filename` specifies name of the file;
the file extension is .xco. If no filename is specified then the default of
ximage.xco is used.
 
A script file will be closed if:
---
 * a new file name is specified (this will open a new file);
 
 * the filename is given as `none`;
 
 * or ximage is exited.
---
The script files are in plain ASCII text. Running the program
`ximage @filename` will startup XIMAGE and execute all the
commands stored in the file `filename.xco`.
 
4 Example
 
script filename             ! all commands subsequently executed are stored
                            ! in a file called `filename.xco`
 
3 search
search - slide-cell search
-----------------------------------------------------------------------
  search[/qualifiers]
-----------------------------------------------------------------------
 
This command is the final step in a process which
locates point sources in the current image using a sliding-cell method.
The commands `background` and `excess` must be run before `search`.
The commands, `background`, `excess`, and `search` run in succession
are functionally equivalent to executing the `detect` command.
 
In this process the average background intensity is estimated in
several small square boxes uniformly located within the image through
the `background` command.  Sliding boxes across the image are accepted
as excesses if their probability of not being background is above a
certain threshold in the `excess` command.  The position and intensity
of each detected source are calculated in a box whose size maximizes
the signal-to-noise ratio in the `search` command.  If the source is
not pointlike the estimated count rate is in general inaccurate and
likely to be under-estimated. A good estimate of the intensity of
extended sources can be obtained with command `COUNTS`.
 
Corrections to the net counts are applied if the proper calibration
information are available for that instrument. The corrections are
dead times, vignetting and psf (the fraction of the source counts that
fall outside the box where the net counts are estimated).  Count rate
errors include both statistical and systematic uncertainties added
quadratically. To minimize the number of spurious sources detected the
threshold used by `search` is somewhat conservative. Consequently, some
sources with intensity just above the image background can be missed.
In order to allow `background` to obtain a sufficiently good estimate
of the background only images of size 128x128 pixels or larger should
be used. Maximum accuracy is obtained running
`background/excess/search` on full resolution images.
 
4 /prob_limit
search/prob_limit=x
 
Change the background probability limit from the default value
(`1E-04`).
 
4 /snr_threshold
search/snr_threshold=x
 
Change the signal to noise acceptance threshold from its default value
of 2.
 
4 /nolabel
search/nolabel
 
Omit the number label when plotting the detected source boxes.
 
4 /color
search/color=n
 
Set the color index for the detected source boxes and labels.
 
4 /lwidth
search/lwidth=n
 
The width of the line used to draw the detected source boxes.  Possible
values range from thinnest of 1 up to 201.
 
4 /lstyle
search/lstyle=n
 
The style of the line used to draw the detected source boxes: 1 (solid
line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5
(dash-dot-dot-dot).
 
4 /font
search/font=[fontname]
 
Sets the font of the detected source labels.  Use `font=?` to see
available fonts.
 
4 /filedet
search/filedet=[filename]
 
To specify an output filename which contains the detected source
results.  The default value is the input filename with extension
`.det`.  The output file from search is plain ascii.
 
4 /fitsdet
detect/fitsdet=[filename]
 
Specify an output FITS file containing the detected source results.
By default no FITS file is written, only the ascii `.det` file.
If no extension is provided in the filename, `.fits` will be appended.
The detect results are written to a FITS table with the following column
names: SRCRATE, SRCRATE_ERR, X, Y, VIGNET, RA, DEC, ERRRAD, HBOXSIZE,
PROB, and SNR.
 
4 /outfile
search/outfile=filename
 
The results of the search command are saved as text into a file.
 
4 /infile
search/infile=filename
 
The results of the search command are read in from a text file
generated by using the outfile qualifier.
 
4 Example
back                ! Search for point sources using a search cell size of
excess/source=10    ! 10 original pixels
search
 
3 select
select - cursor selection
-----------------------------------------------------------------------
 select[/qualifiers]
-----------------------------------------------------------------------
 
This command is primarily for use in interactive scripts, enabling all
standard cursor selections available to the PGPLOT package.  The default
behavior is to return the selection as a list.
This command works on all interactive devices, however, the
/xtk device has the additional ability to temporarily restore standard
behavior (left-click zooms in, middle-click recenters, right-click zooms
out) while the Shift key is being pressed.
 
4 /xpix/ypix
select/xpix=x/ypix=y
 
Anchors a line at x,y which follows the cursor until the selection is
made.  In order to make a persistent line use the `draw line` command.
 
4 /box
select/box
 
This option is used to select a box area.  The first click will
anchor one corner of the box and a box will be drawn following the
cursor until the opposite corner is selected.  In order to make a
persistent box use the `draw box` command.
 
4 /xrange
select/xrange
 
This option is used select a range in the x direction.  A vertical line
follows the cursor until the first selection is made, leaving a
temporary line at the selected x coordinate.  A vertical line follows
the cursor until the second selection is made.  The coordinates of both
selected points are returned.
 
4 /yrange
select/yrange
 
This option is used select a range in the y direction.  A horizontal line
follows the cursor until the first selection is made, leaving a
temporary line at the selected y coordinate.  A horizontal line follows
the cursor until the second selection is made.  The coordinates of both
selected points are returned.
 
4 /cross
select/cross
 
This option is used to precisely select a point.  Crosshairs extending
throughout the entire image follow the cursor until a selection is made.
 
4 /color
select/color=n
 
Set the color used to draw the temporary cursor lines. The index of
each color can be found by plotting a color legend with the
`colors` command.
 
4 /noerr
select/noerr
 
By default clicking the right mouse button at any point will cancel the
selection returning a Tcl error.  This options removes the special
meaning of the right-click and behaves as if a valid selection (i.e.
left-click) was made.
 
4 Example
 
set xy [select]      ! User selects a point, saved in xy variable
 
3 show
show - current ximage status
-----------------------------------------------------------------------
  show
-----------------------------------------------------------------------
 
Show information about the current state of XIMAGE.  Properties that
are directly changeable are listed with their associated commands in
parentheses.
 
---
 * XIMAGE version
 
 * plot device (`cpd`)
 
 * equinox (`cey`)
 
 * field string for image
 
 * file loaded to create image
 
 * image size in sky coordinates
 
 * number of levels (`levels/num`)
 
 * displayed color table info
 
 * default color table info (`cct/set`)
 
 * viewport configuration (`viewport`)
 
 * display status
---
 
4 Example
 
show                 ! show the current ximage status
 
3 skymap
skymap - overlay a star chart
---------------------------------------------------------------------------
  skymap[/qualifiers] [filename]
---------------------------------------------------------------------------
 
The skymap command reads in a list of star positions and overlays them
on the current image. The default will open a connection to the HEASARC
database and retrieve all the object positions from the optical catalog
within a radius that contains the current image.
Using the `/db=` qualifier will direct the search to a specific catalog
present at HEASARC.
 
4 /dbase
skymap/dbase=[databasename]
 
Queries a search cone from the HEASARC database system on
legacy.gsfc.nasa.gov, and returns a file containing a list of
coordinates of all sources found within the field of view of the
current image. Using the `/label` and `/class` qualifiers will display
respectively the name or class of the object.
 
For a listing of available databases use the syntax, `skymap/dbase=?`.
Good databases to start with are optical, xray, rosid, and radio.
Database names containing a slash, such as Guide Star Catalog 2.2 (I/271),
2MASS Database (B/2mass) and USNO A2 Catalog (I/252) must be quoted (e.g.
`skymap/dbase="B/2mass"`).
 
4 /labels
skymap/labels
 
Overlay the source name, rather than the number.  In a user-input source
list (comma- or space-delimited), the third column is the label by default.
See the `incolumns` qualifier for ways to modify the default.
 
4 /class
skymap/class
 
Write on the image the class string if found in the file which
contains the catalogue positions.
 
4 /color
skymap/color=n
 
Set the color used for overlayed text.
 
4 /font
skymap/font=[fontname]
 
Set the font of the overlayed text.  Use `font=?` to see available
fonts.
 
4 /csize
skymap/csize=x
 
Set the character size of the overlayed text. The default text size
is 0.8.  A csize of 0 is used to to indicate that only the symbol,
not the source number is to be plotted.
 
4 /lwidth
skymap/lwidth=n
 
Set the width of the lines used to draw the overlayed text.
Possible values range from thinnest of 1 up to 201.
 
4 /symbol
skymap/symbol=n
 
Set the symbol used to plot sources. Default is 3, an asterisk.
 
4 /symcolor
skymap/symcolor=n
 
Set the symbol color.
 
4 /symcsize
skymap/symcsize=x
 
Set the character size for the symbol, which defaults to 3.0.
 
4 /symlwidth
skymap/symlwidth=n
 
Set the width of the lines used to draw the symbol.
 
4 /sdc
skymap/sdc
 
By default the HEASARC database is queried.  This qualifier indicates
that the query will be made using the SAX-SDC center in Italy.
It returns a file in BROWSE format.
 
4 /file_input
skymap/file_input=[filename]
 
Enter the filename of an ascii input file. This may also be specified
as the last argument of the `skymap` command.  By default, the input
file supports the pipe-delimited format output by the batch
interface to the HEASARC database.  Failing that, it will try processing
the input as comma-delimited and then space-delimited, using the first
two columns as RA and Dec.  The equinox may be specified in the first line
surrounded by parentheses, but is not required.  If no equinox is given,
the current equinox defined with the `cey` command will be assumed.
 
4 /incolumns
skymap/incolumns=[column list]
 
This qualifier is used to override the default interpretation of the
input file. The expected value is a comma-delimited list of column names
or numbers.  If only one value is given (e.g. `incolumns=4`) and the
`labels` qualifier is set, values from that column are printed next to
the sources.  If two values are given (e.g. `incolumns=2,3`), those two
columns are used as RA and Dec respectively.  If three values are given
(e.g. `incolumns=2,3,1`) the first two are used as RA and Dec, while the
third is used as the label if `labels` is set.
 
4 /browse_dcoord_output
skymap/browse_dcoord_output
 
Read in a list of star positions from a file created within BROWSE (the
HEASARC on-line database software), using the command dcoord/deg/full.
Specify the filename with `file_input`.
 
4 /out_file
skymap/out_file=[filename]
 
Enter the filename of the output text file to hold star positions. Only
the RA and Dec will be written to this file.
 
4 Examples
 
skymap/browse/file=browse.txt           ! read in a browse file.
 
skymap/db=optical/label                 ! overlay all the sources in
                                        ! the optical catalogue
 
3 skyview
skyview - retrieve an image from skyview
-----------------------------------------------------------------------
  skyview[/qualifiers] [survey name]
-----------------------------------------------------------------------
 
Open a connection to the HEASARC Skyview system and retrieve a sky
survey image with the position and size of the current image. The
retrieved image must be read in XIMAGE using the `read` command.
The retrieved file has `skyview.fits` as default name , but can be named
something else using the `file` qualifier.
 
4 /survey_name
skyview/survey_name=[string]
 
Survey to retrieve image from. The default is
`Digitized Sky Survey`.
 
4 /list_surveys
skyview/list_surveys
 
List the available surveys.
 
4 /file
skyview/file=[filename]
 
Specify a name for the retrieved file. The file is named
`skyview.fits` by default.
 
4 /size
skyview/size=n
 
Specify size in pixels of skyview output image.  The default size is 300.
 
4 /fov
skyview/fov=[value]
 
Field of view of skyview image in degrees.  The default FOV is based on
the current image.
 
4 /ra/dec
skyview/ra=[value]/dec=[value]
 
Center of skyview image in RA/Dec.  The default center is based on the
current image.
 
4 Example
 
skyview                 ! Retrieve current field from DSS
read skyview.fits       ! Read in queried file
disp                    ! Display image
 
 
3 slice
slice - draw an x or y slice of the image
-----------------------------------------------------------------------
  slice[/qualifiers]
-----------------------------------------------------------------------
 
Sum intensity values from a slice of the image. The slice limits by
defaults are input using the mouse by clicking the left button on the
lower and upper limits of the desired slice. On the command line the slice
limits may be specified using the `/start_pixel` and `/end_pixel` qualifiers.
By default the slice is along the x axis, and the range of values to include
in the slice is selected by clicking along the y axis.  The right button can
be used to cancel the slice operation.  The default will draw the slice
over the image. Use the `/nooverlay` qualifier to draw the slice outside the
image.
 
4 /xslice
slice/xslice
 
The slice is along the x axis. Click the cursor along the y axis to
specify the range of y to include.
 
4 /yslice
slice/yslice
 
The slice is along the y axis. Click the cursor along the x axis to
specify the range of x to include.
 
4 /log
slice/log
 
The slice data are plotted on a logarithmic scale.
 
4 /start_pixel
slice/start_pixel=x
 
The pixel value defining the beginning of the slice range.  This
qualifier along with `/end_pixel` overrides the default cursor
selection.
 
4 /end_pixel
slice/end_pixel=x
 
The pixel value defining the end of the slice range.  This qualifier
along with `/start_pixel` overrides the default cursor selection.
 
4 /previous_frame
slice/previous_frame
 
Use min/max range from the previous slice.  Allows for the comparison
of results from current slice with the previous one.
 
4 /minframe
slice/minframe=x
 
Set minimum value to be plot as result of the slice.
 
4 /maxframe
slice/maxframe=x
 
Set the maximum value to be plot as result of the slice.
 
4 /no_overlay
slice/no_overlay
 
Draw the slice outside the image area.
 
4 /color
slice/color=n
 
The color to be used for the slice plot.
 
4 /lwidth
slice/lwidth=n
 
Set the width of the slice plot line. Possible values range from
thinnest of 1 up to 201.
 
4 /lstyle
slice/lstyle=n
 
Set the style of the slice plot line: 1 (solid line), 2 (dashed), 3
(dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
 
4 /infile
slice/infile=[filename]
 
Plot an existing slice output file over the image.
 
4 /outfile
slice/outfile=[filename]
 
Specify the output filename (Default extension, .cut).  Write into a
file the pixel number, the count per pixel (using only the nonempty
pixels in the slice), the total count, and the number of nonempty
pixels.
 
4 /plot
slice/plot
 
Plot the slice output with qdp.  If the `/outfile` qualifier is not
specified, the output file is set to `slice.cut`.
 
4 /spectrogram
slice/spectrogram
 
For images containing a series of spectra. Plots points instead of
lines.  Use `/no_overlay` to plot the results of the slice in a
separate viewport.
 
4 /connect
slice/connect
 
By default, if the `/spectrogram` is being used, points are plotted
with error bars.  This qualifier overrides that behavior, connecting
them into a line.
 
4 /symbol
slice/symbol=n
 
Sets the symbol to plot the points in the spectrogram case.
 
4 /error
slice/error=x
 
Error bars plotted in spectrogram are at Value +/-(Value*x).  Default
for x is 0.001.
 
4 /mean
slice/mean
 
Plots the fraction of the average that the slice bin deviates from the
average across the slice.  Only available in conjunction with the
`/spectrogram` qualifier.
 
4 Examples
slice                           ! slice in the x direction
 
slice/y/log                     ! slice along y axis with the result plotted
                                ! on a log scale.
 
slice/y/start=100/end=200       ! y axis slice with limits set to
                                ! x start=100, x end=200.
 
3 smc
smc - minimum display level
---------------------------------------------------------------------------
  smc [level]
---------------------------------------------------------------------------
 
Copies the color for the lowest level, 0, up to the specified level.
This covers lower levels with the background color, reducing image
clutter.  To revert to normal colors, use a level of 0.  Only has an
effect on PseudoColor devices.
 
3 smooth
smooth - gaussian image smoothing
-----------------------------------------------------------------------
  smooth[/qualifiers]
-----------------------------------------------------------------------
 
Gaussian smoothing of current image. The gaussian width can be
specified with qualifier `/sigma`. If a sigma is not specified a
default value of 1.5 image pixels is used.
 
4 /real
smooth/real
 
Retain real values after smoothing instead of truncating to integers.
 
4 /exposure_map
smooth/exposure_map
 
Smooth the exposure map.
 
4 /sigma
smooth/sigma=x
 
Enter value of sigma in image pixels for the Gaussian smoothing.  If
not specified, the default is 1.5.
 
4 /scaling_factor
smooth/scaling_factor=x
 
Enter a scaling factor.
 
4 /back_brightness
smooth/back_brightness=x
 
Scaling factor is calculated by dividing the entered value by the image
background (in counts/image pixel).
 
4 /to_exposure
smooth/to_exposure=x
 
Scaling factor is calculated by dividing the entered value by the image
exposure time.
 
4 /x_only
smooth/x_only
 
The smoothing is applied only in the x direction.
 
4 /y_only
smooth/y_only
 
The smoothing is applied only in the y direction.
 
4 /wavelet
smooth/wavelet
 
A wavelet function is used in the smoothing instead of a Gaussian.
 
4 Examples
smooth/sigma=2.         ! Smooth the current image using a gaussian filter with
                        ! sigma equal to 2 image pixels.
 
3 sosta
sosta - source statistics
-----------------------------------------------------------------------
  sosta[/qualifiers]
-----------------------------------------------------------------------
 
The `sosta` command counts the number of events within a specified box,
corrects those counts for vignetting, exposure and the point spread
function to give the source intensity and its statistical significance.
Optionally the correction for the point spread function can be weighted
by the exposure map. If the significance is less than `1.e-3` an upper
limit is automatically calculated. The `sosta` command defaults to the
simplest method, which defines the source center with the mouse, and
automatically calculates the source radius as the box that corresponds
to 66% of the encircled energy function (EEF), then uses a background
from a region surrounding the source, outside the 98% EEF boundary.
 
The background can be estimated using several different methods, specified
by the user. These are:
---
 * The background is estimated from a region within two boxes centered
on the source using the option `/inner_radius` and `/outer_radius` to
specify the half-sizes of the two boxes. This is the default.
 
 * The background is taken from any specified part of the image using
`/box_background`;
 
 * The background intensity can be calculated from a representative
region with `/bgregion`.
 
 * The background intensity can be given using the qualifier
`/background_level`. In this case the background statistical error is
assumed to be zero.
---
The uncertainty in the count rate returned by `sosta` is purely statistical i.e.
does not include systematic errors. In general, sosta count rate errors are
smaller than those given by `detect` which always adds (quadratically) an
estimate of the systematic uncertainties. Also `sosta` will give slightly
different count rates from `detect`, and is in most cases is probably more
accurate. This is because `detect` uses a global background for the entire
image, whereas `sosta` is using a local background.
 
The `sosta` command will estimate the optimum box size to maximize the
signal to noise ratio.  This is given at the end of each run. By using
the `/optimize` option `sosta` will go around a second time, and use
the optimum box size to calculate the optimum source statistics.
 
4 /xpix
sosta/xpix=x
 
The source position in x given in units of original pixels. Must be
used in combination with the `/ypix` qualifier.
 
4 /ypix
sosta/ypix=x
 
The source position in y given in units of original pixels. Must be
used in combination with the `/xpix` qualifier.
 
4 /source_box_radius
sosta/source_box_radius=x
 
This specifies the half-size of the box where the source intensity is
estimated.
 
4 /optimize
sosta/optimize
 
Make an estimate of the optimum box size to maximize the signal to
noise ratio. This qualifier will make `sosta` go around a second
time so that it uses the optimum box size to estimate the source statistics.
 
4 /local_background
sosta/local_background
 
This is the default, and specifies that the background intensity must be
calculated within two boxes centered on the source and of half-size equal
to inner_radius and outer_radius respectively. The default starts the
inner box at the 98% EEF and includes an area approx twice that of the
98% EEF area.
 
4 /inner_radius
sosta/inner_radius=x
 
The radius of inner box (centered on the source) where local background is
calculated. The background intensity is calculated within the inner and
outer boxes and rescaled to the position of the source. Must be used in
combination with the `/outer_radius` qualifier.
 
4 /outer_radius
sosta/outer_radius=x
 
The radius of outer box (centered on the source) where local background is
calculated. The background intensity is calculated within the inner and
outer boxes and rescaled to the position of the source. Must be used in
combination with the `/inner_radius` qualifier.
 
4 /box_background
sosta/box_background
 
Estimate the background with boxes defined with mouse.
 
4 /background_level
sosta/background_level=x
 
Specify a constant background intensity in units of `counts/original pixel`.
 
4 /srcregion
sosta/srcregion=[regionfile]
 
Specify region to use for source statistics
 
4 /bgregion
sosta/bgregion=[regionfile]
 
Specify region which represent the background.
 
4 /expowgt
sosta/expowgt
 
Weight the psf correction by the exposure map.
 
4 /detect_sources
sosta/detect_sources
 
Run source statistics on the sources found in the previous run of
`detect`.
 
4 /eef_source
sosta/eef_source=x
 
The fractional EEF used to determine the source box size. The default
is 0.66.
 
4 /eef_background
sosta/eef_background=x
 
The fractional EEF used to determine where the inner background box
size begins. The default is 0.98.
 
4 Examples
sosta                   ! The source position is specified using the cursor.
                        ! All the defaults are used. The background is
                        ! determined from an area surrounding the source.
 
sosta/opt               ! The optimum source box size is determined.
 
sosta/box               ! The background is to be determined from boxes
                        ! specified by the user.
 
sosta/in=20/out=40      ! The background is determined from the difference
                        ! between the two boxes with half sizes 20 and 40
                        ! elemental radii.
 
sosta/source=10         ! The source box size is set to 10 pixels.
 
sosta/eef_s=0.5         ! The source box size is set to be at the 50% EEF.
 
sosta/eef_b=0.5         ! The inner background box size is set to be at the
                        ! 50% source EEF.
 
3 srcmrg
srcmrg - merge detect output files
-----------------------------------------------------------------------
  srcmrg[/qualifiers] [file1] [file2] ... [fileN]
-----------------------------------------------------------------------
 
This command merges multiple detect output text files (.det) into a
single output file with duplicates removed.  In the simplest case,
multiple detect files can be merged into a new file with the same
column order as detect output.  For example,
 
srcmrg tolerance=4 outfile=merged.txt run1.det run2.det run3.det
 
Merges the sources found in run[1-3].det removing duplicates.  A
duplicate is anything that lies within the tolerance value (in units of
arcsec).  The result is written into the outfile.
 
Note: When writing the original input columns (e.g. the counts
column) the first file in which a duplicate source appears
is used.
 
4 /tolerance
srcmrg/tolerance=[arcsecs]
 
When merging, all duplicates are removed.  A duplicate is anything
that lies within the tolerance value (in units of arcsec).  The default
value is a conservative, 1e-5 arcsec.
 
4 /outfile
srcmrg/outfile=[file location]
 
Write the results of the merge into the output file.  Note `outfile`
or `plot` must be set for the command to execute.
 
4 /racol/deccol
srcmrg/racol=n/deccol=n
 
Although, the command defaults to detect output format, any list of
sources may be used.  The key is to indicate where the RA and Dec are
located in the files with the `racol` and `deccol` parameters.  For example,
in a simple file where the first column is RA and second column is Dec,
`racol=1 deccol=2` is required.  Note, that the detect output is special
as the RA and Dec values are defined by three columns each,
(i.e. HH MM SS.S and DD MM SS.S format).  The default values are
`racol=6,7,8 deccol=9,10,11` so if you have a similarly formatted file
give a comma-delimited list of column numbers to `racol` and `deccol`.
 
4 /format
srcmrg/format=[columns]
 
By default all the columns of the original input are printed out in the
same order, however, the `format` parameter can be used to customize the
output.  Once again a comma-delimited list of columns is used.  There
are some special column values beyond the original column number that
can be used, as well.
 
-----------------------------------------------------------------------
ra    RA value
dec   Dec value
#     Source number (newly ordered for output list)
old   The old source number values in the form: file#-src#/file#-src#
-----------------------------------------------------------------------
 
The `ra` and `dec` columns are most useful in the case where the RA and Dec
values in the original file are split up into HH/DD MM SS.SS format.
If `ra,dec` is given as part of the format list, the DDD.DDDDD form
of RA and Dec will be printed regardless of the input format.
 
Printing out the first column of the detect files
in the new merged file is essentially useless as it is the source
number from the original file, but which file is not known.  So,
there are two possible types of source numbers that a user might want.
The "#" character in the format parameter tells the command to print a
new source number, the default option when merging detect files.
So instead of seemingly random source numbers, you get a new set of
sequential numbers corresponding to the new merged output.  In some
cases one might want to see which of the original sources
that the merged source corresponds to, so the "old" column prints a
representation of the original source number.  This representation
takes each input file in order and numbers them.  In our example above,
run1.det would be file 1, run2.det would be file 2, etc.  If a source
was common across all these files, but had a different number it
would look something like 1-25/2-27/3-10, meaning that the 25th source
of file 1 is the same as the 27th source of file 2 and the 10th source
of file 3.
 
4 /plot
srcmrg/plot
 
If this option is set, the merged results will be plotted on the image.
Each source will be labeled with file number and source number
separated by a hyphen.  Note, it's possible to give this command
only one file to "merge" and plot.  In that case, only the source
number is printed.  Note `outfile` or `plot` must be set for the
command to execute.
 
4 /color
srcmrg/color=n
 
Set the color used to draw the source. The index of each color can be
found by plotting a color legend with the `colors` command.
 
4 /csize
srcmrg/csize=x
 
Set the character size for the source label.  Standard character size is 1.0.
 
4 /font
srcmrg/font=[fontname]
 
Set the font of the source label.  Use `font=?` to see available fonts.
 
4 /just
srcmrg/just=[left|center|right]
 
Set the justification of source label.  Possible values are left, right,
and center.
 
4 /angle
srcmrg/angle=x
 
Set the angle in degrees of the source label.  The standard orientation of
the text is at zero degrees.  Positive angle values rotate the text
counterclockwise.
 
4 /symbol
srcmrg/symbol=n
 
Set the symbol representing the source location. The value n defines
different symbols.
 
4 /symcolor
srcmrg/symcolor=n
 
Set the color index used to plot the source.
 
4 /symcsize
srcmrg/symcsize=x
 
Set the character size of the source from the default value of 1.0.
Values more than 2.0 will tend to be too large.
 
4 /symlwidth
srcmrg/symlwidth=n
 
Set the width of the lines used to draw the source symbol.
 
 
4 Examples
 
srcmrg/out=mrg.txt run1.det run2.det  ! Merge run1.det and run2.det
                                      ! into mrg.txt
 
srcmrg/plot run1.det run2.det         ! Merge run1.det and run2.det
                                      ! plotting the results
 
3 sum_images
sum_images - add the saved and current images
-----------------------------------------------------------------------
  sum_images[/qualifiers]
-----------------------------------------------------------------------
 
Sums the current image with the image previously saved with the
`save_image` command. The result of the sum becomes the current image.
The two images are rotated to a common roll of -90 degrees (north up,
east left). By default  the center of the current image is used. This
command assumes the two images have the same elemental pixel scale size
(on the sky).
To make mosaics using the last summed image, this must first be saved
(using the `save_image`).
 
4 /ra
sum_images/ra=[value]
 
The right ascension of summed image center. The default is equal to that of
the current image. May be entered in degrees or "hh mm ss.s" format.
 
4 /dec
sum_images/dec=[value]
 
The declination of summed image center. The default is equal to that of the
current image.  May be entered in degrees or "deg mm ss.s" format.
 
4 /equinox
sum/equinox=n
 
Specify the equinox for the requested coordinate image center, given
using the `/ra` and `/dec` qualifiers. By default the current XIMAGE
equinox is assumed.
 
4 Example
sum_image              ! sum the current and saved images
 
3 surface
surface - plot a surface based on the current image
-----------------------------------------------------------------------
  surface[/qualifiers]
-----------------------------------------------------------------------
 
Plots a pseudo-3D surface of the current image data, where the pixel
values correspond to the height of the surface.  The surface is made up
of lines tracing cross-sections of the image.  By default, the
cross-sections are evenly-spaced cuts through the image.  It is
possible for image features to be lost between the cuts, so there are
two other methods for calculating the cross-sections, `/avgcut` and
`/nonemptyavgcut`, which calculate an average value from nearby image
rows.
 
4 /avgcut
surface/avgcut
 
The plotted lines are obtained by averaging image rows near the
cross-section. The number of rows used in the average depends on the
size of the original image and the number of cross-section (set by
`/numcross`)
 
4 /nonemptyavgcut
surface/avgcut
 
The plotted lines are obtained by averaging image rows near the
cross-section, excluding empty pixels.
The number of rows used in the average depends on the
size of the original image and the number of cross-section (set by
`/numcross`)
 
4 /log
surface/log
 
Use logarithmic scaling in plotting the surface.
 
4 /overlay
surface/overlay
 
Overlay the surface on an open device. The default is for the
surface plot to be drawn on a new Pgplot page.
 
4 /numcross
surface/numcross=n
 
Number of cross-sectional lines to draw.  The default is 100.
For higher values of n (more lines) the plot becomes too crowded.
Data are missing from the surface plot if lower values of n (less lines)
are requested.
 
4 /percentmax
surface/percentmax=x
 
The percentage of the viewport which the maximum peak of the surface
should take up.  The default is 25.  Higher values (as 80) are suggested for
images with few very bright sources compared to the surrounding field.
Lower values ( < 25 ) are instead suggested for image with small intensity
range.
 
4 /slantpix
surface/slantpix=n
 
The number of device pixels to offset the drawing of each successive
cross-sectional line. This gives the slanted appearance.
The default for n is 3 pixels, which is optimized for default number
of cross-sections (100). Decreasing `/numcross`, requires an increase
in slantpix to maintain the same slant and vice versa.
A negative slantpix will offset the cross-sectional lines to the left.
 
4 /noframe
surface/noframe
 
Suppress plotting of the frame which labels the surface axes.
 
4 /color
surface/color=n
 
Set the color used for the cross-sectional lines.
 
4 /lwidth
surface/lwidth=x
 
Set the width of the lines used to draw the timestamp text.  Values
range from 1 to 201.
 
4 /csize
surface/csize=x
 
Set the character size of the axis label text.  The default size is 0.6.
 
4 /font
surface/font=[fontname]
 
Set the font of the axis label text.  Use `font=?` to see available fonts.
 
4 /refresh/xmin/xmax/ymin/ymax
surface/refresh/xmin=[n]/xmax=[n]/ymin=[n]/ymax=[n]
 
Plots surface for portion of map defined by array indices.
Primarily for internal use by the zooming and recentering
capabilities of /xtk device.
 
4 Example
 
surface/non/per=80         ! Plot surface for bright source where non-empty
                           ! average is used for cross-sections
 
3 syscall
syscall - spawn system call
-----------------------------------------------------------------------
  syscall [system command]
-----------------------------------------------------------------------
 
With no arguments, a shell is spawned.  Exiting shell returns to
XIMAGE.  With arguments, after all are executed in shell, returns
to XIMAGE immediately.  Note that command flags, etc. should all be
separate arguments to syscall.
 
For example, `syscall ls -l`, not `syscall "ls -l"`.  If command
takes form of Tcl variable, use eval (See example).
 
4 Examples
 
syscall rm -f tmpfile         ! Remove temporary file
 
set cmd "ls -l"               ! Execute shell command stored
eval syscall $cmd             ! in variable
 
 
3 timestamp
timestamp - plot time/user info
-----------------------------------------------------------------------
  timestamp[/qualifiers]
-----------------------------------------------------------------------
 
Plots time/user info in the lower right corner of the Pgplot device.
 
4 /color
timestamp/color=n
 
Set the color used for the timestamp text.
 
4 /csize
timestamp/csize=x
 
Set the character size for the timestamp text.  The default size is 0.6.
 
4 /font
timestamp/font=[fontname]
 
Set the font of the timestamp text.  Use `font=?` to see available fonts.
 
4 /lwidth
timestamp/lwidth=x
 
Set the width of the lines used to draw the timestamp text.  Values
range from 1 to 201.
 
4 Example
 
timestamp                ! timestamp lower right corner of device
 
3 title
title - set an image title
-----------------------------------------------------------------------
  title[/qualifiers] [string]
-----------------------------------------------------------------------
 
Defines a title to be used when displaying an image. If the string
includes one or more blank characters it must be written within quotes
(").  This setting overrides the standard title constructed from the
header, and remains in effect until a new image is read in or a
`title/reset` is executed.
 
4 /lower
title/lower
 
The title is composed of two lines.  The upper line is set by default.
When this qualifier is on the lower line is set.
 
4 /reset
title/reset
 
Remove any title settings so the standard title is used.
 
4 Examples
title "This is a test"        ! write the string `This is a test`
                              ! above the image when displayed.
 
title " "                     ! blank both titles
title/lower " "
 
3 uplimit
uplimit - calculate upper limit
-----------------------------------------------------------------------
  uplimit[/qualifiers]
-----------------------------------------------------------------------
 
The `uplimit` command calculates an upper limit on the source signal.
The command can be used by entering either the counts or a region file
or specifing the boundary of a box via the qualifiers
'xmin/ymin/xmax/ymax' and the selected area is plotted on the image.
If the region or the 'xmin/ymin/xmax/ymax' are specified, it is necessary
to have read the image from which the region file or pixel boundary of the
box were derived. If neither 'counts' or 'regionfile' or
'xmin/ymin/xmax/ymax' are specified, ximage will assume that the user
wants to calculate the upper limit on the current image loaded
and will be prompted to select opposite corners of a box on the plotted
image with the mouse cursor.  By default, the selected area is plotted.
The background value can be either input or if there is an image
loaded is calculated by executing automatically the 'background' command.
 
The upper limit is calculated using two methods:
 The first is the Classic Approach. See for example
"Confidence limits for small numbers of events"
by Gehrels, N. (ApJ 303:336-346, 1986), valid when the
background is zero:
http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=1986ApJ...303..336G
 
However the uplimit routine has been modified for this method in
cases with background different from zero (see also the discussion
in Kraft, Burrow and  Nousek, 1991,  ApJ 374:344-355
 
http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=1991ApJ...374..344K
 
This method is not accurate when the background counts are larger
than the counts in the region of interest.
 
The second method uses the Bayesian approach with the prior function set to
the prescription described in Kraft R., Burrows D. and Nousek J., ApJ
374:344-355, 1991.
 
http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=1991ApJ...374..344K
 
There is also a third method which by default is not printed, where the upper
limit is obtained also with the Bayesian approach as described in the
Physical Review D 54, 1991 page 166 equantion 28.40
 
http://prola.aps.org/pagegif/PRD/v54/i1/p1_1/p166
 
To see the results from this last method set the ximage chatter (default 10)
to a higher value. For example:
[XIMAGE> chat 15
 
4 /counts
uplimit/counts=x
 
Specify the raw counts, independent of the currently loaded image.
 
4 /background_level
uplimit/background_level=x
 
Specify a constant background intensity in units of `counts/original pixel`.
When entering `counts` directly, this value is interpretted as counts due to
the background as there is no associated area.
 
4 /sigma
uplimit/sigma=x
 
Specify the sigma to be used in the upper limit calculation.  The routine
accepts sigma levels up to and including 5. The default sigma is 3.
 
 
4 /regionfile
uplimit/regionfile=[filename]
 
Specify the region file used to specify an area for which to calculate
the upper limit.  If the region file ends in '.reg', the extension may
be omitted.  A region file may also be specified as the last argument
of the command.
 
4 /xmin/xmax/ymin/ymax
uplimit/xmin=x/xmax=x/ymin=x/ymax=x
 
Calculate the upper limit for the box defined by the minimum and
maximum x and y values in original detector coordinates.
 
4 /noplot
uplimit/noplot
 
By default the specified area is plotted on the screen.  This qualifier
turns off the plotting.
 
4 /color
uplimit/color=n
 
The color index to be used in plotting the specified area.
 
4 /lwidth
uplimit/lwidth=n
 
The width of the line used to draw the specified area.  Possible values
range from thinnest of 1 up to 201.
 
4 /lstyle
uplimit/lstyle=n
 
The style of the line used to draw the specified area: 1 (solid line),
2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
 
4 Examples
uplimit                 ! The upper limit is calculated for an area
                        ! selected with the cursor
 
uplimit src.reg         ! The upper limit is calculated for an area
                        ! specified in the src.reg region file
 
uplimit counts=10 background=8 sigma=1 ! The upper limit is calculated for
                                       ! 10 raw counts with a background of 8
                                       ! at 1 sigma level.
 
3 value
value - print data value
-----------------------------------------------------------------------
  value[/qualifiers]
-----------------------------------------------------------------------
 
Print data values from a displayed image by selected via a cursor
a polygonal area. The values printed for the vertex of the polygon
are pixels coordinates, pixel intensity and the corresponding celestial
coordinates.
The `/box` qualifier prints only intensity pixel values of a square part
of the image. The mouse buttons have the following functions: select left
button, deselect middle button, end selection right button.
 
4 /line
value/line
 
A line is drawn between points.
 
4 /fill
value/fill
 
The polygonal area specified is filled with solid color.
 
4 /label
value/label
 
Plots the pixel value of each vertex on the image as they are
selected.
 
4 /box
value/box=n
 
Print to the screen the box of values which are within n image pixels
from the selected vertex.
 
4 /symbol
value/symbol=n
 
Symbol to be used to mark the vertices. Symbols are specified by means of
numbers. The correspondence number-symbols is that defined in the PGPLOT
package. The default symbol is number 2 (a cross).
 
4 /color
value/color=n
 
Set the color to be used for elements plotted on the image.
 
4 /lwidth
value/lwidth=n
 
Set the width of the lines drawn with the line option and lines used to
draw symbols and labels.  Possible values range from thinnest of 1 up
to 201.
 
4 /lstyle
value/lstyle=n
 
Set the style of the line: 1 (solid line), 2 (dashed), 3
(dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
 
4 /font
value/font=[fontname]
 
Set the font of the labels.  Use `font=?` to see available fonts.
 
4 /csize
value/csize=x
 
Set the character size of the labels.  Standard character size is 1.0.
 
4 Examples
 
value/line                   ! Define a polygonal area and draw straight lines
                             ! between the vertices.
 
value/label                  ! Plot value of each pixel as they are clicked
 
value/symbol=3               ! Define a polygonal area marking the vertices
                             ! with symbol number 3 (a star)
 
value/box=2                  ! Print the pixel value and values within
                             ! 2 image pixels away:
                             !
                             !        2 2 2 2 2
                             !        2 1 1 1 2
                             !        2 1 0 1 2
                             !        2 1 1 1 2
                             !        2 2 2 2 2
 
3 viewport
viewport - set viewport
-----------------------------------------------------------------------
  viewport[/qualifiers] [viewport configuration]
-----------------------------------------------------------------------
 
Sets up single or multiple (via a viewport configuration file) viewports
for image display. In a single viewport setting the images are plotted
over and over in the same location of the screen. Alternatively if
a viewport configuration file is set the image plots cycle through the
different viewports. At any time to see the viewport in use, type the
command `show` and to reset the viewport to the standard setting use
the command  `viewport/reset` or `viewport/center`.
Single viewport can be defined anywhere on the display screen by using
the `/v1`,`/v2`, `/v3`, `/v4` qualifiers or via the cursor .
Already made single viewport can be set by using the qualifiers
`/top`, `/bottom` `/left` and `/right` which will place the image
to the top half or bottom half or the screen or to the left or to
the right of the screen (the usage of the `/left` and `/right` is equivalent
to `display/left` and `display/right`).
 
Multiple viewports can be set with the `viewport/file=filename`
or `viewport filename`, where filename is a viewport configuration file
(see below about the format). There are already available a number of
viewport configuration file that can be listed via `viewport ?`.
 
4 /file
viewport/file=[viewport configuration]
 
Assign a file containing the viewport configuration.  This file
contains a line for each viewport. A viewport is defined by 4 numbers,
ranging from 0 to 1, and represents the vertices of the viewport
(see also Displaying_Images section).
Subsequent displays will cycle through the viewports, displaying each
image on the same Pgplot page in the order they appear in the file.
A new page begins when the first viewport in the file is reached again.
XIMAGE will remain in this mode until the viewport is set differently or
the command `viewport/reset` is used.
The local directory is searched for the specified viewport configuration
file (extension .vpc) before the installed area.  A `?` in place of
the viewport configuration gives the list of all installed configurations.
 
4 /switch
viewport/switch
 
Switch the current viewport to the one specified with the `number`
qualifier.  Coordinate information is reported relative to the
current viewport.
 
4 /number
viewport/number=n
 
In combination with `switch`, this sets the coordinate information
to be reported relative to the nth viewport (Current). Without
`switch`, the next plot will by plotted in the nth viewport (Next).
Use the `show` command to see the "Next" and "Current" viewport
numbers.
 
4 /v1/v2/v3/v4
viewport/v1=x/v2=x/v3=x/v4=x
 
Specify the viewport where the image is to be displayed by the subsequent
executions of the `display` or `contour` commands.  Viewport
coordinates number the entire device from 0.0 at the left to 1.0 at the
right and 0.0 at the bottom to 1.0 at the top.  The parameter `/v1`
corresponds to the left side of the viewport, `/v2` to the right, `/v3`
to the bottom, and `/v4` to the top.  This viewport setting will remain
in effect for all subsequent `display` and `contour` commands unless
redefined or reset in the `viewport` command or overridden in the
`display` and `contour` commands themselves.
 
4 /center
viewport/center
 
Set the viewport to the standard, centered on the device.
 
4 /left
viewport/left
 
Set the viewport to the left half of the device.
 
4 /right
viewport/right
 
Set the viewport to the right half of the device.
 
4 /top
viewport/top
 
Set the viewport to the top half of the device.
 
4 /bottom
viewport/bottom
 
Set the viewport to the bottom half of the device.
 
4 /cursor
viewport/cursor
 
Set viewport by selecting a region with the mouse on an open
interactive device.
 
4 /reset
viewport/reset
 
Reset all viewport settings to their defaults.
 
4 /devsz
viewport/devsz
 
Print information on the size in actual device pixels of the currently
opened Pgplot device.  This is useful for calculating viewport limits
if unique placement of images is desired or the images are nonsquare.
 
4 /info
viewport/info
 
Print information on the current and next viewports as well as their
contents.  Each viewport is given a number, which is followed
by a list of plot elements designated `plottype(mapid)` where
`plottype` can be display, contour or surface and `mapid` is the
map used to render that plot.  If the map is no longer available
(i.e. overwritten or freed) the `mapid` is displayed as `*`.
 
 
4 Examples
 
viewport 2x2           !  Display subsequent images in quadrants of the
                       !  device, numbered left to right and down
 
viewport/reset         !  Revert to usual viewport behavior
 
3 vignetting
vignetting - correct exposure map for vignetting
-----------------------------------------------------------------------
  vignetting
-----------------------------------------------------------------------
Multiply the current exposure map by the vignetting function. Be careful
not to correct an exposure map that might already have been corrected.
 
4 Example
vig                           ! apply the vignetting
 
3 vplabel
vplabel - write label with respect to viewport
-----------------------------------------------------------------------
  vplabel[/qualifiers] [string]
-----------------------------------------------------------------------
 
Write text outside the image with respect to the viewport. This
command is complementary to `label`. The difference is that
`vplabel` writes text without specifying the viewport coordinates.
If the text string contains spaces, it must be surrounded by double quotes.
 
4 /top
vplabel/top
 
Place label along top of image.  This is the default.
 
4 /bottom
vplabel/bottom
 
Place label along bottom of image.
 
4 /left
vplabel/left
 
Place label vertically along left side of image.
 
4 /right
vplabel/right
 
Place label vertically along right side of image.
 
4 /just
vplabel/just=[left|center|right]
 
Set the justification of label text.  Possible values are left, right,
and center.
 
4 /position
vplabel/position=x
 
Set position along viewport and text is justified in relation to this
point. The values for x ranges from 0 to 1.
For example, the command `vplabel/just=right/position=0.5` will start
write the text such that ends at the center of the top side of the viewport.
 
4 /margin
vplabel/margin=x
 
Distance between image edge and label text measured in units of the
current character size.
 
4 /color
vplabel/color=n
 
Define the color used for the label text.
 
4 /csize
vplabel/csize=x
 
Set the character size for the label text.  Standard character size
is 1.0.
 
4 /font
vplabel/font=[fontname]
 
Set the font of the label text.  Use `font=?` to see available fonts.
 
4 /lwidth
vplabel/lwidth=x
 
Set the width of the lines used to draw the label text.
Values range from 1 to 201.
 
4 /curvp
vplabel/curvp
 
This qualifier only has an effect if a viewport configuration is being
used.  The default is to treat the all the viewports in the
configuration as a whole, labeling them as one object.  If this
qualifier is specified, the labeling is done with respect to only the
current viewport.
 
4 /text
vplabel/text=string
 
Set the label text.  In some cases it may be necessary to use this
qualifier to define the label text, as there can be an ambiguity
if the label matches a qualifier or its abbreviation.
 
4 Example
 
vplabel/bottom/just=right "4U 1822-37"  ! plot label just below image
                                        ! right justified
 
vplabel/right/text=Right                ! plot ambiguous label
 
3 wcs
wcs - monitor and manipulate wcs coordinate data
-----------------------------------------------------------------------
  wcs[/qualifiers] [idstring]
-----------------------------------------------------------------------
 
The WCS data associated with image map data and plots
are stored in structures identified by a wcsid of the form "WCS"
followed by a number.  Most options of this command are used internally
to manage these data structures.
 
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.  The `frame` option of this command
is used to select among these systems.
 
This command is required after updating coordinate keywords
in the internal header with `chheader`.  The wcsid associated with the
map must be updated to reflect the changes with `wcs upwcs`.
 
4 /wcsid
wcs/wcsid=[idstring]
 
Sets the wcsid to be used by this command.
 
4 /mapid
wcs/mapid=[idstring]
 
If set, the wcsid associated with the given mapid will be used.
 
4 /frameid
wcs/frameid=[idstring]
 
Specify the primary coordinate frame, which is used for example when
plotting a grid or in the topmost coordinate readout when rolling over
the /xtk device.  By default, the first sky coordinate frame encountered
upon reading a fits file is considered the primary coordinate frame.  If
no sky coordinate frame is found, the first coordinate frame that is not
image or detector coordinates is used.  If no such coordinate frame exists,
the default primary coordinate frame will be set to detector coordinates.
 
The frame id can be an integer or one of the following three-character
ids:  IMG=image coordinates, DET=detector coordinates, SKY=first sky
coordinates.  Also, if a frame is defined by an alternate WCS axis descriptor
code, the character-valued code may be used.  For example, a frame id of
'P' will select the coordinate system originally defined using the
FITS keywords: CTYPE1P, CRPIX1P, etc.  A listing of the available frames
can be viewed by using the command 'wcs/frame=?'
 
4 /uphdr
wcs/uphdr
 
Update the internal header based on the contents of the wcs data
structure.  Primarily run internally to keep the internal header
up-to-date when the wcs changes.
 
4 /upwcs
wcs/upwcs
 
Update the wcs based on the contents of the internal header.  If the
internal header's coordinate keywords have been modified with `chheader`,
the changes will not take effect in the wcs data structure unless this
command is run.  Note: the primary coordinate management mechanism in
ximage is through wcsids, as many more kinds of coordinate systems may be
expressed in that data structure than in the internal header.  Some
coordinate systems cannot be effectively tweaked by modifying the
internal header and running `wcs upwcs`.
 
4 /incr
wcs/incr
 
Increment the reference count of the specified wcsid.  Primarily for
internal memory management.
 
4 /decr
wcs/decr
 
Decrement the reference count of the specified wcsid.  Primarily for
internal memory management.
 
4 /show
wcs/show
 
Print text description of the specified wcsid.  Primarily for
diagnostic purposes.
 
4 Examples
 
wcs/upwcs/map=2         ! Update the wcsid of MAP2 using internal header
 
wcs/frame=?             ! Print a list of coordinate system frames for
                        !  the current map
 
3 write_image
write_image - write the current image to a file
-----------------------------------------------------------------------
  write_image[/qualifiers] [filename]
-----------------------------------------------------------------------
 
Images can be written to a file using FITS, EXOSAT or ASCII format.
The FITS format is the default due to its portability and wide usage.
format.  The name of the output file can be specified as either a
qualifier or as the command's last argument.
 
4 /mapid
write_image/mapid=[idstring]
 
Write specified map to file. Without this qualifier, the default is
to write current map.
 
4 /exposure_map
write_image/exposure_map
 
Write the current exposure map to a file.
 
4 /display_map
write_image/display_map
 
Write the map last displayed to a file.
 
4 /file
write_image/file=[filename]
 
The name of the image file to be created.  May also be specified as the
last argument of the command.  If the specified file has no extension,
one will be appended based on the file type: `.img` for fits, `.qdp` for
ascii and `.exo` for exosat.
 
4 /template
write_image/template=[template_name]
 
Sets the template which defines the keywords from the header which will
be written to the file.  If a `?` is given, the available templates
will be listed.
 
4 /fits
write_image/fits
 
Write an image in FITS format (this is the default).
 
4 /ascii
write_image/ascii
 
Write image into text file where each row of the image is written as a
list of space-delimited numbers with a `-` used to continue the row on
the following line.  The header is written as comment lines, which are
preceded by a `!` character.
 
4 /sigfig
write_image/sigfig=n
 
The number of significant digits (figures) to use when writing values into a
text file.  Only has an effect if the `/ascii` qualifier is used in
combination with the `/display_map` or `/exposure_map` qualifier.
 
4 /exosat
write_image/exosat
 
Write image in exosat format. This format is not recommended, as it is
machine-dependent and rarely used.
 
4 /nonull
write_image/nonull
 
Zero out null values in map when writing output image.  Only necessary
if image will be used with an application which does not recognize null pixel
values.
 
4 /nowcs
write_image/nowcs
 
Ignore the wcs data structure when writing the output image, using the
internal header with no modification.
 
 
4 Examples
write filename          ! write the current image to disk
                        ! in FITS format as `filename.img`
 
2 Data_formats
3 Input
 
Input
 
XIMAGE accepts two type of FITS file as input : an image or an event file.
It also seven different types of files containing image,
spectral and timing  data. These files can all be read in by
command `read_image`
 
 
4 FITS
FITS - FITS image and event files
 
A FITS image is an array stored in the
primary array or an image extension.  By default XIMAGE reads the
first array in the primary header.
 
An event file is a FITS binary table where each row describes
quantities associated with an event. These typically are coordinates in
detector or sky, energy channels, and time. An event file can be read
within XIMAGE provided that at least two columns exist, representing x
and y for an image.
 
 
4 EXOSAT
EXOSAT - EXOSAT image files
 
These are simply integer*2 binary files with record length
equal to the number of image pixels in the X dimension.
The image header takes 64 bytes and is stored in the first
record of the file if the record length is greater or equal to
64,bytes or in as many initial records as necessary if the record
length is less than 64 bytes. As many data records as the number
of pixels in the Y direction follow.
 
3 Output
 
Output
4 EXOSAT_Images
EXOSAT Images
 
EXOSAT image files (.IMG) are produced by command `write/exo filename`.
These binary files are operating system dependent (so don't ftp them!).
 
4 FITS_image
FITS Images
 
A FITS image file (.FITS) is produced by the command `write/fits filename`.
These files are operating system independent.
 
3 Ximage-Specific_Files
 
4 Color_Table
 
Color tables are text files (usually ending with .tab) where each line
defines a color which has a Red value of the first row, a Green value
of the second row and a Blue value of the third row.  RGB values can
range from 0.0 to 1.0
 
For example, this table goes from black to white.  XIMAGE will
calculate intermediate colors to fill in the necessary number
of colors, which depends on the number of levels set.
 
----------------------------------------------------------------------
  CCT [color table]          - Loads existing color table
  CCT/OUTFILE=[color table]  - Writes out color table
----------------------------------------------------------------------
 
----------------------------------------------------------------------
!
!  Black to white color table
!
0. 0. 0.
1. 1. 1.
----------------------------------------------------------------------
 
4 Levels
 
XIMAGE levels files contain a level value on each line.  For example,
the following levels file contains 16 levels.
 
----------------------------------------------------------------------
  LEVELS/LOAD [levels file]  - Loads levels file
  LEVELS/SAVE [levels file]  - Writes out levels file
----------------------------------------------------------------------
 
----------------------------------------------------------------------
!
!  Calculated levels
!  Total number: 16
!
0
1
2
3
4
5
6
7
8
9
10
11
13
15
18
49
----------------------------------------------------------------------
 
 
4 Viewport_Configuration
 
Viewport configuration files (usually ending with .vpc) contain a line
for each viewport.  A viewport is defined by four columns, v1=left
edge, v2=right edge, v3=bottom edge, and v4=top edge.  Viewport
coordinate number the device from 0.0 to 1.0 from left to right and 0.0
to 1.0 from bottom to top.
 
----------------------------------------------------------------------
  VIEWPORT [configuration file]  - Loads vpc file
----------------------------------------------------------------------
 
----------------------------------------------------------------------
!
!  Viewport configuration file (2x1)
!
!        -------------
!        |     |     |
!        |  1  |  2  |
!        |     |     |
!        -------------
!
!v1  v2  v3  v4
!-- --- --- ---
0.1 0.5 0.2 0.8
0.5 0.9 0.2 0.8
----------------------------------------------------------------------
 
4 Header_Template
 
Header template files (usually ending with .hdr) define the keywords
from the internal header that are to be written out to the screen in
the case of `CHHEADER [template file]` and to a file in the case of,
for example, `WRITE_IMAGE/TEMPLATE=[template file]`.
 
These files contain a line for each keyword of the form:
 
----------------------------------------------------------------------
OUTKEYWD = *INKEYWD / COMMENT
----------------------------------------------------------------------
 
The OUTKEYWD and COMMENT values are used without modification in
XIMAGE's FITS writer, while the *INKEYWD field contains information on
what type the keyword value is and which internal header key is to be
accessed.  The symbol before INKEYWD represents the keyword type, which
can be: ! = integer, $ = string, # = real, ? = unknown (XIMAGE figures
it out by the internal header definition).  If INKEYWD is left blank,
the value for OUTKEYWD is assumed as well as a ? type.
 
INKEYWD can also be a quoted value which is independent of internal
header values by preceding the the value with a \ character.  If no
type character is given, string is assumed.  The ? is not a valid
type for a quoted value.  If is is necessary to quote a string, the
\ or type indicator must be the first character inside the quotes
(e.g. '\text phrase').
 
Since the addition of a wcsid, the coordinates defined in the wcs
data structure can be more expressive than the internal header.
Consequently, one cannot tweak the coordinate system by manipulating
the internal header as the contents of the wcs structure will override
any modifications.  The wcs information, however, can be suppressed
with any of the following '\wcs' directives.
 
----------------------------------------------------------------------
\wcs nowrite         / Omit image WCS info keys
\wcs history         / Write image WCS info as HISTORY keys
\wcs comment         / Write image WCS info as COMMENT keys
----------------------------------------------------------------------
 
The internal header consists of the following keywords:
 
----------------------------------------------------------------------
#
#  Template for displaying all of internal XIMAGE header
#
#  !,$,# are used here to document types of all header keywords
#  ! = integer, $ = string, # = double (Also, see hdr.doc)
#
MAPPTR   = !         / Internal map pointer
MAPTYPE  = $         / Map data type (I=integer R=real)
MAPCODES = $         / Map manipulation codes (See map command)
MAPCOPY  = $         / Map copy list (keeps track of identical maps)
EXMAPID  = $         / Associated exposure map
EXPMAP   = !         / Whether map is loaded exposure map (0/1)
LOADED   = !         / Whether map is loaded (0/1 = yes/no)
VIGNAPP  = !         / Whether vignetting correction is applied (0/1)
WCSID    = $         / Associated wcs id (refers to AstFrameSet)
FILE     = $         / Filename
ROOT     = $         / File root
SZX      = !         / Size in x direction
SZY      = !         / Size in y direction
XIMZERO  = #         / Offset XIMAGE has applied to original image
XIMSCALE = #         / Scaling factor applied to original image
BZERO    = #         / Offset
BSCALE   = #         / Scaling factor
BUNIT    = $         / Units of image array
OBJECT   = $         / Field identification
TELESCOP = $         / Telescope
INSTRUME = $         / Instrument
DETNAM   = $         / Detector name
FILTER   = $         / Filter
ZMX      = #         / Zoom in x direction
ZMY      = #         / Zoom in y direction
EQUINOX  = #         / Image equinox
CTYPE1   = $         / Coordinate system
CTYPE2   = $         / Coordinate system
CUNIT1   = $         / Unit axis 1
CUNIT2   = $         / Unit axis 2
CRVAL1   = #         / Reference point axis 1
CRVAL2   = #         / Reference point axis 2
CRPIX1   = #         / Reference point pixel location axis 1
CRPIX2   = #         / Reference point pixel location axis 2
DRPIX1   = #         / Reference point of axis 1 in det coords
DRPIX2   = #         / Reference point of axis 2 in det coords
CDELT1   = #         / Pixel size along axis 1
CDELT2   = #         / Pixel size along axis 2
DDELT1   = #         / Pixel size along axis 1 in det coords
DDELT2   = #         / Pixel size along axis 2 in det coords
OCRPIX1  = #         / Original reference pixel axis 1
OCRPIX2  = #         / Original reference pixel axis 2
OCRVAL1  = #         / Original reference value axis 1
OCRVAL2  = #         / Original reference value axis 2
CROTA2   = #         / Rotation angle (degrees)
XIMNORTH = #         / North angle
EXPOSURE = #         / Exposure time (sec)
DTIME    = #         / Dead time correction
DATE-OBS = $         / Date of observation begin
DATE-END = $         / Date of observation end
DATAMIN  = #         / Minimum in array
DATAMAX  = #         / Maximum in array
EMIN     = !         / Minimum energy channel
EMAX     = !         / Maximum energy channel
----------------------------------------------------------------------
 
4 Mission_Database_File
 
The mission database defines the defaults used for specified missions.
The installed mdb file ximage.mdb is loaded at XIMAGE startup.
 
----------------------------------------------------------------------
  CHMDB/OUTFILE=[mdb file]  - Writes out mdb file
  CHMDB/INFILE=[mdb file]   - Inputs an mdb file
----------------------------------------------------------------------
 
----------------------------------------------------------------------
!
!  XIMAGE mission database files have the following syntax:
!
!  TELESCOP : INSTRUME : DETNAM {
!      KEYWORD = VALUE
!  }
!
!  DETNAM is optional.  The following is also valid:
!
!  TELESCOP : INSTRUME {
!      KEYWORD = VALUE
!  }
!
!  Defined keywords
!
!  DEFSZX   = Default image size in x
!  DEFSZY   = Default image size in y
!             Used by event reader if SIZE or SZX/Y not given
!             Note: If DEFSZY not set, DEFSZY=DEFSZX and vice versa
!
!  DEFZOOM  = Default image zoom
!             Used by event reader if REBIN not given
!
!  XCOL     = X column                  [=X, if omitted]
!             Used by event reader if XCOL not given
!
!  YCOL     = Y column                  [=Y, if omitted]
!             Used by event reader if YCOL not given
!
!  ECOL     = Energy column (PI/PHA)    [=PHA, if omitted]
!  EMIN     = Minimum energy channel
!  EMAX     = Maximum energy channel
!             Used by event reader if ECOL, EMIN, EMAX not given
!
!  ENUM     = Number of energy channels
!             Used by extract to allocate spectrum buffer
!
!  DRPIX1   = Detector center in x
!  DRPIX2   = Detector center in y
!             Used by image reader to assign detector coordinates
!             if DRPIX1/2 not in FITS header
!
!  PIXSIZE  = Pixel size in arcsecs
!             Used by PSF and vignetting if function or PSF file
!             needs units of arc
!
!  DOPTIC1  = Optical axis in x
!  DOPTIC2  = Optical axis in y
!             Used by detect (PSF, vignetting, etc.) when offaxis
!             is calculated
!
!  ERRRAD   = Error radius
!             Used in detect for error radius
!
!  DETBOX   = Default detect box size    [=8, if omitted]
!             Used as detect box size if SOURCE_BOX_SIZE not set
!
!  EXCHAN   = Default energy channels list used in EXTRACT
!             Format - "c1,c2,c3,c4" Used for extract color file
!             if C1,C2,C3,C4 qualifiers not set
!
!  ENGFILE  = Energy input file (spectrum used by internal vign or psf)
!             Used to specify spectrum for energy-dependent psf and
!             vignetting functions which overrides the default file in
!             the cal directory
!
!  PSFFILE  = PSF input file (overrides internal calculation)
!             PSF file which overrides default PSF file from cal
!             directory or PSF function
!
!  VIGNFILE = Vignetting fits image (overrides internal calculation)
!             Vignetting FITS image which overrides default from cal
!             directory or vignetting function
!
!  GTIEXT = GTI extension expression (overrides default READ/GTIEXT=*GTI*)
!
!  CHMDB/INFILE [mdb file]   - Loads mdb file
!  CHMDB/OUTFILE [mdb file]  - Writes out mdb file
!
EXTEL : EXINST {
   DEFSZX = 512  DEFZOOM=8
}
----------------------------------------------------------------------
 
4 Psf_File
 
A PSF calibration file is generated with the
`psf/multpsffile=[filename]` command.  This output can be used to set
the `psffile` key in the mdb (e.g. chmdb/key=psffile/val=[filename]).
Subsequent PSF calculations will use that PSF calibration file.
 
The PSF calibration file can include several columns.  The first column
is the distance from centroid of the source and can be expressed in
arcmin or unrebinned pixels.  The remaining columns contain the
fractional PSF at a different offaxis distance, indicated by the
OFFAXISn keywords.
 
----------------------------------------------------------------------
!
!  PSF calibration file for use as PSFFILE
!
!FILE    = 'filename.fits'      / Filename
!OBJECT  = 'field name'         / Field identification
!TELESCOP= 'EXTEL   '           / Telescope
!INSTRUME= 'EXINST  '           / Instrument
!
!  Column 1: Distance from source center (det coords)
!  Columns 2+: Fractional psf
!
$echo UNITTYPE=                    1 / Unit for OFFAXIS (1=pix, 2=arcmin)
$echo OFFAXIS2=            3260.2703 / Offaxis distance for column 2
$echo OFFAXIS3=            1240.3722 / Offaxis distance for column 3
!
7.5 8.5764946E-3 0.1945632
23.5 2.8332831E-2 0.4073279
39.5 8.8323012E-2 0.6626034
55.5 0.1579828 0.7455482
71.5 0.2537213 0.7772189
87.5 0.3439038 0.7928265
103.5 0.4605596 0.8055947
119.5 0.5861865 0.81647
135.5 0.6675338 0.8242607
151.5 0.7392796 0.8362666
167.5 0.8021447 0.8393251
183.5 0.8378382 0.8413145
199.5 0.8699709 0.8336555
215.5 0.8889965 0.8479223
231.5 0.9007197 0.8534872
247.5 0.9042383 0.8599985
263.5 0.9081515 0.8605246
----------------------------------------------------------------------
 
4 Energy_File
 
If an energy-dependent psf routine is available within ximage for a
particular mission, the energy dependence can be calculated using a
spectral file, created by using the `extract/engfile=[filename]`
command. In order for an energy file to be used in the psf calculation,
it must be set with `chmdb/key=engfile/val=[filename]`.
 
----------------------------------------------------------------------
! EXTEL EXINST
! filename.fits
!
!  Energy data file for use as ENGFILE
!
!  TELESCOP = EXTEL
!  INSTRUME = EXINST
!
$echo BINNING =  8              /  Spectrum binning factor
$echo ESTEP =    0.01           /  Energy step between bins (keV)
$echo EOFFSET = -0.05           /  Energy value of first bin (keV)
!
! Total channels:    408
!
           0
           0
           0
           0
           8
         132
         695
         886
         926
           .
           .
           .
           0
           1
----------------------------------------------------------------------
