Table of Contents

Name

fitopen, fitclose, fitread, fitwrite, fitsetpl, fitrdhdr, fitrdhdi, fitwrhdr, fitwrhdi, fitwrhdl, fitwrhda - simple image fits I/O routines

Synopsis


#include <fitsio_nemo.h>
FITS *fitopen(name,status,naxis,nsize)
int fitexhd(file,keyword)void fitrdhdr(file,keyword,rvaluep,rdef)void
fitrdhdi(file,keyword,ivaluep,idef)void fitwrhdr(file,keyword,rvalue)void
fitwrhdi(file,keyword,ivalue)void fitwrhdl(file,keyword,ivalue)void fitwrhda(file,keyword,avalue)void
fitwra(file,keyword,avalue)
void fitread(file,row,data)void fitwrite(file,row,data)void
fitsetpl(file,n,isize)
void fitclose(file)
void fit_setbitpix(bitpix)void
fit_setscale(bscale,bzero)void fit_setblocksize(blocksize)
char *name, *status,
*file;int naxis, nsize[], row, n, isize[], bitpix, blocksize;char *keyword,
*avalue;FLOAT *data, FLOAT *rvaluep, rvalue, rdef, bscale, bzero;int  
*ivaluep, ivalue, idef;

Description

A simple self-contained FITS-I/O library is offered here. The routines write to stderr in case of errors. Fatal errors will cause it to call exit(3) . On input it does automatic data conversion to the host FLOAT datatype (although only BITPIX=16, 32 and -32 can be read ??), but forces the output to be in the IEEE format. (BITPIX=-32).

fitopen() opens a FITS file and readies it for i/o. The name contains the name of the file, status can be "new" ("w" also accepted) or "old" ("r" also accepted), which are the fortran equivalents of fopen()’s "w" and "r". naxis is always an input parameter and gives the (used/usable) length of the nsize array: the nsize array contains the length of each axis. When a fitsfile is read, all unused dimensions are set to 1. On success fitopen returns the address of an allocated FITS structure (see below), else it returns NULL. fitopen also does initial I/O on the basic FITS header keywords to determine the size of the data array (SIMPLE, BITPIX and NAXISn). Parsing the remaining keywords are the responsibility of the user. A call to fitread, fitwrite or fitsetpl will close the header for access and only allow (random) access to the (image) data.

fitclose() closes a FITS file, and deletes any memory associated with it. The input parameter file is a pointer to the FITS structure that was returned by fitopen, and is used in all subsequent fitsio routines as a fits file descriptor.

fitexhd() returns 1 if the keyword exists in file, else 0.

fitread() and fitwrite() read resp. write a row of a FITS image file, indexed to by row (0 being the first row). I/O is done into/from the buffer pointed to by data. It is the callers resonsibility to make sure data points to enough data space (NAXIS1).

fitsetpl() is needed to select the plane to be accessed in a FITS image. If not called, I/O defaults to the first plane. n is the dimension of the isize array, and is at least 2 less than the dimension of the input ’cube’ (naxis in fitopen). Any unspecified elements in isize means the selected hyperplane in that dimension is the first one (0). The isize index array. Note that the fortran array structure is used here: first dimension is running fastest in memory.

fitrdhdr() and fitrdhdi() read the value of a real- resp. integer valued FITS keyword from the file header. The keyword must be at most 8 (upper case) characters. If the keyword is not present the default input in rdef, resp. idef is returned in pointers rvaluep resp. ivaluep. Reading keywords should occur after fitopen, but before the first fitsetpl or fitread call.

fitwrhdr(), fitwrhdi(), fitwrhdl() and fitwrhda() write the value of a real-, integer-, logical- resp. character-valued FITS keyword to the file header. Writing keywords should occur after fitopen, but before the first fitsetpl or fitwrite call.

fitwra() can be used to output a character-value belonging to a FITS keyword that does not have an ’=’ sign between the keyword and the value (e.g. HISTORY and COMMENT).

fit_setbitpix() and fit_setscale() can be used to set bitpix, bscale and bzero when writing fits files. Remember that

    image_value = fits_value * bscale + bzero
If to be effective, they need to be called BEFORE fitopen. If called between fitopen and fitwrite it will not take into effect until the next fitopen. fit_setblocksize() can be used to choose another blocksize from the default 2880 bytes that FITS has defined. When a FITS file has been written with a blocking factor other than 1, the blocksize is a multiple of 2880 bytes.

Fits Structure

A simple basic FITS data structure (referred to as file in the above SYNOPSIS) is used to communicate between different modules:
typedef struct { 
    int ncards;    Current number of 80 column header cards
    int naxis;    dimension of image data
    int axes[MAXNAX];    length of each axis
    int offset;    current byte offset in file due to fitsetpl()
    int type;    fits data type [TYPE_FLOAT, TYPE_16INT, TYPE_32INT]
    int status;    file status [STATUS_OLD, STATUS_NEW, STATUS_NEW_WRITE]
    int fd;     file descriptor in open, seek, read, write, close
    FLOAT bscale;    scaling factor, if bitpix > 0.
    FLOAT bzero;    scaling factor, if bitpix > 0.
} FITS;
in which MAXNAX and FLOAT are #defined in "fitsio.h". In standard fitsio.h 7 resp. float are used. The other upper case names are also defined in fitsio.h.

Example

The following example shows, without any bells, whistles and error checking, how a simple 2D data matrix can be read in:
    char *file;
    float *image, *ip;
    int nx, ny, i, j, k, naxis[2];
    file = fitopen("fits.dat","r",2,naxis);          /* open */
    nx = naxis[0];            /* dimension in x */
    ny = naxis[1];           /* dimension in y */
    image = (float *) malloc(nx*ny*sizeof(float));       /* allocate */
    k=1;                      /* set plane to read */
    fitsetpl(file,1,&k);        /* redundant anyhow */
    for (j=0, ip=image; i<ny; j++, ip += nx)          /* for each row */
      fitread(file,j,ip);    /* read row into appropriate spot */
    fitclose(file);             /* close */

Bugs

Does not do a whole lot of sanity checks on the FITS header structure. Insane cases when e.g. NAXIS1=1 or 0 are not handled well.

Not so sure if defining FLOAT as double would work yet.

No BLANK value substitution.

No provisions to read (or write) FITS files with multiple HDUs. Use scanfits(1NEMO) to extract the required HDU.

If the same (even if mandatory or reserved) keyword is written again, it will appear multiple times in the header, probably violating the standard.

Caveats

"fitsio.h" is a poorly choosen name, as the name conflicts with at least one other package (Pence’ cfitsio library). As of 18-dec-2001 the name was changed to "fitsio_nemo.h" and depending on a C define HAVE_LIBCFITSIO (as determined by configure in the config.h file) it will use CFITSIO emulation.
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html

See Also

fits(3NEMO) , fits(5NEMO) , cfitsio

Author

Bob Sault, Peter Teuben

Files


~/src/image/fits         fitsio.c, fitsio.h fitsio.3 (within NEMO)

History


xx-jul-90       While sweating it out in India  RJS
28-jul-90       hurah - replace wrong in NEMO   PJT
10-oct-90    added some write routines    PJT
12-sep-91    added fitexhd()                PJT
21-mar-00    fixed offset bug for raw cubes    PJT
9-jul-00    fixed offset bug if fitsetpl called before fitwrite    PJT
29-sep-01    added experimental BITPIX 64, removed some lies    PJT
18-dec-01    changed name of header file to fitsio_nemo.h    PJT
23-jul-02    attempted to add fitresize    PJT


Table of Contents