Previous: FITS macros and data structures, Up: FITS files [Contents][Index]
Gnuastro provides the following functions to deal with FITS data related
operations. FITS data can have a variety of types, see CFITSIO datatype for a discussion on this, in particular the integer variables
named datatype, bitpix, and tform. See FITS macros and data structures for the strure and macro definitions.
status, char *message)Report the input or output error as a string and print it along with a
short statement that an error in CFITSIO occurred. All CFITSIO functions
will change the value of status if an error occurs. This function
will print the CFITSIO error string from the value of status
followed by an optional message that you can add to it. If the value
of message is NULL, then a default message will be printed.
*name)Return 1 if the string pointed by name is a standard FITS
filename (or more generally: can be read by CFITSIO) and 0 if it
isn’t. See Arguments for the standard FITS filenames.
*suffix)Return 1 if the string pointed by suffix is a standard FITS
suffix (or more generally: can be read by CFITSIO) and 0 if it
isn’t. suffix can contain a dot or not (for example both
.fits and fits will return 1. See Arguments for
the standard FITS filenames.
bitpix)Return the datatype corresponding to the given bitpix (value to the
BITPIX header keyword) in a FITS image.
tform)Return the datatype corresponding to the given tform character of a
FITS table column: value to the TFORM header keyword for the
column. Note that in the FITS standard, TFORM values are characters.
*fptr, int *bitpix, long *naxes)Return the datatype (in FITS BITPIX format) and image size of a FITS
HDU specified with the fitsfile pointer (defined in CFITSIO). So the
HDU must have been already opened. If the number of dimentions is not 2,
this function will retun an error and abort.
datatype)Allocate the necessary space and put the blank value of type
datatype in it. Finally, return the pointer to the allocated
space. This pointer is commonly necessary when calling CFITSIO read
functions as nulval. See CFITSIO datatype.
size, int datatype)Allocate an array of size elements of type datatype. See
CFITSIO datatype.
datatype)Return the size (in bytes) of the type specified by datatype, see
CFITSIO datatype.
*array, int datatype, size_t size, void *value)Convert the blank values in array (with size elements) into
the value pointed by value.
*in, int inbitpix, size_t size, int anyblank, void **out, int outbitpix)Convert the in array (with inbitpix type) into an array of
type outbitpix that is pointed by out. Space will be
allocated for the output array within this function.
*numhdu)Find the number of HDUs in filename and store it in the space
pointed to by numhdu.
*filename, char *hdu, unsigned char img0_tab1, fitsfile **outfptr)Open the HDU hdu (a string) of the filename FITS file into
the outfptr. See --hdu option in Input/Output options for the
accepted HDU formats.
*filename, char *hdu, struct gal_fits_key *keys, size_t num)Read num keywords (identified in the keys array) in the
hdu HDU of filename. See FITS macros and data structures for the definition of gal_fits_key and its recommended
usage with this function.
CFITSIO will look for the next keyword starting from the last keyword found. Therefore, it is most efficient to specify the keywords in the same order as they appear in the desired HDU.
**list, int datatype, char *keyname, int kfree, void *value, int vfree, char *comment, int cfree, char *unit)Add an element to the top of the gal_fits_key_ll linked list for
writing keywords. This structure (or linked list) is used to write FITS
keywords and is fully described in FITS macros and data structures. Each variable also has the same name as the structure element
that is described there.
Assuming all the keywords were added with this function, you will have a last-in-first-out list: as the the name suggests, the last keyword you add to the list will be the first one that gets popped out and thus written in the FITS file header.
**list, int datatype, char *keyname, int kfree, void *value, int vfree, char *comment, int cfree, char *unit)Similar to gal_fits_add_to_key_ll, except the keyword is added to
the end of the list, creating a first-in-first-out list. Therefore the
order the keywords are written to the FITS header is the same as the order
you have called this function.
*keynamebase, char *filename, struct gal_fits_key_ll **list)Put a filename into the gal_fits_key_ll list to later write into a
HDU header. The FITS standard sets a maximum length for the value of a
keyword. This creates problems with file names (including directories),
because they can become very long. Therefore, when the filename is longer
than the maximum length of a FITS keyword value, this function will break
it into several keywords. The keynamebase string will be appended
with a _N (N>0) and used as the keyword name.
*fptr, char *wcsheader, int nkeyrec)Add the WCS information into the header of the HDU pointed to by
fptr. The WCS information must already be converted into a long
string with the FITS conventions. To help in identifying the WCS
information, a few blank lines and a title will be added ontop.
*fptr, struct gal_fits_key_ll **keylist)Given the an opened FITS HDU (pointed to by fptr), this function
will write, or update, all the keywords given in keylist. See
FITS macros and data structures for more information on the
gal_fits_key_ll structure or linked list.
*fptr, struct gal_fits_key_ll *headers, char *spack_string)Write or update (all the) keyword(s) in headers into the FITS
pointer, but also the date, name of your program (spack_string),
along with the verisons of Gnuastro, CFITSIO, WCSLIB (when available) into
the header, see Output headers. Since the data processing depends on
the versions of the libraries you have used, it is strongly recommended to
include this information in every FITS output. See FITS macros and data structures for more information on the gal_fits_key_ll
structure or linked list.
*fptr, int *nwcs, struct wcsprm **wcs, size_t hstartwcs, size_t hendwcs)Read the WCSLIB WCS structure (wcs, and nwcs the number of WCS
structures) from the FITS pointer fptr. In some cases, it might be
necessary to only consider header keywords between a certain range. You can
define the range of keywords to look for WCS information with the
hstartwcs and hendwcs arguments. The range of header keywords
will only be considered when the value of hstartwcs is less than
hendwcs, so if you don’t want to limit the range, set both values to
0. After you have finished using the WCS structure, use
wcsvfree(&nwcs,&wcs); to free it.
|
WCSLIB is not thread-safe: WCSLIB’s |
*filename, char *hdu, size_t hstartwcs, size_t hendwcs, int *nwcs, struct wcsprm **wcs)Read the WCSLIB WCS structure (wcs and nwcs the number of WCS
structures) from a FITS file (hdu in filename). This is
basically just a wrapper around the gal_fits_read_wcs_from_pointer
function, see that function for more.
*filename, char *hdu, int *bitpix, void **array, size_t *s0, size_t *s1)Read the FITS image (in the hdu extension of filename). The
image array will be stored in array and the number of pixels in the
first and second C axis will be stored in s0 and s1. The type
of the array will be kept in bitpix. See --hdu in
Input/Output options for the acceptable formats of hdu.
*filename, char *extname, int bitpix, void *array, size_t s0, size_t s1, int anyblank, struct wcsprm *wcs, struct gal_fits_key_ll *headers, char *spack_string)Write the array array (with sizes s0 and s1, type
bitpix, and WCS structure wcs) into the FITS file
filename and extension name extname. If the array has any
blank pixels, then you can set anyblank to 1. All the headers in
headers will also be written to this extension and
spack_string is the name of your program (which can include a
version number), which will be written in the output header.
*filename, char *hdu, int bitpix, void *array, size_t s0, size_t s1, char *wcsheader, int wcsnkeyrec, double *crpix, char *spack_string)This is essentially the same as gal_fits_array_to_file, but through
the two element crpix array, you can change the final CRPIX
keywords that will be written in the FITS file.
*fitsptr, size_t *nrows, size_t *ncols)Get the number of rows (nrows) and columns (ncols) in a FITS
table within the fitsptr.
*fptr)Return the type of the table: ASCII_TBL and BINARY_TBL for an
ASCII or binary table. These two macros are defined by CFITSIO.
*inputname, char *inhdu, int othernameset, char **othername, char *ohdu, int ohduset, char *type)This is mainly a function used in Gnuastro programs. Since a FITS image can have many extensions, usually related data are stored within one FITS file. For example an image, its masked pixels, and the sky standard deviation of the noise are various extensions of one FITS file. It would be very inconvenient if the same file name would have to be repeated in a call to a program for all images that are within one file.
To easily manage things, within Gnuastro, each input variable also has an
integer variable with the same name, but suffixed with set. The job
of this function is to use the name of the main input image and based on
the other arguments, determine what filename should be used for each
type. The final argument (type) is the type of input you want, for
example, if you were expecting a mask image, you can give the value
"mask" as type. type is just used to report errors.
*inputname, char *maskname, char *inhdu, char *mhdu, float **img, int *inbitpix, int *anyblank, size_t *ins0, size_t *ins1)Read a FITS image HDU (inhdu in inputname) as a float
type array. An optional mask image and mask hdu can also be given. Single
precision floating point types are one of the most common types to store
data: the observation noise is usually much larger than the extra precision
(and thus volume in your computer, and slower processing) offered by double
precision floating point types. With this function, so when you work
internally with floating points, you can use this function to directly read
a FITS image array into a floating point array.
*inputname, char *maskname, char *inhdu, char *mhdu, double **img, int *inbitpix, int *anyblank, size_t *ins0, size_t *ins1)Similar to gal_fits_file_to_float, but for double precision floating
point type. In some contexts, the internal operations must be done in
double precision floating point types, irrespective of the input type and
this function can be used to directly read a file into an array of this
type.
*inputname, char *inhdu, long **img, int *inbitpix, int *anyblank, size_t *ins0, size_t *ins1)Similar to gal_fits_file_to_float, but will read the image specified
by inputname (inhdu) into a long integer type. Long integer
types are commonly used to store things like segmentation maps or labeled
images.
*inputname, char *inhdu, float **outkernel, size_t *ins0, size_t *ins1)Read inputname (inhdu) will be read as a floating point array
to be used as a convolution kernel. Convolution kernels are commonly
necessary in astronomical image processing, but they need to have certain
properties: their dimensions have to be an odd number and they must not
have any blank pixels. In both cases, this function will abort with an
error notice.
Previous: FITS macros and data structures, Up: FITS files [Contents][Index]
GNU Astronomy Utilities 0.2.28-34fb manual, October 2016.