next up previous contents
Next: 9. Data formats Up: XIMAGE User's Guide Previous: 7. Commands G-R   Contents

Subsections

8. Commands S-Z

8.1 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.

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.

saoimage/template=[templatename]
Set the template used to write header keywords. Use template=? to see available templates. The default is sufficient in most cases.

Example:
     
    saoimage                 !  displays currently loaded image in saoimage

8.2 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.

Example:
     
    save_image                   ! save the current image and exposure map

8.3 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.

scale/no_of_divisions=n
Set the number of divisions to divide up the scale for labeling.

scale/top
Plot scale along top of image.

scale/bottom
Plot scale along bottom of image, which is the default.

scale/left
Plot scale along left side of image.

scale/right
Plot scale along right side of image.

scale/vertical
Force the scale be plotted in the vertical direction of the screen. Identical to /right qualifier. Kept for backwards compatibility.

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.

scale/margin=x
Distance between image edge and nearest edge of color scale measured in units of the current character size.

scale/spacing=x
Spacing between intensity level text and scale itself measured in units of the current character size. Default is 0.5.

scale/lwidth=n
The width of the lines surrounding and dividing the scale. Possible values range from thinnest of 1 up to 201.

scale/csize=x
Sets the character size of the scale labels. Standard character size is 1.0.

scale/font=[fontname]
Sets the font of the scale labels. Use font=? to see available fonts.

scale/label=[string]
Write a string to label the color scale.

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.

Examples:
     
    scale             ! display the color scale at the image's bottom
    scale/right       ! display the color scale along the image's right side

8.4 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.

screengrab/xv
Performs screen capture of /xtk plot, then crops with xv. Graphic must be saved from xv. Note: pgplot.xwd is created.

screengrab/display
Performs screen capture of /xtk plot, then crops with ImageMagick display. Graphic must be saved from display. Note: pgplot.xwd is created.

screengrab/convert
Performs screen capture of /xtk plot, then crops with ImageMagick convert. Saved as pgplot.gif by default. Note: pgplot.xwd is removed.

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.

Examples:
     
    screengrab/xv                ! Grabs and crops in xv
    screengrab/convert grab.jpg  ! Grabs and crops with convert to jpg

8.5 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:

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.

Example:
     
    script filename             ! all commands subsequently executed are stored
                                ! in a file called `filename.xco`

8.6 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.

search/prob_limit=x
Change the background probability limit from the default value (1E-04).

search/snr_threshold=x
Change the signal to noise acceptance threshold from its default value of 2.

search/nolabel
Omit the number label when plotting the detected source boxes.

search/color=n
Set the color index for the detected source boxes and labels.

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.

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).

search/font=[fontname]
Sets the font of the detected source labels. Use font=? to see available fonts.

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.

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.

search/outfile=filename
The results of the search command are saved as text into a file.

search/infile=filename
The results of the search command are read in from a text file generated by using the outfile qualifier.

Example:
    back                ! Search for point sources using a search cell size of
    excess/source=10    ! 10 original pixels
    search

8.7 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.

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.

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.

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.

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.

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.

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.

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.

Example:
     
    set xy [select]      ! User selects a point, saved in xy variable

8.8 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.

Example:
     
    show                 ! show the current ximage status

8.9 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.

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").

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.

skymap/class
Write on the image the class string if found in the file which contains the catalogue positions.

skymap/color=n
Set the color used for overlayed text.

skymap/font=[fontname]
Set the font of the overlayed text. Use font=? to see available fonts.

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.

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.

skymap/symbol=n
Set the symbol used to plot sources. Default is 3, an asterisk.

skymap/symcolor=n
Set the symbol color.

skymap/symcsize=x
Set the character size for the symbol, which defaults to 3.0.

skymap/symlwidth=n
Set the width of the lines used to draw the symbol.

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.

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.

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.

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.

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.

Examples:
     
    skymap/browse/file=browse.txt           ! read in a browse file.
     
    skymap/db=optical/label                 ! overlay all the sources in
                                            ! the optical catalogue

8.10 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.

skyview/survey_name=[string]
Survey to retrieve image from. The default is Digitized Sky Survey.

skyview/list_surveys
List the available surveys.

skyview/file=[filename]
Specify a name for the retrieved file. The file is named skyview.fits by default.

skyview/size=n
Specify size in pixels of skyview output image. The default size is 300.

skyview/fov=[value]
Field of view of skyview image in degrees. The default FOV is based on the current image.

skyview/ra=[value]/dec=[value]
Center of skyview image in RA/Dec. The default center is based on the current image.

Example:
     
    skyview                 ! Retrieve current field from DSS
    read skyview.fits       ! Read in queried file
    disp                    ! Display image

