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
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)
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)
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
-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.
-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
example of usage:
cat file | xpaset pow regions
-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
example of usage:
cat file | xpaset pow xranges
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 20The -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 tclThis 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.