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
colorbar create
  create a colorbar of the current graph
colorbar delete
  delete a colorbar of the current graph
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.
  Note: to avoid hitting the limit on the command line length, use piped stdout command:
  echo dataList | create data dataName
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. A keypress will also be captured and returned in the place of button as its negative ASCII value (ie, -65 for A).
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 10")
             xLabelTicks     -->  list      -->  Boolean indicating whether ticks
             yLabelTicks     -->  list      -->     should be labels for each
                                                    axis on each side of graph.
                                                    Order is [lft rgt top bot]
                                                    (default: "Yes No No Yes")
             tickLabels      -->  string    -->  Format for labeling ticks on
                                                    graphs with WCS information:
                                                    "degrees" or "decimal"
             tickFormatCmdX  -->  string    -->  Tcl command used in formatting
             tickFormatCmdY  -->  string    -->     tick values into labels
                                                    (default: "format %.6lg")

             GridLines       -->  boolean   -->  Draw grid lines?
             GridColor       -->  color     -->  Grid color (any color name
                                                    or #RRGGBB value)
             GridDash        -->  dash      -->  Grid dash pattern
                                                    (" " is solid, "20" is
                                                    20-pixel dashes, "15 10 4 10"
                                                    is Dash-dot, etc)

helpPage ?file?
  Open and display help file in html format. Two ways to do this:

              1. xpaset -p pow helpPage file
                      - if file is not a full path file name, then it is assumed to be one
                        of the installed POW help file.
                      - else, user needs to supply the full path name to the file.
              2. cat file | xpaset pow helpPage

init ?nColors? ?cMode?
  Open and initialize pow's graphing window. If the window is already open, this does nothing.
print ?-file filename? ?-landscape? ?-stretch? ?-multipage?
  Send all images on POW canvas to printer. Save all images if -file is supplied.

              -file        : result file name. The extension of file name should indicates valid saved format
                             (i.e. filename.jpg).  Current valid formats are bmp, jpg, ps, ppm, png, pnm, and tiff.
              -landscape   : print/save result in landscape mode (default is portrait).
              -stretch     : stretch the image to fit the page (default is no).
              -multipage   : one image per page (default is print/save on the same page/file)

              Note: The image needs to be displayed in POW in order to print or save.

position ?offset? x y
  Moves current graph around the canvas. When offset is present, x and y are relative offsets from the current position.
refresh
  Redraws current graph
regionName region file name
  Set output region name, should be used after Region Edit Panel is opened.
regionTool ?-open? ?-close? ?-wait?
  Open the Region Edit Panel on POW.

              -open  : open the region edit panel
              -close : close the region edit panel
              -wait  : wait for region edit panel to close. Return save means data has been saved.
                                                            Return unsave means otherwise

regions
  Open Region Edit Panel (if not opened already), displays input Region of Interest (ROI) on POW image and update entry in the Region Edit Panel.

              example of usage:
                 cat file | xpaset pow regions

remote ?clientXPA?
  Set the XPA access point of a client POW session to which all subsequent commands should be sent. Send an empty clientXPA to have commands executed locally. If the environment variable `POW_LIBRARY` is defined, its value will be used for clientXPA.
remove ?-name graphName? curve|image objName
  Remove an object from the current graph or graphName.
scope width ?height?
  Sets scope window size. If only one value is given, the scope window will be a square.
select curve|image|graph objName
  Select a curve/image/graph for manipulation
size width height
  Set graph size
size stretch ?to? xMag ?yMag?
  Stretch graph size by the given magnification either relative to current magnification or an absolute magnification.
tcl
  Execute tcl code read from stdin (XPA support only).
version
  Return POW version number
xrangeName file name
  Set output file name to save x axis ranges, should be used after X axis Range Edit Panel is opened.
xrangeTool ?-open? ?-close? ?-wait?
  Open the X axis Range Edit Panel on POW.

              -open  : open the x axis range edit panel
              -close : close the x axis range edit panel
              -wait  : wait for x axis range edit panel to close. Return save means data has been saved.
                                                                  Return unsave means otherwise

xranges
  Open X axis Range Edit Panel (if not opened already), displays input X axis Ranges of Interest (XROI) on POW image and update entry in the X axis Range Edit Panel.

              example of usage:
                 cat file | xpaset pow xranges

wcs objName wcsData
  Set (or get) WCS information for the given object (can be a curve or image). The wcsData is a list of the form of either
  - xrval yrval xrpix yrpix xinc yinc rot ctype ?swap?
  - refVals refPix matrix types projections
  If WCS information has not already been provided for objName the "get" version of this command will return an empty string. (See fitsTcl documention for more information.)

Examples

The following commands will create a graph in pow and plot 2 curves in it.

      create data d1 1 2 3 4 5 6 5 4 3 2 1     # Create data object d1
      create data d2 1 4 9 16 20 16 9 4 2 1 1  # Create data object d2
      create curve c1 d1 d2                    # Create curve of d1 vs d2
      create graph g1 c1 NULL                  # Draw graph containing curve
      size 200 150                             # Resize graph to 200x150
      calculate d3 'd1*2'                      # Calculate new data object
      create curve c2 d3 d2                    # Create curve of d3 vs d2
      add curve c2                             # Add curve to graph
      bounds reset                             # Reset bounding box
      select curve c1                          # Select first curve
      curve pFill Yes pColor Blue lDisp No     # Set display options
      select curve c2                          # Select second curve
      curve pDisp No lColor Red lStyle 20      # Set display options

Using XPA from a Unix shell, one would execute the above commands by doing the following:

      xpaset -p pow create data d1 1 2 3 4 5 6 5 4 3 2 1
      xpaset -p pow create data d2 1 4 9 16 20 16 9 4 2 1 1
      xpaset -p pow create curve c1 d1 d2
      xpaset -p pow create graph g1 c1 NULL
      xpaset -p pow size 200 150
      xpaset -p pow calculate d3 d1*2
      xpaset -p pow create curve c2 d3 d2
      xpaset -p pow add curve c2
      xpaset -p pow bounds reset
      xpaset -p pow select curve c1
      xpaset -p pow curve pFill Yes pColor Blue lDisp No
      xpaset -p pow select curve c2
      xpaset -p pow curve pDisp No lColor Red lStyle 20

The -p option tells xpaset to not read any data from stdin. One can instead use stdin to send a series of Tcl commands en masse by putting all the POW commands into a text file and pass them to POW, using the command...

      cat commands.txt | xpaset pow tcl

This second method allows one to insert real TCL commands (providing access to the entire POW API) into the command sequence, whereas the individual xpaget/xpaset calls are restricted to the specific scripting commands.

Alternatively, if using AppleScript, the commands are...

      tell application "fv"
        activate
        -- Because POW is available only as part of POW on Macs, the following
        -- line is needed to open POW's window, if it doesn't already exist
        do script "if { ![winfo exist .pow.pow] } { powInit .dummy }"
        do script "powCmds::create data d1 1 2 3 4 5 6 5 4 3 2 1"
        do script "powCmds::create data d2 1 4 9 16 20 16 9 4 2 1 1"
        do script "powCmds::create curve c1 d1 d2"
        do script "powCmds::create graph g1 c1 NULL"
        do script "powCmds::size 200 150"
        do script "powCmds::calculate d3 d1*2"
        do script "powCmds::create curve c2 d3 d2"
        do script "powCmds::add curve c2"
        do script "powCmds::bounds reset"
        do script "powCmds::select curve c1"
        do script "powCmds::curve pFill Yes pColor Blue lDisp No"
        do script "powCmds::select curve c2"
        do script "powCmds::curve pDisp No lColor Red lStyle 20"
      end tell

Note that AppleScript will actually start fv if it isn't already running.

Now that the graph is created, one can make inquiries with the following commands using XPA...

      xpaget pow bounds         # Get the bounding box of current graph
      xpaget pow select graph   # Get name of the currently selected graph
      xpaget pow position       # Get position of the graph
      xpaget pow curve          # Get display options of current curve
      xpaget pow version        # Get pow version number

... or, using AppleScript...

      set x to (do script "powCmds::bounds")
      set x to (do script "powCmds::select graph")
      set x to (do script "powCmds::position")
      set x to (do script "powCmds::curve")
      set x to (do script "powCmds::version")

... or, using an as-yet-missing interactive console...

      bounds
      select graph
      position
      curve
      version

Additional examples of scripting can be found in the `sample_scripts` directory within the fv distribution.