The SAOtng Public Access Points

SAOtng has defined a number of Public Access Points through which XPA commands can be communicated with SAOtng. A list of public access points is displayed below. The current list can obtained by typing: 

    xpaget SAOtng

Each public access point can be accessed by means of the xpaset or xpaget command. For example, to change the colormap, type: 

    csh> echo "colormap I8" | xpaset SAOtng
To get the current colormap, type: 
    csh> xpaget SAOtng colormap
    I8

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: 

    csh> imset colormap I8
To get the current colormap, type: 
    csh> imget colormap
    I8

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:

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
Last Updated June 17, 1998