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 `` to get info on it. Use `` 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 `` to get info on it. Use `` 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 ----------------------------------------------------------------------