slang-cfitsio 0.3.8+nosvn-4.1+b1 / usr / share / slsh / local-packages / help / cfitsio.hlp

_fits_get_errstatus

 SYNOPSIS
  Retrieve a text string corresponding to an error code

 USAGE
  String_Type _fits_get_errstatus (Int_Type status)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_errstatus'.
  See its documentation for additional information.

 SEE ALSO
  fits_read_errmsgs, _fits_read_errmsg

--------------------------------------------------------------

_fits_read_errmsg

 SYNOPSIS
  Retrieve an error message from the cfitsio error message stack

 USAGE
  String_Type _fits_read_errmsg ()

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_read_errmsg'.
  See its documentation for additional information.

 NOTES
  This function returns NULL if there are no error messages available.

 SEE ALSO
  fits_read_errmsgs, fits_set_verbose_errors

--------------------------------------------------------------

_fits_open_file

 SYNOPSIS
  Open a fits file

 USAGE
  status = _fits_open_file (Ref_Type fptr, String_Type file, String_Type mode)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_open_file'.
  See its documentation for additional information.

  The main difference between this function and its cfitsio
  counterpart is that the `mode' argument is a string whose value
  must be one of the following:

    "r"     Open the file in read-only mode
    "w"     Open the file in read-write mode
    "c"     Create a new file.

  Note that if the mode argument is `"c"', then the
  cfitsio `fits_create_file' function will be called.  An
  important difference between this intrinsic function and the
  `fits_create_file' library function is that if the file already
  exists, the library function will return an error, whereas
  `_fits_open_file' will simply delete the file before creating a
  new one.

--------------------------------------------------------------

_fits_delete_file

 SYNOPSIS
  Delete the file associated with a Fits_File_Type object

 USAGE
  status = _fits_delete_file (Fits_File_Type fptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_delete_file'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_close_file

 SYNOPSIS
  Close a fits file

 USAGE
  status = _fits_close_file (Fits_File_Type fptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_close_file'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_movabs_hdu

 SYNOPSIS
  Move to an absolute HDU number

 USAGE
  status = _fits_movabs_hdu (Fits_File_Type fptr, Int_Type hdunum)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_movabs_hdu'.
  See its documentation for additional information.

 NOTES
  The cfitsio counterpart also returns the HDU type of the resulting
  HDU.

--------------------------------------------------------------

_fits_movrel_hdu

 SYNOPSIS
  Move a relative number of HDUs

 USAGE
  status = _fits_movrel_hdu (Fits_File_Type fptr, Int_Type nmove)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_movrel_hdu'.
  See its documentation for additional information.

 NOTES
  The cfitsio counterpart also returns the HDU type of the resulting
  HDU.

--------------------------------------------------------------

_fits_movnam_hdu

 SYNOPSIS
  Move to a named HDU

 USAGE
  status = _fits_movnam_hdu (fptr, hdutype, extname, extvers)

   Fits_File_Type fptr;
   Int_Type hdutype, extvers;
   String_Type extname;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_movnam_hdu'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_num_hdus

 SYNOPSIS
  Return the number of HDUs in a FITS file

 USAGE
  status = _fits_get_num_hdus (Fits_File_Type fptr, Ref_Type hdunum)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_num_hdus'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_hdu_num

 SYNOPSIS
  Return the current HDU number

 USAGE
  hdunum = _fits_get_hdu_num (Fits_File_Type fptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_hdu_num'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_hdu_type

 SYNOPSIS
  Get the current HDU type

 USAGE
  status = _fits_get_hdu_type (Fits_File_Type fptr, Ref_Type hdutype)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_hdu_type'.
  See its documentation for additional information.

  Upon a sucessful return, the value of the variable associated with
  the `hdutype' reference will be set to one of the following
  constants:

   _FITS_IMAGE_HDU
   _FITS_ASCII_TBL
   _FITS_BINARY_TBL


--------------------------------------------------------------

