The following utility routines may be useful for certain applications.
float fits_get_version / ffvers ( > float *version)
void fits_write_errmsg / ffpmsg (char *err_msg)
void fits_uppercase / ffupch (char *string)
void fits_compare_str / ffcmps
(char *templt, char *string, int casesen, > int *match, int *exact)
This routine is similar to the ANSI C 'strtok' function:
The first call to fits_split_names has a non-null input string. It finds the first name in the string and terminates it by overwriting the next character of the string with a null terminator and returns a pointer to the name. Each subsequent call, indicated by a NULL value of the input string, returns the next name, searching from just past the end of the previous name. It returns NULL when no further names are found.
char *fits_split_names(char *namelist)The following example shows how a string would be split into 3 names:
myfile[1][bin (x,y)=4], file2.fits file3.fits
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
1st name 2nd name 3rd name
int fits_test_keyword / fftkey (char *keyname, > int *status) int fits_test_record / fftrec (char *card, > int *status)
int fits_null_check / ffnchk (char *card, > int *status)
int fits_get_keyname / ffgknm
(char *card, > char *keyname, int *keylength, int *status)
int fits_parse_value / ffpsvc
(char *card, > char *value, char *comment, int *status)
int fits_make_keyn / ffkeyn
(char *keyroot, int value, > char *keyname, int *status)
int fits_make_nkey / ffnkey
(int value, char *keyroot, > char *keyname, int *status)
int fits_get_keytype / ffdtyp
(char *value, > char *dtype, int *status)
Class Value Keywords
TYP_STRUC_KEY 10 SIMPLE, BITPIX, NAXIS, NAXISn, EXTEND, BLOCKED,
GROUPS, PCOUNT, GCOUNT, END
XTENSION, TFIELDS, TTYPEn, TBCOLn, TFORMn, THEAP,
and the first 4 COMMENT keywords in the primary array
that define the FITS format.
TYP_CMPRS_KEY 20 The experimental keywords used in the compressed
image format ZIMAGE, ZCMPTYPE, ZNAMEn, ZVALn,
ZTILEn, ZBITPIX, ZNAXISn, ZSCALE, ZZERO, ZBLANK
TYP_SCAL_KEY 30 BSCALE, BZERO, TSCALn, TZEROn
TYP_NULL_KEY 40 BLANK, TNULLn
TYP_DIM_KEY 50 TDIMn
TYP_RANG_KEY 60 TLMINn, TLMAXn, TDMINn, TDMAXn, DATAMIN, DATAMAX
TYP_UNIT_KEY 70 BUNIT, TUNITn
TYP_DISP_KEY 80 TDISPn
TYP_HDUID_KEY 90 EXTNAME, EXTVER, EXTLEVEL, HDUNAME, HDUVER, HDULEVEL
TYP_CKSUM_KEY 100 CHECKSUM, DATASUM
TYP_WCS_KEY 110 WCS keywords defined in the the WCS papers, including:
CTYPEn, CUNITn, CRVALn, CRPIXn, CROTAn, CDELTn
CDj_is, PVj_ms, LONPOLEs, LATPOLEs
TCTYPn, TCTYns, TCUNIn, TCUNns, TCRVLn, TCRVns, TCRPXn,
TCRPks, TCDn_k, TCn_ks, TPVn_m, TPn_ms, TCDLTn, TCROTn
jCTYPn, jCTYns, jCUNIn, jCUNns, jCRVLn, jCRVns, iCRPXn,
iCRPns, jiCDn, jiCDns, jPVn_m, jPn_ms, jCDLTn, jCROTn
(i,j,m,n are integers, s is any letter)
TYP_REFSYS_KEY 120 EQUINOXs, EPOCH, MJD-OBSs, RADECSYS, RADESYSs, DATE-OBS
TYP_COMM_KEY 130 COMMENT, HISTORY, (blank keyword)
TYP_CONT_KEY 140 CONTINUE
TYP_USER_KEY 150 all other keywords
int fits_get_keyclass / ffgkcl (char *card)
int fits_binary_tform / ffbnfm
(char *tform, > int *typecode, long *repeat, long *width,
int *status)
int fits_binary_tformll / ffbnfmll
(char *tform, > int *typecode, LONGLONG *repeat, long *width,
int *status)
int fits_ascii_tform / ffasfm
(char *tform, > int *typecode, long *width, int *decimals,
int *status)
int fits_get_tbcol / ffgabc
(int tfields, char **tform, int space, > long *rowlen,
long *tbcol, int *status)
int fits_parse_template / ffgthd
(char *templt, > char *card, int *keytype, int *status)
The input templt character string generally should contain 3 tokens:
(1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string. The
TEMPLATE string must adhere to the following format:
The keytype output parameter indicates how the returned CARD string should be interpreted:
keytype interpretation
------- -------------------------------------------------
-2 Rename the keyword with name = the first 8 characters of CARD
to the new name given in characters 41 - 48 of CARD.
-1 delete the keyword with this name from the FITS header.
0 append the CARD string to the FITS header if the
keyword does not already exist, otherwise update
the keyword value and/or comment field if is already exists.
1 This is a HISTORY or COMMENT keyword; append it to the header
2 END record; do not explicitly write it to the FITS file.
EXAMPLES: The following lines illustrate valid input template strings:
INTVAL 7 / This is an integer keyword
RVAL 34.6 / This is a floating point keyword
EVAL=-12.45E-03 / This is a floating point keyword in exponential notation
lval F / This is a boolean keyword
This is a comment keyword with a blank keyword name
SVAL1 = 'Hello world' / this is a string keyword
SVAL2 '123.5' this is also a string keyword
sval3 123+ / this is also a string keyword with the value '123+ '
# the following template line deletes the DATE keyword
- DATE
# the following template line modifies the NAME keyword to OBJECT
- NAME OBJECT
The user passes an array of patterns to be matched. Input pattern number i is pattern[i][0], and output pattern number i is pattern[i][1]. Keywords are matched against the input patterns. If a match is found then the keyword is re-written according to the output pattern.
Order is important. The first match is accepted. The fastest match will be made when templates with the same first character are grouped together.
Several characters have special meanings:
i,j - single digits, preserved in output template
n - column number of one or more digits, preserved in output template
m - generic number of one or more digits, preserved in output template
a - coordinate designator, preserved in output template
# - number of one or more digits
? - any character
* - only allowed in first character position, to match all
keywords; only useful as last pattern in the list
i, j, n, and m are returned by the routine.
For example, the input pattern "iCTYPn" will match "1CTYP5" (if n_value is 5); the output pattern "CTYPEi" will be re-written as "CTYPE1". Notice that "i" is preserved.
The following output patterns are special:
"-" - do not copy a keyword that matches the corresponding input pattern
"+" - copy the input unchanged
The inrec string could be just the 8-char keyword name, or the entire 80-char header record. Characters 9 - 80 in the input string simply get appended to the translated keyword name.
If n_range = 0, then only keywords with 'n' equal to n_value will be considered as a pattern match. If n_range = +1, then all values of 'n' greater than or equal to n_value will be a match, and if -1, then values of 'n' less than or equal to n_value will match.
int fits_translate_keyword(
char *inrec, /* I - input string */
char *outrec, /* O - output converted string, or */
/* a null string if input does not */
/* match any of the patterns */
char *patterns[][2],/* I - pointer to input / output string */
/* templates */
int npat, /* I - number of templates passed */
int n_value, /* I - base 'n' template value of interest */
int n_offset, /* I - offset to be applied to the 'n' */
/* value in the output string */
int n_range, /* I - controls range of 'n' template */
/* values of interest (-1,0, or +1) */
int *pat_num, /* O - matched pattern number (0 based) or -1 */
int *i, /* O - value of i, if any, else 0 */
int *j, /* O - value of j, if any, else 0 */
int *m, /* O - value of m, if any, else 0 */
int *n, /* O - value of n, if any, else 0 */
int *status) /* IO - error status */
char *patterns[][2] = {{"TSCALn", "BSCALE" }, /* Standard FITS keywords */
{"TZEROn", "BZERO" },
{"TUNITn", "BUNIT" },
{"TNULLn", "BLANK" },
{"TDMINn", "DATAMIN" },
{"TDMAXn", "DATAMAX" },
{"iCTYPn", "CTYPEi" }, /* Coordinate labels */
{"iCTYna", "CTYPEia" },
{"iCUNIn", "CUNITi" }, /* Coordinate units */
{"iCUNna", "CUNITia" },
{"iCRVLn", "CRVALi" }, /* WCS keywords */
{"iCRVna", "CRVALia" },
{"iCDLTn", "CDELTi" },
{"iCDEna", "CDELTia" },
{"iCRPXn", "CRPIXi" },
{"iCRPna", "CRPIXia" },
{"ijPCna", "PCi_ja" },
{"ijCDna", "CDi_ja" },
{"iVn_ma", "PVi_ma" },
{"iSn_ma", "PSi_ma" },
{"iCRDna", "CRDERia" },
{"iCSYna", "CSYERia" },
{"iCROTn", "CROTAi" },
{"WCAXna", "WCSAXESa"},
{"WCSNna", "WCSNAMEa"}};
int fits_translate_keywords( fitsfile *infptr, /* I - pointer to input HDU */ fitsfile *outfptr, /* I - pointer to output HDU */ int firstkey, /* I - first HDU record number to start with */ char *patterns[][2],/* I - pointer to input / output keyword templates */ int npat, /* I - number of templates passed */ int n_value, /* I - base 'n' template value of interest */ int n_offset, /* I - offset to be applied to the 'n' */ /* value in the output string */ int n_range, /* I - controls range of 'n' template */ /* values of interest (-1,0, or +1) */ int *status) /* IO - error status */
int fits_parse_range / ffrwrg(char *rowlist, LONGLONG maxrows, int maxranges, >
int *numranges, long *rangemin, long *rangemax, int *status)
int fits_parse_rangell / ffrwrgll(char *rowlist, LONGLONG maxrows, int maxranges, >
int *numranges, LONGLONG *rangemin, LONGLONG *rangemax, int *status)
int ffchfl(fitsfile *fptr, > int *status)
int ffcdfl(fitsfile *fptr, > int *status)