Provided by: tcl-fitstcl_2.4-3build1_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