fv 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 fv does can be controlled by a user-created Tcl script running inside of fv. This, however, is a formidable task. Plus, fv'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 fv. It consists of a small set of commands which perform the basic operations of opening FITS files and displaying their contents. Future versions should contain more capabilities.

(Note: This method of scripting fv replaces an earlier method. Although the older method still can be used, it is deprecated.)


Operational Summary


There are several ways to access fv's scripting commands. The simplest is to write a Tcl script which uses the commands directly and then have fv execute it. Give the script a ".fv" filename extension so that fv can recognize it. This method requires the user to open the file interactively within fv (using the same method as opening a FITS file). This scripting method is useful for implementing macros which can perform certain common operations at the user's request.

Alternatively, fv can be scripted by other programs, allowing those programs to make use of fv's capabilities remotely. These programs, however, do not need to be written in Tcl so long as they can communicate with fv. Currently fv 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. fv 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 fv and must be obtained and built by the user. (Use '--with-tcl=$FV/lib' when configuring XPA to have it build the tcl extension; if not installing XPA into the fv directories, using '--prefix=$FV', one must also set the LD_LIBRARY_PATH environment variable to point to the directory containing libtclxpa.so.)

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 fv remotely. (Actually, any program on the Mac can control fv through the use of Apple Events.) Using the do script command, Tcl code can be passed to fv. Due to how Tcl's do script command and fv's scripting commands are implemented, fv commands must be prefixed with the fvCmds:: namespace specifier.

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 fv should return the current settings. When used with XPA, inquiries must use the xpaget tool and commands the xpaset tool.


Command Summary


close ?extNum ...?
Close the current file or one of its extensions. If no extension numbers are specified, the entire file will be closed, potentially exitting fv if no windows remain open. To close all extensions, but keep the file open, give an extNum of -1. Otherwise, specify the particular extensions which should be closed; this will close any windows (header or table) linked to that extension.
create file fileName signed/unsigned bitpix dimension
Create a file by providing fileName with keyword signed or unsigned and a value for bitpix (8, 16, etc). Also users need to provide value for dimension (11, 22 23, etc).
create extension extName image signed/unsigned bitpix dimension
Create an image extension extName in current opened FITS file with keyword signed or unsigned and a value for bitpix (8, 16, etc). Also users need to provide value for dimension (11, 22 23, etc).
create extension extName table binary/ASCII
Create a table extension extName in current opened FITS file with keyword Binary or ASCII to indicate what type of extension is going to be created.
delete rows extNum rowRange
Delete rows of extension extNum of the currently selected file. An example rowRange is 2-10,15-20.
delete cols extNum colName(s)
Delete columns of extension extNum of the currently selected file. Column names should be separated by the space.
display header extNum
Open a window containing the header keywords of extension extNum of the currently selected file. If extNum is current or ".", use the default extension (or zero if undefined).
display table extNum ?columnName ...|frame?
Open a window containing the extension data in a table format. If a real table extension, one can either supply a series of column names to display or "-" to display all the columns. Not specifying a number will pop-up a column selection box requiring user input. If the extension is an image, no arguments are required unless it has 3 dimensions in which case the desired frame must be specified. If extNum is current or ".", use the default extension (or zero if undefined).
display image extNum ?start? ?end?
Display the contents of the extension as an image using either POW or DS9, depending on fv's settings. If the image has 3 dimensions, the frames to plot must be specified. If both a start and end frame are supplied, the frames will be animated in POW. If extNum is current or ".", use the default extension (or zero if undefined).
display curve extNum -rows|-cols start ?end? ?currGraph?
Display a scatter plot of pixel intensity vs axis index from selected rows or columns in an image. If both start and end are present, the range of rows/cols will be averaged before plotting. currGraph is a boolean flag indicating whether this curve should be placed on the currently selected graph in POW. If false/zero (or absent), a new graph will be created. If extNum is current or ".", use the default extension (or zero if undefined).
display curve extNum X xErr Y yErr ?currGraph? ?rowrange?
Plot an X vs Y curve from a table. Errors for X and Y can optionally be displayed. Both error parameters must be present, although an empty place-holder ({}) can be used to indicate the absence of errors. Each of these parameters can be either a simple column name or a complex arithmetic expression evaluated using the extension's data. The optional parameter, currGraph, is a boolean flag indicating whether this curve should be placed on the currently selected graph in POW. If false/zero (or absent), a new graph will be created. The parameter, rowrange specify which rows' data will be plot. If extNum is current or ".", use the default extension (or zero if undefined).
export hdu extNum ?fileName?
Export a given extNum in the current fits file. The result file will be saved in the current directory and be opened after the exporting function is finished. The optional 'fileName' argument specify the output file name.
export summary extNum ?fileName?
Export the summary in a given extNum in the current file to a text file. The result file will be named with _hdu.txt at the end or 'fileName' and saved in the current directory.
exporttable fileName option extNum
Export the selected columns and rows from the table in a given extNum in the given fileName to a fits file or text file. The option will be hdu and text. The valid extNum will be 0, 4 and etc.
insert rows extNum afterRow numRows
Insert 'numRows' rows after row 'afterRow' in a given extNum in the current file.
insert col extNum colName colFormat ?beforeCol
Insert a column in a given table (extNum) at the end or before 'beforeCol' in the current file.
help operation ...
Display short help on UNIX command line. The valid value for operation, can be just one or a list of, are close, create, delete,display, export, ecporttable,insert,open, opentool, pow, preference, quit, save, select, sort, tcl, version
open filename ...
Open one or more FITS files. The full paths to the files should be specified since fv will probably have a different working directory than the caller (ftp/http urls are acceptable). Without a filename, a list of open files will be returned. (When used with XPA, inquiries must use the xpaget tool).
opentool toolName
Open available ftools dialog. The valid values for toolName are skyview, catalog, vizier, or ftools
pow powCommand ...
Execute one of POW's scripting commands. These commands are described in the POW Scripting Guide.
preference parameter ?value?
Set fv preference.
preference parameter valid value
open preference panel open N/A
close preference panel close N/A
minimize preference panel minimize N/A
iconify preference panel iconify N/A
select preference page page App, Keywords, Tables, Graphs, and Colors
display File Selection fileSelection Open, Close
color choice activebackground red, green, #cccccc, etc
color choice activeforeground red, green, #cccccc, etc
color choice background red, green, #cccccc, etc
color choice checkbuttoncolor red, green, #cccccc, etc
color choice foreground red, green, #cccccc, etc
graph display displayer ds9, pow, saotng
graph display graphsize 300x300, 500x300, 300x500
500x500, 700x500, 500x700
700x700
desk topy help help N/A
auto-plot primary image autoplotprimary 0 - deselect
1 - select
automatic format keys autoreformatkeys 0 - deselect
1 - select
automatic update
checksum
autoupdatechecksum 0 - never
1 - if exist
2 - always
display Fits
file only
dispfitsonly 0 - deselect
1 - select
left justify string leftjustifystring 0 - right
1 - left
protect required keyword protectedkeys 0 - deselect
1 - select
show desktop manager usedesktopmanager 0 - deselect
1 - select
use WCS info wcsinfo 0 - deselect
1 - selects
write history key
after modification
writehiskey 0 - deselect
1 - select
Window Management winmanagement Keep, Hid, Close
quit
Quit fv.
save ?fileName?
Save current file. If fileName is specified, the file will be saved under that name. A pre-existing file of that name will be overwritten.
select fileIndex|fileName ?extNum?
Select an opened file for manipulation. One can specify it either as an index into the list of opened filenames returned by the open command or as a proper filename. fileName can be either a fully-specified pathname of the file or just the filename itself. The optional extNum can be used to select a default extension which can be used in some other commands. A fileName of current or "." can be used to modify the default extension of the current file. Without parameters, the full pathname of the default file will be returned. (When used with XPA, inquiries must use the xpaget tool).
sort extNum ?-unique? ?-ascending|-descending? colName ?-ascending|-descending? colName ...
Sort a table extension according to the supplied colNames. Each column can be sorted in either -ascending or -descending order. The default is ascending, but a column will inherit the order of a previous column, if not explicit set. If the -unique flag is set, duplicate rows which contain identical sorted values will be deleted, leaving only one such row per unique set of values.
tcl
Execute tcl code read from stdin (XPA support only).
version
Return fv version number. When used with XPA, inquiries must use the xpaget tool.

