Provided by: tcl-fitstcl_2.4-3build1_amd64 bug

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