8.11 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.

slice/xslice
The slice is along the x axis. Click the cursor along the y axis to specify the range of y to include.

slice/yslice
The slice is along the y axis. Click the cursor along the x axis to specify the range of x to include.

slice/log
The slice data are plotted on a logarithmic scale.

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.

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.

slice/previous_frame
Use min/max range from the previous slice. Allows for the comparison of results from current slice with the previous one.

slice/minframe=x
Set minimum value to be plot as result of the slice.

slice/maxframe=x
Set the maximum value to be plot as result of the slice.

slice/no_overlay
Draw the slice outside the image area.

slice/color=n
The color to be used for the slice plot.

slice/lwidth=n
Set the width of the slice plot line. Possible values range from thinnest of 1 up to 201.

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).

slice/infile=[filename]
Plot an existing slice output file over the image.

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.

slice/plot
Plot the slice output with qdp. If the /outfile qualifier is not specified, the output file is set to slice.cut.

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.

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.

slice/symbol=n
Sets the symbol to plot the points in the spectrogram case.

slice/error=x
Error bars plotted in spectrogram are at Value +/-(Value*x). Default for x is 0.001.

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.

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.

8.12 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.

8.13 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.

smooth/real
Retain real values after smoothing instead of truncating to integers.

smooth/exposure_map
Smooth the exposure map.

smooth/sigma=x
Enter value of sigma in image pixels for the Gaussian smoothing. If not specified, the default is 1.5.

smooth/scaling_factor=x
Enter a scaling factor.

smooth/back_brightness=x
Scaling factor is calculated by dividing the entered value by the image background (in counts/image pixel).

smooth/to_exposure=x
Scaling factor is calculated by dividing the entered value by the image exposure time.

smooth/x_only
The smoothing is applied only in the x direction.

smooth/y_only
The smoothing is applied only in the y direction.

smooth/wavelet
A wavelet function is used in the smoothing instead of a Gaussian.

Examples:
    smooth/sigma=2.         ! Smooth the current image using a gaussian filter with
                            ! sigma equal to 2 image pixels.

8.14 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 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.

sosta/xpix=x
The source position in x given in units of original pixels. Must be used in combination with the /ypix qualifier.

sosta/ypix=x
The source position in y given in units of original pixels. Must be used in combination with the /xpix qualifier.

sosta/source_box_radius=x
This specifies the half-size of the box where the source intensity is estimated.

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.

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.

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.

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.

sosta/box_background
Estimate the background with boxes defined with mouse.

sosta/background_level=x
Specify a constant background intensity in units of counts/original pixel.

sosta/srcregion=[regionfile]
Specify region to use for source statistics

sosta/bgregion=[regionfile]
Specify region which represent the background.

sosta/expowgt
Weight the psf correction by the exposure map.

sosta/detect_sources
Run source statistics on the sources found in the previous run of detect.

sosta/eef_source=x
The fractional EEF used to determine the source box size. The default is 0.66.

sosta/eef_background=x
The fractional EEF used to determine where the inner background box size begins. The default is 0.98.

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.
     

8.15 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.

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.

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.

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.

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.

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.

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.

srcmrg/csize=x
Set the character size for the source label. Standard character size is 1.0.

srcmrg/font=[fontname]
Set the font of the source label. Use font=? to see available fonts.

srcmrg/just=[left|center|right]
Set the justification of source label. Possible values are left, right, and center.

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.

srcmrg/symbol=n
Set the symbol representing the source location. The value n defines different symbols.

srcmrg/symcolor=n
Set the color index used to plot the source.

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.

srcmrg/symlwidth=n
Set the width of the lines used to draw the source symbol.

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

8.16 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).

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.

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.

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.

Example:
    sum_image              ! sum the current and saved images

8.17 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.

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)

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)

surface/log
Use logarithmic scaling in plotting the surface.

surface/overlay
Overlay the surface on an open device. The default is for the surface plot to be drawn on a new Pgplot page.

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.

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.

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.

surface/noframe
Suppress plotting of the frame which labels the surface axes.

surface/color=n
Set the color used for the cross-sectional lines.

surface/lwidth=x
Set the width of the lines used to draw the timestamp text. Values range from 1 to 201.

surface/csize=x
Set the character size of the axis label text. The default size is 0.6.

surface/font=[fontname]
Set the font of the axis label text. Use font=? to see available fonts.

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.

Example:
     
    surface/non/per=80         ! Plot surface for bright source where non-empty
                               ! average is used for cross-sections

8.18 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).

Examples:
     
    syscall rm -f tmpfile         ! Remove temporary file
     
    set cmd "ls -l"               ! Execute shell command stored
    eval syscall $cmd             ! in variable