Examples


The following commands will open 2 files and display their contents in several ways.

  open ngc1316r.fit rate.fit       # open 2 files included with fv
  select rate.fit                  # select one of files
  display header 1                 # Open window of first extension's keywords
  display curve 1 time rate        # Plot a curve of time vs rate in POW
  pow bounds 720 -30 950 300       # Resize graph's bounding box
  select ngc1316r.fit              # Select other file
  display image 0                  # Plot image
  set x [version]                  # Get fv's version number
Type the preceding lines (without the comments) into a text file, name it commands.fv, then run it: either put it in the command line when starting fv (eg, "fv commands.fv") or open the file with the Open File menu item.

Using XPA from a Unix shell, one would do the following:

  xpaset -p fv open ngc1316r.fit rate.fit
  xpaset -p fv select rate.fit       
  xpaset -p fv display header 1            
  xpaset -p fv display curve 1 time rate   
  xpaset -p fv pow bounds 720 -30 950 300  
  xpaset -p fv select ngc1316r.fit        
  xpaset -p fv display image 0             
  xpaget    fv version
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, using the command...
  cat commands.fv | xpaset fv tcl
This latter method allows one to insert real Tcl commands into the command sequence, whereas the individual xpaget/xpaset calls are restricted to the specific scripting commands.

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

  tell application "fv"
    activate
    do script "fvCmds::open ngc1316r.fit rate.fit"
    do script "fvCmds::select rate.fit"
    do script "fvCmds::display header 1"
    do script "fvCmds::display curve 1 time rate"
    do script "fvCmds::pow bounds 720 -30 950 300"
    do script "fvCmds::select ngc1316r.fit"
    do script "fvCmds::display image 0"
    do script "fvCmds::version"
    set x to the result
  end tell
Note that AppleScript will actually start fv if it isn't already running.

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


Pages maintained by Bryan Irby
Send bug reports or feature requests via the FTOOLS help desk.


HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Thursday, 16-Jul-2009 14:09:27 EDT

Pages maintained by Bryan Irby
Send bug reports or feature requests via the FTOOLS help desk.


HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: 16-Jul-2009