#ifndef _QFITS_H_ #define _QFITS_H_ #include #include #include #include extern char *qfits_version (void); /*----------------------------------------------------------------------------*/ /** @brief Purge the qfits cache. @return void This function is useful for programs running for a long period, to clean up the cache. Ideally in a daemon, it should be called by a timer at regular intervals. Notice that since the cache is fairly small, you should not need to care too much about this. */ /*----------------------------------------------------------------------------*/ void qfits_cache_purge (void); /*----------------------------------------------------------------------------*/ /** @brief Expand a keyword from shortFITS to HIERARCH notation. @param keyword Keyword to expand. @return 1 pointer to statically allocated string. This function expands a given keyword from shortFITS to HIERARCH notation, bringing it to uppercase at the same time. Examples: @verbatim det.dit expands to HIERARCH ESO DET DIT ins.filt1.id expands to HIERARCH ESO INS FILT1 ID @endverbatim If the input keyword is a regular FITS keyword (i.e. it contains not dots '.') the result is identical to the input. */ /*----------------------------------------------------------------------------*/ char *qfits_expand_keyword (const char *keyword); /*----------------------------------------------------------------------------*/ /** @brief FITS header object This structure represents a FITS header in memory. It is actually no more than a thin layer on top of the keytuple object. No field in this structure should be directly modifiable by the user, only through accessor functions. */ /*----------------------------------------------------------------------------*/ typedef struct qfits_header { void *first; /* Pointer to list start */ void *last; /* Pointer to list end */ int n; /* Number of cards in list */ } qfits_header; /*----------------------------------------------------------------------------- Function ANSI prototypes -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief FITS header constructor @return 1 newly allocated (empty) FITS header object. This is the main constructor for a qfits_header object. It returns an allocated linked-list handler with an empty card list. */ /*----------------------------------------------------------------------------*/ qfits_header *qfits_header_new (void); /*----------------------------------------------------------------------------*/ /** @brief FITS header default constructor. @return 1 newly allocated qfits_header object. This is a secondary constructor for a qfits_header object. It returns an allocated linked-list handler containing two cards: the first one (SIMPLE=T) and the last one (END). */ /*----------------------------------------------------------------------------*/ qfits_header *qfits_header_default (void); /*----------------------------------------------------------------------------*/ /** @brief Add a new card to a FITS header @param hdr qfits_header object to modify @param key FITS key @param val FITS value @param com FITS comment @param lin FITS original line if exists @return void This function adds a new card into a header, at the one-before-last position, i.e. the entry just before the END entry if it is there. The key must always be a non-NULL string, all other input parameters are allowed to get NULL values. */ /*----------------------------------------------------------------------------*/ void qfits_header_add (qfits_header * hdr, char *key, char *val, char *com, char *lin); /*----------------------------------------------------------------------------*/ /** @brief add a new card to a FITS header @param hdr qfits_header object to modify @param after Key to specify insertion place @param key FITS key @param val FITS value @param com FITS comment @param lin FITS original line if exists @return void Adds a new card to a FITS header, after the specified key. Nothing happens if the specified key is not found in the header. All fields can be NULL, except after and key. */ /*----------------------------------------------------------------------------*/ void qfits_header_add_after (qfits_header * hdr, char *after, char *key, char *val, char *com, char *lin); /*----------------------------------------------------------------------------*/ /** @brief Append a new card to a FITS header. @param hdr qfits_header object to modify @param key FITS key @param val FITS value @param com FITS comment @param lin FITS original line if exists @return void Adds a new card in a FITS header as the last one. All fields can be NULL except key. */ /*----------------------------------------------------------------------------*/ void qfits_header_append (qfits_header * hdr, const char *key, const char *val, const char *com, const char *lin); /*----------------------------------------------------------------------------*/ /** @brief Delete a card in a FITS header. @param hdr qfits_header to modify @param key specifies which card to remove @return void Removes a card from a FITS header. The first found card that matches the key is removed. */ /*----------------------------------------------------------------------------*/ void qfits_header_del (qfits_header * hdr, char *key); /*----------------------------------------------------------------------------*/ /** @brief Modifies a FITS card. @param hdr qfits_header to modify @param key FITS key @param val FITS value @param com FITS comment @return void Finds the first card in the header matching 'key', and replaces its value and comment fields by the provided values. The initial FITS line is set to NULL in the card. */ /*----------------------------------------------------------------------------*/ void qfits_header_mod (qfits_header * hdr, char *key, char *val, char *com); /*----------------------------------------------------------------------------*/ /** @brief Sort a FITS header @param hdr Header to sort (modified) @return -1 in error case, 0 otherwise */ /*----------------------------------------------------------------------------*/ int qfits_header_sort (qfits_header ** hdr); /*----------------------------------------------------------------------------*/ /** @brief Copy a FITS header @param src Header to replicate @return Pointer to newly allocated qfits_header object. Makes a strict copy of all information contained in the source header. The returned header must be freed using qfits_header_destroy. */ /*----------------------------------------------------------------------------*/ qfits_header *qfits_header_copy (qfits_header * src); /*----------------------------------------------------------------------------*/ /** @brief Touch all cards in a FITS header @param hdr qfits_header to modify @return void Touches all cards in a FITS header, i.e. all original FITS lines are freed and set to NULL. Useful when a header needs to be reformatted. */ /*----------------------------------------------------------------------------*/ void qfits_header_touchall (qfits_header * hdr); /*----------------------------------------------------------------------------*/ /** @brief Dump a FITS header to stdout @param hdr qfits_header to dump @return void Dump a FITS header to stdout. Mostly for debugging purposes. */ /*----------------------------------------------------------------------------*/ void qfits_header_consoledump (qfits_header * hdr); /*----------------------------------------------------------------------------*/ /** @brief qfits_header destructor @param hdr qfits_header to deallocate @return void Frees all memory associated to a given qfits_header object. */ /*----------------------------------------------------------------------------*/ void qfits_header_destroy (qfits_header * hdr); /*----------------------------------------------------------------------------*/ /** @brief Return the value associated to a key, as a string @param hdr qfits_header to parse @param key key to find @return pointer to statically allocated string Finds the value associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it. Returns NULL if no matching key is found or no value is attached. */ /*----------------------------------------------------------------------------*/ char *qfits_header_getstr (qfits_header * hdr, const char *key); /*----------------------------------------------------------------------------*/ /** @brief Find a matching key in a header. @param hdr qfits_header to parse @param key Key prefix to match @return pointer to statically allocated string. This function finds the first keyword in the given header for which the given 'key' is a prefix, and returns the full name of the matching key (NOT ITS VALUE). This is useful to locate any keyword starting with a given prefix. Careful with HIERARCH keywords, the shortFITS notation is not likely to be accepted here. Examples: @verbatim s = qfits_header_findmatch(hdr, "SIMP") returns "SIMPLE" s = qfits_header_findmatch(hdr, "HIERARCH ESO DET") returns the first detector keyword among the HIERACH keys. @endverbatim */ /*----------------------------------------------------------------------------*/ char *qfits_header_findmatch (qfits_header * hdr, char *key); /*----------------------------------------------------------------------------*/ /** @brief Return the i-th key/val/com/line tuple in a header. @param hdr Header to consider @param idx Index of the requested card @param key Output key @param val Output value @param com Output comment @param lin Output initial line @return int 0 if Ok, -1 if error occurred. This function is useful to browse a FITS header object card by card. By iterating on the number of cards (available in the 'n' field of the qfits_header struct), you can retrieve the FITS lines and their components one by one. Indexes run from 0 to n-1. You can pass NULL values for key, val, com or lin if you are not interested in a given field. @code int i ; char key[FITS_LINESZ+1] ; char val[FITS_LINESZ+1] ; char com[FITS_LINESZ+1] ; char lin[FITS_LINESZ+1] ; for (i=0 ; in ; i++) { qfits_header_getitem(hdr, i, key, val, com, lin); printf("card[%d] key[%s] val[%s] com[%s]\n", i, key, val, com); } @endcode This function has primarily been written to interface a qfits_header object to other languages (C++/Python). If you are working within a C program, you should use the other header manipulation routines available in this module. */ /*----------------------------------------------------------------------------*/ int qfits_header_getitem (qfits_header * hdr, int idx, char *key, char *val, char *com, char *lin); /*----------------------------------------------------------------------------*/ /** @brief Return the FITS line associated to a key, as a string @param hdr qfits_header to parse @param key key to find @return pointer to statically allocated string Finds the FITS line associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it. Returns NULL if no matching key is found or no line is attached. */ /*----------------------------------------------------------------------------*/ char *qfits_header_getline (qfits_header * hdr, char *key); /*----------------------------------------------------------------------------*/ /** @brief Return the comment associated to a key, as a string @param hdr qfits_header to parse @param key key to find @return pointer to statically allocated string @doc Finds the comment associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it. Returns NULL if no matching key is found or no comment is attached. */ /*----------------------------------------------------------------------------*/ char *qfits_header_getcom (qfits_header * hdr, char *key); /*----------------------------------------------------------------------------*/ /** @brief Return the value associated to a key, as an int @param hdr qfits_header to parse @param key key to find @param errval default value to return if nothing is found @return int Finds the value associated to the given key and return it as an int. Returns errval if no matching key is found or no value is attached. */ /*----------------------------------------------------------------------------*/ int qfits_header_getint (qfits_header * hdr, const char *key, int errval); /*----------------------------------------------------------------------------*/ /** @brief Return the value associated to a key, as a double @param hdr qfits_header to parse @param key key to find @param errval default value to return if nothing is found @return double Finds the value associated to the given key and return it as a double. Returns errval if no matching key is found or no value is attached. */ /*----------------------------------------------------------------------------*/ double qfits_header_getdouble (qfits_header * hdr, const char *key, double errval); /*----------------------------------------------------------------------------*/ /** @brief Return the value associated to a key, as a boolean (int). @param hdr qfits_header to parse @param key key to find @param errval default value to return if nothing is found @return int Finds the value associated to the given key and return it as a boolean. Returns errval if no matching key is found or no value is attached. A boolean is here understood as an int taking the value 0 or 1. errval can be set to any other integer value to reflect that nothing was found. errval is returned if no matching key is found or no value is attached. A true value is any character string beginning with a 'y' (yes), a 't' (true) or the digit '1'. A false value is any character string beginning with a 'n' (no), a 'f' (false) or the digit '0'. */ /*----------------------------------------------------------------------------*/ int qfits_header_getboolean (qfits_header * hdr, const char *key, int errval); /*----------------------------------------------------------------------------*/ /** @brief Write out a key tuple to a string on 80 chars. @param line Allocated output character buffer. @param key Key to write. @param val Value to write. @param com Comment to write. @return void Write out a key, value and comment into an allocated character buffer. The buffer must be at least 80 chars to receive the information. Formatting is done according to FITS standard. */ /*----------------------------------------------------------------------------*/ void keytuple2str (char *line, char *key, char *val, char *com); /*----------------------------------------------------------------------------*/ /** @brief Dump a FITS header to an opened file. @param hdr FITS header to dump @param out Opened file pointer @return int 0 if Ok, -1 otherwise Dumps a FITS header to an opened file pointer. */ /*----------------------------------------------------------------------------*/ int qfits_header_dump (qfits_header * hdr, FILE * out); /*----------------------------------------------------------------------------*/ /** @brief Dump a FITS header to an opened file (one card per line). @param hdr FITS header to dump @param out Opened file pointer @return int 0 if Ok, -1 otherwise @see qfits_header_dump() Dumps a FITS header to an opened file pointer. This function is meant to create hdr files. */ /*----------------------------------------------------------------------------*/ int qfits_header_dump_hdr (qfits_header * hdr, FILE * out); /*----------------------------------------------------------------------------*/ /** @brief Dump a fits header into a memory block. @param fh FITS header to dump @param hsize Size of the returned header, in bytes (output). @return 1 newly allocated memory block containing the FITS header. This function dumps a FITS header structure into a newly allocated memory block. The block is composed of characters, just as they would appear in a FITS file. This function is useful to make a FITS header in memory. The returned block size is indicated in the passed output variable 'hsize'. The returned block must be deallocated using free(). */ /*----------------------------------------------------------------------------*/ char *qfits_header_to_memblock (qfits_header * fh, int *hsize); /*----------------------------------------------------------------------------*/ /** @brief Compute the MD5 hash of data zones in a FITS file. @param filename Name of the FITS file to examine. @return 1 statically allocated character string, or NULL. This function expects the name of a FITS file. It will compute the MD5 hash on all data blocks in the main data section and possibly extensions (including zero-padding blocks if necessary) and return it as a string suitable for inclusion into a FITS keyword. The returned string is statically allocated inside this function, so do not free it or modify it. This function returns NULL in case of error. */ /*----------------------------------------------------------------------------*/ char *qfits_datamd5 (char *filename); /*----------------------------------------------------------------------------- Function ANSI C prototypes -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Find the keyword in a key card (80 chars) @param line allocated 80-char line from a FITS header @return statically allocated char * Find out the part of a FITS line corresponding to the keyword. Returns NULL in case of error. The returned pointer is statically allocated in this function, so do not modify or try to free it. */ /*----------------------------------------------------------------------------*/ char *qfits_getkey (char *line); /*----------------------------------------------------------------------------*/ /** @brief Find the value in a key card (80 chars) @param line allocated 80-char line from a FITS header @return statically allocated char * Find out the part of a FITS line corresponding to the value. Returns NULL in case of error, or if no value can be found. The returned pointer is statically allocated in this function, so do not modify or try to free it. */ /*----------------------------------------------------------------------------*/ char *qfits_getvalue (char *line); /*----------------------------------------------------------------------------*/ /** @brief Find the comment in a key card (80 chars) @param line allocated 80-char line from a FITS header @return statically allocated char * Find out the part of a FITS line corresponding to the comment. Returns NULL in case of error, or if no comment can be found. The returned pointer is statically allocated in this function, so do not modify or try to free it. */ /*----------------------------------------------------------------------------*/ char *qfits_getcomment (char *line); /*----------------------------------------------------------------------------*/ /** @brief Read a FITS header from a file to an internal structure. @param filename Name of the file to be read @return Pointer to newly allocated qfits_header or NULL in error case. This function parses a FITS (main) header, and returns an allocated qfits_header object. The qfits_header object contains a linked-list of key "tuples". A key tuple contains: - A keyword - A value - A comment - An original FITS line (as read from the input file) Direct access to the structure is not foreseen, use accessor functions in fits_h.h Value, comment, and original line might be NULL pointers. */ /*----------------------------------------------------------------------------*/ qfits_header *qfits_header_read (char *filename); /*----------------------------------------------------------------------------*/ /** @brief Read a FITS header from a 'hdr' file. @param filename Name of the file to be read @return Pointer to newly allocated qfits_header or NULL in error case This function parses a 'hdr' file, and returns an allocated qfits_header object. A hdr file is an ASCII format were the header is written with a carriage return after each line. The command dfits typically displays a hdr file. */ /*----------------------------------------------------------------------------*/ qfits_header *qfits_header_read_hdr (char *filename); /*----------------------------------------------------------------------------*/ /** @brief Read a FITS header from a 'hdr' string @param hdr_str String containing the hdr file @param nb_char Number of characters in the string @return Pointer to newly allocated qfits_header or NULL in error case This function parses a 'hdr' string, and returns an allocated qfits_header object. */ /*----------------------------------------------------------------------------*/ qfits_header *qfits_header_read_hdr_string (unsigned char *hdr_str, int nb_char); /*----------------------------------------------------------------------------*/ /** @brief Read an extension header from a FITS file. @param filename Name of the FITS file to read @param xtnum Extension number to read, starting from 0. @return Newly allocated qfits_header structure. Strictly similar to qfits_header_read() but reads headers from extensions instead. If the requested xtension is 0, this function calls qfits_header_read() to return the main header. Returns NULL in case of error. */ /*----------------------------------------------------------------------------*/ qfits_header *qfits_header_readext (char *filename, int xtnum); /*----------------------------------------------------------------------------*/ /** @brief Pad an existing file with zeros to a multiple of 2880. @param filename Name of the file to pad. @return void This function simply pads an existing file on disk with enough zeros for the file size to reach a multiple of 2880, as required by FITS. */ /*----------------------------------------------------------------------------*/ void qfits_zeropad (char *filename); /*----------------------------------------------------------------------------*/ /** @brief Identify if a file is a FITS file. @param filename name of the file to check @return int 0, 1, or -1 Returns 1 if the file name looks like a valid FITS file. Returns 0 else. If the file does not exist, returns -1. */ /*----------------------------------------------------------------------------*/ int is_fits_file (char *filename); /* FITS header constants */ /** FITS block size */ #define FITS_BLOCK_SIZE (2880) /** FITS number of cards per block */ #define FITS_NCARDS (36) /** FITS size of each line in bytes */ #define FITS_LINESZ (80) /** FITS magic number */ #define FITS_MAGIC "SIMPLE" /** Size of the FITS magic number */ #define FITS_MAGIC_SZ 6 /* FITS pixel depths */ /** FITS BITPIX=8 */ #define BPP_8_UNSIGNED (8) /** FITS BITPIX=16 */ #define BPP_16_SIGNED (16) /** FITS BITPIX=32 */ #define BPP_32_SIGNED (32) /** FITS BITPIX=-32 */ #define BPP_IEEE_FLOAT (-32) /** FITS BITPIX=-64 */ #define BPP_IEEE_DOUBLE (-64) /** Default BITPIX for output */ #define BPP_DEFAULT BPP_IEEE_FLOAT /** Compute the number of bytes per pixel for a given BITPIX value */ #define BYTESPERPIXEL(x) ( ((x) == BPP_8_UNSIGNED) ? 1 : \ ((x) == BPP_16_SIGNED) ? 2 : \ ((x) == BPP_32_SIGNED) ? 4 : \ ((x) == BPP_IEEE_FLOAT) ? 4 : \ ((x) == BPP_IEEE_DOUBLE) ? 8 : 0 ) /*----------------------------------------------------------------------------- Function ANSI C prototypes -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Find the directory name in the given string. @param filename Full path name to scan. @return Pointer to statically allocated string. Provide a full path name and you get in return a pointer to a statically allocated string containing the name of the directory only, without trailing slash. If the input string does not contain a slash (i.e. it is not a full path), the returned string is '.', corresponding to the current working directory. Since the returned string is statically allocated, do not try to free it or modify it. This function does not check for the existence of the path or the file. Examples: @verbatim get_dir_name("/cdrom/data/image.fits") returns "/cdrom/data" get_dir_name("filename.fits") returns "." @endverbatim */ /*----------------------------------------------------------------------------*/ char *qfits_get_dir_name (char *filename); /*----------------------------------------------------------------------------*/ /** @brief Find out the base name of a file (i.e. without prefix path) @param filename Full path name to scan. @return Pointer to char within the input string. Provide a full path name and you get in return a pointer to a statically allocated string containing the name of the file only, without prefixing directory names. If the input string does not contain a slash (i.e. it is not a full path), the returned string is a copy of the input string. This function does not check for the existence of the path or the file. Examples: @verbatim qfits_get_base_name("/cdrom/data/image.fits") returns "image.fits" qfits_get_base_name("filename.fits") returns "filename.fits" @endverbatim */ /*----------------------------------------------------------------------------*/ char *qfits_get_base_name (const char *filename); /*----------------------------------------------------------------------------*/ /** @brief Find out the root part of a basename (name without extension). @param filename File name to scan. @return Pointer to statically allocated string. Find out the root part of a file name, i.e. the file name without extension. Since in Unix a file name can have several dots, only a number of extensions are supported. This includes: - .fits and .FITS - .tfits and .TFITS - .paf and .PAF - .ascii and .ASCII - .dat and .DAT This function does not check for the existence of the path or the file. Examples: @verbatim get_root_name("/cdrom/filename.fits") returns "/cdrom/filename" get_root_name("filename.paf") returns "filename" get_root_name("filename") returns "filename" get_root_name("filename.ext") returns "filename.ext" @endverbatim Since the returned string is statically allocated in this module, do not try to free it or modify its contents. */ /*----------------------------------------------------------------------------*/ char *qfits_get_root_name (char *filename); /*----------------------------------------------------------------------------*/ /** @brief Find out the extension of a file name @param filename File name without path prefix. @return Pointer to char within the input string. Find out the extension of a given file name. Notice that the input character string must not contain a path prefix (typically, you feed in the output of @c qfits_get_base_name). Works with all kinds of extensions: returns the part of the string after the last dot. If no dot is found in the input string, NULL is returned. Examples: @verbatim get_ext_name("filename.fits") returns "fits" get_ext_name("hello.c") returns "c" get_ext_name("readme") returns NULL @endverbatim */ /*----------------------------------------------------------------------------*/ char *qfits_get_ext_name (char *filename); /*----------------------------------------------------------------------------*/ /** @brief Returns the user login name. @return Pointer to statically allocated character string. Finds out what the login name of the current user is. The result is placed in a static character string inside this module and a pointer to the first character in this string is returned. Do not modify or free the returned string! If the user name cannot be determined, the returned pointer will point to a string which first character is a null character. */ /*----------------------------------------------------------------------------*/ char *qfits_get_login_name (void); /*----------------------------------------------------------------------------*/ /** @brief Test a floating-point variable for NaN value. @param n Number to test (float or double) @return 1 if n is NaN, 0 else. This macro is needed to support both float and double variables as input parameter. It checks on the size of the input variable to branch to the float or double version. Portability is an issue for this function which is present on most Unixes but not all, under various libraries (C lib on BSD, Math lib on Linux, sunmath on Solaris, ...). Integrating the code for this function makes qfits independent from any math library. */ /*----------------------------------------------------------------------------*/ #define qfits_isnan(n) ((sizeof(n)==sizeof(float)) ? _qfits_isnanf(n) : \ (sizeof(n)==sizeof(double)) ? _qfits_isnand(n) : -1) /*----------------------------------------------------------------------------*/ /** @brief Test a floating-point variable for Inf value. @param n Number to test (float or double) @return 1 if n is Inf or -Inf, 0 else. This macro is needed to support both float and double variables as input parameter. It checks on the size of the input variable to branch to the float or double version. Portability is an issue for this function which is missing on most Unixes. Most of the time, another function called finite() is offered to perform the opposite task, but it is not consistent among platforms and found in various libraries. Integrating the code for this function makes qfits independent from any math library. */ /*----------------------------------------------------------------------------*/ #define qfits_isinf(n) ((sizeof(n)==sizeof(float)) ? _qfits_isinff(n) : \ (sizeof(n)==sizeof(double)) ? _qfits_isinfd(n) : -1) /*----------------------------------------------------------------------------- Function prototypes -----------------------------------------------------------------------------*/ /** * Test a float variable for NaN value. * Do not call directly, call qfits_isnan(). */ int _qfits_isnanf (float f); /** * Test a float variable for Inf value. * Do not call directly, call qfits_isinf(). */ int _qfits_isinff (float f); /** * Test a double variable for NaN value. * Do not call directly, call qfits_isnan(). */ int _qfits_isnand (double d); /** * Test a double variable for Inf value. * Do not call directly, call qfits_isinf(). */ int _qfits_isinfd (double d); /*----------------------------------------------------------------------------- Function prototypes -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Open a new PAF file, output a default header. @param filename Name of the file to create. @param paf_id PAF identificator. @param paf_desc PAF description. @param login_name Login name @param datetime Date @return Opened file pointer. This function creates a new PAF file with the requested file name. If another file already exists with the same name, it will be overwritten (if the file access rights allow it). A default header is produced according to the VLT DICB standard. You need to provide an identificator (paf_id) of the producer of the file. Typically, something like "ISAAC/zero_point". The PAF description (paf_desc) is meant for humans. Typically, something like "Zero point computation results". This function returns an opened file pointer, ready to receive more data through fprintf's. The caller is responsible for fclose()ing the file. */ /*----------------------------------------------------------------------------*/ FILE *qfits_paf_print_header (char *filename, char *paf_id, char *paf_desc, char *login_name, char *datetime); /*----------------------------------------------------------------------------*/ /** @brief Query a PAF file for a value. @param filename Name of the PAF to query. @param key Name of the key to query. @return 1 pointer to statically allocated string, or NULL. This function parses a PAF file and returns the value associated to a given key, as a pointer to an internal statically allocated string. Do not try to free or modify the contents of the returned string! If the key is not found, this function returns NULL. */ /*----------------------------------------------------------------------------*/ char *qfits_paf_query (char *filename, char *key); /*----------------------------------------------------------------------------*/ /** @brief returns 1 if file is in PAF format, 0 else @param filename name of the file to check @return int 0, 1, or -1 Returns 1 if the file name corresponds to a valid PAF file. Returns 0 else. If the file does not exist, returns -1. Validity of the PAF file is checked with the presence of PAF.HDR.START at the beginning */ /*----------------------------------------------------------------------------*/ int qfits_is_paf_file (char *filename); /*----------------------------------------------------------------------------- Defines -----------------------------------------------------------------------------*/ /** Symbol to set returned pixel type to float */ #define PTYPE_FLOAT 0 /** Symbol to set returned pixel type to int */ #define PTYPE_INT 1 /** Symbol to set returned pixel type to double */ #define PTYPE_DOUBLE 2 /*----------------------------------------------------------------------------- New types -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Alias for unsigned char A 'byte' is just an alias for an unsigned char. It is only defined for readability. */ /*----------------------------------------------------------------------------*/ typedef unsigned char byte; /*----------------------------------------------------------------------------*/ /** @brief qfits loader control object This structure serves two purposes: input and output for the qfits pixel loading facility. To request pixels from a FITS file, you need to allocate (statically or dynamically) such a structure and fill up the input fields (filename, xtension number, etc.) to specify the pixels you want from the file. Before performing the actual load, you must pass the initialized structure to qfitsloader_init() which will check whether the operation is feasible or not (check its returned value). If the operation was deemed feasible, you can proceed to load the pixels, passing the same structure to qfits_loadpix() which will fill up the output fields of the struct. Notice that a pixel buffer will have been allocated (through malloc or mmap) and placed into the structure. You need to call free() on this pointer when you are done with it, typically in the image or cube destructor. The qfitsloader_init() function is also useful to probe a FITS file for useful informations, like getting the size of images in the file, the pixel depth, or data offset. Example of a code that prints out various informations about a plane to load, without actually loading it: @code int main(int argc, char * argv[]) { qfitsloader ql ; ql.filename = argv[1] ; ql.xtnum = 0 ; ql.pnum = 0 ; if (qfitsloader_init(&ql)!=0) { printf("cannot read info about %s\n", argv[1]); return -1 ; } printf( "file : %s\n" "xtnum : %d\n" "pnum : %d\n" "# xtensions : %d\n" "size X : %d\n" "size Y : %d\n" "planes : %d\n" "bitpix : %d\n" "datastart : %d\n" "datasize : %d\n" "bscale : %g\n" "bzero : %g\n", ql.filename, ql.xtnum, ql.pnum, ql.exts, ql.lx, ql.ly, ql.np, ql.bitpix, ql.seg_start, ql.seg_size, ql.bscale, ql.bzero); return 0 ; } @endcode */ /*----------------------------------------------------------------------------*/ typedef struct qfitsloader { /** Private field to see if structure has been initialized */ int _init; /** input: Name of the file you want to read pixels from */ char *filename; /** input: xtension number you want to read */ int xtnum; /** input: Index of the plane you want, from 0 to np-1 */ int pnum; /** input: Pixel type you want (PTYPE_FLOAT, PTYPE_INT or PTYPE_DOUBLE) */ int ptype; /** input: Guarantee file copy or allow file mapping */ int map; /** output: Total number of extensions found in file */ int exts; /** output: Size in X of the requested plane */ int lx; /** output: Size in Y of the requested plane */ int ly; /** output: Number of planes present in this extension */ int np; /** output: BITPIX for this extension */ int bitpix; /** output: Start of the data segment (in bytes) for your request */ int seg_start; /** output: Size of the data segment (in bytes) for your request */ int seg_size; /** output: BSCALE found for this extension */ double bscale; /** output: BZERO found for this extension */ double bzero; /** output: Pointer to pixel buffer loaded as integer values */ int *ibuf; /** output: Pointer to pixel buffer loaded as float values */ float *fbuf; /** output: Pointer to pixel buffer loaded as double values */ double *dbuf; } qfitsloader; /*----------------------------------------------------------------------------*/ /** @brief qfits dumper control object This structure offers various control parameters to dump a pixel buffer to a FITS file. The buffer will be dumped as requested to the requested file in append mode. Of course, the requested file must be writeable for the operation to succeed. The following example demonstrates how to save a linear ramp sized 100x100 to a FITS file with BITPIX=16. Notice that this code only dumps the pixel buffer, no header information is provided in this case. @code int i, j ; int * ibuf ; qfitsdumper qd ; // Fill a buffer with 100x100 int pixels ibuf = malloc(100 * 100 * sizeof(int)); for (j=0 ; j<100 ; j++) { for (i=0 ; i<100 ; i++) { ibuf[i+j*100] = i+j ; } } qd.filename = "out.fits" ; // Output file name qd.npix = 100 * 100 ; // Number of pixels qd.ptype = PTYPE_INT ; // Input buffer type qd.ibuf = ibuf ; // Set buffer pointer qd.out_ptype = BPP_16_SIGNED ; // Save with BITPIX=16 // Dump buffer to file (error checking omitted for clarity) qfits_pixdump(&qd); free(ibuf); @endcode If the provided output file name is "STDOUT" (all capitals), the function will dump the pixels to the stdout steam (usually the console, could have been re-directed). */ /*----------------------------------------------------------------------------*/ typedef struct qfitsdumper { /** Name of the file to dump to, "STDOUT" to dump to stdout */ char *filename; /** Number of pixels in the buffer to dump */ int npix; /** Buffer type: PTYPE_FLOAT, PTYPE_INT or PTYPE_DOUBLE */ int ptype; /** Pointer to input integer pixel buffer */ int *ibuf; /** Pointer to input float pixel buffer */ float *fbuf; /** Pointer to input double pixel buffer */ double *dbuf; /** Requested BITPIX in output FITS file */ int out_ptype; } qfitsdumper; /*----------------------------------------------------------------------------- Function prototypes -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Initialize a qfitsloader control object. @param ql qfitsloader object to initialize. @return int 0 if Ok, -1 if error occurred. This function expects a qfitsloader object with a number of input fields correctly filled in. The minimum fields to set are: - filename: Name of the file to examine. - xtnum: Extension number to examine (0 for main section). - pnum: Plane number in the requested extension. You can go ahead with these fields only if you only want to get file information for this plane in this extension. If you want to later load the plane, you must additionally fill the 'ptype' field to a correct value (PTYPE_INT, PTYPE_FLOAT, PTYPE_DOUBLE) before calling qfits_loadpix() so that it knows which conversion to perform. This function is basically a probe sent on a FITS file to ask qfits if loading these data would be Ok or not. The actual loading is performed by qfits_loadpix() afterwards. */ /*----------------------------------------------------------------------------*/ int qfitsloader_init (qfitsloader * ql); /*----------------------------------------------------------------------------*/ /** @brief Load a pixel buffer for one image. @param ql Allocated and initialized qfitsloader control object. @return int 0 if Ok, -1 if error occurred. This function performs a load of a pixel buffer into memory. It expects an allocated and initialized qfitsloader object in input. See qfitsloader_init() about initializing the object. This function will fill up the ibuf/fbuf/dbuf field, depending on the requested pixel type (resp. int, float or double). The returned buffer has been allocated using one of the special memory operators present in xmemory.c. To deallocate the buffer, you must call the version of free() offered by xmemory, not the usual system free(). It is enough to include "xmemory.h" in your code before you make calls to the pixel loader here. */ /*----------------------------------------------------------------------------*/ int qfits_loadpix (qfitsloader * ql); /*----------------------------------------------------------------------------*/ /** @brief Load a pixel buffer as floats. @param p_source Pointer to source buffer (as bytes). @param npix Number of pixels to load. @param bitpix FITS BITPIX in original file. @param bscale FITS BSCALE in original file. @param bzero FITS BZERO in original file. @return 1 pointer to a newly allocated buffer of npix floats. This function takes in input a pointer to a byte buffer as given in the original FITS file (big-endian format). It converts the buffer to an array of float (whatever representation is used for floats by this platform is used) and returns the newly allocated buffer, or NULL if an error occurred. The returned buffer must be deallocated using the free() offered by xmemory. It is enough to #include "xmemory.h" before calling free on the returned pointer. */ /*----------------------------------------------------------------------------*/ float *qfits_pixin_float (byte *, int, int, double, double); /*----------------------------------------------------------------------------*/ /** @brief Load a pixel buffer as ints. @param p_source Pointer to source buffer (as bytes). @param npix Number of pixels to load. @param bitpix FITS BITPIX in original file. @param bscale FITS BSCALE in original file. @param bzero FITS BZERO in original file. @return 1 pointer to a newly allocated buffer of npix ints. This function takes in input a pointer to a byte buffer as given in the original FITS file (big-endian format). It converts the buffer to an array of int (whatever representation is used for int by this platform is used) and returns the newly allocated buffer, or NULL if an error occurred. The returned buffer must be deallocated using the free() offered by xmemory. It is enough to #include "xmemory.h" before calling free on the returned pointer. */ /*----------------------------------------------------------------------------*/ int *qfits_pixin_int (byte *, int, int, double, double); /*----------------------------------------------------------------------------*/ /** @brief Load a pixel buffer as doubles. @param p_source Pointer to source buffer (as bytes). @param npix Number of pixels to load. @param bitpix FITS BITPIX in original file. @param bscale FITS BSCALE in original file. @param bzero FITS BZERO in original file. @return 1 pointer to a newly allocated buffer of npix doubles. This function takes in input a pointer to a byte buffer as given in the original FITS file (big-endian format). It converts the buffer to an array of double (whatever representation is used for int by this platform is used) and returns the newly allocated buffer, or NULL if an error occurred. The returned buffer must be deallocated using the free() offered by xmemory. It is enough to #include "xmemory.h" before calling free on the returned pointer. */ /*----------------------------------------------------------------------------*/ double *qfits_pixin_double (byte *, int, int, double, double); /*----------------------------------------------------------------------------*/ /** @brief Dump a pixel buffer to an output FITS file in append mode. @param qd qfitsdumper control object. @return int 0 if Ok, -1 otherwise. This function takes in input a qfitsdumper control object. This object must be allocated beforehand and contain valid references to the data to save, and how to save it. The minimum fields to fill are: - filename: Name of the FITS file to dump to. - npix: Number of pixels in the buffer to be dumped. - ptype: Type of the passed buffer (PTYPE_FLOAT, PTYPE_INT, PTYPE_DOUBLE) - out_ptype: Requested FITS BITPIX for the output. One of the following fields must point to the corresponding pixel buffer: - ibuf for an int pixel buffer (ptype=PTYPE_INT) - fbuf for a float pixel buffer (ptype=PTYPE_FLOAT) - dbuf for a double pixel buffer (ptype=PTYPE_DOUBLE) This is a fairly low-level function, in the sense that it does not check that the output file already contains a proper header or even that the file it is appending to is indeed a FITS file. It will convert the pixel buffer to the requested BITPIX type and append the data to the file, without padding with zeros. See qfits_zeropad() about padding. If the given output file name is "STDOUT" (all caps), the dump will be performed to stdout. */ /*----------------------------------------------------------------------------*/ int qfits_pixdump (qfitsdumper * qd); /*----------------------------------------------------------------------------*/ /** @brief Convert a float pixel buffer to a byte buffer. @param buf Input float buffer. @param npix Number of pixels in the input buffer. @param ptype Requested output BITPIX type. @return 1 pointer to a newly allocated byte buffer. This function converts the given float buffer to a buffer of bytes suitable for dumping to a FITS file (i.e. big-endian, in the requested pixel type). The returned pointer must be deallocated using the free() function offered by xmemory. */ /*----------------------------------------------------------------------------*/ byte *qfits_pixdump_float (float *buf, int npix, int ptype); /*----------------------------------------------------------------------------*/ /** @brief Convert an int pixel buffer to a byte buffer. @param buf Input int buffer. @param npix Number of pixels in the input buffer. @param ptype Requested output BITPIX type. @return 1 pointer to a newly allocated byte buffer. This function converts the given int buffer to a buffer of bytes suitable for dumping to a FITS file (i.e. big-endian, in the requested pixel type). The returned pointer must be deallocated using the free() function offered by xmemory. */ /*----------------------------------------------------------------------------*/ byte *qfits_pixdump_int (int *buf, int npix, int ptype); /*----------------------------------------------------------------------------*/ /** @brief Convert a double pixel buffer to a byte buffer. @param buf Input double buffer. @param npix Number of pixels in the input buffer. @param ptype Requested output BITPIX type. @return 1 pointer to a newly allocated byte buffer. This function converts the given double buffer to a buffer of bytes suitable for dumping to a FITS file (i.e. big-endian, in the requested pixel type). The returned pointer must be deallocated using the free() function offered by xmemory. */ /*----------------------------------------------------------------------------*/ byte *qfits_pixdump_double (double *buf, int npix, int ptype); /*----------------------------------------------------------------------------*/ /** @brief Get the current status of error display. @return int 1 if error display is active, 0 if not. This function returns the current error display status. If it returns 1, it means that all calls to qfits_error/qfits_warning will display messages using the registered functions, otherwise they do nothing. */ /*----------------------------------------------------------------------------*/ int qfits_err_statget (void); /*----------------------------------------------------------------------------*/ /** @brief Set the current status of error display. @param sta New status to be set. @return int giving the previous display status. This function sets the current error display status to the required value, and returns the previous value. It is useful to store the previous value, in view of restoring it afterwards, e.g. to make a function silent on all its errors. Example: \begin{verbatim} int prev_stat = qfits_err_statset(0) ; function_call() ; qfits_err_statset(prev_stat); \end{verbatim} */ /*----------------------------------------------------------------------------*/ int qfits_err_statset (int sta); /*----------------------------------------------------------------------------*/ /** @brief Register a function to display error/warning messages. @param dispfn Display function (see doc below). @return int 0 if function was registered, -1 if not. This function registers a display function into the error-handling module. Display functions have the following prototype: @code void display_function(char * msg); @endcode They are simple functions that expect a ready-made error message and return void. They can do whatever they want with the message (log it to a file, send it to a GUI, to the syslog, ...). The message is built using a printf-like statement in qfits_error and qfits_warning, then passed to all registered display functions. A maximum of QFITS_ERR_MAXERRDISP can be registered (see source code). If the limit has been reached, this function will signal it by returning -1. */ /*----------------------------------------------------------------------------*/ int qfits_err_register (void (*dispfn) (char *)); /*----------------------------------------------------------------------------- Defines -----------------------------------------------------------------------------*/ /** Unknown type for FITS value */ #define QFITS_UNKNOWN 0 /** Boolean type for FITS value */ #define QFITS_BOOLEAN 1 /** Int type for FITS value */ #define QFITS_INT 2 /** Float type for FITS value */ #define QFITS_FLOAT 3 /** Complex type for FITS value */ #define QFITS_COMPLEX 4 /** String type for FITS value */ #define QFITS_STRING 5 /*----------------------------------------------------------------------------- Function codes -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Retrieve the value of a key in a FITS header @param filename Name of the FITS file to browse @param keyword Name of the keyword to find @return pointer to statically allocated character string Provide the name of a FITS file and a keyword to look for. The input file is memory-mapped and the first keyword matching the requested one is located. The value corresponding to this keyword is copied to a statically allocated area, so do not modify it or free it. The input keyword is first converted to upper case and expanded to the HIERARCH scheme if given in the shortFITS notation. This function is pretty fast due to the mmapping. Due to buffering on most Unixes, it is possible to call many times this function in a row on the same file and do not suffer too much from performance problems. If the file contents are already in the cache, the file will not be re-opened every time. It is possible, though, to modify this function to perform several searches in a row. See the source code. Returns NULL in case the requested keyword cannot be found. */ /*----------------------------------------------------------------------------*/ char *qfits_query_hdr (char *filename, const char *keyword); /*----------------------------------------------------------------------------*/ /** @brief Retrieve the value of a keyin a FITS extension header. @param filename name of the FITS file to browse. @param keyword name of the FITS key to look for. @param xtnum xtension number @return pointer to statically allocated character string Same as qfits_query_hdr but for extensions. xtnum starts from 1 to the number of extensions. If xtnum is zero, this function is strictly identical to qfits_query_hdr(). */ /*----------------------------------------------------------------------------*/ char *qfits_query_ext (char *filename, const char *keyword, int xtnum); /*----------------------------------------------------------------------------*/ /** @brief Counts the number of extensions in a FITS file @param filename Name of the FITS file to browse. @return int Counts how many extensions are in the file. Returns 0 if no extension is found, and -1 if an error occurred. */ /*----------------------------------------------------------------------------*/ int qfits_query_n_ext (char *filename); /*----------------------------------------------------------------------------*/ /** @brief Counts the number of planes in a FITS extension. @param filename Name of the FITS file to browse. @param exnum Extensin number @return int Counts how many planes are in the extension. Returns 0 if no plane is found, and -1 if an error occurred. */ /*----------------------------------------------------------------------------*/ int qfits_query_nplanes (char *filename, int extnum); /*----------------------------------------------------------------------------*/ /** @brief Clean out a FITS string value. @param s pointer to allocated FITS value string. @return pointer to statically allocated character string From a string FITS value like 'marvin o''hara', remove head and tail quotes, replace double '' with simple ', trim blanks on each side, and return the result in a statically allocated area. Examples: - ['o''hara'] becomes [o'hara] - [' H '] becomes [H] - ['1.0 '] becomes [1.0] */ /*----------------------------------------------------------------------------*/ char *qfits_pretty_string (char *s); /*----------------------------------------------------------------------------*/ /** @brief Identify if a FITS value is boolean @param s FITS value as a string @return int 0 or 1 Identifies if a FITS value is boolean. */ /*----------------------------------------------------------------------------*/ int qfits_is_boolean (char *s); /*----------------------------------------------------------------------------*/ /** @brief Identify if a FITS value is an int. @param s FITS value as a string @return int 0 or 1 Identifies if a FITS value is an integer. */ /*----------------------------------------------------------------------------*/ int qfits_is_int (char *s); /*----------------------------------------------------------------------------*/ /** @brief Identify if a FITS value is float. @param s FITS value as a string @return int 0 or 1 Identifies if a FITS value is float. */ /*----------------------------------------------------------------------------*/ int qfits_is_float (char *s); /*----------------------------------------------------------------------------*/ /** @brief Identify if a FITS value is complex. @param s FITS value as a string @return int 0 or 1 Identifies if a FITS value is complex. */ /*----------------------------------------------------------------------------*/ int qfits_is_complex (char *s); /*----------------------------------------------------------------------------*/ /** @brief Identify if a FITS value is string. @param s FITS value as a string @return int 0 or 1 Identifies if a FITS value is a string. */ /*----------------------------------------------------------------------------*/ int qfits_is_string (char *s); /*----------------------------------------------------------------------------*/ /** @brief Identify the type of a FITS value given as a string. @param s FITS value as a string @return integer naming the FITS type Returns the following value: - QFITS_UNKNOWN (0) for an unknown type. - QFITS_BOOLEAN (1) for a boolean type. - QFITS_INT (2) for an integer type. - QFITS_FLOAT (3) for a floating-point type. - QFITS_COMPLEX (4) for a complex number. - QFITS_STRING (5) for a FITS string. */ /*----------------------------------------------------------------------------*/ int qfits_get_type (char *s); /*----------------------------------------------------------------------------*/ /** @brief Retrieve offset to start and size of a header in a FITS file. @param filename Name of the file to examine @param xtnum Extension number (0 for main) @param seg_start Segment start in bytes (output) @param seg_size Segment size in bytes (output) @return int 0 if Ok, -1 otherwise. This function retrieves the two most important informations about a header in a FITS file: the offset to its beginning, and the size of the header in bytes. Both values are returned in the passed pointers to ints. It is Ok to pass NULL for any pointer if you do not want to retrieve the associated value. You must provide an extension number for the header, 0 meaning the main header in the file. */ /*----------------------------------------------------------------------------*/ int qfits_get_hdrinfo (char *filename, int xtnum, int *seg_start, int *seg_size); /*----------------------------------------------------------------------------*/ /** @brief Retrieve offset to start and size of a data section in a file. @param filename Name of the file to examine. @param xtnum Extension number (0 for main). @param seg_start Segment start in bytes (output). @param seg_size Segment size in bytes (output). @return int 0 if Ok, -1 otherwise. This function retrieves the two most important informations about a data section in a FITS file: the offset to its beginning, and the size of the section in bytes. Both values are returned in the passed pointers to ints. It is Ok to pass NULL for any pointer if you do not want to retrieve the associated value. You must provide an extension number for the header, 0 meaning the main header in the file. */ /*----------------------------------------------------------------------------*/ int qfits_get_datinfo (char *filename, int xtnum, int *seg_start, int *seg_size); /*----------------------------------------------------------------------------*/ /** @brief Query a card in a FITS (main) header by a given key @param filename Name of the FITS file to check. @param keyword Where to read a card in the header. @return Allocated string containing the card or NULL */ /*----------------------------------------------------------------------------*/ char *qfits_query_card (char *filename, char *keyword); /*----------------------------------------------------------------------------*/ /** @brief Replace a card in a FITS (main) header by a given card @param filename Name of the FITS file to modify. @param keyword Where to substitute a card in the header. @param substitute What to replace the line with. @return int 0 if Ok, -1 otherwise Replaces a whole card (80 chars) in a FITS header by a given FITS line (80 chars). The replacing line is assumed correctly formatted and containing at least 80 characters. The file is modified: it must be accessible in read/write mode. The input keyword is first converted to upper case and expanded to the HIERARCH scheme if given in the shortFITS notation. Returns 0 if everything worked Ok, -1 otherwise. */ /*----------------------------------------------------------------------------*/ int qfits_replace_card (char *filename, const char *keyword, char *substitute); /*----------------------------------------------------------------------------- Defines -----------------------------------------------------------------------------*/ /** Maximum supported file name size */ #define FILENAMESZ 512 /** Maximum number of characters per line in an ASCII file */ #define ASCIILINESZ 1024 /*----------------------------------------------------------------------------- Function ANSI C prototypes -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Returns the current date as a long (CCYYMMDD). @return The current date as a long number. Returns the current date as a long value (CCYYMMDD). Since most system clocks do not return a century, this function assumes that all years 80 and above are in the 20th century, and all years 00 to 79 are in the 21st century. For best results, consume before 1 Jan 2080. Example: 19 Oct 2000 is returned as 20001019 */ /*----------------------------------------------------------------------------*/ long qfits_date_now (void); /*----------------------------------------------------------------------------*/ /** @brief Returns the current time as a long (HHMMSSCC). @return The current time as a long number. Returns the current time as a long value (HHMMSSCC). If the system clock does not return centiseconds, these are set to zero. Example: 15:36:12.84 is returned as 15361284 */ /*----------------------------------------------------------------------------*/ long qfits_time_now (void); /*----------------------------------------------------------------------------*/ /** @brief Returns the current date as a static string. @return Pointer to statically allocated string. Build and return a string containing the date of today in ISO8601 format. The returned pointer points to a statically allocated string in the function, so no need to free it. */ /*----------------------------------------------------------------------------*/ char *qfits_get_date_iso8601 (void); /*----------------------------------------------------------------------------*/ /** @brief Returns the current date and time as a static string. @return Pointer to statically allocated string Build and return a string containing the date of today and the current time in ISO8601 format. The returned pointer points to a statically allocated string in the function, so no need to free it. */ /*----------------------------------------------------------------------------*/ char *qfits_get_datetime_iso8601 (void); /*----------------------------------------------------------------------------- Defines -----------------------------------------------------------------------------*/ /* The following defines the maximum acceptable size for a FITS value */ #define FITSVALSZ 60 #define QFITS_INVALIDTABLE 0 #define QFITS_BINTABLE 1 #define QFITS_ASCIITABLE 2 /*----------------------------------------------------------------------------- New types -----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** @brief Column data type */ /*----------------------------------------------------------------------------*/ typedef enum _TFITS_DATA_TYPE_ { TFITS_ASCII_TYPE_A, TFITS_ASCII_TYPE_D, TFITS_ASCII_TYPE_E, TFITS_ASCII_TYPE_F, TFITS_ASCII_TYPE_I, TFITS_BIN_TYPE_A, TFITS_BIN_TYPE_B, TFITS_BIN_TYPE_C, TFITS_BIN_TYPE_D, TFITS_BIN_TYPE_E, TFITS_BIN_TYPE_I, TFITS_BIN_TYPE_J, TFITS_BIN_TYPE_L, TFITS_BIN_TYPE_M, TFITS_BIN_TYPE_P, TFITS_BIN_TYPE_X, TFITS_BIN_TYPE_UNKNOWN } tfits_type; /*----------------------------------------------------------------------------*/ /** @brief Column object This structure contains all information needed to read a column in a table. These informations come from the header. The qfits_table object contains a list of qfits_col objects. This structure has to be created from scratch and filled if one want to generate a FITS table. */ /*----------------------------------------------------------------------------*/ typedef struct qfits_col { /** Number of atoms in one field. In ASCII tables, it is the number of characters in the field as defined in TFORM%d keyword. In BIN tables, it is the number of atoms in each field. For type 'A', it is the number of characters. A field with two complex object will have atom_nb = 4. */ int atom_nb; /** Number of decimals in a ASCII field. This value is always 0 for BIN tables */ int atom_dec_nb; /** Size of one element in bytes. In ASCII tables, atom_size is the size of the element once it has been converted in its 'destination' type. For example, if "123" is contained in an ASCII table in a column defined as I type, atom_nb=3, atom_size=4. In ASCII tables: - type 'A' : atom_size = atom_nb = number of chars - type 'I', 'F' or 'E' : atom_size = 4 - type 'D' : atom_size = 8 In BIN tables : - type 'A', 'L', 'X', 'B': atom_size = 1 - type 'I' : atom_size = 2 - type 'E', 'J', 'C', 'P' : atom_size = 4 - type 'D', 'M' : atom_size = 8 In ASCII table, there is one element per field. The size in bytes and in number of characters is atom_nb, and the size in bytes after conversion of the field is atom_size. In BIN tables, the size in bytes of a field is always atom_nb*atom_size. */ int atom_size; /** Type of data in the column as specified in TFORM keyword In ASCII tables : TFITS_ASCII_TYPE_* with *=A, I, F, E or D In BIN tables : TFITS_BIN_TYPE_* with *=L, X, B, I, J, A, E, D, C, M or P */ tfits_type atom_type; /** Label of the column */ char tlabel[FITSVALSZ]; /** Unit of the data */ char tunit[FITSVALSZ]; /** Null value */ char nullval[FITSVALSZ]; /** Display format */ char tdisp[FITSVALSZ]; /** zero and scale are used when the quantity in the field does not represent a true physical quantity. Basically, thez should be used when they are present: physical_value = zero + scale * field_value They are read from TZERO and TSCAL in the header */ int zero_present; float zero; int scale_present; float scale; /** Offset between the beg. of the table and the beg. of the column. */ int off_beg; /** Flag to know if the column is readable. An empty col is not readable */ int readable; } qfits_col; /*----------------------------------------------------------------------------*/ /** @brief Table object This structure contains all information needed to read a FITS table. These information come from the header. The object is created by qfits_open(). To read a FITS table, here is a code example: @code int main(int argc, char* argv[]) { qfits_table * table ; int n_ext ; int i ; // Query the number of extensions n_ext = qfits_query_n_ext(argv[1]) ; // For each extension for (i=0 ; inatoms * col->atom_size Numeric types are correctly understood and byte-swapped if needed, to be converted to the local machine type. NULL values have to be handled by the caller. The returned buffer has been allocated using one of the special memory operators present in xmemory.c. To deallocate the buffer, you must call the version of free() offered by xmemory, not the usual system free(). It is enough to include "xmemory.h" in your code before you make calls to the pixel loader here. */ /*----------------------------------------------------------------------------*/ unsigned char *qfits_query_column (qfits_table * th, int colnum, int *selection); /*----------------------------------------------------------------------------*/ /** @brief Extract consequtive values from a column in a FITS table @param th Allocated qfits_table @param colnum Number of the column to extract (from 0 to colnum-1) @param start_ind Index of the first row (0 for the first) @param nb_rows Number of rows to extract @return unsigned char array Does the same as qfits_query_column() but on a consequtive sequence of rows Spares the overhead of the selection object allocation */ /*----------------------------------------------------------------------------*/ unsigned char *qfits_query_column_seq (qfits_table * th, int colnum, int start_ind, int nb_rows); /*----------------------------------------------------------------------------*/ /** @brief Compute the table width in bytes from the columns infos @param th Allocated qfits_table @return the width (-1 in error case) */ /*----------------------------------------------------------------------------*/ int qfits_compute_table_width (qfits_table * th); /*----------------------------------------------------------------------------*/ /** @brief Extract binary data from a column in a FITS table @param th Allocated qfits_table @param colnum Number of the column to extract (from 0 to colnum-1) @param selection bollean array to identify selected rows @param null_value Value to return when a NULL value comes @return Pointer to void * Extract a column from a FITS table and return the data as a generic void* array. The returned array type and size are determined by the column object in the qfits_table. Returned array size in bytes is: nb_selected * col->atom_nb * col->atom_size NULL values are recognized and replaced by the specified value. The returned buffer has been allocated using one of the special memory operators present in xmemory.c. To deallocate the buffer, you must call the version of free() offered by xmemory, not the usual system free(). It is enough to include "xmemory.h" in your code before you make calls to the pixel loader here. */ /*----------------------------------------------------------------------------*/ void *qfits_query_column_data (qfits_table * th, int colnum, int *selection, void *null_value); /*----------------------------------------------------------------------------*/ /** @brief Extract binary data from a column in a FITS table @param th Allocated qfits_table @param colnum Number of the column to extract (from 0 to colnum-1) @param start_ind Index of the first row (0 for the first) @param nb_rows Number of rows to extract @param null_value Value to return when a NULL value comes @return Pointer to void * Does the same as qfits_query_column_data() but on a consequtive sequence of rows. Spares the overhead of the selection object allocation */ /*----------------------------------------------------------------------------*/ void *qfits_query_column_seq_data (qfits_table * th, int colnum, int start_ind, int nb_rows, void *null_value); /*----------------------------------------------------------------------------*/ /** @brief Detect NULL values in a column @param th Allocated qfits_table @param colnum Number of the column to check (from 0 to colnum-1) @param selection Array to identify selected rows @param nb_vals Gives the size of the output array @param nb_nulls Gives the number of detected null values @return array with 1 for NULLs and 0 for non-NULLs */ /*----------------------------------------------------------------------------*/ int *qfits_query_column_nulls (qfits_table * th, int colnum, int *selection, int *nb_vals, int *nb_nulls); /*----------------------------------------------------------------------------*/ /** @brief Save a table to a FITS file with a given FITS header. @param array Data array. @param table table @param fh FITS header to insert in the output file. @return -1 in error case, 0 otherwise */ /*----------------------------------------------------------------------------*/ int qfits_save_table_hdrdump (void **array, qfits_table * table, qfits_header * fh); /*----------------------------------------------------------------------------*/ /** @brief Appends a std extension header + data to a FITS table file. @param outfile Pointer to (opened) file ready for writing. @param t Pointer to qfits_table @param data Table data to write @return int 0 if Ok, -1 otherwise Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file. An extension header is produced with all keywords needed to describe the table, then the data is dumped to the file. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part. */ /*----------------------------------------------------------------------------*/ int qfits_table_append_xtension (FILE * outfile, qfits_table * t, void **data); /*----------------------------------------------------------------------------*/ /** @brief Appends a specified extension header + data to a FITS table file. @param outfile Pointer to (opened) file ready for writing. @param t Pointer to qfits_table @param data Table data to write @param hdr Specified extension header @return int 0 if Ok, -1 otherwise Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file following the specified fits header. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part. */ /*----------------------------------------------------------------------------*/ int qfits_table_append_xtension_hdr (FILE * outfile, qfits_table * t, void **data, qfits_header * hdr); /*----------------------------------------------------------------------------*/ /** @brief given a col and a row, find out the string to write for display @param table table structure @param col_id col id (0 -> nbcol-1) @param row_id row id (0 -> nrow-1) @param use_zero_scale Flag to use or not zero and scale @return the string to write */ /*----------------------------------------------------------------------------*/ char *qfits_table_field_to_string (qfits_table * table, int col_id, int row_id, int use_zero_scale); #endif