National Aeronautics and Space Administration

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

  cat commands.txt | xpaset pow tcl

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

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

  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")

  bounds
  select graph
  position
  curve
  version

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