8.19 timestamp - plot time/user info

      timestamp[/qualifiers]

Plots time/user info in the lower right corner of the Pgplot device.

timestamp/color=n
Set the color used for the timestamp text.

timestamp/csize=x
Set the character size for the timestamp text. The default size is 0.6.

timestamp/font=[fontname]
Set the font of the timestamp text. Use font=? to see available fonts.

timestamp/lwidth=x
Set the width of the lines used to draw the timestamp text. Values range from 1 to 201.

Example:
     
    timestamp                ! timestamp lower right corner of device

8.20 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.

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.

title/reset
Remove any title settings so the standard title is used.

Examples:
    title "This is a test"        ! write the string `This is a test`
                                  ! above the image when displayed.
     
    title " "                     ! blank both titles
    title/lower " "

8.21 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

uplimit/counts=x
Specify the raw counts, independent of the currently loaded image.

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.

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.

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.

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.

uplimit/noplot
By default the specified area is plotted on the screen. This qualifier turns off the plotting.

uplimit/color=n
The color index to be used in plotting the specified area.

uplimit/lwidth=n
The width of the line used to draw the specified area. Possible values range from thinnest of 1 up to 201.

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).

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.

8.22 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.

value/line
A line is drawn between points.

value/fill
The polygonal area specified is filled with solid color.

value/label
Plots the pixel value of each vertex on the image as they are selected.

value/box=n
Print to the screen the box of values which are within n image pixels from the selected vertex.

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).

value/color=n
Set the color to be used for elements plotted on the image.

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.

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).

value/font=[fontname]
Set the font of the labels. Use font=? to see available fonts.

value/csize=x
Set the character size of the labels. Standard character size is 1.0.

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

8.23 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 ?.

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.

viewport/switch
Switch the current viewport to the one specified with the number qualifier. Coordinate information is reported relative to the current viewport.

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.

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.

viewport/center
Set the viewport to the standard, centered on the device.

viewport/left
Set the viewport to the left half of the device.

viewport/right
Set the viewport to the right half of the device.

viewport/top
Set the viewport to the top half of the device.

viewport/bottom
Set the viewport to the bottom half of the device.

viewport/cursor
Set viewport by selecting a region with the mouse on an open interactive device.

viewport/reset
Reset al.l viewport settings to their defaults.

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.

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 *.

Examples:
     
    viewport 2x2           !  Display subsequent images in quadrants of the
                           !  device, numbered left to right and down
     
    viewport/reset         !  Revert to usual viewport behavior

8.24 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.

Example:
    vig                           ! apply the vignetting

8.25 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.

vplabel/top
Place label along top of image. This is the default.

vplabel/bottom
Place label along bottom of image.

vplabel/left
Place label vertically along left side of image.

vplabel/right
Place label vertically along right side of image.

vplabel/just=[left|center|right]
Set the justification of label text. Possible values are left, right, and center.

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.

vplabel/margin=x
Distance between image edge and label text measured in units of the current character size.

vplabel/color=n
Define the color used for the label text.

vplabel/csize=x
Set the character size for the label text. Standard character size is 1.0.

vplabel/font=[fontname]
Set the font of the label text. Use font=? to see available fonts.

vplabel/lwidth=x
Set the width of the lines used to draw the label text. Values range from 1 to 201.

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.

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.

Example:
     
    vplabel/bottom/just=right "4U 1822-37"  ! plot label just below image
                                            ! right justified
     
    vplabel/right/text=Right                ! plot ambiguous label

8.26 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.

wcs/wcsid=[idstring]
Sets the wcsid to be used by this command.

wcs/mapid=[idstring]
If set, the wcsid associated with the given mapid will be used.

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=?'

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.

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.

wcs/incr
Increment the reference count of the specified wcsid. Primarily for internal memory management.

wcs/decr
Decrement the reference count of the specified wcsid. Primarily for internal memory management.

wcs/show
Print text description of the specified wcsid. Primarily for diagnostic purposes.

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

8.27 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.

write_image/mapid=[idstring]
Write specified map to file. Without this qualifier, the default is to write current map.

write_image/exposure_map
Write the current exposure map to a file.

write_image/display_map
Write the map last displayed to a 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.

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.

write_image/fits
Write an image in FITS format (this is the default).

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.

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.

write_image/exosat
Write image in exosat format. This format is not recommended, as it is machine-dependent and rarely used.

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.

write_image/nowcs
Ignore the wcs data structure when writing the output image, using the internal header with no modification.

Examples:
    write filename          ! write the current image to disk
                            ! in FITS format as `filename.img`

next up previous contents
Next: 9. Data formats Up: XIMAGE User's Guide Previous: 7. Commands G-R   Contents
Alex Padgett 2010-03-25