Provided by: tcl-fitstcl_2.5-2build2_amd64 
NAME
fits - Tcl interface to FITS Files
SYNOPSIS
fits (open|info|close)
Handling FitsFile objects
fits open fileName mode ?objName?
Create a FitsFile object, open the file and read the header of the current HDU. (Read the CFITSIO web
pages or documentation to learn about its "Extended File Name Syntax".) mode can be 0 (read only) or 1
(read and write). If no objName is given, a name will be automatically assigned. A new empty FITS file
can be created by setting mode to 2. In this case, if the named file exists, then it will be overwritten.
Returns objName which will be used in most of the methods as the handle to the object.
fits info ?objName ...?
Return a list of all the existing objects, or the named objects (supports regular expressions), with the
following information: {objName fileName mode CHDU hduType} where CHDU is the current HDU (1-primary
array, 2-the first extension ...) and hduType is the type of the HDU (0-image, 1-ASCII table, 2-Binary
table).
objName move ?+/-?n
If n has ``+/-'' sign, then move n units relative to the CHDU, otherwise move to the nth HDU. Return the
extension type of the new HDU: 0-image, 1-ASCII table, 2-Binary Table.
objName close
Delete object objName.
fits close
Delete all the existing objects.
Getting information about the CHDU
objName info chdu
Return the CHDU. 1=primary, 2=first extension, etc.
objName info filesize
Return the size of the file (in units of 2880 bytes).
objName info hdutype
Return ``Primary array'', ``Image extension'', ``Binary Table'', or ``ASCII Table''.
objName info imgdim
Return the dimensions of the image if the CHDU is an image extension.
objName info ncols
Return the number of columns in the table if the CHDU is a table extension.
objName info nrows
Return the number of rows in the table if the CHDU is a table extension.
objName info nkwds
Return the number of keywords in the header of the CHDU.
objName info column ?-exact? ?colList?
Without any arguments, return a list of all the column names in the table if the CHDU is a table
extension. If colList is present, detailed information about the listed columns, using regular expression
name comparisons, is returned in the form of:
{Name Type Unit DisplayFormat DefaultFormat ColumnWidth isOffset isScaled defaultNull}
where
Name name of the column (TTYPE keyword)
Type type of the column (TFORM keyword)
Unit unit of the column (TUNIT keyword)
DisplayFormat format for display (TDISP keyword)
DefaultFormat default format for display (if TDISP keyword is absent)
ColumnWidth the width of the column (in units of characters).
isOffset 0 = no offset (no TZERO keyword), 1 = offset.
isScaled 0 = not scaled (no TSCALE keyword), 1 = scaled.
defaultNull default NULL value (TNULL keyword)
The -exact option turns off the regular expression matching.
Reading data from a FITS file
objName dump ?-s/-e/-l?
Return all the keyword records in the current header. The following options control how the information
is formatted:
none return list of all ards in header
-s return three lists: {keywords} {values} {comments}
-e return a single string containing a newline-separated list of all header records
-l return all the keyword names
objName get keyword ?keyList?
Return a list of {keyword value comment} for all the keywords in keyList (supports regular expressions).
If no keyList is given, return a list of entries for all the keywords in the CHDU. The order in which
keywords are listed is undefined. (HISTORY and COMMENT keywords are never returned.)
objName get keyword -num n
Return a list of {keyword value comment} of the nth keyword.
objName get wcs ?RAcol DecCol?
Return a list of the WCS parameters -- {xrval yrval xrpix yrpix xinc yinc rot ctype} -- for the CHDU. If
the current HDU is a table, supply the RAcol and DecCol parameters specifying the two columns (as names
or column numbers) containing WCS data. Use defaults for any missing WCS keywords: 1.0 for xinc/yinc;
``none'' for ctype; and 0.0 or all others. If the RA/Dec identity of the columns (or image axes) are not
known, an extra WCS parameter -- wcsSwap -- can be obtained which, when on, indicates that the X
parameters are for Dec instead of RA. Turn this option on with fits option wcsSwap 1.
objName get wcs -m ?Col1 ...?
Similar to above, but information is returned in new-style format, allowing arbitrary matrix transforms.
Return value is {refVals refPix matrix types projections} where each item (except matrix) contains a list
of the given information for each image dimension or table column; matrix is the rotation, scale, skew,
NxN transformation matrix given as {cd11 .. cd1N cd21 .. cd2N .. cdNN}. The wcsSwap option has no effect
on this command; one must check the types values to see if the RA and Dec transforms are backwards.
objName get image ?firstElem? ?numElem?
Read data elements from the current IMAGE extension and return them in a list. Without any parameters,
the entire image will be returned. If only firstElem is given, return just one element.
objName get table ?-c? ?-noformat? ?colList? ?rows?
Read a block of a table and return list(s) of data. The block range is set in
colList a list of all the columns one wants to read. Read all columns if missing or is
``*''.
rows a comma-separated list of row ranges of the form start-end (eg, ``3-5,7,9-'')
-c return data from each column as a separate list
-noformat do not format results according to a TDISPn, or default, format
objName get vtable ?-noformat? colName n ?rows?
Return a list of data in the nth vector element in column colName of the given rows. The -noformat option
turns off any TDISPn formatting.
Loading data into memory or to a TCL array
When loading data into memory, fitsTcl will normally return address dataType numElements where these are:
address Memory address of the data. Can be recovered in C by
sscanf(address, "%p", &databuff); with void *databuff dataType 0 - BYTE_DATA 1 byte data
1 - SHORTINT_DATA 2 byte integer 2 - INT_DATA 4 byte integer 3 - FLOAT_DATA 4 byte floating
point 4 - DOUBLE_DATA 8 byte floating point numElement Number of data elements in the array
objName load image ?slice? ?rotate?
Load a full 2D image in the CHDU into memory and return the address address (see above). slice indicates
which frame to use if image is 3D. rotate indicates how many 90-degree counter-clockwise rotations to
perform on the image (0-3).
objName load iblock arrayName firstRow numRows firstCol numCols ?slice?
Load a block (start from firstCol, firstRow with size numCols x numRows) of image data to a 2-D TCL array
arrayName or to memory if arrayName is ``--''. The indices of the array variable are (firstCol-1 ...
firstCol+numCols-1, firstRow-1 ... firstRow+numRows-1). A 1D image will be treated as either a single row
or column, depending on the row/column parameters supplied. For a 3D image, slice indicates which frame
to use. If arrayName is ``--'', read the data block into memory and return the pointer information:
address dataType numElements.
objName load irows firstRow lastRow ?slice?
objName load icols firstCol lastCol ?slice?
Read and average together a range of rows or columns of an image. Returns address dataType numElements.
dataType will be 3 for all image data types except for double for which dataType is 4.
objName load column colName ?defaultNull? ?firstElement?
Load a column of a table into memory and return address dataType numElements. Use the value of
defaultNull for NULL values, or internal defaults (normally the data type's maximum value) if ``NULL'' or
absent. If colName is a vector column, read the firstElement-th element. One can only load numerical
columns.
objName load vtable colName
Load all elements of the vector column colName and return address dataType numElements.
objName load tblock ?-noformat? arrayName colList firstRow numRows colIndex ?firstElem?
Load a block of table data to a 2-D TCL array arrayName. colIndex is (almost) the column index of the
array to use for the first column read. The first data index is actually (as for images)
(colIndex-1,firstRow-1). For scaler columns, firstElem = 1. Without the -noformat flag, values will be
returned as strings formatted according to a TDISP keyword or default format based on data type.
objName load expr ?-rows rows? expression ?defaultNull?
Evaluate the arithmetic expression on each row (or a subset of rows given by rows) of the CHDU's table
and return address dataType numElements, using defaultNull as the null value of any NULL results.
objName load keyword
Load keywords into fitsTcl's internal hash table. One usually will not need to call this routine.
objName load chdu
Reload the information about the current HDU. One usually will not need to call this routine.
Writing to a FITS file
objName insert image bitpix naxis naxesList
objName insert image -p ?bitpix naxis naxesList?
Insert an empty image HDU (primary header with -p) after the current HDU (or, at start of file for
primary array). The image parameters -- bitpix naxis naxesList -- can be left off if creating a zero-
length primary array.
objName insert table numRows {colNames} {colFormats} ?{colUnits} extensionName?
objName insert table -ascii numRows {colNames} {colFormats} ?{colUnits} {colPosition} extensionName rowWidth?
Insert an empty BINARY (default) or ASCII (with -ascii flag) table HDU after the current HDU. The
colNames and colFormats lists must be of equal length (possibly both empty). The optional parameters can
each be empty if one wants to use default/empty values.
objName insert keyword index record ?formatFlag?
Insert a new record at the index-th keyword. If formatFlag is 0, write the record exactly as passed,
otherwise parse it as a free form keyname value comment and reformat it into a standardized KEYNAME =
VALUE / COMMENT (default).
objName put keyword ?-num index? record ?formatFlag?
Write a keyword record either at position index; the position of a pre-existing keyword with the same
name; or append it if no such keyword exists. See above for format/meaning of record and formatFlag.
objName put history historyStr
Write a HISTORY keyword with content historyStr
objName insert column index colName colFormat
Insert an empty column with format colFormat before the index-th column. colFormat specifies the column
format as, for example:
ASCII Table: A15, I10, E12.5, D20.10, F14.6 ...
BINARY Table: 15A, 1I, 1J, 1E, 1D, 1L, 1X, 1B, 1C, 1M
objName add column colName colFormat ?expression?
Without an expression, append an empty column to the CHDU table; return nothing. Given an arithmetic
expression, though, the indicated column (new or old) will be filled in with the results of the
expression evaluated for each row of the table. If colName does not exist in the current table extension,
a new one will be created with format colFormat (see above). If colFormat is ``default'', the column will
be created based on the data type of the result. Return 1 or 0 to indicate whether a new column was
created (1) or not (0). expression can be in either C or Fortran format with table columns and keywords
referenced by their names. Here are some expression samples:
Expression Result
17.2 17.2 for every row
17 + 4*(PHI > 32) 17 or 21, depending on whether that row of the PHI column is greater than 32
sqrt( (X-X0)^2 + (Y-Y0)^2 ) Distance of the (X,Y) column coordinates from the (X0,Y0) keyword
values See the CFITSIO web pages and documentation for more details.
objName insert row index numRows
Insert number of numRows rows after the index-th row.
objName add row numRows
Add numRows rows at the end of the CHDU table.
objName put image firstElem listOfData
Write a block of data to the CHDU image. The first pixel of an image has firstElem = 1, not zero.
objName put table colName firstElem rowSpan listOfData
Write a list of data to the firstElem-th element of column colName in the CHDU table. (For scalar columns
firstElem is 1.) rowSpan is a single row range of form start-end with ``-'' indicating all rows.
Deleting data from a FITS file
objName delete keyword keyList
Delete listed keywords, where the keyList can be the mix of keyword names and index numbers. Keywords are
deleted individually in sequence, causing keyword positions to change after each deletion, so be careful
when deleting multiple keywords by index.
objName delete cols colList
Delete listed columns in a table extension.
objName delete rows firstRow numRows
Delete a block of rows.
objName delete rows -expr expression
Delete rows using expression which must evaluate to a boolean value. Rows for which expression evaluates
to TRUE get deleted.
objName delete chdu
Delete the current HDU. The HDU immediately following the one deleted (or the preceding one if the
current HDU is the last one of the file) will become the new current HDU. Returns extension type of new
HDU: 0-image, 1-ASCII table, 2-Binary Table.
Analyzing FITS data
objName sort ?-merge? colList ?ascendFlags?
Sort table rows using columns in colList. When -merge is present, if multiple rows have identical sort
keys all but one of the rows will be deleted. If present, ascendFlags contains a list of 1s and 0s
indicating whether that column will be sorted in ascending (1, the default) or descending (0) order.
objName column -stat colName ?firstElem? ?rows?
Return statistics on the firstElem-th element (1 for scalar columns) of column colName in the order min
firstMinRow max firstMaxRow mean stdDev numData.
objName column -minmax colName ?firstElem? ?rows?
Returns minimum and maximum values of the firstElem-th element (1 for scalar columns) of column colName.
objName histogram ?-weight colName|value? ?-inverse? ?-rows rows? filename {binAxis1} ?{binAxis2} ...?
Create a 1D - 4D histogram from columns in the current table. The binning parameters are given by the
binAxisN parameters which are lists of the form colName min max binSize where the last 3 elements can
each be ``-'', indicating default values. If TLMINn, TLMAXn, and/or TDBINn exist, those values will be
used for defaults. Otherwise, for min and max the defaults are the actual min/max values of the data; for
binSize the smaller of one-tenth the data span or 1.0 will be selected. A weighting value can be
indicated with the -weight option. This can be either another column or a numerical constant. The
-inverse option indicates the weight should be 1.0/weight instead of the weighting value itself. The
histogram can be restricted to certain row ranges using the -rows option.
objName smooth {width height} outfile ?inPrimary?
Smooth the current image extension with a boxcar function of dimensions width by height pixels. The
dimensions must be odd integers. The resulting image will be placed in a new extension appended to the
file outfile. If outfile does not exist, the image will be placed either in the primary or in the first
extension, depending on the value of the inPrimary flag; the default is to place it in an extension.
List/Pointer Manipulation
lst2ptr dataList ?dataType? ?naxesList?
Convert a TCL list into a memory-resident array. Returns address dataType naxesList (see the load
commands above). The TCL list will be cast as double values in the absence of the dataType parameter. The
parameter naxesList gives the vector dimensions of the list. It can be a single number indicating the
length of the list (the default value when absent) or a list of numbers which must multiply together to
be the list length. If a list entry contains the string "NULL", the maximum value of the given dataType
will be inserted.
ptr2lst address dataType naxesList
Convert a memory pointer into a TCL list. Returns dataList dataType naxesList (see lst2ptr). If an array
element contains the maximum value for the given dataType, the string "NULL" will be inserted into the
list.
vexpr ?-ptr? ?-use getDataCallback? expression
Perform a vector calculation using lists or arrays where expression is a C-style arithmetic expression.
(Ie, do not use $var notation unless you explicitly want variable substitution before passing expression
to vexpr.) Without any of the options, variable references within expression will be interpretted as
local TCL lists (or scalars) containing double data and the result will itself be a simple TCL list. With
the -ptr option set, the answer instead will be returned as a pointer to a memory-resident array. With
either option set, two additional parameters will be returned in a list of the form dataList dataType
naxesList or address dataType naxesList. The -use option provides a "callback" routine which is to be
used for supplying the variable data. It gets called when a variable is encountered in the expression and
will be passed a single argument containing the name of the variable. The callback routine should return
either "dataList dataType naxesList" or "-ptr address dataType naxesList". If the callback routine
doesn't recognize the variable, it should return an empty string. The parser will then try to find the
variable in the local namespace, as when no callback is supplied. If this fallback behavior is not
desired, raise an error instead. The callback function can itself check for local variables using the TCL
command upvar 1 $varName localName. The following code snippet provides a sample callback function which
assumes the expression contains variables storing the results of a load or lst2ptr command (ie, address
dataType naxesList):
proc getPtrData { varName } { upvar $varName myName if [info exists myName] { return [eval list -ptr
$myName] } else { error "Variable doesn't exist" } }
then the following code would calculate the average value of a table column:
set myCol [objName load column X] vexpr -use getPtrData "sum( (double)myCol ) / nelem( myCol )" By
default, a vector with a single-valued naxesList is interpretted as a single vector containing n elements
such that the above "sum" function sums all of the elements. In the context of loading a column, though,
one actually has an array of n rows with each row containing 1 (or perhaps more) elements. To handle this
case, one must use the callback function to provide an naxisList of "1 n" (or "2 m", etc) instead of
merely "n". In that case each row will be calculated separately and have its own result. When naxesList
has multiple elements, the final element specifies the number of rows.
See the CFITSIO web pages and documentation for details on expression syntax. One can also read the fv
online help file on expression syntax, noting that vexpr can only handle numerical input and output.
fits free addressList
Free the memory occupied by the data generated by one of the load, lst2ptr, and vexpr commands.
Other commands
objName copy filename
Copy the CHDU to a new FITS file. If the CHDU is not an image array, then an empty primary array is
inserted.
objName sascii table filename fileMode firstRow numRows colList widthList
Write the listed columns into an ASCII file. In the output file, each column has the width listed in
widthList. fileMode indicates how to write the data to filename: 0-create new file and write column
headings; 1-append to old file and write column headings; 2-append to old file, but don't write any
headings.
objName sascii image filename fileMode firstRow numRows firstCol numCols cellSize ?slice?
Write a block of the image data to an ASCII file. In the output file, the data has width of cellSize. Use
frame slice for 3D image data.
objName flush ?clear?
Flush any dirty buffers to the disk. With clear, free the buffers, too.
objName append filename
Append current HDU to another FITS file.
objName checksum update|verify
Update or Verify the checksum keywords in the current HDU. If none exist, update will create them. For
verify, the return values are 1 for valid values, 0 if either keyword (CHECKSUM or DATASUM) is missing,
and -1 for invalid values.
objName info expr expression
Get information on the result of the supplied arithmetic expression. Return value is cDataType
numElements {naxesList} where cDataType is the CFITSIO datatype (not fitsTcl's): TDOUBLE, TSTRING, etc;
numElements is the number of elements in the result; and naxesList contains the vector dimensions of the
result ({1} for scalar result). An expression which evaluates to a constant (no dependency on the
contents of the table) will be indicated by a negative number of elements.
range count rangeStr maxElem
Count the number of elements (esp. rows) contained within the comma-separated list of ranges in rangeStr
(eg, 1-4,5,7-). To support ranges of the form "7-" which specifies a range from element 7 through the
final element, maxElem is passed with the maximum element number.
fits option ?option? ?value?
Modify fitsTcl's default behavior. With no options, this returns a list of all the current fitsTcl
options and their values. With the option parameter, return the value of that parameter. When both option
and value are supplied, set the parameter to the given value. Current options: wcsSwap (0).
fits version
Get version numbers for fitsTcl and underlying cfitsio.
AUTHOR
Bryan Irby
Tcl interface to FITS Files 2.3 Tcl fits(3tcl)