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.