POW Scripting Guide

Because fv and POW are written in Tcl, they are inherently scriptable. So long as one knows the necessary data structures and function calls, everything POW does can be controlled by a user-created Tcl script running inside of POW. This, however, is a formidable task. Plus, POW's internal behavior and data are subject to change with each new release.

To make scripting possible, then, a simplified (and hence limited) script interface has been added to POW. It consists of a small set of commands which perform the basic operations of creating and modifying graphs. Future versions should contain more capabilities.

Operational Summary

There are several ways to access POW's scripting commands. The simplest is to write a Tcl script which uses the commands directly and then execute it within POW's powCmds namespace. As POW has no file capabilities nor command console of its own, this currently can be done only if implemented within an application containing POW, such as fv. (See fv's Scripting Guide for details on executing POW commands within fv.) This scripting method is useful for implementing macros which can perform certain common operations at the user's request, such as setting specific graph options.

Alternatively, POW can be scripted by other programs, allowing those programs to make use of POW's capabilities remotely. These programs, however, do not need to be written in Tcl so long as they can communicate with POW. Currently POW supports XPA on unix platforms and AppleScript on MacOS for communication:

The XPA messaging system (http://hea-www.harvard.edu/RD/xpa/) developed by the SAO/HEAD R&D group implements a method of communicating between two programs running on unix platforms. Communication occurs either through standalone programs (ie, xpaget and xpaset), a C subroutine library, or a Tcl extension. POW uses the Tcl extension to make its scripting commands available, but the calling program can use any of the XPA methods to access the commands. The XPA software is not distributed with POW or fv and must be obtained and built by the user.

AppleScript (http://www.apple.com/applescript), the English-like language on all Macintosh computers (circa MacOS 7.5 and up), can also be used to control POW remotely. (Actually, any program on the Mac can control POW through the use of Apple Events.) Using the do script command, Tcl code can be passed to POW. Due to how Tcl's do script command and POW's scripting commands are implemented, POW commands must be prefixed with the powCmds:: namespace specifier.

POW's scripting capabilities closely mimic the interface described in POW's Developer's Guide. In general, one first creates a data object from which either a curve or image is produced. One then creates a graph onto which a series of curves and/or images is placed. The graph size, position, and viewing region can then be modified as needed. Once plotted in a graph, curves and images can be displayed using different point shapes, line styles, or colormaps. In most cases, commands operate on the currently selected object (as appropriate).

Many scripting commands also can be used as inquiries. Inquiries and commands are implemented using the same syntax, differing only in that commands supply the necessary parameters to perform an action, whereas inquiries leave them off indicating POW should return the current settings. When used with XPA, inquiries must use the xpaget tool and commands the xpaset tool.

Command Summary

add curve|image objName

Add a curve or image to the current graph.

array channel dataName bitpix ?byteOrder?

Imports data into POW from a TCL channel. When run using XPA, channel is dropped and the data is read form stdin. bitpix indicates the data format of the binary data (eg., 8, -32, INT, DOUBLE, etc) and byteOrder indicates whether the data is stored in bigEndian or littleEndian format. The default value of byteOrder is whichever is native for the platform. FITS and IEEE are synonyms for bigEndian. If bitpix has the string value LIST, the data is read treated as an ASCII stream with double values. If dataName has a singular element, all values in the table are placed into a single data object with the supplied name. If dataName is instead a list, the stream will be considered as a columnar table with each column going into a corresponding data element of dataName.

axes xscale ?yscale?

Sets axes as log or linear. If only one value applied it will be applied to both axes.

bounds xLft yBtm xRgt yTop ?wcs|pixel?

Set the bounding box of the current graph in either wcs (default) or pixel coordinates.

bounds reset

Reset the current graph's bounding box to its default values.

bounds zoom xMag ?yMag?

Increase or decrease the bounding box by the given magnification factors.

calculate newDataName expression

Perform a calculation on existing data objects

close

Close/Exit POW

colormap cmap

Set the colormap of images in the current graph

colormap add cmap R G B R G B ...

Add a custom colormap named cmap. The RGB values are given in triplets of integer values ranging over 0 to 255. Any number of triplets can be provided and will be scaled to the number of colors available on screen.

colormap invert Yes|No

Invert colormap of images

colormap scale ?mode? ?min max?

Set the colormap scaling mode and range of images

contour ?-res n? ?-image imgName? crvName level1 ?level2 ...?

Create a contour map of the current (or imgName) image. The result is a single curve object named crvName outlining regions of the image with intensities level1 etc. If -image is used to specify the image, the image does not need to be plotted in the current (or any other) graph. The -res option gives the image resolution to use in calculating the contour (default is 1); the image will be smoothed over this number of pixels square. The curve contour will not be plotted automatically; use add curve crvName to add it to the current graph.

create data dataName dataList

Create a data object with the supplied values.

create curve curveName xDataName ?xeDataName? yDataName ?yeDataName?

Create an X/Y curve object with or without errors from the supplied data objects.

create image imageName dataName width height

Create an image object of given dimensions and data object.

create graph graphName curveList imageList ?width height?

Create a graph with the given curves and images. width and height give the screen size of the graph in pixels (default is set in the Preferences panel). Either of the lists can have a value of NULL if no objects of that type are being used.

cursor

Wait for the user to click on the current graph then return the graph coordinates and mouse button pressed: x y button.

curve ?-name crvName? param value ?param value? ...

Set curve options. The currently-selected curve will be used if the -name option isn't specified; otherwise set options for the indicated curve. The curve crvName does not have to exist prior to executing this command, so options can be set before a curve is created and drawn. If crvName is "default", the value will apply to all curves not yet plotted. The available parameters and value types are:

       pDisp     -->  boolean  -->  Display Points?
       pShape    -->  string   -->  Point shape (Cross, Diamond, Box,
                                       Octagon, Triangle, "Inv. Triangle")
       pSizeErr  -->  boolean  -->  Draw point the size of errorbars?
       pSize     -->  integer  -->  Size of point
       pFill     -->  boolean  -->  Fill in point, if an outline
       pColor    -->  color    -->  Color of points (any color name
                                       or #RRGGBB value)
   	       	             	  
       lDisp     -->  boolean  -->  Display line?
       lStyle    -->  dash     -->  Dash style of line (" " is solid, 
                                       "20" is 20-pixel dashes,
                                       "15 10 4 10" is Dash-dot, etc)
       lWidth    -->  integer  -->  Width of line
       lStep     -->  boolean  -->  Draw line as histogram?
       lBoxFill  -->  boolean  -->  Fill histogram boxes?
       lColor    -->  color    -->  Color of line (any color name
                                       or #RRGGBB value)

delete ?-propogate? graph|image|curve|data objName

Delete an object from POW, freeing any memory it occupied. Deleted curves and images will be removed from all graphs in which they are displayed. With the -propogate option, the contents of the object are also deleted, meaning all the curves and images in a graph, and the original data within an image or curve. Data which is still being used by a curve or image object, however, will not be deleted.

graph ?-name graphName? param value ?param value? ...

Set graph options. The currently-selected graph will be used if the -name option isn't specified; otherwise set options for the indicated graph. The graph graphName does not have to exist prior to executing this command, so options can be set before a graph is created and drawn. If graphName is "default", the value will apply to all future graphs. The available parameters and value types are:

       bgcolor         -->  color     -->  Color behind graph (any color
                                              name or #RRGGBB value)
       xmargin         -->  integer   -->  Intergraph spacing; affects
       ymargin         -->  integer   -->     placement of new graphs
       xdimdisp        -->  integer   -->  Screen dimensions of graph;
       ydimdisp        -->  integer   -->     affects size of new graphs
       FixedAspect     -->  boolean   -->  Force identical horizontal
                                              and vertical scales for graph
                                              (defaults to yes if any
                                               images present)

       xlabel          -->  string    -->  Label for X axis
       ylabel          -->  string    -->  Label for Y axis
       xunits          -->  string    -->  Optional unit value for X axis
       yunits          -->  string    -->  Optional unit value for Y axis
       titleString     -->  string    -->  Title for graph
       titlePosition   -->  direction -->  Position around graph to place
                                              title... value is a string
                                              containing the letters n, e,
                                              w, s (for north, east, etc)
       titleAnchor     -->  direction -->  Position in title to place at
                                              the titlePosition... value is
                                              a string containing n, e, w, s.

       xNumTicks       -->  integer   -->  Scaling parameter for number of
       yNumTicks       -->  integer   -->     tick marks on each axis
                                              (default, 3; not 1-to-1)
       xTickScal       -->  string    -->  Scaling of tick marks along
       yTickScal       -->  string    -->     each axis: "linear" or "log".
                                              Graphs with WCS information
                                              ignore this and use ra/dec.
       xTickLength     -->  list      -->  Length of tick marks for each
       yTickLength     -->  list      -->     axis on each side of graph.
                                              Order is [lft rgt top bot]
                                              (default: "10 10 10 10xLft yBtm xRgt yTop ?wcs|pixel?
   
 Set the bounding box of the current graph in either
        wcs (default) or pixel coordinates.  

   
 bounds reset 
   
 Reset the current graph's bounding box to its default values. 

   
 bounds zoom xMag ?yMag?
   
 Increase or decrease the bounding box by the given
        magnification factors. 

   
 calculate newDataName expression
   
 Perform a calculation on existing data objects

   
 close
   
 Close/Exit POW 

   
 colormap cmap
   
 Set the colormap of images in the current graph

   
 colormap add cmap R G B R G B ...
   
 Add a custom colormap named cmap.  The RGB values are given
        in triplets of integer values ranging over 0 to 255.  Any number
        of triplets can be provided and will be scaled to the number of
        colors available on screen. 

   
 colormap invert Yes|No 
   
 Invert colormap of images 

   
 colormap scale ?mode? ?min max?
   
 Set the colormap scaling mode and range of images

   
 contour ?-res n? ?-image imgName?
        crvName level1 ?level2 ...?
   
 Create a contour map of the current (or imgName) image.
        The result is a single curve object named crvName
        outlining regions of the image with intensities level1
        etc.  If -image is used to specify the image, the image
        does not need to be plotted in the current (or any other) graph.
        The -res option gives the image resolution to use in
        calculating the contour (default is 1); the image will be
        smoothed over this number of pixels square.  The curve contour
        will not be plotted automatically; use add curve crvName
        to add it to the current graph.

   
 create data dataName dataList
   
 Create a data object with the supplied values. 

   
 create curve curveName xDataName ?xeDataName?
        yDataName ?yeDataName?
   
 Create an X/Y curve object with or without errors from the
        supplied data objects. 

   
 create image imageName dataName width height
   
 Create an image object of given dimensions and data object.

   
 create graph graphName curveList imageList ?width
        height? 
 Create a graph with the given curves and
        images.  width and height give the screen size
        of the graph in pixels (default is set in the Preferences panel).
        Either of the
        lists can have a value of NULL if no objects of that
        type are being used. 

   
 cursor
   
 Wait for the user to click on the current graph then return the
        graph coordinates and mouse button pressed:  x y button.

   
 curve ?-name crvName? param value
        ?param value? ...
   
 Set curve options.  The currently-selected curve will be used
        if the -name option isn't specified; otherwise set options
        for the indicated curve. The curve crvName does not have to
        exist prior to executing this command, so options can be set
        before a curve is created and drawn.  If crvName is
        "default", the value will apply to all curves not yet plotted.
        The available parameters and value types are:

       pDisp     -->  boolean  -->  Display Points?
       pShape    -->  string   -->  Point shape (Cross, Diamond, Box,
                                       Octagon, Triangle, "Inv. Triangle")
       pSizeErr  -->  boolean  -->  Draw point the size of errorbars?
       pSize     -->  integer  -->  Size of point
       pFill     -->  boolean  -->  Fill in point, if an outline
       pColor    -->  color    -->  Color of points (any color name
                                       or #RRGGBB value)
   	       	             	  
       lDisp     -->  boolean  -->  Display line?
       lStyle    -->  dash     -->  Dash style of line (" " is solid, 
                                       "20" is 20-pixel dashes,
                                       "15 10 4 10" is Dash-dot, etc)
       lWidth    -->  integer  -->  Width of line
       lStep     -->  boolean  -->  Draw line as histogram?
       lBoxFill  -->  boolean  -->  Fill histogram boxes?
       lColor    -->  color    -->  Color of line (any color name
                                       or #RRGGBB value)
 

   
 delete ?-propogate? graph|image|curve|data objName
   
 Delete an object from POW, freeing any memory it occupied.
        Deleted curves and images will be removed from all graphs in
        which they are displayed.  With the -propogate option,
        the contents of the object are also deleted, meaning all the
        curves and images in a graph, and the original data within an
        image or curve.  Data which is still being used by a curve or
        image object, however, will not be deleted.

   
 graph ?-name graphName? param value
        ?param value? ...
   
 Set graph options.  The currently-selected graph will be used
        if the -name option isn't specified; otherwise set options
        for the indicated graph. The graph graphName does not have to
        exist prior to executing this command, so options can be set
        before a graph is created and drawn.  If graphName is
        "default", the value will apply to all future graphs.
        The available parameters and value types are:
       bgcolor         -->  color     -->  Color behind graph (any color
                                              name or #RRGGBB value)
       xmargin         -->  integer   -->  Intergraph spacing; affects
       ymargin         -->  integer   -->     placement of new graphs
       xdimdisp        -->  integer   -->  Screen dimensions of graph;
       ydimdisp        -->  integer   -->     affects size of new graphs
       FixedAspect     -->  boolean   -->  Force identical horizontal
                                              and vertical scales for graph
                                              (defaults to yes if any
                                               images present)

       xlabel          -->  string    -->  Label for X axis
       ylabel          -->  string    -->  Label for Y axis
       xunits          -->  string    -->  Optional unit value for X axis
       yunits          -->  string    -->  Optional unit value for Y axis
       titleString     -->  string    -->  Title for graph
       titlePosition   -->  direction -->  Position around graph to place
                                              title... value is a string
                                              containing the letters n, e,
                                              w, s (for north, east, etc)
       titleAnchor     -->  direction -->  Position in title to place at
                                              the titlePosition... value is
                                              a string containing n, e, w, s.

       xNumTicks       -->  integer   -->  Scaling parameter for number of
       yNumTicks       -->  integer   -->     tick marks on each axis
                                              (default, 3; not 1-to-1)
       xTickScal       -->  string    -->  Scaling of tick marks along
       yTickScal       -->  string    -->     each axis: "linear" or "log".
                                              Graphs with WCS information