_fits_copy_file

 SYNOPSIS
  Copy a fits file

 USAGE
  status = _fits_copy_file (infptr, outfptr, previous, current, following)

   Fits_File_Type infptr, outfptr;
   Int_Type previous, current, following;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_copy_file'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_copy_hdu

 SYNOPSIS
  Copy an HDU

 USAGE
  status = _fits_copy_hdu (infptr, outfptr, morekeys)

   Fits_File_Type infptr, outfptr;
   Int_Type morekeys;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_copy_hdu'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_copy_header

 SYNOPSIS
  Copy a fits header from one HDU to another

 USAGE
  status = _fits_copy_header (Fits_File_Type infptr, Fits_File_Type outfptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_copy_header'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_delete_hdu

 SYNOPSIS
  Delete the current HDU

 USAGE
  status = _fits_delete_hdu (Fits_File_Type fptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_delete_hdu'.
  See its documentation for additional information.

 NOTES
  The corresponding cfitsio function also returns the HDU type of the
  new HDU.  If that information is necessary, make a separate call to
  `_fits_get_hdu_type'.

--------------------------------------------------------------

_fits_create_img

 SYNOPSIS
  Create a new image extension

 USAGE
  status = _fits_create_img (fptr, bitpix, dims)

   Fits_File_Type fptr;
   Int_Type bitpix;
   Array_Type dims;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_create_img'.
  See its documentation for additional information.

 NOTES
  This function differs from the corresponding cfitsio function in
  that the `dims' array is assumed to be a 1-d integer array
  whose elements specify the number of axes and the size of each axis.
  In particular, the value of the NAXIS keyword will be given by
  `length(dims)', the value of NAXIS1 will be given by
  `dims[0]', and so forth.

--------------------------------------------------------------

_fits_write_img

 SYNOPSIS
  Write an image

 USAGE
  status = _fits_write_img (Fits_File_Type fptr, Array_Type img

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_write_img'.
  See its documentation for additional information.

 NOTES
  This function differs from its cfitsio counterpart in that the whole
  image represented by the array `img' will be written out.

--------------------------------------------------------------

_fits_read_img

 SYNOPSIS
  Read an image

 USAGE
  status = _fits_read_img (Fits_File_Type fptr, Ref_Type img)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_read_img'.
  See its documentation for additional information.

 NOTES
  This function differs from the corresponding cfitsio routine in that
  the type of the image returned is automatically determined by the
  routine via a call to `fits_get_img_type'.  The dimensionality
  of the returned image is given by `[...,NAXIS2,NAXIS1]' such
  that `NAXIS1' corresponds to the fastest varying dimension,
  `NAXIS2' the next fastest varying, etc.

--------------------------------------------------------------

_fits_create_binary_tbl

 SYNOPSIS
  Create a binary table extension

 USAGE
  status = _fits_create_binary_tbl (fptr, naxis2, ttype, tform, tunit, extname)

   Fits_File_Type fptr;
   Array_Type tunit, tform, ttype;
   Int_Type naxis2;
   String_Type extname;


 NOTES
  The `_fits_create_binary_tbl' function is a wrapper around the
  fits_create_tbl function explicitly creating a binary table.
  The input arrays `ttype', `tform', and `tunit' must
  be the same length, which determines the number of columns in the
  table.  The `tunit' and `extname' parameters may be set to
  NULL.

--------------------------------------------------------------

_fits_update_key

 SYNOPSIS
  Update a keyword or append a new one

 USAGE
  status = _fits_update_key (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname, comment;
   Any_Type value;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_update_key'.
  See its documentation for additional information.

 NOTES
  The data-type for the `value' argument must be an approriate type for
  FITS keywords.  If `value' is a string, then the string will be
  written as a cfitsio long-string using the
  fits_update_key_longstr function.  If `value' is NULL,
  then the fits_update_key_null function will be called to
  update the keyword.

  The `comment' parameter may be set to NULL to if the comment
  field associated with the keyword is not to be modified.

  To update the value of a boolean (logical) keyword, use the
  `_fits_update_logical' function.

--------------------------------------------------------------

_fits_update_logical

 SYNOPSIS
  Update the value of a boolean keyword

 USAGE
  status = _fits_update_logical (fptr, keyname, value, comment)

  Fits_File_Type fptr;
  String_Type keyname, comment;
  Int_Type value;


 DESCRIPTION
  The `_fits_update_logical' function is a wrapper around the
  cfitsio fits_update_key function with TLOGICAL specified as
  the datatype argument.  If the `value' parameter is non-zero,
  then a value `T' (TRUE) will be given to the specified
  keyword.  Otherwise, the value of the keyword will be set to
  `F' (FALSE).

  If the `comment' parameter is NULL, then the keyword's comment
  field will not be modified.

 SEE ALSO
  _fits_update_key

--------------------------------------------------------------

_fits_write_comment

 SYNOPSIS
  Write a COMMENT header

 USAGE
  status = _fits_write_comment (Fits_File_Type fptr, String_Type comment)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_write_comment'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_write_history

 SYNOPSIS
  Write a HISTORY header

 USAGE
  status = _fits_write_history (Fits_File_Type fptr, String_Type history)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_write_history'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_write_date

 SYNOPSIS
  Write a DATE keyword

 USAGE
  status = _fits_write_date (Fits_File_Type fptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_write_date'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_write_record

 SYNOPSIS
  Write a keyword record

 USAGE
  status = _fits_write_record (Fits_File_Type fptr, String_Type card)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_write_record'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_modify_name

 SYNOPSIS
  Rename a keyword

 USAGE
  status = _fits_modify_name (fptr, oldname, newname)

   Fits_File_Type fptr;
   String_Type oldname, newname;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_modify_name'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_num_keys

 SYNOPSIS
  Get the number of keywords in the current HDU

 USAGE
  status _fits_get_num_keys (Fits_File_Type fptr, Ref_Type numkeys)

 DESCRIPTION
  This function is a wrapper around the cfitsio
  fits_get_hdrspace function.  It obtains the number of
  existing keywords in the current HDU (excluding the END keyword) and
  assigns that value to variable associated with the `numkeys'
  parameter.

--------------------------------------------------------------

_fits_read_key_integer

 SYNOPSIS
  Read the value of a keyword as an integer

 USAGE
  status = _fits_read_key_integer (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;


 DESCRIPTION
  This function uses the cfitsio fits_read_key function to read
  the value of the specifed keyword as an integer.  Its value is
  assigned to the variable referenced by the `value' parameter.
  If the comment parameter is non-NULL, then the value of the comment
  field will be assigned to it.

 SEE ALSO
  _fits_read_key, _fits_read_key_string, _fits_read_key_double

--------------------------------------------------------------

_fits_read_key_string

 SYNOPSIS
  Read the value of a keyword as a string

 USAGE
  status = _fits_read_key_string (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;


 DESCRIPTION
  This function uses the cfitsio fits_read_key_longstr function
  to read the value of the specifed keyword as a cfitsio long-string.
  The string is assigned to the variable referenced by the
  `value' parameter. If the comment parameter is non-NULL, then
  the value of the comment field will be assigned to it.

 SEE ALSO
  _fits_read_key, _fits_read_key_integer, _fits_read_key_double

--------------------------------------------------------------

_fits_read_key_double

 SYNOPSIS
  Read the value of a keyword as a double

 USAGE
  status = _fits_read_key_double (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;


 DESCRIPTION
  This function uses the cfitsio fits_read_key function
  to read the value of the specifed keyword as a double.
  The keyword's value is assigned to the variable referenced by the
  `value' parameter. If the comment parameter is non-NULL, then
  the value of the comment field will be assigned to it.

 SEE ALSO
  _fits_read_key, _fits_read_key_integer, _fits_read_key_string

--------------------------------------------------------------

_fits_read_key

 SYNOPSIS
  Read the value of a keyword

 USAGE
  status = _fits_read_key (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;


 DESCRIPTION
  This function uses the cfitsio fits_read_key function
  to read the value of the specifed keyword.  It first uses the cfitsio
  fits_get_keytype function to determine the data-type for the
  keyword and then calls fits_read_key using that data-type.
  The resulting value is assigned to the variable referenced by the
  `value' parameter. If the comment parameter is non-NULL, then
  the value of the comment field will be assigned to it.

 SEE ALSO
  _fits_read_key_integer, _fits_read_key_string, _fits_read_key_double

--------------------------------------------------------------

_fits_read_record

 SYNOPSIS
  Read a specified record from the current HDU

 USAGE
  status = _fits_read_record (fptr, keynum, card)

   Fits_File_Type fptr;
   Int_Type keynum;
   Ref_Type card;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_read_record'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_delete_key

 SYNOPSIS
  Delete a keyword from the header

 USAGE
  status = _fits_delete_key (Fits_File_Type fptr, String_Type keyname)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_delete_key'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_colnum

 SYNOPSIS
  Get the column number of a specfied table column

 USAGE
  status = _fits_get_colnum (fptr, colname, colnum)

   Fits_File_Type fptr;
   String_Type colname;
   Ref_Type colnum;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_colnum'.
  See its documentation for additional information.

 NOTES
  The corresponding cfitsio function permits a wildcard match to the
  `colname' parameter.  The current wrapping of this function
  does not support such matching.

  The `colname' parameter is treating in a case-insensitive manner.

--------------------------------------------------------------

_fits_insert_rows

 SYNOPSIS
  Insert rows into a table

 USAGE
  status = _fits_insert_rows (fptr, firstrow, nrows)

   Fits_File_Type fptr;
   Int_Type firstrow, nrows;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_insert_rows'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_delete_rows

 SYNOPSIS
  Delete rows from a table

 USAGE
  status = _fits_delete_rows (fptr, firstrow, nrows)

   Fits_File_Type fptr;
   Int_Type firstrow, nrows;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_delete_rows'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_insert_cols

 SYNOPSIS
  Insert columns into a table

 USAGE
  status = _fits_insert_cols (fptr, colnum, ttype, tform)

   Fits_File_Type fptr;
   Int_Type colnum;
   Array_Type ttype, tform;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_insert_cols'.
  See its documentation for additional information.

 NOTES
   The number of columns to be inserted is given by the length of
   the `ttype' and `tform' arrays, which must be of the same
   length.

--------------------------------------------------------------

_fits_delete_col

 SYNOPSIS
  Delete a column from a table

 USAGE
  status = _fits_delete_col (Fits_File_Type fptr, Int_Type colnum)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_delete_col'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_num_cols

 SYNOPSIS
  Get the number of table columns

 USAGE
  status = _fits_get_num_cols (Fits_File_Type fptr, Ref_Type ncols)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_num_cols'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_rowsize

 SYNOPSIS
  Get the number of rows to read or write for maximum efficiency

 USAGE
  status = _fits_get_rowsize (Fits_File_Type fptr, Ref_Type nrows)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_rowsize'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_num_rows

 SYNOPSIS
  Get the number of table rows

 USAGE
  status = _fits_get_num_cols (Fits_File_Type fptr, Ref_Type nrows)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_num_rows'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_write_col

 SYNOPSIS
  Write data to a table column

 USAGE
  status = _fits_write_col (fptr, colnum, firstrow, firstelem, array)

   Fits_File_Type fptr;
   Int_Type colnum;
   Int_Type firstrow, firstelem;
   Array_Type array;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_write_col'.
  See its documentation for additional information.

 NOTES
   The number of elements written out to the column by this function
   will be equal to the number of elements in the array.

--------------------------------------------------------------

_fits_read_col

 SYNOPSIS
  Read elements from a column

 USAGE
  status = _fits_read_col (fptr, colnum, firstrow, numrows, array

   Fits_File_Type fptr;
   Int_Type colnum, firstrow, numrows;
   Ref_Type array;


 DESCRIPTION
  This function is a complicated wrapper around a number of cfitsio
  functions to enable it to read any type of column, including vector
  and variable length columns.  The data read by the function is
  assigned as the appropriately typed array to the variable referenced
  by the `array' argument.

  For ordinary scalar columns, a 1-d array of size `numrows' will
  be produced.  For a vector column, a 2d array of size
  `[numrows,repeat]' will be generated.  Here `repeat' is
  given by the repeat value associated with the column.  For a
  variable length column, where data are stored in the heap of the
  HDU, the data will be read as a 1-d array of `numrows' arrays.

  If the column is a bit-valued column, then data will be returned as
  an array of integers of the appropriate size.  Currently only 8X,
  16X, and 32X bit columns are supported.

 SEE ALSO
  _fits_read_cols, _fits_write_col

--------------------------------------------------------------

_fits_get_keytype

 SYNOPSIS
  Get a keyword's data type

 USAGE
  status = _fits_get_keytype (fptr, keyname, type)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type type;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_keytype'.
  See its documentation for additional information.

 NOTES
  This function differs from its cfitsio counterpart in that instead
  of explicitly specifying the keyword's value string, this function
  uses the value of the specified keyword.  It also returns the type
  as a S-Lang `DataType_Type' object, e.g., `Int_Type',
  `Complex_Type', etc.

--------------------------------------------------------------

_fits_get_keyclass

 SYNOPSIS
  Get the class of an input header record

 USAGE
  Int_Type _fits_get_keyclass (String_Type card)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_keyclass'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_read_cols

 SYNOPSIS
  Read one or more table columns

 USAGE
  status = _fits_read_cols (fptr, colnums, firstrow, nrows, arrays)

   Fits_File_Type fptr;
   Array_Type colnums;
   Int_Type firstrow, numrows;
   Ref_Type arrays;


 DESCRIPTION
  This function performs a similar task as the `_fits_read_col'.
  The main difference is that instead of reading a single column, it
  is capable of reading multiple columns specified by the `colnums'
  parameter.  It assigns the data as an array of arrays to the
  variable referenced by the `arrays' parameter.  See the
  documentation for the `_fits_read_col' function for more
  information.

 NOTES
  This function takes advantage of the cfitsio buffering mechanism to
  optimize the reads.

--------------------------------------------------------------

_fits_write_chksum

 SYNOPSIS
  Compute and write DATASUM and CHECKSUM keywords

 USAGE
  status = _fits_write_chksum (Fits_File_Type fptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_write_chksum'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_update_chksum

 SYNOPSIS
  Update the CHECKSUM keyword

 USAGE
  status = _fits_update_chksum (Fits_File_Type fptr)

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_update_chksum'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_verify_chksum

 SYNOPSIS
  Verify the checksums for the current HDU

 USAGE
  status = _fits_verify_chksum (fptr, dataok, hduok)

   Fits_File_Type fptr;
   Ref_Type dataok, hduok;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_verify_chksum'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_chksum

 SYNOPSIS
  Get the checksums for the current HDU

 USAGE
  status = _fits_get_chksum (fptr, datasum, hdusum)

   Fits_File_Type fptr;
   Ref_Type datasum, hdusum;


 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_chksum'.
  See its documentation for additional information.

--------------------------------------------------------------

_fits_get_version

 SYNOPSIS
  Get the cfitsio library version number

 USAGE
  Float_Type _fits_get_version ()

 DESCRIPTION
  This function is a wrapper around the CFITSIO function `fits_get_version'.
  See its documentation for additional information.

--------------------------------------------------------------

fits_read_errmsgs

 SYNOPSIS
  Retrieve all error messages from the CFITSIO error stack

 USAGE
  String_Type[] fits_read_errmsgs ()

 DESCRIPTION
 This function returns all the error messages from the CFITSIO error
 message stack as an array of strings.

 NOTES
 Using this function will cause the error message stack to be cleared.

 SEE ALSO
  _fits_read_errmsg, fits_set_verbose_errors

--------------------------------------------------------------

fits_set_verbose_errors

 SYNOPSIS
  Set the verbosity level of the cfitsio error messages

 USAGE
  fits_set_verbose_errors (Int_Type level)

 DESCRIPTION
 When a call to a function in the high-level interface fails, a error
 message will get generated.  By default, all messages from the
 underlying cfitsio error stack are printed.  This behavior may be
 turned off by calling this function with `level' equal to 0.

 SEE ALSO
  fits_read_errmsgs

--------------------------------------------------------------

fits_open_file

 SYNOPSIS
  Open a fits file

 USAGE
  Fits_File_Type fits_open_file (String_Type filename, String_Type mode)

 DESCRIPTION
  The `fits_open_file' function can be used to open and existing fits
  file for reading or updating, or to create a new fits file, depending upon
  the value of the `mode' parameter.  Specifically, if `mode' is
  `"r"', the file will be opened for reading.  If `mode' is `"w"',
  the file will be opened for updating (both reading and writing).  Otherwise,
  `mode' must be `"c"', which indicates that a new file is to be created.
  In the latter case, if a file already exists with the specified name, it will
  get deleted and a new one created in its place.

  If the function fails, it will signal an error; otherwise an open file
  pointer will be returned.

 SEE ALSO
  fits_close_file, fits_create_binary_table

--------------------------------------------------------------

fits_close_file

 SYNOPSIS
  Close a fits file

 USAGE
  fits_close_file (Fits_File_Type f)

 DESCRIPTION
  The `fits_close_file' closes a previously opened fits file.  The function
  will signal an error if the operation fails.

 NOTES
  This function could fail if it fails to write out any buffered data because
  of filesystem errors (disk full, etc.).

 SEE ALSO
  fits_open_file

--------------------------------------------------------------

fits_move_to_interesting_hdu

 SYNOPSIS
  Move to an extension that looks interesting

 USAGE
  fits_move_to_interesting_hdu (fp [, hdu_type]

  Fits_File_Type fp;
  Int_Type hdu_type;


 DESCRIPTION
  The function move the fits file pointer `fp' forward to an HDU that looks
  interesting.  By definition, an interesting HDU is one in which NAXIS is
  non-zero.  The first parameter `fp' must be a pointer to an already open
  fits file.  The second parameter, if present, may be used to specifiy the
  type of HDU, e.g., either an image (`hdu_type=_FITS_IMAGE_HDU') or a
  binary table (`hdu_type=_FITS_BINARY_TBL').

  If the function fails to find an interesting HDU of the appropriate type,
  an exception will be generated.

 SEE ALSO
  fits_open_file

--------------------------------------------------------------

fits_key_exists

 SYNOPSIS
  Check for the existence of a keyword

 USAGE
  Int_Type fits_key_exists (fd, key)

   Fits_File_Type or String_Type fd;
   String_Type key;


 DESCRIPTION
  The `fits_key_exists' function checks for the existence of a specified
  keyword in the file specified by the descriptor `fd', which must specify
  the name of a file or an open file pointer.

  If the specified key exists, the function return 1, otherwise it returns 0.

 SEE ALSO
  fits_read_key, fits_read_header

--------------------------------------------------------------

fits_get_colnum

 SYNOPSIS
  Get the column numbers of specified columns

 USAGE
  column_num = fits_get_colnum (fd, column_name)

   Fits_File_Type or String_Type fd;
   String_Type column_name;


 DESCRIPTION
  This function returns the column number of the column with the specified name.
  The file-descriptor `fd' must specify the name of a file, or an open
  fits file pointer.

 SEE ALSO
  fits_binary_table_column_exists

--------------------------------------------------------------

fits_binary_table_column_exists

 SYNOPSIS
  Check for the existence of a binary table column

 USAGE
  Int_Type fits_binary_table_column_exists (fd, col)

   Fits_File_Type or String_Type fd;
   String_Type col;


 DESCRIPTION
  This function may be used to determine whether or not a named column
  exists in a binary table.  The table is specified via the `fd'
  parameter which must either be the name of a file containing the binary
  table, or an file pointer.

  If the specified column exists, 1 will be returned; otherwise the function
  will return 0.

 SEE ALSO
  fits_key_exists, fits_open_file

--------------------------------------------------------------

fits_read_col

 SYNOPSIS
  Read one or more columns from a FITS binary table

 USAGE
  (x1, ...xN) = fits_read_col (file, c1, ... cN)

   Fits_File_Type or String_Type file;
   Int_Type or String_Type c1, ...cN;


 DESCRIPTION
  This function returns one or more vectors containing objects in the
  specified columns of the binary table indicated by `file'.  If
  `file' is a string, then the file will be opened via the virtual
  file specification implied by `file'. Otherwise, `file'
  should represent an already opened FITS file.  The column parameters
  may either be strings denoting the column names, or integers
  representing the column numbers.

 SEE ALSO
  fits_read_cell, fits_read_row, fits_read_table

--------------------------------------------------------------

fits_read_col_struct

 SYNOPSIS
  Read one or more columns from a FITS binary table

 USAGE
  struct = fits_read_col_struct (file, col1, ...)

    Fits_File_Type or String_Type file;
    String_Type col1, ...;


 DESCRIPTION
  This function works exactly like `fits_read_col' except it returns the
  values in a structure.  See the documentation on that function for more
  information.

 SEE ALSO
  fits_read_col, fits_read_key_struct, fits_read_row, fits_read_header

--------------------------------------------------------------

fits_read_cell

 SYNOPSIS
  Read a cell from a FITS binary table

 USAGE
  X = fits_read_cell (file, c, r)

   Fits_File_Type or String_Type file;
   Int_Type r, c;


 DESCRIPTION
  This function returns the object in the column `c' and row
  `r' of the binary table indicated by `file'.  If `file'
  is a string, then the file will be opened via the virtual file
  specification implied by `file'. Otherwise, `file' should
  represent an already opened FITS file.

 SEE ALSO
  fits_read_col, fits_read_row

--------------------------------------------------------------

fits_read_row

 SYNOPSIS
  Read a row from a FITS binary table

 USAGE
  Struct_Type fits_read_cell (file, r)

   Fits_File_Type or String_Type file;
   Int_Type r;


 DESCRIPTION
  This function returns a structure containing the data in the columns
  of the row `r' of the binary table indicated by `file'. If
  `file' is a string, then the file will be opened via the virtual
  file specification implied by `file'. Otherwise, `file'
  should represent an already opened FITS file.

 SEE ALSO
  fits_read_col, fits_read_cell

--------------------------------------------------------------

fits_read_header

 SYNOPSIS
  Read a FITS header

 USAGE
  Struct_Type fits_read_header (file)

    Fits_File_Type or String_Type file;


 DESCRIPTION
  This function reads the header of the fits file given by the
  `file' parameter and returns it as a structure.  If `file' is
  a string, then the file will be opened via the virtual file
  specification implied by `file'. Otherwise, `file' should
  represent an already opened FITS file.

 SEE ALSO
  fits_read_table

--------------------------------------------------------------

fits_read_table

 SYNOPSIS
  Read a FITS table

 USAGE
  Struct_Type fits_read_table (file [,columns...])

    Fits_File_Type or String_Type file;


 DESCRIPTION
  `fits_read_table' reads the data in a table of the FITS file
  specified by `file' and returns it as a structure.  If the optional
  column name parameters are specified, then only those columns will be read.
  Otherwise, the entire table will be returned.

  If `file' is a string, then the file will be opened via the virtual file
  specification implied by `file'. Otherwise, `file' should
  represent an already opened FITS file.

 SEE ALSO
  fits_read_col, fits_read_cell, fits_read_row, fits_read_header

--------------------------------------------------------------

fits_read_key

 SYNOPSIS
  Read one or more keywords from a FITS file

 USAGE
  (val1,...) = fits_read_key (file, key1, ...)

    Fits_File_Type or String_Type file;
    String_Type key1, ...;


 DESCRIPTION
  `fits_read_key' reads the values of one or more keywords in the fits
  file specified by `file' and returns them.  If `file'
  is a string, then the file will be opened via the virtual file
  specification implied by `file'. Otherwise, `file' should
  represent an already opened FITS file.  If any of the keywords do not exist,
  a value of NULL will be returned for the corresponding keyword.

 SEE ALSO
  fits_read_key_struct, fits_read_col, fits_read_cell, fits_read_row, fits_read_header

--------------------------------------------------------------

fits_read_key_struct

 SYNOPSIS
  Read one or more keywords from a FITS file

 USAGE
  struct = fits_read_key (file, key1, ...)

    Fits_File_Type or String_Type file;
    String_Type key1, ...;


 DESCRIPTION
  This function works exactly like `fits_read_key' excepts returns the
  values in a structure.  See the documentation on that function for more
  information.

 SEE ALSO
  fits_read_key, fits_read_col, fits_read_cell, fits_read_row, fits_read_header

--------------------------------------------------------------

fits_create_binary_table

 SYNOPSIS
  Prepare a binary table

 USAGE
  fits_create_binary_table (file, extname, nrows, ttype, tform, tunit)

    Fits_File_Type or String_Type file;
    String_Type extname;
    Int_Type nrows;
    String_Type ttype[];
    String_Type tform[];
    String_Type tunit[];


 DESCRIPTION
  This creates a new binary table with the specified structure.  The parameters
  `ttype', `tform', and `tunit' are string arrays that specify
  the column names, column data type, and column units, respectively.
  The binary table will be given the extension name `extname'.

 SEE ALSO
  fits_write_binary_table, fits_open_file

--------------------------------------------------------------

fits_write_binary_table

 SYNOPSIS
  Write a binary table

 USAGE
  fits_write_binary_table (file, extname, sdata, [skeys [,hist]])

Fits_File_Type or String_Type file;
String_Type extname;
Struct_Type sdata;
Struct_Type skeys;
Struct_Type hist;


 DESCRIPTION
  The `fits_write_binary_table' function creates a new binary table in
  the specified file.  The parameter `file' specifies either a filename or
  an open file pointer.  The `extname' parameter specifies the extension
  name of the binary table.  The data written to table are specified in the
  `sdata' structure, where the name of the structure field specifies the
  column name.  If `skeys' is non-NULL, then it is a structure indicating
  additional keywords to be written to the header of the binary table.  If the
  optional parameter `hist' is present and non-NULL, then it is a structure
  whose fields indicate either comment or history information to be written
  to the header.

 EXAMPLE
  The following code

    variable data = struct { x, cosx, sinx };
    data.x = [0:2*PI:0.01];
    data.cosx = cos(data.x);
    data.sinx = sin(data.x);

    variable keys = struct { hduname, username};
    keys.hduname = "COSXSINX";
    keys.username = "John Doe";

    variable hist = struct { history, comment};
    hist.history = ["This is a history record", "This is another"];
    hist.comment = ["This is a comment", "And this is another"];

    fits_write_binary_table ("foo.fits", "COSXSINX", data, keys, hist);

 produces a binary table with the header:

    XTENSION= 'BINTABLE' / binary table extension
    BITPIX  =                   8 / 8-bit bytes
    NAXIS   =                   2 / 2-dimensional binary table
    NAXIS1  =                  24 / width of table in bytes
    NAXIS2  =                 629 / number of rows in table
    PCOUNT  =                   0 / size of special data area
    GCOUNT  =                   1 / one data group (required keyword)
    TFIELDS =                   3 / number of fields in each row
    TTYPE1  = 'x       ' / label for field   1
    TFORM1  = 'D       ' / data format of field: 8-byte DOUBLE
    TTYPE2  = 'cosx    ' / label for field   2
    TFORM2  = 'D       ' / data format of field: 8-byte DOUBLE
    TTYPE3  = 'sinx    ' / label for field   3
    TFORM3  = 'D       ' / data format of field: 8-byte DOUBLE
    EXTNAME = 'COSXSINX' / name of this binary table extension
    HDUNAME = 'COSXSINX'
    USERNAME= 'John Doe'
    HISTORY This is a history record
    HISTORY This is another
    COMMENT This is a comment
    COMMENT And this is another


 NOTES
  This function provides no mechanism to mix comments and keyword records.  As
  the example shows, this function places the comment and history records at
  the end of the table.

 SEE ALSO
  fits_create_binary_table, fits_open_file

--------------------------------------------------------------

fits_update_key

 SYNOPSIS
  Update the value of a keyword

 USAGE
  fits_update_key (fd, key, val [,comment])

    String_Type or Fits_File_Type fd;
    String_Type key;
    Any type val;
    String_Type comment;


 DESCRIPTION
  The `fits_update_key' function updates the value and comment fields
  of an existing keyword with the specified name.  If the keyword does not
  exist, a new keyword will be appended to the end of the header.

 SEE ALSO
  fits_update_logical, fits_read_key

--------------------------------------------------------------

fits_update_logical

 SYNOPSIS
  Update the value of a logical (boolean) keyword

 USAGE
  fits_update_logical (fd, key, val, comment)

    String_Type or Fits_File_Type fd;
    String_Type key;
    Any type val;
    String_Type comment;


 DESCRIPTION
  The `fits_update_logical' function updates the value and comment fields
  of an existing keyword of the specified name with the specified boolean value.
  If the keyword does not exist, a new keyword will be appended to the end of
  the header.

 SEE ALSO
  fits_update_key

--------------------------------------------------------------

fits_write_comment

 SYNOPSIS
  Write a comment to the header

 USAGE
  fits_write_comment (fd, comment)

  Fits_File_Type or String_Type fd;
  String_Type comment;


 DESCRIPTION
  As the name indicates, this function writes a comment record to the specified
  fits file.  The file-descriptor `fd' must either be the name of a fits
  file or an open fits file pointer.

 SEE ALSO
  fits_update_key, fits_write_history

--------------------------------------------------------------

fits_write_history

 SYNOPSIS
  Write a history record to the header

 USAGE
  fits_write_history (fd, history)

  Fits_File_Type or String_Type fd;
  String_Type history;


 DESCRIPTION
  As the name indicates, this function writes a history record to the specified
  fits file.  The file-descriptor `fd' must either be the name of a fits
  file or an open fits file pointer.

 SEE ALSO
  fits_update_key, fits_write_comment

--------------------------------------------------------------

fits_write_date

 SYNOPSIS
  Write the DATE keyword to the current HDU

 USAGE
  fits_write_date (fd)

   Fits_File_Type or String_Type fd;


 DESCRIPTION
  The `fits_write_date' function calls `_fits_write_date' to write
  the DATE to the header of the specified file descriptor, which  must either
  be the name of a fits file or an open fits file pointer.

 SEE ALSO
  fits_update_key

--------------------------------------------------------------

fits_write_chksum

 SYNOPSIS
  Compute and write the DATASUM and CHECKSUM keywords

 USAGE
  fits_write_chksum (fd)

   Fits_File_Type or String_Type fd;


 DESCRIPTION
  The `fits_write_chksum' function calls `_fits_write_comment' to
  compute and write the DATASUM and CHECKSUM keywords to the
  header of the specified file descriptor, which  must either
  be the name of a fits file or an open fits file pointer.

 SEE ALSO
  fits_update_key, fits_verify_chksum

--------------------------------------------------------------

fits_verify_chksum

 SYNOPSIS
  Verify the checksums for the current HDU

 USAGE
  isok = fits_verify_chksum (fd [,dataok, hduok])

   Fits_File_Type or String_Type fd;
   Ref_Type dataok, hduok;


 DESCRIPTION
  The `fits_verify_chksum' function calls `_fits_verify_chksum' to
  verify the header and data checksums of the current HDU.  A non-zero return value
  signifies that the checksums are ok, otherwise the function returns 0 to indicate
  that the checksums are invalid.  The individual checksums of the HDU or data
  can be checked through the use of the optional parameters.

 SEE ALSO
  fits_write_chksum

--------------------------------------------------------------

fits_read_records

 SYNOPSIS
  Read all the records in a fits header

 USAGE
  String_Type[] fits_read_records (Fits_File_Type or String_Type fp)

 DESCRIPTION
  This function returns a list of all the header records associated with the
  fits file descriptor as an array of strings.

 SEE ALSO
  fits_write_records, fits_read_key

--------------------------------------------------------------

fits_write_records

 SYNOPSIS
  Write records to fits header

 USAGE
  fits_write_records (fd, records)

   Fits_File_Type or String_Type fd;
   Array_Type records;


 DESCRIPTION
  This function uses the `_fits_write_record' function to write a series
  of records to the current HDU.

 SEE ALSO
  fits_read_records

--------------------------------------------------------------

fits_get_keyclass

 SYNOPSIS
  Obtain the key classes for a set of cards

 USAGE
  Int_Type[] = fits_get_keyclass (Array_Type cards)

 DESCRIPTION
  This function uses the `_fits_get_keyclass' function to obtain the
  key-classes associated with one or more cards.  The function returns an
  integer-valued array of the same length as the `cards' array.

 EXAMPLE
  Obtain set of header cards to those that are not associated with the cards
  describing the structure of the HDU:

    variable cards = fits_read_records ("evt2.fits[EVENTS]");
    variable classes = fits_get_keyclass (cards);
    cards = cards[where (classes != _FITS_TYP_STRUC_KEY)];


 SEE ALSO
  fits_read_records, fits_read_key

--------------------------------------------------------------

fits_get_bitpix

 SYNOPSIS
  Get the fits bitpix value for an array

 USAGE
  Int_Type fits_get_bitpix (array)

 DESCRIPTION
  This function may be used to obtain the bitpix value for a specified image
  array.  The array must be an integer or floating point type, otherwise
  and error will be generated.  The bitpix value is returned.

 SEE ALSO
  fits_write_image_hdu, fits_read_img

--------------------------------------------------------------

fits_read_img

 SYNOPSIS
  Read image data from a fits file

 USAGE
  Array_Type fits_read_img (fd)

   Fits_File_Type or String_Type fd;


 DESCRIPTION
  This function reads an image from the specified file descriptor.
  The file descriptor must be either the name of an existing file, or an
  open file pointer.  It returns the image upon sucess, or signals an error
  upon failure.

 SEE ALSO
  fits_read_table, fits_read_col, fits_open_file, fits_write_img

--------------------------------------------------------------

fits_create_image_hdu

 SYNOPSIS
  Create a primary array or image extension

 USAGE
  fits_create_image_hdu (fd, extname, type, dims)

   Fits_File_Type or String_Type fd;
   String_Type extname;
   Array_Type dims;
   DataType_Type type;


 DESCRIPTION
  This function make use of the `_fits_create_img' function to create an
  image extension or primary array of the specified type and size.  If the
  `extname' parameter is non-NULL, then an EXTNAME keyword will be
  written out with the value of the extname parameter.
  The `dims' parameter must be a 1-d integer array that corresponds
  to the dimensions of the array to be written.

  If `fd' is specified as a string, then a new file of that name will be
  created.  If a file by that name already exists, it will be deleted and
  a new one created.  If this behavior is undesired, then explicitly open the
  file and pass this routine the resulting file pointer.

 SEE ALSO
  fits_write_image_hdu

--------------------------------------------------------------

fits_write_image_hdu

 SYNOPSIS
  Write an image extension

 USAGE
  fits_write_image_hdu (file, extname, image [,skeys [,hist]])

    Fits_File_Type or String_Type file;
    String_Type extname;
    Any_Type image
    Struct_Type skeys;
    Struct_Type hist;


 DESCRIPTION
  The `fits_write_image_hdu' function creates a new image extension in
  the specified file.  The parameter `file' specifies either a filename or
  an open file pointer.  The `extname' parameter specifies the extension
  name of the image, or NULL for the primary image.  The image data written
  to the file are specified by the `image' parameter.
  If the optional parameter `skeys' is non-NULL, then it is a
  structure indicating additional keywords to be written to the HDU.
  If the optional parameter `hist' is present and non-NULL,
  then it is a structure whose fields indicate either comment or history
  information to be written to the header.

 EXAMPLE
  The following code

     variable img = [1:128*128]; reshape (img, [128,128]);
     variable keys = struct { hduname, username};
     keys.hduname = "MY_IMAGE";
     keys.username = "John Doe";
     variable hist = struct { history, comment};
     hist.history = ["This is a history record", "This is another"];
     hist.comment = ["This is a comment", "And this is another"];
     fits_write_image_hdu ("foo.fits", NULL, img, keys, hist);

 produces an image HDU with the header:

     SIMPLE  =                   T / file does conform to FITS standard
     BITPIX  =                  32 / number of bits per data pixel
     NAXIS   =                   2 / number of data axes
     NAXIS1  =                 128 / length of data axis 1
     NAXIS2  =                 128 / length of data axis 2
     EXTEND  =                   T / FITS dataset may contain extensions
     COMMENT   FITS (Flexible Image Transport System) format is defined in 'Astronomy
     COMMENT   and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H
     HDUNAME = 'MY_IMAGE'
     USERNAME= 'John Doe'
     HISTORY This is a history record
     HISTORY This is another
     COMMENT This is a comment
     COMMENT And this is another


 NOTES
  This function provides no mechanism to mix comments and keyword records.  As
  the example shows, this function places the comment and history records at
  the end of the table.

 SEE ALSO
  fits_create_binary_table, fits_open_file

--------------------------------------------------------------

fits_write_img

 SYNOPSIS
  Write the image data to an Image HDU

 USAGE
  fits_write_img (Fits_File_Type fptr, Any_Type data)

 DESCRIPTION
  This function writes the image data out to current HDU, assumed to be
  an Image HDU.

 SEE ALSO
  fits_write_image_hdu, fits_create_image_hdu

--------------------------------------------------------------

fitswcs_new

 SYNOPSIS
  Create a new-ndimensional linear WCS

 USAGE
  wcs = fitswcs_new (Int_Type naxis)

 DESCRIPTION
  This function returns a new WCS structure of the specified dimensionality
  that represents an identity (linear) transformation.

 SEE ALSO
  fitswcs_get_img_wcs, fitswcs_get_column_wcs, fitswcs_get_vector_wcs

--------------------------------------------------------------

fitswcs_slice

 SYNOPSIS
  Form a new wcs from one or more axes of another

 USAGE
  new_wcs = fitswcs_slice (wcs, dims)

 DESCRIPTION
  This function may be used to construct a new wcs from another by rearranging
  its axes or by using a subset of them.  The `dims' argument specifies
  the dimensions to use.

 EXAMPLE
  Suppose that `wcs' represents a 4 dimensional WCS. Then

    wcs2 = fitswcs_slice (wcs, [0,1]);

  will result in a 2 dimensional WCS from the first 2 axis of the input WCS.
  Similarly,

    wcs2 = fitswcs_slice (wcs, [1,0]);

  will produce a 2d WCS with the first two axes swapped.

 SEE ALSO
  fitswcs_get_img_wcs, fitswcs_get_column_wcs, fitswcs_get_vector_wcs

--------------------------------------------------------------

fitswcs_get_img_wcs

 SYNOPSIS
  Read a WCS for a FITS image

 USAGE
  wcs = fitswcs_get_img_wcs (fp [,alt])

 DESCRIPTION
  The `fitswcs_get_img_wcs' returns a structure representing a WCS from
  the specified file descriptor `fp' corresponding to an image HDU.
  An optional parameter may be used to specified an alternate WCS.

 EXAMPLE

   wcs = fitswcs_get_img_wcs ("img.fits[IMAGE]", 'P');


 SEE ALSO
  fitswcs_put_img_wcs, fitswcs_get_column_wcs, fitswcs_get_vector_wcs

--------------------------------------------------------------

fitswcs_get_column_wcs

 SYNOPSIS
  Get the WCS attached to one or more columns of a binary table

 USAGE
  fitswcs_get_column_wcs (fp, columns-array [,alt]

 DESCRIPTION
  This function may be used to obtain the WCS associated with one or more
  columns of a binary table.  The file descriptor `fp' must specify
  a binary table.  The `columns-array' parameter should be an array
  of columns names.  The third parameter is optional and is used to specify
  an alternate WCS.

 EXAMPLE

   wcs = fitswcs_get_column_wcs ("evt1.fits[EVENTS]", ["X","Y"]);


 SEE ALSO
  fitswcs_put_column_wcs, fitswcs_get_img_wcs, fitswcs_get_vector_wcs

--------------------------------------------------------------

fitswcs_get_vector_wcs

 SYNOPSIS
  Get the WCS of an image in a specified table cell

 USAGE
  wcs = fitswcs_get_vector_wcs (fp, column_name, row [,alt])

 DESCRIPTION
  This function reads the WCS of an image in a specified cell of a binary
  table given by `fp' parameter.  The second and third parameters specify
  the column name and row number of the cell.  An optional fourth parameter
  may be used to obtain the corresponding alternate WCS.

 EXAMPLE
  This example reads the WCS associated with the image in the second row
  of the QEU column of the binary table with HDUNAME equal to AXAF_QEU1
  in the file "HRCQEU.fits":

    wcs = fitswcs_get_vector_wcs ("HRCQEU.fits[AXAF_QEU1], "QEU", 2);


 NOTES
  The current implementation does not yet support references to the WCS
  of other cells.

 SEE ALSO
  fitswcs_get_column_wcs, fitswcs_get_img_wcs

--------------------------------------------------------------

fitswcs_new_img_wcs

 SYNOPSIS
  Create a linear WCS for an image

 USAGE
  wcs = fitswcs_new_img_wcs (grid0,grid1,...)

 DESCRIPTION
  This function may be used to construct a linear WCS for an image with the
  specified grids.  The grids are assumed to be linear.

 EXAMPLE
  Use the histogram module's hist2d function to create an image from the X
  and Y columns in a file, and the construct a corresponding WCS:

    (x,y) = fits_read_col ("table.fits", "X", "Y");
    gridx = [min(x):max(x):0.5];
    gridy = [min(y):max(y):0.5];
    img = hist2d (y,x,gridy,gridx);
    wcs = fitswcs_new_img_wcs (gridy, gridx);


 SEE ALSO
  fitswcs_new, fitswcs_get_img_wcs

--------------------------------------------------------------

fitswcs_put_img_wcs

 SYNOPSIS
  Write a WCS out to an image header

 USAGE
  fitswcs_put_img_wcs (fp, wcs [,alt])

 DESCRIPTION
  The `fitswcs_put_img_wcs' may be used to write the specified wcs
  out to the image HDU specified by the `fp' parameter.  An optional
  third parameter may be used to specify an alternate WCS.

 EXAMPLE

    fp = fits_open_file ("img.fits", "w");
      .
      .
      .
    fits_put_img_wcs (fp, wcs, 'P');
    fits_close_file (fp);


 SEE ALSO
  fitswcs_put_column_wcs

--------------------------------------------------------------

fitswcs_put_column_wcs

 SYNOPSIS
  Write the WCS attached to one or more table columns

 USAGE
  fitswcs_put_column_wcs (fp, wcs, columns-array [,alt])

 DESCRIPTION
  This function may be used to attach a WCS to one or more columns of a binary
  table.  The dimensionality of the specified WCS must match the length of the
  array specifying the column names.  The first parameter, `fp' must specify
  a binary table extension.  The fourth parameter is optional and may be used
  to specify an alternate WCS.

 EXAMPLE

   fitswcs_put_column_wcs ("evt2.fits[EVENTS], wcs, ["X","Y"]);


 SEE ALSO
  fitswcs_get_column_wcs, fitswcs_put_img_wcs, fitswcs_get_img_wcs

--------------------------------------------------------------

fitswcs_linear_transform_wcs

 SYNOPSIS
  Apply a linear transformation to a WCS

 USAGE
  wcs1 = fitswcs_linear_transform_wcs (wcs, U0, A, X0)

     wcs: The specified WCS to transform
   U0,X0: 1-d arrays
       A: 2-d array (or 1-d array representing a diagonal matrix)


 DESCRIPTION
  This function may be used to create a new WCS by applying a linear
  transformation to an existing one.  This is useful when one
  has a WCS associated with physical coordinates `X', and then
  applies the linear transformation

     U = U0 + A#(X-X0)

  to the coordinates X.  Then corresponding WCS for the resulting image is
  given by

     new_wcs = fitswcs_linear_transform_wcs (wcs, U0, A, X0);


 NOTES
  The dimensionality of the WCS is limited to 2 in the
  current implementation.

 SEE ALSO
  fitswcs_rebin_wcs, fitswcs_bin_wcs

--------------------------------------------------------------

fitswcs_rebin_wcs

 SYNOPSIS
  This function may be used to obtain the wcs for a rebinned image

 USAGE
  wcs1 = fitswcs_rebin_wcs (wcs, old_dims, new_dims...)

 DESCRIPTION
  This function may be used to construct the WCS for a rebinned image from
  the WCS of of the unbinned image.  The grid parameters specify the linear
  grids the new image.

 EXAMPLE
  new_img = hist2d_rebin (new_yrid, new_xgrid,
                          old_ygrid, old_xgrid, old_img);
  new_wcs = fitswcs_rebin_wcs (old_wcs,
                               array_shape(old_img),
                               array_shape(new_img));

 SEE ALSO
  fitswcs_bin_wcs, fitswcs_linear_transform_wcs, fitswcs_slice

--------------------------------------------------------------

fitswcs_bin_wcs

 SYNOPSIS
  This function may be used to obtain the wcs for a rebinned image

 USAGE
  wcs1 = fitswcs_rebin_wcs (wcs, grid0, grid1, ...)

 DESCRIPTION

 This function may be used to construct the WCS for an image created
 by binning a set of coordinates from, e.g., a pixel-list.  The
 `wcs' parameter represents the wcs attached to the unbinnned
 coordinates.  The grid parameters specify the linear grids that were
 used to create the image.

 SEE ALSO
  fitswcs_rebin_wcs, fitswcs_linear_transform_wcs, fitswcs_slice

--------------------------------------------------------------