Next: 9. Data formats
Up: XIMAGE User's Guide
Previous: 7. Commands G-R
Contents
Subsections
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
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
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
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
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.
Example:
script filename ! all commands subsequently executed are stored
! in a file called `filename.xco`
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
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
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
Example:
show ! show the current ximage status
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.
Examples:
skymap/browse/file=browse.txt ! read in a browse file.
skymap/db=optical/label ! overlay all the sources in
! the optical catalogue
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
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.
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.
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.
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.
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.
- 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/bgregion=[regionfile]
Specify region which represent the background.
- 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.
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
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
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
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
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
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 " "
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.
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
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
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
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
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
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: 9. Data formats
Up: XIMAGE User's Guide
Previous: 7. Commands G-R
Contents
Micah Johnson
2006-07-19