Next: 8. Commands S-Z
Up: XIMAGE User's Guide
Previous: 6. Commands A-F
Contents
Subsections
gencolor[/qualifiers] [infile]
Takes event file, and based on the mission, extracts images for three
ranges of energy, representing red, green and blue. Then, these images
are fed into the external program mkcolor, that generates an encoded
color image. This image is read into ximage and displayed.
- gencolor/infile=[file]
Sets the event file to be read in. In displayonly mode,
however, this qualifier is used to set the encoded color image
to be read in for display.
- gencolor/outfile=[image file]
Sets the name of the encoded color output image, which is "gencolor.img" by
default.
- gencolor/jpgfile=[graphic file]
Sets the name of output jpg graphic file into which the color output image
is converted. If a base of color encoding greater than 6 is selected,
jpgfile is automatically set to "gencolor.jpg". If, however, this
qualifier is set by the user, a graphic file is generated with that name
regardless of the base setting.
- gencolor/chanlist=[channel list]
If the default settings for a particular mission are not preferable,
the channel ranges may be set explicitly with this qualifier. The
channel list takes the form: {rminch rmaxch gminch gmaxch bminch bmaxch}
- gencolor/displayonly
If this qualifier is specified, an existing encoded color image is
displayed with the proper color table and levels.
- gencolor/xpix=[x]/ypi=[y]
Extract images centered on this x,y location in original pixel coordinates.
- gencolor/ra=[RA]/dec=[Dec]
Extract images centered on this location in sky coordinates. The
values can be specified either as "hh mm ss"/"deg mm ss" or deg.ddd (in
degrees). The current XIMAGE equinox is assumed. The command show
lists the current XIMAGE equinox, and the command cey changes the
current XIMAGE equinox.
- gencolor/size=n
Extract images with the set size in pixels. XIMAGE only deals in
images of even size. If an odd number is given for the size, the next
highest even number is used. If the size is given as a negative value,
then it defines the size of the image in arc minutes. Be warned that
it will round this number to the closest even pixel.
The value set through this qualifier is assumed for both the x and y
directions. If a non-square image is desired, use the /szx and
/szy qualifiers.
- gencolor/szx=[i]/szy=[j]
These qualifiers perform the same function as /size, except the
extracted image need not be square.
- gencolor/rebin=[n]
Extract images rebinned by a factor of n. n is 1 or a
multiple of 2 (the default is 1).
- gencolor/ecol=[column name]
Set the energy column to which chanlist refers.
- gencolor/cutmode=[HIST|LINEAR|LOG|MAXCOL]
Set the method by which mkcolor uses to cut and scale the intensities.
If the cutmode is HISTogram, a histogram equalization is used to assign
intensity values. If the cutmode is LINEAR, the values will be scaled
linearly from [rgb]min to [rgb]max. If the cutmode is LOG, the values
will be scaled logarithmically from [rgb]min to [rgb]max. If a MAXCOL
cutmode is used, the maximum value for an individual pixel from the
three component images is used as the maximum intensity, and the other
two colors are scaled relative to the that maximum and [rgb]min.
- gencolor/rmin=[value]/rmax=[value]
Set the minimum and maximum value to use from the red image in the
final encoded color image. The default values are the min and max
of the red image.
- gencolor/gmin=[value]/gmax=[value]
Set the minimum and maximum value to use from the green image in the
final encoded color image. The default values are the min and max
of the green image.
- gencolor/bmin=[value]/bmax=[value]
Set the minimum and maximum value to use from the blue image in the
final encoded color image. The default values are the min and max
of the blue image.
- gencolor/base=[n]
Base of color encoding. For example, the default value of 6 assigns
the pixels in each component image (red, green, and blue) a value
from 0 to 5. Recommended base values are 4 and 6 for displaying within
ximage, and 8 for generating a jpg file.
Examples:
gencol/xpix=6000/ypix=6000 file.evt ! center image on (6000,6000)
! generate and display in color
gencol/chan={10 40 41 90 91 202} file.evt ! override default channels
grid[/qualifiers] [dalpha] [ddelta]
Draw a grid in the sky coordinates of the original image over the
displayed image. The default will plot a preassigned grid
spacing. This can be changed by specifying dalpha and ddelta in
degrees. If the primary coordinate frame has been changed with the
'wcs/frameid=n' command, the grid will reflect the specified frame.
Note: The grid command is implemented using the Starlink AST library.
The default behavior of the grid command may be tweaked to a great
degree by setting the 'grid_astoptions' variable to a comma-delimited
list of AST options. For example, the following forces the axis labelling
to inside the frame and plots the numeric labels in red (color index 2):
set grid_astoptions "Labelling=interior,Color(NumLab)=2"
For a full list see the Attributes section of the AST Plot documentation:
http://www.starlink.ac.uk/~dsb/ast/sun211.htx/node553.html
Ximage uses the following plot defaults:
Grid=1 Border=1 Edge(1)=top Edge(2)=right TextLab=0 DrawTitle=0
MinTickLen=0
- grid/radec
Draw the grid in equatorial (R.A./Dec) coordinates.
- grid/galactic
Draw the grid in galactic coordinates.
- grid/equinox=[value]
Set the equinox of plotted coordinate system.
- grid/abbrev
Abbreviate grid line labels to display only changing portions of the
coordinate. For example, if the Declination of a field of view ranges
from 23 40'00" to 24 10'00", the degree position will only be written once
for each unique value (e.g. 23 40'00", 50'00", 24 00'00", 10'00").
- grid/csize=x
Set the character size of the grid line labels displayed by this command.
Standard character size is 0.75.
- grid/color=n
Specify the color index to be used for the grid.
- grid/lwidth=n
Specify the width of the lines used to draw the grid.
- grid/lstyle=n
Specify the style of the lines used to draw the grid: 1 (solid line), 2
(dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5 (dash-dot-dot-dot).
- grid/ticks_only
This will plot only tick marks on the frame of the image, corresponding
to dalpha and ddelta. If not specified a full grid across the
image is plotted.
- grid/labcolor=n
Specify the color index to be used for the numeric grid labels.
- grid/nolabel
Turn off plotting of numeric grid labels, drawing only grid lines.
Examples:
grid ! draw a grid with the default steps in
! in celestial coordinates
grid 0.5 0.5 ! draw a grid in 0.5 deg ra and dec steps
grid/gal ! draw a grid in galactic coordinates
header[/qualifiers]
Lists part of the header information in a pre-set format. All header
information may be viewed through the chheader command.
- header/mapid=[string]
Selects the header to be displayed. By default the mapid
is MAP, which corresponds to the header for the current image map.
EXMAP corresponds to the current exposure map, MAPSV to the saved map,
EXMAPSV to the saved exposure map, and BGMAP to the background map.
help [command name]
Help will describe in detail each XIMAGE command. In help, type the
first few characters of the topic followed by <cr> to get info on
it. Use <cr> to back up a level. Ctrl-D exits help.
Example:
help detect ! show detailed information about command `detect`
hotspot[/qualifiers]
Shows the position of the CMA hot spot on a pre-displayed image. This
command only works for EXOSAT LE-1 or LE-2 images that have not been
rotated. The qualifiers for hotspot merely affect the appearance of
the plotted symbol and label. See the label command for details.
Example:
hotspot ! A small circle is drawn around the expected position
! of the CMA hot spot.
iminfo[/qualifiers] [string]
Overlay information onto a pre-displayed image. In its default
mode iminfo includes image orientation, instrumentation name, exposure
time and image scale. If only a string is given, that string will be
displayed in place of the iminfo command's text information.
- iminfo/textonly
Display only the default text information,
i.e. the instrumentation name, field name, and exposure time.
- iminfo/scale
Display only the bar indicating the image scale, labeled with the sky
coordinate value it represents.
- iminfo/compass
Display only the compass which indicates the image orientation.
- iminfo/short
Display the image orientation compass and the image scale.
- iminfo/widscale=x
Specify the width of the bar indicating the image scale in sky
coordinates. Entered value is interpretted in arcmin.
- iminfo/xpix=x
Specify the x pixel location of where to write the information.
The x value must be given in original pixel coordinates.
- iminfo/ypix=x
Specify the y pixel location of where to write the information.
The y value must be given in original pixel coordinates.
- iminfo/cursor
Select the location where position the information on the display.
For /scale, /compass, and short the information will be plotted
centered at the selected point. For /textonly and string,
the selected point corresponds to the left/bottom point of the
first line of text.
- iminfo/color=n
Set the color index used to draw the scale, compass, and text.
- iminfo/csize=x
Set the character size of the text displayed by this command.
Standard character size is 1.0.
- iminfo/lwidth=n
Set the width of the lines used to draw the scale, compass and text.
- iminfo/font=[fontname]
Set the font of the text displayed by this command. Use font=? to see
available fonts.
Examples:
iminfo ! write the default info
iminfo "text string" ! write "text string" in upper left hand corner
iminfo/scale/cur ! display an image scale centered on the
! clicked point
label[/qualifiers] [text]
This command allows you to write labels anywhere on the display, with any size.
The /xpix and /ypix qualifiers give the label location in pixel coordinates
as labeled in the image frame, the /vx=x/vy=x qualifiers give the
label location in viewport coordinates, and the /ra=x/dec=x qualifiers
give the label location in sky coordinates. If the label has spaces,
the text must be included in double quotes, e.g. "write this here".
A symbol can also be written using the /symbol qualifier.
- label/xpix=x/ypix=x
Define the location of the label in original pixel coordinates (i.e.
the coordinates that the image frame is labeled with).
- label/vx=x/vy=x
Define the location of the label in viewport coordinates, which number
the entire device from 0.0 at the left to 1.0 at the right and 0.0 at
the bottom to 1.0 at the top.
- label/ra=x/dec=x
Define the location of the label in sky coordinates.
- label/cursor
Define the label location as a point selected by the mouse.
- label/color=n
Set the color used to draw the label. The index of each color can be
found by plotting a color legend with the colors command.
- label/csize=x
Set the character size for the label text. Standard character size is 1.0.
- label/font=[fontname]
Set the font of the label text. Use font=? to see available fonts.
- label/just=[left|center|right]
Set the justification of label text. Possible values are left, right,
and center.
- label/angle=x
Set the angle in degrees of the label text. The standard orientation of
the text is at zero degrees. Positive angle values rotate the text
counterclockwise.
- label/symbol=n
Plot a symbol on the screen. The value n defines different symbols. The
center of the symbol is plotted at the given coordinate.
- label/symcolor=n
Set the color index used to plot the symbol.
- label/symcsize=x
Set the character size of the symbol from the default value of 1.0.
Values more than 2.0 will tend to be too large.
- label/symlwidth=n
Set the width of the lines used to draw the symbol.
- label/clip
Turn on clipping, so labels outside viewport are not plotted.
- label/text=string
Set the label text. If no symbol is given, the lower left corner
of the text will be plotted at the given coordinate. In some cases
it may be necessary to use this qualifier to define the label text,
as there can be an ambiguity if the label matches a qualifier or
its abbreviation.
Examples:
label/x=128/y=128 "<-- 4U 1822-37" ! Write this label
label/x=128/y=128/text=X ! Write ambiguous label
levels[/qualifiers] [filename]
List and manipulate intensity levels. If no qualifiers are given, the levels
used to display last the current image are printed to the screen.
Note that the intensity levels are listed only after the display or contour
command have been used, since they are calculated by default within these
commands. User defined levels may be input using the qualifier /file
which is an ascii file containing one level per row. The number of
levels is preserved between ximage sessions.
- levels/number=n
Set number of intensity levels to use when displaying images.
- levels/reset
Reset number of intensity levels to default of 16.
- levels/show
List intensity levels for currently displayed image. This is the
default action if no qualifiers are given.
- levels/file=[filename]
Specify a levels file for saving or loading. A levels file may also be
specified as the last argument of the command.
This qualifier must be used in conjunction with the qualifiers /save or
/load.
- levels/save
Save current intensity levels to a file.
To be used with the qualifier /file=[filename].
- levels/load
Load intensity levels from a file. To be used with the qualifier
/file=[filename]. These user defined levels are applied by the
display or contour commands using the syntax display/loaded
or contour/loaded.
- levels/histo
Calculate levels based on histogram equalization.
- levels/linear
Calculate levels based on linear scaling.
- levels/log
Calculate levels based on logarithmic scaling.
- levels/sqrt
Calculate levels based on square-root scaling.
- levels/minlevel=[value]
Set minimum level in levels calculation.
- levels/maxlevel=[value]
Set maximum level in levels calculation.
- levels/list=[levels list]
Set levels through use of list. Syntax example: "1 2 3 4" or {1 2 3 4}
Examples:
levels/num=64 ! Set the number of intensity levels to 64 for
! future images that are displayed
levels/load saved.lev ! Load levels from file `saved.lev`
log [filename]
Write a log file containing the screen output generated by XIMAGE.
The option filename specifies the name of the log file; the file
extension is .log. If no filename is specified then the default of
ximage.log is used.
A log file will be closed if:
- a new log file name is specified (this will open a new log file);
- the filename is given as "none";
- or XIMAGE is exited.
The log files are in plain ASCII text.
Example:
log results ! open a log file called results.log
map[/qualifiers] [mapid]
If given no qualifiers or arguments, prints a description of the
currently loaded image maps to screen, including the filename,
size, rebinning factor, center, and codes which represent
map-altering operations performed in XIMAGE. Also, the current map
and displayed map are indicated.
If a mapid with no qualifiers is given, the current map, the map
which commands operate on by default, is set to that mapid.
Note that the full id for a map is MAP1-9 for
image maps and EXMAP1-9 for associated exposure maps. These
may be shortened to 1-9 and EX1-9, respectively.
- map/copy [frommap] [tomap]
Copy the contents of [frommap] to the [tomap] position, overwriting
anything that may have been there.
- map/move [frommap] [tomap]
Move the contents of [frommap] to the [tomap] position, overwriting
anything that may have been there, and then freeing the memory occupied
by the original [frommap].
- map/free [mapid]
Free the memory occupied by [mapid].
- map/isequal [mapid] [mapid]
Returns 1 if mapids are equal, 0 otherwise. Useful in Tcl scripting for
determining whether CUR (current map) and DIS (display map) are the same
map as MAP1, etc. For example, in a Tcl if statement
if [map isequal map1 dis] { do something }
- map/gettmp
Returns temporary mapid independent of slots MAP1 to MAP9. Useful in
Tcl scripting when a mapid is needed, but the danger of overwriting
one of the existing map slots must be avoided. For example,
set newmap [map gettmp] then perform some action with temporary map
and release it with map free $newmap.
Examples:
map ! Lists the current status of all maps
map 3 ! Sets the current map to MAP3
map/copy 1 2 ! Copies MAP1 to MAP2
map/move 2 1 ! Moves MAP2 to MAP1
map/free exmap3 ! Frees the memory occupied by EXMAP3
marith[/qualifiers] [expression]
The marith command allows the user to perform arithmetic on stored
image maps. Valid operations are +,-,/,*,int(), and
float(). The +,-,/,* operators may have only two arguments,
one of which must be an image map, specified by the full id for an
image map (MAP1-9) or an associated exposure map (EXMAP1-9), and the
other argument may be a numeric constant or another map. MAP1-9 may
not be shortened to 1-9 in the expression, as the parser has no way of
differentiating between an integer constant and a map shortened to its
numeric id. The int and float functions may only take a map as an
argument. Note that this command is currently limited to one
operation.
The results of the operation are stored in the current map.
Alternately, the output map may be stored in the map specified with
marith's mapout qualifier. For example,
marith/mapout=map3 map1+map2 behaves in the following arithmetic
sense: map3=map1+map2
The map output from marith will have an integer or float type depending
on the arguments and operations used to create it. The / and
float() operations will always result in a float type. The int()
operation will always result in an integer type. The +, -, and
* operations will result in an integer type if both of their arguments
are integers, otherwise a float type will result.
When only one map is involved in an operation, all header information
is copied from that map into the output map. The DATAMIN/MAX keywords
are updated after the map arithmetic is performed. Consequently, the
coordinates of the output image are identical to the input map. When
two image maps are involved, the first image map of an operation is
assumed as the output image map's header, unless overridden with the
hdrid qualifier. Image maps with rotation, centering and/or size
different from the output image will be transformed to match its
coordinates. Note: In the transformation, a Monte Carlo distribution of
the pixel values is done. The total number of counts is preserved.
The user may also set explicit coordinates for the output image
independent of any existing header. Use the crota qualifier for
rotation, which is specified in degrees and assumes the convention
where crota=0 when celestial north is up. Use the ra, dec, and
(optionally) equinox qualifiers to specify the output image map's
center.
The output map inherits its size from the larger of the two
input maps. The user may specify the desired output size with the size
qualifier, or if a nonsquare output image is desired, the szx and szy
qualifiers are available.
When summing images with associated exposure maps, their exposure maps
will also be combined. Other operations between maps with associated
exposure maps will result in an output map with no exposure map.
- marith/mapout=[mapid]
Set the map location where the results of the operation should be
stored, overwriting anything that exists in that location.
- marith/hdrid=[mapid]
Set the map whose header should be copied into the final image map,
inheriting the center, rotation, etc. of the indicated hdrid. The
necessary offset, rotation, etc. will be applied to the maps to
yield an image with proper coordinates.
- marith/expr=[expression]
Specify the mathematical expression used to calculate the resulting
image map. Valid operations include: +,-,*,/,int(),float()
- marith/crota=[value]
Specify the rotation of the resulting image map
- marith/ra=[value]/dec=[value]/equinox=[value]
Specify the center of the resulting image map in sky coordinates.
If equinox is not specified, the current equinox, defined by the cey
command, is used.
- marith/size=n
Specify the size of the resulting image map.
The value set through this qualifier is assumed for both the x and y
directions. If a non-square image is desired, use the /szx and
/szy qualifiers.
- marith/szx=n/szy=m
Specify the size of the resulting image map, where the size in x
doesn't have to be the same as the size in y.
Examples:
marith int(map2) ! Truncate MAP2, store in current
marith/map=1 int(map1) ! Truncate MAP1, overwriting itself
marith/map=3 map1+map2 ! Add MAP1 and MAP2, store in MAP3
marith/map=3/hdr=2 map1+map2 ! Same as above, except use MAP2 coords
moper[/qualifiers] [mapid] [mapid]
The moper command performs elementary operations between image maps
with no consideration for matching sky coordinates. If two images are
operated on they must be of identical size. This command is primarily
intended for internal use by marith.
- moper/mapout=[mapid]
Set the map location where the results of the operation should be
stored, overwriting anything that exists in that location. If mapout
is not set, the output image will be written to the current map.
- moper/hdrid=[mapid]
Set the map whose header should be copied into the final image map,
inheriting the center, rotation, etc. of the indicated hdrid.
By default, operations with one map argument copy the header from the
that map and operations with two map arguments copy the header from the
first map given.
- moper/add [arg1] [arg2]
Add images together. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
- moper/sub [arg1] [arg2]
Substract images. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
- moper/mult [arg1] [arg2]
Multiply images. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
- moper/div [arg1] [arg2]
Divide images. An argument can be a mapid or a constant value, but
at least one of the arguments must be a mapid.
- moper/int [mapid]
Truncate values in image to integer value.
- moper/float [mapid]
Set values in image to float (i.e. real) values.
- moper/procname=[name]
Define a Tcl proc to operate on each value in the image. The proc must
take one argument (the original image value) and return the new image
value. For example:
proc negzero {value} {
if { $value < 0. } { return 0. }
return $value
}
The command moper mopproc=negzero map1 will set al.l negative values in
map1 to zero.
offset[/qualifiers]
Given two points in the current image, calculate the offset between
them in sky coordinates.
- offset/cursor
Specify two points by clicking the mouse on the current plot.
- offset/ra1=hms/dec1=dms/ra2=hms/dec2=dms
Specify the RA/Dec for two points as part of the command line.
The RA can be given as either decimal degrees or as hr, mn, sec.
In the latter case it must be included in double quotes
(e.g. /ra="12 23 12.1") The Dec can be given as either
decimal degrees or as degrees, minutes and seconds. In the latter case
it must be included in double quotes (e.g. /dec="50 31 10.1")
- offset/x1pix=x1/y1pix=y1/x2pix=x2/y2pix=y2
Specify the coordinates for two points in detector coordinates.
- offset/plot
Plot both points. By default, nothing is plotted.
- offset/symbol=n
Set the symbol used in plotting both points.
- offset/csize=x
Set the character size of the symbol. Standard character size is 1.0.
- offset/color=n
Set the color used to plot the symbol.
- offset/lwidth=n
Set the width of the lines used to draw the symbol.
Examples:
off/cur ! Use the mouse to find the offset
off/x1=6270/y1=1973/x2=1112/y2=1985 ! Use x,ypix coords
pcontour[/qualifiers]
Core contour plotting routine. Primarily for internal use by
contour. See contour for description of following qualifiers:
csize, font, noframe, nobox, overlay, color, lwidth,
lstyle, first_contour_drawn
- pcontour/nolabel
Turns off labelling of X/Y axis
- pcontour/trf=[transformation matrix]
Transformation used to draw contours, so coordinates align with
underlying image in overlay case. Formatted as six element list
(e.g. {0 1 0 0 0 1} for no transformation).
- pcontour/fromwcs=[wcsid]
Transformation used to draw the contours assumes the starting
coordinates are those associated with the specified wcsid.
If not defined, the wcsid associated with the mapid being plotted
is used.
- pcontour/towcs=[wcsid]
Transformation used to draw the contours assumes the final
coordinates are those associated with the specified wcsid.
If not defined, the wcsid associated with the mapid being
overlayed on is used.
- pcontour/refresh/xmin=[n]/xmax=[n]/ymin=[n]/ymax=[n]
Plots contours for portion of map defined by array indices.
Primarily for internal use by the zooming and recentering
capabilities of /xtk device.
pimage[/qualifiers]
Core image plotting routine. Primarily for internal use by
display. See display for description of following qualifiers:
csize, font, noframe, nobox, overlay, color, lwidth, lstyle
- pimage/nolabel
Turns off labelling of X/Y axis
- pimage/refresh/xmin=[n]/xmax=[n]/ymin=[n]/ymax=[n]
Plots image for portion of map defined by array indices.
Primarily for internal use by the zooming and recentering
capabilities of /xtk device.
pixel_to_ra_dec[/qualifiers]
Converts a specified pixel position in the current image to RA and DEC.
If /cur is not specified, then XIMAGE will ask for X and Y pixel
coordinates.
- pixel_to_ra_dec/xpix=x
Specify the X coordinate of the pixel position
- pixel_to_ra_dec/ypix=x
Specify the Y coordinate of the pixel position
- pixel_to_ra_dec/cursor
The pixel position is specified using cursor.
- pixel_to_ra_dec/symbol=n
Set the symbol used to plot the position.
- pixel_to_ra_dec/color=n
Set the color used to draw the symbol.
- pixel_to_ra_dec/csize=x
Set the character size of the symbol.
- pixel_to_ra_dec/lwidth=n
Set the width of the lines used to draw the symbol.
Example:
pixel_to_ra_dec/cur ! Input the position using the cursor.
powplot[/qualifiers] [filename]
This command writes a temporary FITS file and spawns POWplot
to view it.
It is important to note that any region files written from POWplot will not
correct for any rebinning made within XIMAGE. The XIMAGE circ and
box commands do not suffer from this problem.
To read POWplot regions back into XIMAGE, the region values need to be
multiplied by the XIMAGE rebinning factor and the reference pixel value
as reported within XIMAGE needs to be added.
- powplot/filename=[filename]
Set the name of the temporary file, which is pow_temp.img by default.
The temporary file may also be specified as the last argument of the
command.
- powplot/template=[templatename]
Set the template used to write header keywords. Use template=? to
see available templates. The default is sufficient in most cases.
Example:
powplot ! displays currently loaded image in POWplot
prarray[/qualifiers] [array name]
This command prints the values contained in a Tcl array to the screen
or to a file. A related command, rdarray exists for
reading text files into an array.
- prarray/varname=[variable name]
Sets the variable name of the array that is to be printed.
- prarray/filename=[file location]
Sets the output text file location. The command will write
values to the screen by default, unless filename is set.
- prarray/noheader
By default the screen output lists the array name and the column names
above the column values, and file output lists the column names in a
command line preceded by a "#". When this option is set, only the column
values are printed.
- prarray/comments=[comment string]
The string specified with this qualifier will be printed to
file preceded by a "#" to indicate a comment. To specify multiple lines
insert a "
n" character in the comment string.
- prarray/order=[column list]
The order that the array values are printed out may be altered by
setting this option to a comma-delimited list of column names.
For example, suppose the array inarray contains a dec and ra
column. In order to display ra before dec, use order=ra,dec.
To see what column names are available in the array, use the command
array names inarray.
- prarray/index
This qualifier may be used to print a column which doesn't exist in the
array, corresponding to the index number in the list. Tcl uses a
0-index system, so it will begin with 0.
- prarray/iplus
This qualifier may be used to print a column which doesn't exist in the
array, corresponding to the index number plus one in the list. Tcl uses a
0-index system, but in some cases one may want to start with 1 by using
the iplus option.
Examples:
prarray/iplus inarray ! Print `inarray` to the screen with numbers
prarray/file=out.txt inarray ! Write `inarray` to the file out.txt
psf[/qualifiers]
Calculates differential and integral Point Spread Function and plots
them onto the currently defined graphic device. The expected PSF for a
pointlike source is also calculated and displayed. This command needs
an accurate estimate of the image background. The psf command uses
as background value the results of the previously run background
command, but it can be overridden with the /back qualifier.
By default the command calculates counts within an annulus which is
incremented by one pixel per iteration.
- psf/back=x
Enter the image background in units of cts/original-pixel.
- psf/energy=x
The expected PSFs for different detectors are derived in XIMAGE using,
when available, the 'theoretical' algorithms usually derived from
ground or inflight calibration data. Dependent on the detector
the expected PSF can be energy dependent. This qualifier allows
to specify the single 'interesting' energy value (in keV, the default
value is 1.0). The expected PSF is plotted together with the measured PSF.
- psf/engfile=[filename]
This qualifier may be used to input a spectrum to evaluate the energy
dependence of the psf, instead of a single value. The appropriate
file can be derived using extract/engfile for a specific regionfile.
The energy dependent psf is calculated only if XIMAGE has a valid
routine for that mission.
- psf/pileup
When this qualifier is given, the psf calculation assumes the center of
the source is piled-up. The extent of the piled-up region is determined
by including all annuli that contain zero counts starting from the
center. The next non-zero annulus is also included in the piled-up
region to account for the edge of the region. The remainder of the
source is used to scale the theoretical psf for comparison with the
actual distribution.
- psf/radius
Give the outer radius in arcminutes.
- psf/box
Use boxes, instead of annuli. Concentric boxes are plotted on the image.
- psf/cursor
Enter the position of the centroid and outer radius using the cursor.
- psf/xpix=x/ypix=y
Specify the x and y coordinate for the center of the box position.
- psf/calfilegen
The /calfilegen qualifier is obsolete. See /multpsffile.
- psf/multpsffile=[filename]
Write the psf to the specified file. If the file already exists,
append the results as another column in the file. This can be used as
'calibration' file within XIMAGE by setting PSFFILE in the mission
database for use by detect, sosta or even psf.
- psf/fileplot=[filename]
Write the psf results to the specified ASCII file. If not specified,
the result is written to psf.qdp by default.
- psf/print
Write to the screen the quantities calculated for each step.
- psf/color=n
Set the color used to plot the concentric boxes of the /box qualifier.
- psf/lstyle=n
Set the line style used to plot the concentric boxes of the /box
qualifier: 1 (solid line), 2 (dashed), 3 (dot-dash-dot-dash), 4
(dotted), 5 (dash-dot-dot-dot).
- psf/lwidth=n
Set the line width used to plot the concentric boxes of the /box
qualifier.
- psf/noplot
Suppress automatic plotting of psf in QDP, allowing for script-driven
sessions to continue without user intervention.
Examples:
psf/cur/back=2.3e-03 ! calculate the psf for a position specified
! by the cursor and setting the background.
psf/cur/back=2.3e-03/rad=6 ! calculate the psf for a 6 arc min rad
ra_dec_to_pixel[/qualifiers]
Converts RA and Dec into the image pixel coordinates.
If the image is displayed, a crosshair symbol is drawn at the corresponding
position. Coordinates may be input via the qualifiers /ra and /dec or
by answering RA/Dec prompts. Input coordinates are assumed to be in the
current equinox set with the cey command. The input ra, dec, and
equinox are saved between ximage sessions. This saved position is
available as a default at the RA/Dec prompts. Press return without
entering a value to accept the default.
- ra_dec_to_pixel/ra=hms
Give the RA as part of the command line. The RA can be given as either
decimal degrees or as hr, mn, sec. Acceptable formats include:
12 23 12.1, 12:23:12.1, 12h23m12.1s In the space-delimited case the
value must be included in double quotes (e.g. ra="12 23 12.1")
- ra_dec_to_pixel/dec=dms
Give the Dec as part of the command line. The Dec can be given as either
decimal degrees or as degrees, minutes and seconds. Acceptable formats
include: 12 23 12.1, 12:23:12.1 In the space-delimited case the value
must be included in double quotes (e.g. dec="12 23 12.1")
- ra_dec_to_pixel/circle=x
Draw a circle with a radius in arcsec around the given position. Useful
for drawing error circles.
- ra_dec_to_pixel/symbol=n
Set the symbol plotted at the centroid location. The default value is
8, a circle with crosshairs.
- ra_dec_to_pixel/csize=x
Set the character size of the symbol. Standard character size is 1.0.
- ra_dec_to_pixel/color=n
Set the color used to plot the symbol or circle.
- ra_dec_to_pixel/lwidth=n
Set the width of the lines used to draw the symbol or circle.
- ra_dec_to_pixel/lstyle=n
The style of the line used to draw the circle: 1 (solid
line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted), 5
(dash-dot-dot-dot).
Examples:
ra ! Enter the RA and Dec from a prompt
ra/circle=600.0 ! Draw a 600 arc sec radius circle centered
! at the given ra and dec
ra/dec="-61 12 1.0"/ra="11 45 2.1" ! Give the RA and Dec on the command line
rdarray[/qualifiers] [filename]
This command reads a text file containing columns of values into a Tcl
array. Text files can come in many formats, so the command is
flexible to support them. A related command, prarray exists for
writing arrays to screen or back to a file.
- rdarray/filename=[file location]
Sets the input text file location. The file must contain columns of
values, using a consistent delimiter. The number of values in each
column must be equal. Lines beginning with "#" or "!" are interpretted
as comments.
- rdarray/varname=[variable name]
Sets the variable name of the array that the file is read into.
By default, this is set to inarray.
- rdarray/delim=[character]
Sets the delimiter used to parse each line of the text file. Quoting
the character is recommended (e.g. delim="|") By default, whitespace
is used as the delimiter.
- rdarray/readhead
If set, the first non-comment line will be used as the column names.
If the text file looks like this:
|name |ra |dec |pmag |
|GSC 1800-01800|03 46 54.36|+24 06 43.2|14.01|
|GSC 1800-01684|03 46 58.92|+24 05 21.3|11.67|
|GSC 1800-02109|03 47 02.50|+24 09 00.0|14.30|
|GSC 1800-01790|03 46 56.80|+24 08 57.8|13.50|
The array is created:
$inarray(name) => {{GSC 1800-01800} {GSC 1800-01684} {GSC 1800-02109}
{GSC 1800-01790}}
$inarray(ra) => {{03 46 54.36} {03 46 58.92} {03 47 02.50} {03 46 56.80}}
$inarray(dec) => {{+24 06 43.2} {+24 05 21.3} {+24 09 00.0} {+24 08 57.8}}
$inarray(pmag) => {14.01 11.67 14.30 13.50}
If readhead is not set and headers is not used to define column
names, numbers beginning with 1 through the number of columns will be
used as the column names.
- rdarray/headers=[header list]
If column names are not in the text file, they may be assigned with this
qualifier by giving a comma-delimited list of values (e.g.
headers=name,ra,dec,pmag). If headers is not used and readhead is
not set, numbers beginning with 1 through the number of columns will be
used as the column names.
- rdarray/columns=[column list]
This qualifier may be used to limit the columns which are actually saved
in the array by giving a comma-delimited list of column names.
In the readhead example, if only RA and Dec values are desired, use
columns=ra,dec.
- rdarray/expr=[regular expression]
Sets a regular expression used to match every line of the text file.
If matchlist is not set the effective behavior is to ignore every line
that matches the expression. For example, a file may use a % as the
first character of a comment line. In that case expr="^%" would match
all lines beginning with a percent sign and ignore them. A regular
expression may also have submatches saved if matchlist is set. See
matchlist for details.
- rdarray/matchlist=[variable list]
If the regular expression set with expr contains sub-expressions
surrounded by parentheses, each sub-expression in order will be assigned
to variables given in the matchlist. For example, given the following
file:
DATE: May 23, 2002
name ,ra ,dec ,pmag
GSC 1800-01800,03 46 54.36,+24 06 43.2,14.01
GSC 1800-01684,03 46 58.92,+24 05 21.3,11.67
GSC 1800-02109,03 47 02.50,+24 09 00.0,14.30
GSC 1800-01790,03 46 56.80,+24 08 57.8,13.50
The following command:
rdarray delim="," readhead {expr=^DATE: ([a-zA-Z]+) ([0-9]+), ([0-9]+)}
matchlist=month,day,year
will assign May to the month variable, 23
to the day variable and 2002 to the year variable. Note: The use of
square brackets in the expression can be misinterpretted as Tcl command
evaluations if the entire qualifier is not surrounded by curly brackets.
If more than one line matches the expression, the matching will be
appended to the variables making them lists of values.
- rdarray/sublist=[list of expr/substitution pairs]
The sublist option may be used to alter the lines of the text file
before delimiter-based processing occurs. The list must have an even
number of elements, the first contains the expression to match and the
second contains the substitution, the third contains the next
expression and the fourth contains the corresponding substitution and
so on. For example, suppose the text file contains a special string
corresponding to a null value, NULL or INDEF, and for your purposes 0
is more appropriate. The following command would perform the
substitution: rdarray {sublist={INDEF|NULL} {0}} file.txt Note, when
specifying lists, enclosing the entire qualifier in curly brackets may
be necessary. The syntax, rdarray sublist=[list {INDEF|NULL} {0}]
will also work.
If the expression contains sub-expressions surrounded
by parentheses, the substitution may contain references to those
sub-matches in the form of a backslash followed by the sub-match number.
For example, suppose the file contains RA and Dec as
follows:
00 47 10.984 -11 53 18.92
00 47 09.153 -11 52 52.70
00 46 58.055 -11 50 36.60
00 47 00.064 -11 52 49.89
00 46 56.044 -11 54 32.13
The default behavior is to give each number its own column, clearly not
the desired result. The sublist option can help you merge these based
on a pattern:
rdarray {sub={([+-]*[0-9]+) ([0-5][0-9]) ([0-5][0-9]\.[0-9]+)} {\1:\2:\3}}
file.txt
The parser will then see:
00:47:10.984 -11:53:18.92
00:47:09.153 -11:52:52.70
00:46:58.055 -11:50:36.60
00:47:00.064 -11:52:49.89
00:46:56.044 -11:54:32.13
A colon has been inserted between the numbers making up the coordinates,
grouping them together.
Example:
rdarray var=src file.txt ! Read space-delimited file into `src` variable
read_image[/qualifiers] [filename]
Read an image into the current map. If no file type is specified,
a FITS file is assumed, and various checks are made to identify it as
either an image or event file. The only non-FITS type supported is
EXOSAT, a binary machine-dependent format indicated by the /exosat
qualifier.
Whether specified with the file qualifier or as an argument
to the command, any FITS file given as a filename may use the
extended filename syntax briefly described on this page:
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/filters.html
A common usage, for example, is to filter out events with certain
energies, filename.evt[EVENTS][PHA 
5]. The Tcl environment
used by ximage, however, interprets square brackets [] as commands
within commands. In order to prevent expansion by Tcl, use curly
braces to quote the filename. For example,
read {filename.evt[EVENTS][PHA > 5]}
- read/mapid=[idstring]
Read image into specified map. Without this qualifier, the default
is to read into current map.
- read/exposure_map
The /exposure_map qualifier indicates the image contains an exposure
map and loads it into the exposure map arrays. It can be displayed
using the disp/exp command.
- read/exosat
File is an image in EXOSAT format. This is machine specific.
- read/fits
File is an image in FITS format.
- read/rfits
File is in FITS photon event format.
- read/xpix=x
Load an image centered on this x location in original pixel coordinates.
Requires the /ypix qualifier to also be set.
- read/ypix=x
Load an image centered on this y location in original pixel coordinates.
Requires the /xpix qualifier to also be set.
- read/ra=[value]
Load an image centered on the specified RA. The value can be specified
either as ra="hh mm ss" (hour minute and second) or ra=deg.ddd (in
degrees). The current XIMAGE equinox is assumed, unless the /equinox
qualifier is set. The command show lists the current XIMAGE equinox,
and the command cey changes the current XIMAGE equinox.
- read/dec=[value]
Load an image centered on the specified Dec. The value can be specified
either as dec="deg mm ss" or dec=deg.ddd (in degrees). The current
XIMAGE equinox is assumed, unless the /equinox qualifier is set. The
command show list the current XIMAGE equinox, and the command cey
change the current XIMAGE equinox).
- read/equinox=n
To specify the equinox if the requested image center is given using
/ra and /dec. By default the current XIMAGE equinox is assumed.
- read/size=n
This qualifier specifies the image size in pixels. XIMAGE only deals in
images of even size. If an odd number is given for the size, the next
highest even number is used. If the size is given as a negative value,
then it defines the size of the image in arc minutes. This is useful
when overlaying or comparing two images. Be warned that it will round
this number to the closest even pixel.
When a fits image is read in and no size is specified, the size of
the image (NAXIS1/2) is used. By default, however, a fits image
is limited to 1024x1024. This default limit can be changed by setting
the 'read_image_limitsize' variable. A value of zero is interpretted
as setting no limit for the image size. For example, if
set read_image_limitsize 0 is entered in the ~/.ximagerc file,
a 2048x2048 fits image will be read into ximage in its entirety.
The value set through this qualifier is assumed for both the x and y
directions. If a non-square image is desired, use the /szx and
/szy qualifiers.
- read/szx=n
This qualifier is identical to the /size qualifier except it
specifies the image size in the x direction. Use with /szy to define
the image size.
- read/szy=n
This qualifier is identical to the /size qualifier except it
specifies the image size in the y direction. Use with /szx to define
the image size.
- read/rebin=n
As the image is read into memory it is rebinned by n bins. n is usually
1 or a multiple of 2 (the default is 1). If the input file is an event
list, it is possible to use float values.
For example, rebin=0.5 divides each original pixel in
half in each dimension, redistributing the events among
the new sub-pixels. If an event falls exactly on a horizonal pixel
boundary, it will be counted in the pixel above. If it falls on a
vertical pixel boundary, it will be counted in the pixel to the right
of the event coordinate.
If used in conjunction with the 'exposure_map' option, the rebinned
pixels are averaged rather than summed.
- read/bscale=x
Apply a scaling to the read in image.
- read/bzero=x
Add an offset to the read in image.
- read/detector
Allow to accumulate an image using the content of the DETX, DETY columns.
- read/expr=[expression]
A boolean expression used to filter rows in an event file. Every event
for which the expression is false will be excluded. The expressions are
identical to the row-filtering mechanism provided by FTOOLS through
CFITSIO. Run the ftool fhelp rowfilter for documentation.
- read/xcol=[column_name]
Accumulate an image using the column specified by this qualifier for the
x coordinate.
- read/ycol=[column_name]
Accumulate an image using the column specified by this qualifier for the
y coordinate.
- read/zcol=[column_name]
Accumulate an image by piling the value in the zcol column for
each event onto the pixel it falls in. When /zcol is not specified
the default is to simply add one to a pixel for each event which falls
in it.
- read/ecol=[column_name]
Set name of energy column to read in. Generally used in association
with the /emin and /emax qualifiers. For most known missions there
is already a defined energy column. In those cases, this qualifier will
override the value set in the mission information database.
- read/emin=n
The minimum energy channel to accept from the energy column defined in
the mission info database or through the /ecol qualifier.
- read/emax=n
The maximum energy channel to accept from the energy column defined in
the mission info database or through the /ecol qualifier.
- read/tcol=[column_name]
Set name of time column to read in. Generally used in association
with the /tmin and /tmax qualifiers. The default is TIME, but
this qualifier will override that value.
- read/tmin=x
The minimum time accepted. The time value should be given in the same
format used in the time column of the fits file.
- read/tmax=x
The maximum time accepted. The time value should be given in the same
format used in the time column of the fits file.
- read/gtiext=[gtiext]
When reading a FITS event file, the default is to use the first
extension with a name containing 'GTI' to filter events. The
treatment of the GTI extensions within the event file being read can
be specified with this option. Possible expressions include an
extension number (e.g. 3), extension name (e.g. GTI1), extension name
pattern (e.g. GTI*), or any of these combined with an OR/AND function
(e.g. OR(GTI1,GTI2) ). If an OR/AND function is specified, and the
expression matches multiple extensions (e.g. AND(GTI*) matches
GTI1,GTI2,GTI3) all matching extensions will be combined together.
Otherwise, only the first matching extension will be used as a filter
on the events.
An extension name pattern can contain any of the
following wildcards: '*' will match any sequence of characters
(including zero characters), '?' will match any single character, and
'#' will match one or more contiguous digits.
In some cases, there are mission-specific default settings (see
'chmdb' command) for GTIEXT. If this option is set, these defaults
are overridden.
- read/gtifile=[gtifile]
The GTI extension contained in the file specified by this qualifier
constrain which time intervals events must fall in to be accepted.
If /gtimode is not specified, the GTIs specified by the /gtifile
qualifier substitute for the GTIs in the event file being read. An explicit
extension number may be specified. For example, fitsfile.fits[2] or
fitsfile.fits+2 are both valid methods.
Multiple GTI files may be combined using an AND/OR function either
with a comma-delimited list of files (e.g. AND(a.gti,b.gti) ) or by
providing a text file listing all the files using the '@' syntax (e.g.
OR(@gtifile.list) ).
- read/gtimode=[and|or|sub|none]
This qualifier determines how the GTI extension(s) of the read in event
file, determined by the /gtiext qualifier, interacts with the GTIs
specified through the /gtifile qualifier. The and mode logically
ands the intervals together, resulting in a set of intervals such that
only the times where both sets have good times are present. The or
mode logically ors the intervals together, resulting in a set of
intervals such that the times where either set has a good
time is represented. The sub mode substitutes the /gtifile
intervals, throwing out the ones in the file being read. The none
mode ignores all GTI constraints, effectively assuming all events fall
in a good time.
- read/image_number=n
Specify which image of a 3D cube to read. Each integer, from 1 to the
depth of the cube represents a separate 2D slice of the data. If this
is not specified, the top slice of a cube (n=1) will be read in.
- read/file=filename
Allow to specify the filename of the image or event list using a qualifier
instead of specifying the filename on the command line.
- read/regionfile=filename
Specify a spatial region file. The circle or box region file can be
created using the command circle and/or box. If no size and
centering is specified, the bounds of the region will be used.
Prior to version 4.2 the region bounds had no effect on size and
centering. To restore that behavior, enter the line
set read_image_regcenoff 1 in the ~/.ximagerc file.
- read/time_image
The /time_image qualifier generates a time variability map by
calculating the time chi-square distribution in a pixel. Chi-square
values are stored in each pixel scaled from 0-200, values greater than
100 mean the source is probably variable. It's important to make sure
there are a sufficient number of photons per bin, by heavily rebinning
the image. To use this option the event file must be time ordered.
- read/color_image
The /color_image qualifier generates a color weighted image by using
the PI or a PHA column in an event list. In each pixel the energy
information is summed and weighted by the number of photons. The
resulting image is scaled from 0-100.
- read/unknown
Treat image as from an unknown mission, ignoring any mission-specific
settings. For example, the original pixel coordinates will be unknown
and XIMAGE will have to display straight image coordinates.
Examples:
read/size=512/xpix=6000/ypix=6000 ! center image on (6000,6000)
! with an image size of 512x512
read/xcol=dx/ycol=dy ! use `dx` and `dy` columns
! to construct image
read/ecol=pi/emin=24/emax=224 ! exclude events where `pi`
! column is outside 24-224
rebin[/qualifiers] factor
The current image is rebinned by the number of bins specified by the
factor parameter. The /mode parameter can be used to apply some
slight smoothing, or do rebinning for mosaics.
- rebin/mode=n
If n=0, the new pixel values are obtained by averaging pixels involved
in the rebinning (e.g. rebin=2, 4 pixels). The image and pixel size
remains the same. If n=1, which is the default, "normal" rebinning is
done. The image and pixel size change by the rebinning factor. If
n=2, the pixel size changes, but the image size remains the same,
shrinking the image in the frame. This mode is useful for image
mosaics.
mode =0 rebinning with slight smoothing
mode =1 normal rebinning, the default
mode =2 rebinning for image mosaics
- rebin/rebinning_fact=m
Used to specify the rebinning factor. The command rebin/reb=2
is equivalent to rebin 2. Note: The rebin factor must be an integer
value. Use the remap command if a non-integer rebin is desired.
Example:
rebin 8 ! rebin the image by a factor of 8
recall[/qualifiers] [n]
The command recall is used to list previous commands. The global
Tcl variable, htyshow, determines the default number of commands to
list. Initially this is set to 20, however it may be redefined by
the user. Any command can be reexecuted by typing recall n where n
is the command number given in the listing.
The history of commands is preserved between sessions of Ximage by
storing them in a file at '~/ximage.hty'. The name of this file can
be changed by setting the 'ximage_history_file' variable in
'~/.ximagerc'. No history file is written if this variable is set to
an empty string. For example:
set ximage_history_file ""
- recall/max
Specify the maximum number of commands to list. Note, this number
only applies to the current command listing. If max is not specified,
the value set in the Tcl global variable htyshow is always used.
Examples:
recall/max=100 ! display last 100 commands
recall 242 ! run command number 242
remap[/qualifiers]
The remap command maps an existing image to new coordinate system,
distributing (or resampling) the original pixels into the new pixel
grid.
The default resampling method is CONSERVE, which redistributes the
values in the original image pixels based on the fractional area
intersecting the new pixel, conserving the total value. Integer values
are redistributed using probabilities to preserve Poissionian
characteristics. This pixel resampling method is the most rigorous and
hence the slowest by a large margin.
The remaining pixel resampling methods are directly implemented in the
Starlink AST library (method descriptions excerpted from astResample
docs). Note: The params qualifier is a list of
parameters that may be used to tweak the operation of some remap methods.
See the description of each method for the definition of params in
that context.
NEAREST: The value of the input pixel with the nearest center to the
interpolation point is used. This is very quick to execute and will
preserve single-pixel features in the data, but may displace them by up
to half their width along each dimension. It often gives a good cosmetic
result, so is useful for quick-look processing, but is unsuitable if
accurate geometrical transformation is required.
LINEAR: Uses linear interpolation between the nearest neighboring pixels
in the input grid. It is superior to the nearest-pixel scheme (above) in
not displacing features in the data, yet it still executes fairly rapidly.
It cannot introduce oscillations, however, it does introduce some spatial
smoothing which varies according to the distance of the interpolation
point from the neighboring pixels. This can degrade the shape of sharp
features in the data in a position-dependent way.
BLOCKAVE: Takes an average of all the pixels on the input grid in a
cube centered on the interpolation point. The number of pixels in the
cube is determined by the value of params,
which gives the number of pixels in each dimension on either side
of the central point. Hence a block of (2 * params) pixels in each
dimension of the input grid will be examined to determine the value
of the output pixel. This scheme is suitable where the output grid
is much coarser than the input grid; if the ratio of pixel sizes is R
then a suitable value of params may be R/2.
The remaining pixel resampling methods are based on a 1-dimensional
interpolation kernel. The params qualifier may be given a single value
(e.g. params=1) or two values in a Tcl list (e.g. params={1 1}).
The first or only value should be used to specify how many pixels are
to contribute to the interpolated result on either side of the
interpolation point in each dimension (the nearest integer value is
used). Execution time increases rapidly with this number. Typically,
a value of 2 is appropriate and the minimum value used will be 1
(i.e. two pixels altogether, one on either side of the interpolation
point). A value of zero or less may be given to indicate that a
suitable number of pixels should be calculated automatically. If a list
is given, the second value has a definition which varies based on the
resampling method (see below). If no params value is defined, zero is
assumed for all parameters.
SINC: Uses a sinc(pi*x) kernel, where x is the pixel offset from the
interpolation point and sinc(z)=sin(z)/z. In practice it is not useful
for astronomical data. It is merely provided for completeness.
SINCSINC: Uses an improved kernel, of the form sinc(pi*x).sinc(k*pi*x),
with k a constant, out to the point where sinc(k*pi*x) goes to zero, and
zero beyond. The second sinc() factor provides an "envelope" which
gradually rolls off the normal sinc(pi*x) kernel at large offsets. The
width of this envelope is specified by giving the number of pixels
offset at which it goes to zero by means of the second value in the
params list, which should be at least 1.0 (in addition, setting
the first value in the params list to zero will select the number of
contributing pixels so as to utilize the full width of the kernel, out
to where it reaches zero). The case given by params={2 2} is typically
a good choice and is sometimes known as the Lanczos kernel. This is a
valuable general-purpose interpolation scheme, intermediate in its
visual effect on images between the NEAREST and LINEAR schemes. Although
the kernel is slightly oscillatory, ringing is adequately suppressed if
the data are well sampled.
SINCCOS: Uses a kernel of the form sinc(pi*x).cos(k*pi*x),
with k a constant, out to the point where cos(k*pi*x) goes to zero, and
zero beyond. As above, the cos() factor provides an envelope which
gradually rolls off the sinc() kernel at large offsets. The width of
this envelope is specified by giving the number of pixels offset at
which it goes to zero by means of the second value in the params list,
which should be at least 1.0 (in addition, setting the first value in
the params list to zero will select the number of contributing pixels
so as to utilize the full width of the kernel, out to where it reaches zero).
This scheme gives similar results to the SINCSINC scheme, which it
resembles.
SINCGAUSS: Uses a kernel of the form sinc(pi*x).exp(-k*x*x),
with k a positive constant. Here, the sinc() kernel is rolled off using
a Gaussian envelope which is specified by giving its full-width at
half-maximum (FWHM) by means of the second value of the params list,
which should be at least 0.1 (in addition, setting the first value of
the params list to zero will select the number of contributing pixels
so as to utilize the width of the kernel out to where the envelope declines
to 1% of its maximum value). On astronomical images, good results are
often obtained by approximately matching the FWHM of the envelope function,
given by the second value of the params list, to the point spread function
of the input data. However, there does not seem to be any theoretical
reason for this.
- remap/method=[name]/params=[value(s)]
Method and parameter definitions are detailed in command description
above. Set method=? to list available remap methods.
The default remap method and params may be altered from
their usual values (i.e. method=CONSERVE with no params) by setting the
Tcl variables remap_method and remap_params. For example,
running set remap_method SINCSINC; set remap_params {2 2} before using
remap or inserting these commands in the ~/.ximagerc will set the
default to the Lanczos kernel mentioned above.
- remap/inmap=[idstring]
Specify input map to be remapped. The default value is the current map.
- remap/outmap=[idstring]
Specify where to save the resulting map. The default behavior is to use
the inmap value, overwriting the input map.
- remap/coorid=[idstring]
Specify the coordinates to remap into. If a mapid is given, the wcsid
associated with the map will be used. A wcsid may also be given.
- remap/rotangle=[value]
Rotate the image grid of the input map about the center by the given
number of degrees. The resulting image will effectively be rotated
in a counter-clockwise direction for positive values.
- remap/xsky=[value]/ysky=[value]
Specify the center of the remapped image in sky coordinates of the
original image.
- remap/ra=[value]/dec=[value]
Aliases for xsky/ysky, except they will also accept "hh mm ss.sss" and
"dd mm ss.sss" formats.
- remap/equinox=[value]
Specify the equinox if the remapped image center is given in
sky coordinates. By default the current XIMAGE equinox (defined with the
cey command) is assumed.
- remap/size=n
Specify the size of the remapped image. The value set through this
qualifier is assumed for both the x and y directions. If a non-square
image is desired, use the /szx and /szy qualifiers.
- remap/szx=n/szy=n
These qualifiers are identical to the /size qualifier except they
specify the image size in the x and y direction independently.
- remap/rebin=[value]
Rebin the original image by the given factor. The rebin factor may be a
real or integer value. For example, rebin=0.5 divides each pixel in
half in each dimension, redistributing the pixel values amoung the new
sub-pixels.
Examples:
remap/coor=sav ! Remap current map to the coordinates
! of the saved map
remap/xp=128/yp=128/out=2 ! Recenter map at 128,128 saving result in MAP2
remove_sources[/qualifiers]
This can be used to remove sources or unwanted features from the image
(such as hot spots or events caused by cosmic rays).
The area to remove may be defined via the cursor or by a region file
or through the x/y_min/max qualifiers. All the sources found with
detect or search may be removed using the special qualifier /detect.
By default remove calculates a standard background and replaces the
removed area with this value. A more customized background value
can be estimated using the background command and its qualifier
prior running remove. The output of background is automatically used
by remove.
Alternatively the pixels in the removed area may be replaced with a
constant value set through the /constant qualifier.
- remove/cursor
Specify the area to be removed by clicking the two opposite corners of
a rectangular box.
- remove/nsources=n
Loop through the removal process n times. This option is only useful
with the /cursor qualifier.
- remove/xmin=x/xmax=x/ymin=x/ymax=x
Remove the box defined by the minimum and maximum x and y values in
original detector coordinates.
- remove/detect_sources
Remove all the sources found in the last run of the detect or
search commands.
- remove/regionfile=[filename]
Remove area defined in a region file.
- remove/constant=x
Replace the removed regions with a constant value, rather than the
average value from the background command. A special null value
may be specified with the usage remove/const=null.
Examples:
remove/cursor/nsources=5 ! remove 5 regions defined by the cursor
remove/detect ! remove the sources found by detect
rescale[/qualifiers]
Rescale multiply, add or divide the current image for either a constant
value or a vector.
The vector can be input as an ascii file, containing one or more columns,
where each column has the same number of elements in the x or y directions
of the image.
- rescale/multiply
Specifies that the scaling factors is multiplicative. The value of
each pixels in the current image are multiplied by a constant or a
vector. This is the default scaling method.
- rescale/divide
Specifies that the scaling factor is used to divide each pixel of the
image by a constant or a vector.
- rescale/add
Specifies that the scaling is additive. A constant is added to the value
of the pixels in the current image. This option may not be used in
conjunction with /file_vector.
- rescale/scaling_factor=x
Set the scaling factor to constant value.
- rescale/to_exposure=x
Set scaling factor to be x/exposure where the exposure is taken from the
header of the current image (i.e. scaling_factor = to_exposure/image
exposure time) and applied to the image using one of the arithmetic
qualifiers. The qualifier /scaling_factor has not effect is /to_exposure
is in use.
- rescale/file_vector=[filename]
Perform rescaling by using vector from a file. If the file contain
multiple columns the qualifier /column set the column number
to use. The qualifiers /x_direction or /y_direction
define which direction is used to perform the vector arithmetic.
- rescale/column=n
Set the column number to use from the /file_vector file as the
rescaling vector.
- rescale/x_direction
Perform the vector arithmetic in the x direction.
- rescale/y_direction
Perform the vector arithmetic in the y direction.
- rescale/min_fraction=x
Minimum fraction to use in rescaling image. Only applicable
when dividing by a vector. If the reciprocal of the vector value is
less than /min_fraction, pixels in that position are zeroed out.
Examples:
rescale/scal=10 ! every pixel value in the current image
! is multiplied by a factor 10.
rescale/add/scal=25 ! 25 is added to every pixel value
! in the current image.
rescale/file=slice.cut/col=2/x ! multiply the values in the 2nd
! column of slice.cut along the
! x direction of the image
resize/[qualifiers]
This command allows to size the pixel up to a maximum of twice the original
value. This is useful when two images from different detectors need to be
summed but the pixel scale for the two images is different.
- resize/pixel_size=x
Specify the value of the new pixel size in arcseconds.
Examples:
resize/pixel_size=10 ! the pixel size will be change from the
! original value to 10 arcsecs.
restore_image
Copy the saved image to the current image, along with its associated
exposure map. The first image in an XIMAGE session is automatically
saved. The current image can be saved with the save_image command. In
tight memory situations, saved images can be freed with the free_saved
command.
Note, restore_image actually runs map copy sav cur The command is
provided mainly for backwards compatibility with existing scripts. If
the map command is used directly, the continued use of save_image
and restore_image is not recommended.
Example:
restore_image ! restore the saved image
rotate[/qualifiers]
This routine properly rotates sparse arrays such as X-ray images. In
order to preserve the poissonian nature of the background a Monte Carlo
redistribution of some events is carried out. The total number of
photons is strictly conserved. This operation is however
irreversible, that is, a rotation of +x degrees, followed by a
rotation of -x degrees will produce an image that although closely
resembles the original one, it is not identical. For this reason it is
advisable to keep to a minimum the number of rotations performed on one
image.
- rotate/roll_angle=dms
This qualifier can be used to specify the roll angle at which to rotate
the image. The default angle is -90, corresponding to North up and East
to the left. Angle may be entered as degrees or in "dd mm ss.s"
format.
Example:
rotate/roll_angle=-20.1 ! Rotates the current image to a roll
! angle of -20.1 degrees
Next: 8. Commands S-Z
Up: XIMAGE User's Guide
Previous: 6. Commands A-F
Contents
Micah Johnson
2006-07-19