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

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

  cat commands.fv | xpaset fv tcl

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

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