next up previous contents
Next: 8. Commands S-Z Up: XIMAGE User's Guide Previous: 6. Commands A-F   Contents

Subsections

7. Commands G-R

7.1 gencolor - generate color image from event file

      gencolor[/qualifiers] [infile]

Takes event file, and based on the mission, extracts images for three ranges of energy, representing red, green and blue. Then, these images are fed into the external program mkcolor, that generates an encoded color image. This image is read into ximage and displayed.

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

7.2 grid - overlay a sky coordinate grid

      grid[/qualifiers] [dalpha] [ddelta]

Draw a grid in the sky coordinates of the original image over the displayed image. The default will plot a preassigned grid spacing. This can be changed by specifying dalpha and ddelta in degrees. If the primary coordinate frame has been changed with the 'wcs/frameid=n' command, the grid will reflect the specified frame.

Note: The grid command is implemented using the Starlink AST library. The default behavior of the grid command may be tweaked to a great degree by setting the 'grid_astoptions' variable to a comma-delimited list of AST options. For example, the following forces the axis labelling to inside the frame and plots the numeric labels in red (color index 2):

set grid_astoptions "Labelling=interior,Color(NumLab)=2"

For a full list see the Attributes section of the AST Plot documentation:

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

7.3 header - display header summary

      header[/qualifiers]

Lists part of the header information in a pre-set format. All header information may be viewed through the chheader command.

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.

7.4 help - ximage help

      help  [command name]

Help will describe in detail each XIMAGE command. In help, type the first few characters of the topic followed by <cr> to get info on it. Use <cr> to back up a level. Ctrl-D exits help.

Example:
     
    help detect           ! show detailed information about command `detect`

7.5 hotspot - show position of EXOSAT CMA hot spot

     hotspot[/qualifiers]

Shows the position of the CMA hot spot on a pre-displayed image. This command only works for EXOSAT LE-1 or LE-2 images that have not been rotated. The qualifiers for hotspot merely affect the appearance of the plotted symbol and label. See the label command for details.

Example:
    hotspot            ! A small circle is drawn around the expected position
                       ! of the CMA hot spot.

7.6 iminfo - text overlay

     iminfo[/qualifiers] [string]

Overlay information onto a pre-displayed image. In its default mode iminfo includes image orientation, instrumentation name, exposure time and image scale. If only a string is given, that string will be displayed in place of the iminfo command's text information.

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

7.7 label - write labels on the image

     label[/qualifiers] [text]

This command allows you to write labels anywhere on the display, with any size. The /xpix and /ypix qualifiers give the label location in pixel coordinates as labeled in the image frame, the /vx=x/vy=x qualifiers give the label location in viewport coordinates, and the /ra=x/dec=x qualifiers give the label location in sky coordinates. If the label has spaces, the text must be included in double quotes, e.g. "write this here". A symbol can also be written using the /symbol qualifier.

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

7.8 levels - manipulate intensity levels

      levels[/qualifiers] [filename]

