--- name: "fits" section: "3tcl" platform: "linux" package: "tcl-fitstcl" version: "2.5-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/fits" --- # fits(3tcl) Tcl interface to FITS Files ## 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*