pCFITSIO 0.99.0

The following document contains the list of CFITSIO functions that are available to Python with the help of the module pCFITSIO. The pCFITSIO module was generated using SWIG . In general, functions which in the original C functions changed one or more arguments return these in a python list. Data images (binary data) is returned as a numarray Python Array.

pCFITSIO was successfuly compiled and used on Solaris 2.5.1, Linux Red Hat 5.x and 6.x, MacOSX 10.3.x and OpenStep 4.2.

CFITSIO Helper functions

  • fits_get_version()
    Returns the version of the CFITSIO module
  • fits_get_errstatus(input)
    Returns the text description corresponding to the given CFITSIO error
  • fits_write_errmsg(err_message)
    Write the given error message into the CFITSIO error stack
  • fits_read_errmsg()
    Returns a list containg the latest integer error and the corresponding text message from the CFITSIO error stack
  • fits_clear_errmsg()
    Clears the CFITSIO error message stack

    File Access Functions

  • fits_open_file(filename,mode)
    Returns a FITSfile pointer to an existing FITS file Set mode = 0 for READONLY Set mode = 1 for READWRITE
  • fits_reopen_file(fptr)
    Returns a new FITSfile pointer to an already opened FITS file
  • fits_create_file(filename)
    Initializes a new FITS file with name filename and returns a FITSfile pointer No header nor extension is created
  • fits_create_template(filename,template)
    Returns a new FITSfile pointer after creating a new FITS file using a template FITS file
  • fits_close_file(fptr)
    Close an already opened FITS file pointed to by the given FITSfile pointer
  • fits_delete_file(fptr)
    Deletes the FITS file pointed to by the given FITSfile pointer
  • fits_file_name(fptr)
    Returns the name of the FITS file pointed to by the given FITSfile pointer
  • fits_file_mode(fptr)
    Returns the access mode of the FITS file pointed to by the given FITSfile pointer = 0 for READONLY = 1 for READWRITE

    FITS Header Functions

  • fits_get_hdrspace(fptr)
    Returns a PyList containing the number of existing keywords and the number of free cards in the current FITS extension
  • fits_get_hdrpos(fptr)
    Returns a PyList containing the total number of records in the header, and the current position.
  • fits_get_hdu_num(fptr)
    Returns the number of extension in this FITS file
  • fits_get_hdu_type(fptr)
    Returns the type of the current extension. Numbering scheme in CFITSIO manual.
  • fits_get_hduaddr(fptr)
    Returns a PyList containing the beginning address and the ending address of the current extenstion's header, and the total size of this FITS file.
  • fits_movabs_hdu(fptr,hdunum)
    Moves to a given (absolute number) extension in the FITS file In this case, the first extension is numbered 1
  • fits_movrel_hdu(fptr,hdumov)
    Moves to a given (relatively to current position) extension in the FITS file i.e. +1 moves 1 forward, -2 moves backward 2
  • fits_movnam_hdu(fptr,exttype,hduname,hduvers)
    Moves to the given (by name) extension
  • fits_get_num_hdus(fptr)
    Returns the number of extensions in the FITS file
  • fits_create_hdu(fptr)
    Creates a new HDU at the end of the current FITS file.
  • fits_delete_hdu(fptr)
    Deletes the current extension from the FITS file. Returns the type of the new current extension (which remains).
  • fits_copy_hdu(infptr,outfptr,morekeys)
    Copy the current extension associated with infptr to the end of the file associated with outfptr Space for a number of additional keys can be reserved by setting morekeys to a non-zero value

    FITS Keyword Functions

  • fits_read_keyword(fptr,keyname)
    Returns a PyList containing the (text) value and the comment field.
  • fits_read_key_log(fptr,keyname)
    Reads a logical valued keyword. Returns a PyList containing 0 or 1 (false/true) and the comment field.
  • fits_read_key_dbl(fptr,keyname)
    Reads a double valued keyword. Returns a PyList containing the value and the comment field.
  • fits_read_key_lng(fptr,keyname)
    Reads a long valued keyword. Returns a PyList containing the value and the comment field.
  • fits_movabs_key(fptr,nrec)
    Move to the absolute nrec card in the current extension's header
  • fits_movrel_key(fptr,nrec)
    Move to the nrec card in the current extension's header relatively to the current position in that header
  • fits_update_key(fptr,keyname,value,comment)
    Replace an existing keyword's value and comment with the ones passed to the function.
  • fits_update_key_null(fptr,keyname,comm)
    Replace an existing keyword's value with a null string and replaces the comment field with the one passed to the functions.
  • fits_write_comment(fptr,comment)
    Writes a COMMENT card in the current extension's header.
  • fits_write_history(fptr,hist)
    Writes a HISTORY card in the current extension's header
  • fits_write_date(fptr)
    Writes/updates a DATE card with the current date and time (UTC) in the current extension's header
  • fits_write_record(fptr,card)
    Writes a complete card (80 characters) into the current extension's header.
  • fits_write_key_unit(fptr,keyname,unit)
    Writes/updates the units in [] for the given key. This uses the CFITSIO Units convention.
  • fits_read_record(fptr,nrec)
    Reads and returns the nth record (entire 80 characters) of the current extension's header.
  • fits_read_card(fptr,keyname)
    Reads and return the record (entire 80 characters) corresponding to the given key.
  • fits_read_key_unit(fptr,keyname)
    Returns the units of the given key. Follows CFITSIO Units convention.
  • fits_write_key(fptr,keyname,value,comment)
    Adds a new key to the current extension's header The given value is assigned to the key. Integer, double, and string casting is done automatically. Also writes the given comment which can be an empty string
  • fits_update_card(fptr,keyname,card)
    Replaces the record corresponding to the given keyword by the given record string (80 characters). No checking is done.
  • fits_modify_name(fptr,oldname,newname)
    Modifies the name of a key to a new name.
  • fits_modify_comment(fptr,keyname,comment)
    Modifies the comment of the given key.
  • fits_modify_key_null(fptr,keyname,comment)
    Assigns the NULL/comment pair to the given key
  • fits_modify_key_str(fptr,keyname,value,comment)
    Replaces the value/comment pair of the given key with the given string/comment pair
  • fits_modify_key_log(fptr,keyname,value,comment)
    Replaces the value/comment pair of the given key with the given boolean/comment pair
  • fits_modify_key_lng(fptr,keyname,value,comment)
    Replaces the value/comment pair of the given key with the given long/comment pair
  • fits_delete_key(fptr,keyname)
    Deletes the given key (by name) from the current extension's header
  • fits_delete_record(fptr,keypos)
    Deletes the given key (by position) from the current extension's header
  • fits_read_keys_lng(fptr,keyname,nstart,nmax)
    Reads up to nmax long values from keys that have the form keyname### where ### is a sequential integer number.
  • fits_read_keys_dbl(fptr,keyname,nstart,nmax)
    Reads up to nmax double values from keys that have the form keyname### where ### is a sequential integer number.
  • fits_read_keys_str(fptr,keyname,nstart,nmax)
    Reads up to nmax string values from keys that have the form keyname### where ### is a sequential integer number.

    FITS Image functions:

  • fits_create_img(fptr,bitpix,naxes)
    Creates (appends to file ) an image extension, using the given bitpix value, and naxis values contained in the array naxes. The data values are left empty but the space is allocated.
  • fits_write_img(fptr,firstelem,nelem,array)
    Writes nelements elements from array into the current image extension
  • fits_resize_img(fptr,bitpix,naxes)
    Updates the size of the data extension and the values of the BITPIX, and NAXES keywords.
  • fits_read_img(fptr,firstelem,nelements,nulval)
    Reads nelements, starting at position firstelem, from the current image extension. Substitute the given nulval value for any null values in the image. Returns an array containing the flattened image as first element, and the number of null value in the second element
  • fits_write_imghdr(fptr,bitpix,naxes)
    Writes the BITPIX, and NAXES keywords in the current extension's header
  • fits_read_img_coord(fptr,type)
    Reads ans returns the image coordinate system. Set type to the appropriate string (See CFITSIO manual).

    FITS Table Functions:

  • fits_get_num_cols(fptr)
    Returns the number of columns in a table extension.
  • fits_get_num_rows(fptr)
    Returns the number of rows in a table extension.
  • fits_read_col(fptr,colnum,firstrow,firstelem,nelements,nulval)
    Returns the content of the column colnum. Starts at firstrow, and returns nelements. If the table is a binary vector table, firstelem defines the starting pixel within the cell (See CFITSIO manual). It is ingnored otherwise.
  • fits_get_colnum(fptr,caseseen,templt)
    Returns the table column number of the column whose name matches an input template name. Set caseseen=0 for case insensitive, 1 for case sensitive.
  • fits_get_colname(fptr,casesen,templt)
    Returns the table column name of the column whose name matches an input template name. Set caseseen=0 for case insensitive, 1 for case sensitive
  • fits_get_coltype(fptr,colnum)
    Returns the type of the column colnum.
  • fits_write_col(fptr,colnum,firstrow,firstelem,array)
    Writes a column into a table extension usng data from array.
  • fits_insert_rows(fptr,firstrow,nrows)
    Inserts nrows starting at firstrow.
  • fits_delete_rows(fptr,firstrow,nrows)
    Deletes nrows starting at firstrow.
  • fits_delete_rowlist(fptr,rownum)
    Deletes a number of columns based on the input list rownum.
  • fits_delete_col(fptr,numcol)
    Deletes column numcol.
  • fits_copy_col(infptr,outfptr,incol,outcol,create_col)
    Copies the column incol from one fits table infptr to column outcol in the fits table outcol. create_col=1 inserts a new column.
  • fits_insert_col(fptr,numcol,ttype,tform)
    Inserts a new column of type ttype and form tform into the current table extension.

    For comments, bug reports, etc.. please send email to
    Nor Pirzkal
    Disclaimer:

    THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.