Each public access point can be accessed by means of the xpaset or xpaget
command. For example, to change the colormap, type:
The programs imset and imget are provided as a convenience for use
with SAOtng. These programs assume that the target is SAOtng and allow
a more natural command structure. For example, to change the colormap
using imset, type:
The following XPA commands are supported in SAOtng. Arguments
enclosed in square brackets ([...]) are required, while those in curly
brackets ({...}) are optional. Commands can have send and/or receive
functionality, as described in each case:
- accel [name] [type] [cmd] {color}
- Send: add the named command to the accel buttons (left-hand side
of the GUI), allowing you to add a frequently used command to the
accel buttons on the fly. Note that the use of the -accel
switch (or SAOTNG_ACCEL environment variable) is the preferred method
of adding commands on a more permanent basis.
- analysis [cmdno|help string fragment]
- Send: run the 'th analysis command on current image
(command numbers start at 0, as listed in the analysis
menu). Alternatively, a unique substring from a command's help string
can be specified. For example, the command:
echo "analysis entire" | xpaset SAOtng
will execute the minmax command whose help states "calculate the min
and max of the entire file".
If the first argument of the send command is "add", then the argument
that follows is assumed to be a filename containing commands to be
added to the currently available routines. For example:
echo "analysis add new.cmds" | xpaset SAOtng
will add commands from the new.cmds file.
See Analysis Routines in SAOtng
for more information.
Receive: returns a list of the currently available analysis routines.
- array [filename xdim, ydim, bitpix, skip]
- Send: displays array data in current frame. The data
is sent via a command such as:
| xpaset SAOtng array foo.arr 512 256 -32
or
| xpaset SAOtng array foo.arr[xdim=512,ydim=256,bitpix=-32]
where parameters are used to describe the array dimensions and type.
See Array File Specification for more
information.
Note that the array access point is used only when a disk file is
not available (e.g., when a program writes array data to stdout).
Use the file public access point to send a file name to SAOtng.
- autoconfig [true|false|max width {height}|width {height}|manual width {height}]
-
Send: Specifies whether frame #1 should autoconfigure itself to the
size of a newly loaded image. If "true" or "false", then
autoconfiguration is turned on/off. If no argument is specified, the
configuration is turned on;
If one or two numeric values are supplied, then these values are taken
as the width and height of the frame. Autoconfig is turned on. If
"manual" is specified and one or two numeric values are
specified, then the values are taken as the width and height of the
frame, but autoconfig is turned off to prevent this frame size from
being overridden (manual override).
If "max" is specified and one or two numeric values also are specified,
then autoconfig is turned on and the values are taken as the
max width and height to which a frame can be configured. Note that 0
in this context means no maximum.
Receive: returns "true" or "false" and the max width and height for
autoconfiguration. See Autoconfiguration
of Frames for more information.
- autoflip [true|false]
- Send: The autoflip state is set according
to whether the accompanying parameter is "true" or "false". Autoflip
ensures that a newly loaded image containing FITS WCS information will
be flipped if necessary so that "north is up".
- blocking [block factor|sum|average|new|next|prev]
- Send: set the block factor for extracting image data. (NB: This is
not the same as the zoom factor for a displayed image.) An integer
blocking factor can be specified (legal blocking factors are the positive
powers of 2). Use "new" to add the "next" blocking factor (the next
power of 2). Use "next" and "prev" to change the current blocking
factor relative to the current. Use "sum" and "average" to specify
a preference for how data is blocked (but note that it is up to individual
extraction programs to honor this request -- fitsextract does so).
Receive: returns the current blocking factor and blocking preference:
bynars-49: xpaget SAOtng blocking
block=2
pref=average
NB:
The power of 2 restriction on blocking stems from the fact that we
have had problems placing region markers exactly with non-power-of-2 blocking.
If marker accuracy is not a problem and you wish to remove this
restriction, set the environment variable SAOTNG_RESTRICT to
false. With this setting, the blocking factor can be any positive
integer.
- cast [never|always|asNeeded]
- Send: set cast preference for in-memory FITS. SAOtng will make
a guess to determine if in-memory data extraction and blocking will
cause an overflow in char and short images. If so, and if cast is
set to "asNeeded" (the default), then the extracted data will be cast
up to int to avoid the overflow -- at the expense of using more memory.
You can disable this feature by setting cast to "never".
Receive: returns the current setting for casting.
- colormap [colormap name|invert|half|full]
- Send: set colormap for current frame. In specifying a colormap name,
keep in mind that names are case sensitive and generally begin with an upper
case letter. Use "invert" to invert the colormap. [The "half" and "full"
options are used internally to specify the range of mouse movement when
adjusting the colormap with the right mouse buttons and probably are
of no interest to users.]
Receive: returns the colormap name for the current frame.
- coords [none|pixels|hms|degrees] (send)
- coords [format|pixels|hms|degrees] (receive)
- Send: set the preferred coordinate display. If an image contains
the appropriate WCS coordinate information in its header, then
mouse movement across the image will track positions in that coordinate
system using the specified format. For example, RA/Dec can be
displayed in HMS/DMS format or in degrees format. Pixel format always
is available and refers to zoom1 pixel positions from the original
file. Also, region markers are returned in the current format (unless
otherwise specified by parameters in the regions access
point).
Receive: If "format" is specified as an option, return the current
display format. Otherwise, when this receive is executed, the SAOtng
cursor is changed to a blinking circle and SAOtng waits for the user
to position the mouse on an image position and press
. The coordinates of that position are returned. For example:
bynars-64: xpaget SAOtng coords
... wait for the user to position and mouse and press ...
13:36:57.761 -29:52:06.11 J2000 (283.0 263.0) 16496
The receive command can return the coordinate values in a format other
than the default by specifying that format as an option. For example,
the same position can be returned in degree format:
bynars-66: xpaget SAOtng coords degrees
204.241 -29.868 J2000 (283.0 263.0) 16496
- destroy {noerase}
- Send: destroy the current image, including all data maintained
internally by SAOtng. The "noerase" option will leave the image on
the screen (I forget why this is useful, but someone wanted it!)
- display_data
- Receive: retrieve the 8-bit display data for the current frame
in FITS format. The data bits will contain all markers, WCS display,
pan/zoom display as shown on the screen and can be used by programs
such as fits2ps to create PostScript files. (And, in fact, this access
point is used by SAOtng to create GIF and PostScript files of the
current screen.)
- displayed
- Receive: returns "true" is an image is being displayed in the
current frame, "false" otherwise. This is useful in scripts that
want to know whether to switch to a new frame before loading a new
image (I think).
- edge [value]
- Send: set size of image edge to ignore when scaling the
current image. The default is 0.
Receive: get edge size of the current image.
- env [name] [value] (send)
- env [name] (receive)
- Send: set an environment variable inside SAOtng. Such a variable
will be inherited by a spawned analysis process.
Receive: get the value of an existing environment variable. A new-line
is returned is the variable does not exist. For example,
bynars-84: xpaget SAOtng env TERM
dtterm
- exec
- Send: execute XPA commands from the data buffer. This is an internal
SAOtng XPA routine, not needed by users. It can be used to execute:
echo "zoom 2; colormap SLS" | xpaset SAOtng exec
However, this also is accomplished without the "exec" command:
echo "zoom 2; colormap SLS" | xpaset SAOtng
As shown above, the "exec" command is the default command to execute
when no other command is passed to xpaset.
- file [file name] {file type} (send)
- file {param|raw_data|display_data} (receive)
- Send: display the specified
image file in current frame. This is the main entry point for loading
new images. The name of any known file type or FITS file or array
file can be sent to SAOtng through this access point and SAOtng will
process it appropriately. For FITS files and arrays, SAOtng will
process it in memory (depending on the value of the maxsize parameter)
or using fitsextract. For files of other types, the appropriate file access
program will be spun off. If a file is to be loaded that does not
have a known extension, then its type can be added explicitly as a
second parameter. See
HREF="image.html">Loading an Image for more information.
Receive: If no arguments are provided, the "file" receive access point
returns the FITS header for the currently displayed image. If the
option "raw_data" is specified, then the raw data for the currently
displayed image section is returned in FITS format. If the option
"display_data" is specified, then the display data for the currently
displayed image section is returned in FITS format. Otherwise, any
specified argument is assumed to be a FITS parameter and the value of
that parameter is returned.
- fits {fits name}
- Send: display FITS data in current frame. The data
is sent via a command such as:
| xpaset SAOtng fits foo.fits
Note that the "fits" access point is used only when a disk file is
not available (e.g., when a program writes FITS data to stdout).
Use the file public access point to send a file name to SAOtng.
- flavor [bland|beautiful|default]
- Send: set the GUI flavor, i.e., GUI colors and style. The "bland"
flavor is black and white and is used in desperation when colormaps are
going crazy. The "beautiful" flavor gives colorful buttons and backgrounds.
The "default" flavor is Netscape grey.
- flip [x|y|xy]
- Send: The image will be flipped in x, y or xy
according to whether "x", "y", or "xy" is specified.
Receive: get current x and y zoom factors and the x and y flip state:
beberly-315: xpaget SAOtng zoom
xmag=2
ymag=2
xflip=False
yflip=True
- frame [frameno|new|next|prev|del]
- Send: change the display frame, create a new frame, or modify
the autoconfigure setting for frame 1. If a frame number is specified
and that frame exists, it is made the current frame. If the frame
does not exist, it is created first. If "next" or "prev" is
specified, the frame is changed to the next or previous frame, with
wrap-around when the last or first frame is reached. The "del"
specification delete the current frame.
Receive: returns the frame number of the current frame, as well as
the width and height of the current frame.
- gif [GIF filename]
- Send: create a GIF file of the currently displayed frame. The GIF file
will contain all markers, labels, panner/magnifier, wcs display, etc.
that is shown on the screen. Because this function reads the screen pixels
directly, it is important that no other window obscure the screen while
the process is running.
- help [help filename]
- Send: raise the help window and display the named help page.
Normally, help files are displayed by clicking the mouse on
hypertext links in the help display. Other processes also can
display help using this command. This is especially useful if
a site has installed new help files into the SAOtng help system, for
example, to describe site-specific analysis programs.
For example, to display this help file, try:
echo "help xpa_list.html" | xpaset SAOtng
- image
- Receive: get the full pathname of the currently displayed image.
- images
- Receive: get the full pathname of all images currently loaded into
SAOtng.
- lower
- Send: lower the image display window to the bottom of the X window
stack.
- manalysis [cmdno|help string fragment]
- Send: run the 'th marker analysis command on current image.
Command numbers start at 0, as listed in the marker analysis
menu. Alternatively, a unique substring from a command's help string
can be specified. For example, the command:
echo "manalysis active" | xpaset SAOtng
on an IRAF QPOE file will execute the imcnts command whose help states
"counts -- number of events in the activeregion".
If the first argument of the send command is "add", then the argument
that follows is assumed to be a filename containing commands to be
added to the currently available marker routines. For example:
echo "manalysis add new.cmds" | xpaset SAOtng
will add commands from the new.cmds file.
See Marker Analysis Routines in SAOtng
for more information.
Receive: returns a list of the currently available marker analysis routines.
- message [message]
- Send: display a user message. External programs can send messages
to the SAOtng message window using this command. For example:
echo "message This is a test" | xpaset SAOtng
sends a test message, while:
cat ~/.cshrc | xpaset SAOtng message
sends my .cshrc file. Note that TCL looks at curly brackets within
the message in a funny way; they should be avoided in messages if
possible.
- pan ["image"|"frame"] [x|y|reset|center]
- Send: The x and y values specify the image or frame x and y positions
around which to pan the image. If image and pan are not specified, then
image is assumed if an image is displayed in the frame. Otherwise the
coordinates are assumed to be frame coords.
If "reset" is specified, then the image zoom is reset to 1 (or the
value of the -zoom switch) and the pan center is reset to the window
center. If "center" is specified, then the pan center only is reset
to the window center (zoom is left alone).
Receive: get current x and y zoom factors and the x and y flip state:
beberly-315: xpaget SAOtng zoom
xmag=2
ymag=2
xflip=False
yflip=True
- print {printer options}
- Send: create a PostScript representation of the currently
displayed frame and send it to the current "printer". The PostScript
file will contain all markers, labels, panner/magnifier, wcs display,
etc. that is shown on the screen. Because this function reads the
screen pixels directly, it is important that no other window obscure
the screen while the process is running.
The "printer" can be a PostScript printer, a program such as
ghostview, or a disk file, depending on the "printer" options. These
printer options can be placed on the command line or they can
be set up with the "printer" access point. By default,
the output is piped to "lpr".
Receive: get the current printer specification.
- printer [print options|ghostview|file redirect]
- Send: set printer options for PostScript printing.
The default is to pipe the PostScript output to "lpr".
If the options begin with "lpr" or "lp", then the PostScript
is piped to this printer. For example:
lpr -Plpm -h
will print the PostScript on the printer lpm without the standard
header file.
If "ghostview" is specified, the output is sent to the ghostview program
for previewing. (This assumes the ghostview program is available).
If no ">" or "|" symbol is specified as part of the printer specification
string, the output is assumed to be a disk file and the PostScript is
redirected to this file:
/home/eric/foo.ps
will send the postscript output to a file. (Note that the command is
executed via the Borne shell, so the "~" character is not recognized.
Sorry!) If a ">" or "|" symbol is specified, then the output is redirected
or piped to the printer specification.
Receive: get the current printer specification.
- quit
- Send: exit program
- raise
- Send: raise the image display window to the top of the X window
stack.
- redisplay {erase|noerase|rescale|norescale|setframe|nosetframe|image}
- Send: redisplay the selected image in current frame. The redisplay
will extract a new image section, possibly at a new block factor, if
new blocking or sectioning parameters were previously specified. This
is especially useful when used in conjunction with the "shm" shared
memory public access point.
If no arguments are supplied, the current image is
redisplayed. By default, the image first is erased and then rescaled
before being displayed. Either erasing or rescaling can be turned
off.
If an image name is specified and that image has been loaded into
SAOtng, then it is redisplayed, rather than the current image. This
makes sense in tile mode, where multiple images are being displayed at
the same time but only one is "active". If an image other than the
current image is to be redisplayed, SAOtng will change frames to the
redisplayed image before redisplaying it. This can be turned off with
the "nosetframe" option (and is especially useful in tiling).
- regionnames {replace|append}
- Send: modify the region name/color association. This is the mapping
between names and colors that appears in region marker files. The
default mapping is: source/green and background/red, but you can
add to or replace the mapping using this command. For example:
cat newrnames | xpaset SAOtng append
will add the contents of the newrnames file to the current mapping.
See Region Names and Colors for more
information about the region name/color mapping.
- regions [regions] (send)
- regions {hms|degrees|pixels|\n|\;} (receive)
- Send: send and display one or more regions in the current frame.
Regions can be sent to SAOtng in one of two ways:
echo "regions 'c 250 250 10; box 150 200 10 20'" | xpaset SAOtng
or
cat new.reg | xpaset SAOtng regions
where new.reg might contain a list of regions separated by new-lines.
If WCS information is available for the current image, the coordinates
can be specified using RA/Dec in HMS/DMS or degrees (or whatever the
"natural" coordinate system of the image as specified by the FITS
header keywords:
echo "regions +circle(13:37:14.613,-29:56:15.05,27)" | xpaset SAOtng
Receive: get the regions for the current frame. By default, region
marker coordinates are returned using the current WCS display format.
This can be overridden using one of the format keywords (assuming
appropriate WCS information is available for that FITS image). Thus,
for example, if the current format is HMS/DMS, you can retrieve region
markers in degrees using:
xpaget SAOtng regions degrees
By default, regions are separated by new-lines. They also can be
returned separated by semi-colons by specifying the "\;" parameter.
See Region Markers for more information
about manipulating regions.
- rescale {image}
- Send: rescale the image in current frame or the specified image.
Honest truth: I forget why this is useful. It would appear to be
similar to "redisplay", but the latter does a more complete job: it
will re-extract the data at a new block factor, etc.
- scale [scale name|internal [params]|add [filename]]
- Send: set the scale algorithm.
The current image will be rescaled using the specified scale algorithm.
Any newly loaded images also will use the specified scale algorithm.
If "add" is specified as the first parameter, then the second argument is
taken as a filename of scale algorithms to add to the existing scaling
algorithms.
See Adding New Scaling Algorithms
for more information.
If "internal" is specified as the first parameter, then several internal
parameters can be set:
- If "wrap" is specified next, then the argument that follows specifies
the value of the nwrap parameter (pixel value on which to wrap the scale).
- If "pow" is specified next, then the argument that follows specifies
the value of the pow parameter (default is 0.5 for sqrt scaling).
- If "log" is specified next, then the argument that follows specifies
the value of the exp parameter (default is 10.0 for log10 scaling).
Receive: get the current scale algorithm.
- scalelims [val|cur|data] [val|cur|data]
- Send: set limits for data scaling for the currently displayed
image. Normally, the data min and max are taken as scaling limits and
the scaling is done so that data values are mapped from these limits
to the colormap range (200) using the specified scaling algorithm.
This command can be used to set either the min or max scaling
value to something other than the min and max data values. Two
arguments are required: a min and max value. Special keywords "cur"
and "data" can be used in place of numeric values to specify that a
limit is to be taken either from the data or from the currently
specified value. (NB: if the image has FITS BSCALE and BZERO defined,
then the scaling min and max are specified using the scaling parameters, i.e.,
the min and max are "real" data values, not pixel values.)
Receive: get the current scaling limits for this image.
- section [upper_left|upper_right|lower_left|lower_right|center|full]
- Send: define the section of image to extract and display. When a new
image is loaded or an existing image is redisplayed, the appropriate
section will be extracted from the image (if the image is larger than
the frame buffer size). The section specification is combined with the
blocking specification to determine which part of the image to
extract. However, if "full" is specified, the blocking factor is
ignored and the block at which to extract the image is calculated so that the
entire image will be displayed.
Receive: get the current section specification.
- select {image|frame} [x y|none]
- Send: select a point in the current image. By default, the coordinates
are image coordinates unless "frame" is specified. If "none" is specified,
the previously selected point is unselected.
A selected point is used to specify a center around which to extract
an image. The technique used is to load an image using the "full" section,
so that all of the image is viewable. A point is then selected and the
image reloaded, so that the image section is displayed centered on that
point.
- shm [name] [shmid]|[@shmkey] [len] {erase|noerase}
- Send: map a FITS image in shared memory and display it.
This public access point is used by programs that map a FITS image
into shared memory and want SAOtng to display it. Using a shared
memory FITS image will speed up display time, making SAOtng
potentially useful in near-real time data acquisition systems. The
first argument to this command is the name that SAOtng will use to
manage the image (playing the same role as a filename for disk files).
The second argument can either be the shared memory id parameter (shmid)
which is passed to the shmat system call, or else the shared
memory key parameter (shmkey) which is passed to the shmget call in order to
retrieve the shmid. Use of one or the other depends on the needs of
the program which creates the shared memory FITS file. Then third
argument is the length of the shared memory segment.
By default, the previous image is erased from the screen prior to display
of the new shared memory image. For some reason, someone wanted the
ability not to erase the previous image -- hence the "noerase" option.
Typically, the "shm" public access point is called once to set up the
shared memory connection. After that, "redisplay" is used to update
the display of the image.
- tcl [tcl instructions]
- Send: execute a tcl code fragment. This access point can be used to
execute TCL commands in the SAOtng GUI and generally is used as a
debugging tool for development work. Because of the obvious security
risk, it is turned off by default and must be activated explicitly by
means of the -allowtcl switch (or the SAOTNG_ALLOWTCL environment
variable).
- wcs {reset|replace|append} (send)
- Send: Define one or more WCS specifications for the current image.
Using this access point, a new WCS specification can be loaded and
used by the current image regardless of the WCS that was contained in
the image file. Multiple specifications can be loaded and associated with
rectangular regions of the image. As the mouse moves from one region
to another, the WCS display changes to use the appropriate
specification. This is especially useful for mosaic'ing.
WCS specification(s) can be sent to SAOtng using the xpaset command:
cat wcs.list | xpaset SAOtng wcs {options ...}
where the ASCII file wcs.list will contains one or more WCS specifications.
The format of each specification is a set of valid FITS keywords that
describe a WCS. Different WCS specifications are separated in the file by a
blank line. Thus, for example:
LOAXIS1 = 1
LOAXIS2 = 1
HIAXIS1 = 270
HIAXIS2 = 270
CRPIX1 = 257.75
CRPIX2 = 258.93
CRVAL1 = -201.94541667302
CRVAL2 = -47.45444
CDELT1 = -2.1277777E-4
CDELT2 = 2.1277777E-4
CTYPE1 = 'RA---TAN'
CTYPE2 = 'DEC--TAN'
LOAXIS1 = 271
LOAXIS2 = 271
CRPIX1 = 257.75
...
CTYPE2 = 'DEC--TAN'
Note that the WCS definitions can contain standard FITS 80-character
WCS card images, as shown above, or free-form name/value pairs without
the intervening "=" sign:
CRPIX1 257.75
CRPIX2 258.93
CRVAL1 -201.94541667302
CRVAL2 -47.45444
CDELT1 -2.1277777E-4
CDELT2 2.1277777E-4
CTYPE1 'RA---TAN'
CTYPE2 'DEC--TAN'
Additional special keywords specify the range of zoom1 coordinates for
which that WCS is valid. If no such limits are specified, the limits
default to (1, image dimensions), i.e. the entire image. If NAXIS1
and NAXIS2 are specified, then limits are (1, NAXIS1,NAXIS2). If
LOAXIS1 and/or LOAXIS2 are specified, these values are used as the low
value for the x and/or y dimension of the rectangle. If HIAXIS1
and/or HIAXIS2 are specified, these values are used as the high value
for the x and/or y dimension of the rectangle.
If "reset" is specified as a parameter, then previously specified WCS
descriptions are deleted and the WCS is set back to the file-based WCS.
This will be overridden by new WCS definitions that are sent at the same
time; otherwise the file-based WCS will be used. If "replace" is specified
as a parameter, then existing WCS definitions will be replaced by new ones
if the x,y limits match exactly. Otherwise, the new WCS definition will
be appended. If "append" is specified, new WCS definitions are appended.
The default is "reset".
- xpaname
- Receive: get the name of the xpa access point for the current image.
This is composed of the program title (default: SAOtng) and the root
of the image file name:
beberly-289: xpaget SAOtng xpaname
SAOtng.dsstest.fits
- zoom [zoom value|rel|abs|reset|center]
- Send: set the zoom (pixel replication) or pan factor for current frame.
If one numeric value is supplied, then the x and y zoom factors are
set to that value. If two values are supplied, then the x zoom factor
is set to the first value and the y zoom factor set to the second one.
If "abs" is specified before the value(s), then the zoom factor is
set to that value. If "rel" is specified, then the new zoom factor(s)
are set relative to the current zoom factor(s).
To ensure that markers are zoomed and panned correctly, zoom factors
are restricted to powers of two. (Setting the SAOTNG_RESTRICT
environment variable to "false" will override this, but markers might
be zoomed and panned inaccurately.)
Receive: get current x and y zoom factors and the x and y flip state:
beberly-315: xpaget SAOtng zoom
xmag=2
ymag=2
xflip=False
yflip=True