List and manipulate intensity levels. If no qualifiers are given, the levels used to display last the current image are printed to the screen. Note that the intensity levels are listed only after the display or contour command have been used, since they are calculated by default within these commands. User defined levels may be input using the qualifier /file which is an ascii file containing one level per row. The number of levels is preserved between ximage sessions.

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`

7.9 log - open a log file

      log [filename]

Write a log file containing the screen output generated by XIMAGE.

The option filename specifies the name of the log file; the file extension is .log. If no filename is specified then the default of ximage.log is used.

A log file will be closed if:

The log files are in plain ASCII text.

Example:
     
    log results              ! open a log file called results.log

7.10 map - manipulate image maps

      map[/qualifiers] [mapid]

If given no qualifiers or arguments, prints a description of the currently loaded image maps to screen, including the filename, size, rebinning factor, center, and codes which represent map-altering operations performed in XIMAGE. Also, the current map and displayed map are indicated.

If a mapid with no qualifiers is given, the current map, the map which commands operate on by default, is set to that mapid. Note that the full id for a map is MAP1-9 for image maps and EXMAP1-9 for associated exposure maps. These may be shortened to 1-9 and EX1-9, respectively.

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

7.11 marith - perform arithmetic with image maps

      marith[/qualifiers] [expression]

The marith command allows the user to perform arithmetic on stored image maps. Valid operations are +,-,/,*,int(), and float(). The +,-,/,* operators may have only two arguments, one of which must be an image map, specified by the full id for an image map (MAP1-9) or an associated exposure map (EXMAP1-9), and the other argument may be a numeric constant or another map. MAP1-9 may not be shortened to 1-9 in the expression, as the parser has no way of differentiating between an integer constant and a map shortened to its numeric id. The int and float functions may only take a map as an argument. Note that this command is currently limited to one operation.

The results of the operation are stored in the current map. Alternately, the output map may be stored in the map specified with marith's mapout qualifier. For example, marith/mapout=map3 map1+map2 behaves in the following arithmetic sense: map3=map1+map2

The map output from marith will have an integer or float type depending on the arguments and operations used to create it. The / and float() operations will always result in a float type. The int() operation will always result in an integer type. The +, -, and * operations will result in an integer type if both of their arguments are integers, otherwise a float type will result.

When only one map is involved in an operation, all header information is copied from that map into the output map. The DATAMIN/MAX keywords are updated after the map arithmetic is performed. Consequently, the coordinates of the output image are identical to the input map. When two image maps are involved, the first image map of an operation is assumed as the output image map's header, unless overridden with the hdrid qualifier. Image maps with rotation, centering and/or size different from the output image will be transformed to match its coordinates. Note: In the transformation, a Monte Carlo distribution of the pixel values is done. The total number of counts is preserved.

The user may also set explicit coordinates for the output image independent of any existing header. Use the crota qualifier for rotation, which is specified in degrees and assumes the convention where crota=0 when celestial north is up. Use the ra, dec, and (optionally) equinox qualifiers to specify the output image map's center.

The output map inherits its size from the larger of the two input maps. The user may specify the desired output size with the size qualifier, or if a nonsquare output image is desired, the szx and szy qualifiers are available.

When summing images with associated exposure maps, their exposure maps will also be combined. Other operations between maps with associated exposure maps will result in an output map with no exposure map.

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

7.12 moper - perform mathematical operation between image maps

      moper[/qualifiers] [mapid] [mapid]

The moper command performs elementary operations between image maps with no consideration for matching sky coordinates. If two images are operated on they must be of identical size. This command is primarily intended for internal use by marith.

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.

7.13 offset - calculate offset

      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

7.14 pcontour - core contour plotting

      pcontour[/qualifiers]

Core contour plotting routine. Primarily for internal use by contour. See contour for description of following qualifiers: csize, font, noframe, nobox, overlay, color, lwidth, lstyle, first_contour_drawn

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.

7.15 pimage - core image plotting

      pimage[/qualifiers]

Core image plotting routine. Primarily for internal use by display. See display for description of following qualifiers: csize, font, noframe, nobox, overlay, color, lwidth, lstyle

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.

7.16 pixel_to_ra_dec - convert pixel to sky coordinates

      pixel_to_ra_dec[/qualifiers]

Converts a specified pixel position in the current image to RA and DEC. If /cur is not specified, then XIMAGE will ask for X and Y pixel coordinates.

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.

7.17 powplot - start POWplot viewer

      powplot[/qualifiers] [filename]
This command writes a temporary FITS file and spawns POWplot to view it. It is important to note that any region files written from POWplot will not correct for any rebinning made within XIMAGE. The XIMAGE circ and box commands do not suffer from this problem. To read POWplot regions back into XIMAGE, the region values need to be multiplied by the XIMAGE rebinning factor and the reference pixel value as reported within XIMAGE needs to be added.

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

7.18 prarray - print Tcl array to screen or file

      prarray[/qualifiers] [array name]

This command prints the values contained in a Tcl array to the screen or to a file. A related command, rdarray exists for reading text files into an array.

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 "$\backslash$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

7.19 psf - estimate the point spread function

      psf[/qualifiers]

Calculates differential and integral Point Spread Function and plots them onto the currently defined graphic device. The expected PSF for a pointlike source is also calculated and displayed. This command needs an accurate estimate of the image background. The psf command uses as background value the results of the previously run background command, but it can be overridden with the /back qualifier. By default the command calculates counts within an annulus which is incremented by one pixel per iteration.

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/expowgt
When this qualifier is given, the psf calculation will use the exposure map to weight the psf function. The weights are calculated as the total exposure contained with each psf annulus, normalized by the total exposure contained within the given radius. If there is not a current exposure map for the current image map, this is an error.

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

7.20 ra_dec_to_pixel - sky to detector coordinates

      ra_dec_to_pixel[/qualifiers]

Converts RA and Dec into the image pixel coordinates. If the image is displayed, a crosshair symbol is drawn at the corresponding position. Coordinates may be input via the qualifiers /ra and /dec or by answering RA/Dec prompts. Input coordinates are assumed to be in the current equinox set with the cey command. The input ra, dec, and equinox are saved between ximage sessions. This saved position is available as a default at the RA/Dec prompts. Press return without entering a value to accept the default.

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

7.21 rdarray - read text file into Tcl array

      rdarray[/qualifiers] [filename]

This command reads a text file containing columns of values into a Tcl array. Text files can come in many formats, so the command is flexible to support them. A related command, prarray exists for writing arrays to screen or back to a file.

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

7.22 read_image - read an image or events files

      read_image[/qualifiers] [filename]

Read an image into the current map. If no file type is specified, a FITS file is assumed, and various checks are made to identify it as either an image or event file. The only non-FITS type supported is EXOSAT, a binary machine-dependent format indicated by the /exosat qualifier.

Whether specified with the file qualifier or as an argument to the command, any FITS file given as a filename may use the extended filename syntax briefly described on this page:

http://heasarc.gsfc.nasa.gov/docs/software/fitsio/filters.html A common usage, for example, is to filter out events with certain energies, filename.evt[EVENTS][PHA $>$ 5]. The Tcl environment used by ximage, however, interprets square brackets [] as commands within commands. In order to prevent expansion by Tcl, use curly braces to quote the filename. For example, read {filename.evt[EVENTS][PHA > 5]}

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

7.23 rebin - rebin the current image

       rebin[/qualifiers] factor

The current image is rebinned by the number of bins specified by the factor parameter. The /mode parameter can be used to apply some slight smoothing, or do rebinning for mosaics.

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

7.24 recall - recall past command

      recall[/qualifiers] [n]

The command recall is used to list previous commands. The global Tcl variable, htyshow, determines the default number of commands to list. Initially this is set to 20, however it may be redefined by the user. Any command can be reexecuted by typing recall n where n is the command number given in the listing.

The history of commands is preserved between sessions of Ximage by storing them in a file at '~/ximage.hty'. The name of this file can be changed by setting the 'ximage_history_file' variable in '~/.ximagerc'. No history file is written if this variable is set to an empty string. For example:

set ximage_history_file ""

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

7.25 remap - remap image to new coordinates

      remap[/qualifiers]

The remap command maps an existing image to new coordinate system, distributing (or resampling) the original pixels into the new pixel grid.

The default resampling method is CONSERVE, which redistributes the values in the original image pixels based on the fractional area intersecting the new pixel, conserving the total value. Integer values are redistributed using probabilities to preserve Poissionian characteristics. This pixel resampling method is the most rigorous and hence the slowest by a large margin.

The remaining pixel resampling methods are directly implemented in the Starlink AST library (method descriptions excerpted from astResample docs). Note: The params qualifier is a list of parameters that may be used to tweak the operation of some remap methods. See the description of each method for the definition of params in that context.

NEAREST: The value of the input pixel with the nearest center to the interpolation point is used. This is very quick to execute and will preserve single-pixel features in the data, but may displace them by up to half their width along each dimension. It often gives a good cosmetic result, so is useful for quick-look processing, but is unsuitable if accurate geometrical transformation is required.

LINEAR: Uses linear interpolation between the nearest neighboring pixels in the input grid. It is superior to the nearest-pixel scheme (above) in not displacing features in the data, yet it still executes fairly rapidly. It cannot introduce oscillations, however, it does introduce some spatial smoothing which varies according to the distance of the interpolation point from the neighboring pixels. This can degrade the shape of sharp features in the data in a position-dependent way.

BLOCKAVE: Takes an average of all the pixels on the input grid in a cube centered on the interpolation point. The number of pixels in the cube is determined by the value of params, which gives the number of pixels in each dimension on either side of the central point. Hence a block of (2 * params) pixels in each dimension of the input grid will be examined to determine the value of the output pixel. This scheme is suitable where the output grid is much coarser than the input grid; if the ratio of pixel sizes is R then a suitable value of params may be R/2.

The remaining pixel resampling methods are based on a 1-dimensional interpolation kernel. The params qualifier may be given a single value (e.g. params=1) or two values in a Tcl list (e.g. params={1 1}). The first or only value should be used to specify how many pixels are to contribute to the interpolated result on either side of the interpolation point in each dimension (the nearest integer value is used). Execution time increases rapidly with this number. Typically, a value of 2 is appropriate and the minimum value used will be 1 (i.e. two pixels altogether, one on either side of the interpolation point). A value of zero or less may be given to indicate that a suitable number of pixels should be calculated automatically. If a list is given, the second value has a definition which varies based on the resampling method (see below). If no params value is defined, zero is assumed for all parameters.

SINC: Uses a sinc(pi*x) kernel, where x is the pixel offset from the interpolation point and sinc(z)=sin(z)/z. In practice it is not useful for astronomical data. It is merely provided for completeness.

SINCSINC: Uses an improved kernel, of the form sinc(pi*x).sinc(k*pi*x), with k a constant, out to the point where sinc(k*pi*x) goes to zero, and zero beyond. The second sinc() factor provides an "envelope" which gradually rolls off the normal sinc(pi*x) kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the second value in the params list, which should be at least 1.0 (in addition, setting the first value in the params list to zero will select the number of contributing pixels so as to utilize the full width of the kernel, out to where it reaches zero). The case given by params={2 2} is typically a good choice and is sometimes known as the Lanczos kernel. This is a valuable general-purpose interpolation scheme, intermediate in its visual effect on images between the NEAREST and LINEAR schemes. Although the kernel is slightly oscillatory, ringing is adequately suppressed if the data are well sampled.

SINCCOS: Uses a kernel of the form sinc(pi*x).cos(k*pi*x), with k a constant, out to the point where cos(k*pi*x) goes to zero, and zero beyond. As above, the cos() factor provides an envelope which gradually rolls off the sinc() kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the second value in the params list, which should be at least 1.0 (in addition, setting the first value in the params list to zero will select the number of contributing pixels so as to utilize the full width of the kernel, out to where it reaches zero). This scheme gives similar results to the SINCSINC scheme, which it resembles.

SINCGAUSS: Uses a kernel of the form sinc(pi*x).exp(-k*x*x), with k a positive constant. Here, the sinc() kernel is rolled off using a Gaussian envelope which is specified by giving its full-width at half-maximum (FWHM) by means of the second value of the params list, which should be at least 0.1 (in addition, setting the first value of the params list to zero will select the number of contributing pixels so as to utilize the width of the kernel out to where the envelope declines to 1% of its maximum value). On astronomical images, good results are often obtained by approximately matching the FWHM of the envelope function, given by the second value of the params list, to the point spread function of the input data. However, there does not seem to be any theoretical reason for this.

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

7.26 remove_sources - remove sources

      remove_sources[/qualifiers]

This can be used to remove sources or unwanted features from the image (such as hot spots or events caused by cosmic rays). The area to remove may be defined via the cursor or by a region file or through the x/y_min/max qualifiers. All the sources found with detect or search may be removed using the special qualifier /detect. By default remove calculates a standard background and replaces the removed area with this value. A more customized background value can be estimated using the background command and its qualifier prior running remove. The output of background is automatically used by remove. Alternatively the pixels in the removed area may be replaced with a constant value set through the /constant qualifier.

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

7.27 rescale - rescale the current image

      rescale[/qualifiers]

Rescale multiply, add or divide the current image for either a constant value or a vector. The vector can be input as an ascii file, containing one or more columns, where each column has the same number of elements in the x or y directions of the image.

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

7.28 resize - change the pixels size of the current image

      resize/[qualifiers]

This command allows to size the pixel up to a maximum of twice the original value. This is useful when two images from different detectors need to be summed but the pixel scale for the two images is different.

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.

7.29 restore_image - restore the saved image

      restore_image

Copy the saved image to the current image, along with its associated exposure map. The first image in an XIMAGE session is automatically saved. The current image can be saved with the save_image command. In tight memory situations, saved images can be freed with the free_saved command.

Note, restore_image actually runs map copy sav cur The command is provided mainly for backwards compatibility with existing scripts. If the map command is used directly, the continued use of save_image and restore_image is not recommended.

Example:
     
    restore_image                  ! restore the saved image

7.30 rotate - rotate the current image

      rotate[/qualifiers]

This routine properly rotates sparse arrays such as X-ray images. In order to preserve the poissonian nature of the background a Monte Carlo redistribution of some events is carried out. The total number of photons is strictly conserved. This operation is however irreversible, that is, a rotation of +x degrees, followed by a rotation of -x degrees will produce an image that although closely resembles the original one, it is not identical. For this reason it is advisable to keep to a minimum the number of rotations performed on one image.

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 up previous contents
Next: 8. Commands S-Z Up: XIMAGE User's Guide Previous: 6. Commands A-F   Contents
Alex Padgett 2010-03-25