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
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.