/usr/share/doc/libcfitsio-doc/quick/quick005.html is in libcfitsio-doc 3.410-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 | <!DOCTYPE html>
<html >
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.29">
<link rel="stylesheet" type="text/css" href="quick.css">
<title>CFITSIO Routines</title>
</head>
<body >
<a href="quick004.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="quick006.html"><img src="next_motif.gif" alt="Next"></a>
<hr>
<h2 id="sec5" class="section">4  CFITSIO Routines</h2>
<p>This chapter describes the main CFITSIO routines that can be used to
perform the most common types of operations on FITS files.</p><span style="font-weight:bold">
</span><h3 id="sec6" class="subsection"><span style="font-weight:bold">4.1  Error Reporting</span></h3>
<pre class="verbatim">void fits_report_error(FILE *stream, int status)
void fits_get_errstatus(int status, char *err_text)
float fits_get_version(float *version)
</pre><p>The first routine prints out information about any error that
has occurred. Whenever any CFITSIO routine encounters an error it
usually writes a message describing the nature of the error to an
internal error message stack and then returns with a positive integer
status value. Passing the error status value to this routine will
cause a generic description of the error and all the messages
from the internal CFITSIO error stack to be printed to the specified
stream. The <span style="font-family:monospace">stream</span> parameter is usually set equal to
<span style="font-family:monospace">"stdout"</span> or <span style="font-family:monospace">"stderr"</span>.</p><p>The second routine simply returns a 30-character descriptive
error message corresponding to the input status value.</p><p>The last routine returns the current CFITSIO library version number.</p><span style="font-weight:bold">
</span><h3 id="sec7" class="subsection"><span style="font-weight:bold">4.2  File Open/Close Routines</span></h3>
<pre class="verbatim">int fits_open_file( fitsfile **fptr, char *filename, int mode, int *status)
int fits_open_data( fitsfile **fptr, char *filename, int mode, int *status)
int fits_open_table(fitsfile **fptr, char *filename, int mode, int *status)
int fits_open_image(fitsfile **fptr, char *filename, int mode, int *status)
int fits_create_file(fitsfile **fptr, char *filename, int *status)
int fits_close_file(fitsfile *fptr, int *status)
</pre><p>These routines open or close a file. The first <span style="font-family:monospace">fitsfile</span>
parameter in these and nearly every other CFITSIO routine is a pointer
to a structure that CFITSIO uses to store relevant parameters about
each opened file. You should never directly read or write any
information in this structure. Memory for this structure is allocated
automatically when the file is opened or created, and is freed when the
file is closed.</p><p>The <span style="font-family:monospace">mode</span> parameter in the <span style="font-family:monospace">fits_open_xxxx</span> set of routines
can be set to either <span style="font-family:monospace">READONLY</span> or <span style="font-family:monospace">READWRITE</span> to select the
type of file access that will be allowed. These symbolic constants are
defined in <span style="font-family:monospace">fitsio.h</span>.</p><p>The <span style="font-family:monospace">fits_open_file</span> routine opens the file and positions the internal
file pointer to the beginning of the file, or to the specified
extension if an extension name or number is appended to the file name
(see the later section on “CFITSIO File Names and Filters” for a
description of the syntax). <span style="font-family:monospace">fits_open_data</span> behaves similarly except
that it will move to the first HDU containing significant data if a HDU
name or number to open is not explicitly specified as part of the
filename. It will move to the first IMAGE HDU with NAXIS greater than
0, or the first table that does not contain the strings ‘GTI’ (a Good
Time Interval extension) or ‘OBSTABLE’ in the EXTNAME keyword value.
The <span style="font-family:monospace">fits_open_table</span> and <span style="font-family:monospace">fits_open_image</span> routines are similar
except that they will move to the first significant table HDU or image
HDU, respectively if a HDU name of number is not specified as part of
the input file name.</p><p>When opening an existing file, the <span style="font-family:monospace">filename</span> can include optional
arguments, enclosed in square brackets that specify filtering
operations that should be applied to the input file. For example,
</p><pre class="verbatim"> myfile.fit[EVENTS][counts > 0]
</pre><p>opens the table in the EVENTS extension and creates a virtual table by
selecting only those rows where the COUNTS column value is greater than
0. See section 5 for more examples of these powerful filtering
capabilities.</p><p>In <span style="font-family:monospace">fits_create_file</span>, the <span style="font-family:monospace">filename</span> is simply the root name of
the file to be created. You can overwrite an existing file by
prefixing the name with a ‘!’ character (on the Unix command line this
must be prefixed with a backslash, as in <code>`\!file.fit'</code>).
If the file name ends with <span style="font-family:monospace">.gz</span> the file will be compressed
using the gzip algorithm. If the
filename is <span style="font-family:monospace">stdout</span> or <span style="font-family:monospace">"-"</span> (a single dash character)
then the output file will be piped to the stdout stream. You can
chain several tasks together by writing the output from the first task
to <span style="font-family:monospace">stdout</span> and then reading the input file in the 2nd task from
<span style="font-family:monospace">stdin</span> or <span style="font-family:monospace">"-"</span>.</p><span style="font-weight:bold">
</span><h3 id="sec8" class="subsection"><span style="font-weight:bold">4.3  HDU-level Routines</span></h3>
<p>The routines listed in this section operate on Header-Data Units (HDUs) in a file.</p><pre class="verbatim">_______________________________________________________________
int fits_get_num_hdus(fitsfile *fptr, int *hdunum, int *status)
int fits_get_hdu_num(fitsfile *fptr, int *hdunum)
</pre><p>The first routines returns the total number of HDUs in the FITS file,
and the second routine returns the position of the currently opened HDU in
the FITS file (starting with 1, not 0).</p><pre class="verbatim">__________________________________________________________________________
int fits_movabs_hdu(fitsfile *fptr, int hdunum, int *hdutype, int *status)
int fits_movrel_hdu(fitsfile *fptr, int nmove, int *hdutype, int *status)
int fits_movnam_hdu(fitsfile *fptr, int hdutype, char *extname,
int extver, int *status)
</pre><p>These routines enable you to move to a different HDU in the file.
Most of the CFITSIO functions which read or write keywords or data
operate only on the currently opened HDU in the file. The first
routine moves to the specified absolute HDU number in the FITS
file (the first HDU = 1), whereas the second routine moves a relative
number of HDUs forward or backward from the currently open HDU. The
<span style="font-family:monospace">hdutype</span> parameter returns the type of the newly opened HDU, and will
be equal to one of these symbolic constant values: <span style="font-family:monospace">IMAGE_HDU,
ASCII_TBL, or BINARY_TBL</span>. <span style="font-family:monospace">hdutype</span> may be set to NULL
if it is not needed. The third routine moves to the (first) HDU
that matches the input extension type, name, and version number,
as given by the <span style="font-family:monospace">XTENSION, EXTNAME</span> (or <span style="font-family:monospace">HDUNAME</span>) and <span style="font-family:monospace">EXTVER</span> keywords.
If the input value of <span style="font-family:monospace">extver</span> = 0, then the version number will
be ignored when looking for a matching HDU.</p><pre class="verbatim">_________________________________________________________________
int fits_get_hdu_type(fitsfile *fptr, int *hdutype, int *status)
</pre><p>Get the type of the current HDU in the FITS file: <span style="font-family:monospace">IMAGE_HDU,
ASCII_TBL, or BINARY_TBL</span>.</p><pre class="verbatim">____________________________________________________________________
int fits_copy_hdu(fitsfile *infptr, fitsfile *outfptr, int morekeys,
int *status)
int fits_copy_file(fitsfile *infptr, fitsfile *outfptr, int previous,
int current, int following, > int *status)
</pre><p>The first routine copies the current HDU from the FITS file associated
with infptr and appends it to the end of the FITS file associated with
outfptr. Space may be reserved for <span style="font-family:monospace">morekeys</span> additional keywords
in the output header. The second routine copies any HDUs previous
to the current HDU, and/or the current HDU, and/or any HDUs following the
current HDU, depending on the value (True or False) of <span style="font-family:monospace">previous,
current</span>, and <span style="font-family:monospace">following</span>, respectively. For example,
</p><pre class="verbatim"> fits_copy_file(infptr, outfptr, 0, 1, 1, &status);
</pre><p>will copy the current HDU and any HDUs that follow it from the input
to the output file, but it will not copy any HDUs preceding the
current HDU.</p>
<h3 id="sec9" class="subsection">4.4  Image I/O Routines</h3>
<p>This section lists the more important CFITSIO routines which operate on
FITS images.</p><pre class="verbatim">_______________________________________________________________
int fits_get_img_type(fitsfile *fptr, int *bitpix, int *status)
int fits_get_img_dim( fitsfile *fptr, int *naxis, int *status)
int fits_get_img_size(fitsfile *fptr, int maxdim, long *naxes,
int *status)
int fits_get_img_param(fitsfile *fptr, int maxdim, int *bitpix,
int *naxis, long *naxes, int *status)
</pre><p>Get information about the currently opened image HDU. The first routine
returns the datatype of the image as (defined by the <span style="font-family:monospace">BITPIX</span>
keyword), which can have the following symbolic constant values:
</p><pre class="verbatim"> BYTE_IMG = 8 ( 8-bit byte pixels, 0 - 255)
SHORT_IMG = 16 (16 bit integer pixels)
LONG_IMG = 32 (32-bit integer pixels)
LONGLONG_IMG = 64 (64-bit integer pixels)
FLOAT_IMG = -32 (32-bit floating point pixels)
DOUBLE_IMG = -64 (64-bit floating point pixels)
</pre><p>The second and third routines return the number of dimensions in the
image (from the <span style="font-family:monospace">NAXIS</span> keyword), and the sizes of each dimension
(from the <span style="font-family:monospace">NAXIS1, NAXIS2</span>, etc. keywords). The last routine
simply combines the function of the first 3 routines. The input <span style="font-family:monospace">maxdim</span> parameter in this routine gives the maximum number dimensions
that may be returned (i.e., the dimension of the <span style="font-family:monospace">naxes</span>
array)</p><pre class="verbatim">__________________________________________________________
int fits_create_img(fitsfile *fptr, int bitpix, int naxis,
long *naxes, int *status)
</pre><p>Create an image HDU by writing the required keywords which define the
structure of the image. The 2nd through 4th parameters specified the
datatype, the number of dimensions, and the sizes of the dimensions.
The allowed values of the <span style="font-family:monospace">bitpix</span> parameter are listed above in
the description of the <span style="font-family:monospace">fits_get_img_type</span> routine. If the FITS
file pointed to by <span style="font-family:monospace">fptr</span> is empty (previously created with
<span style="font-family:monospace">fits_create_file</span>) then this routine creates a primary array in
the file, otherwise a new IMAGE extension is appended to end of the
file following the other HDUs in the file.</p><pre class="verbatim">______________________________________________________________
int fits_write_pix(fitsfile *fptr, int datatype, long *fpixel,
long nelements, void *array, int *status);
int fits_write_pixnull(fitsfile *fptr, int datatype, long *fpixel,
long nelements, void *array, void *nulval, int *status);
int fits_read_pix(fitsfile *fptr, int datatype, long *fpixel,
long nelements, void *nulval, void *array,
int *anynul, int *status)
</pre><p>Read or write all or part of the FITS image. There are 2 different
’write’ pixel routines: The first simply writes the input array of pixels
to the FITS file. The second is similar, except that it substitutes
the appropriate null pixel value in the FITS file for any pixels
which have a value equal to <span style="font-family:monospace">*nulval</span> (note that this parameter
gives the address of the null pixel value, not the value itself).
Similarly, when reading an image, CFITSIO will substitute the value
given by <span style="font-family:monospace">nulval</span> for any undefined pixels in the image, unless
<span style="font-family:monospace">nulval = NULL</span>, in which case no checks will be made for undefined
pixels when reading the FITS image.</p><p>The <span style="font-family:monospace">fpixel</span> parameter in these routines is an array which gives
the coordinate in each dimension of the first pixel to be read or
written, and <span style="font-family:monospace">nelements</span> is the total number of pixels to read or
write. <span style="font-family:monospace">array</span> is the address of an array which either contains
the pixel values to be written, or will hold the values of the pixels
that are read. When reading, <span style="font-family:monospace">array</span> must have been allocated
large enough to hold all the returned pixel values. These routines
starts at the <span style="font-family:monospace">fpixel</span> location and then read or write the <span style="font-family:monospace">nelements</span> pixels, continuing on successive rows of the image if
necessary. For example, to write an entire 2D image, set <span style="font-family:monospace">fpixel[0] = fpixel[1] = 1</span>, and <span style="font-family:monospace">nelements = NAXIS1 * NAXIS2</span>. Or
to read just the 10th row of the image, set <span style="font-family:monospace">fpixel[0] = 1,
fpixel[1] = 10</span>, and <span style="font-family:monospace">nelements = NAXIS1</span>. The <span style="font-family:monospace">datatype</span>
parameter specifies the datatype of the C <span style="font-family:monospace">array</span> in the program,
which need not be the same as the datatype of the FITS image itself.
If the datatypes differ then CFITSIO will convert the data as it is
read or written. The following symbolic constants are allowed for the
value of <span style="font-family:monospace">datatype</span>:
</p><pre class="verbatim"> TBYTE unsigned char
TSBYTE signed char
TSHORT signed short
TUSHORT unsigned short
TINT signed int
TUINT unsigned int
TLONG signed long
TLONGLONG signed 8-byte integer
TULONG unsigned long
TFLOAT float
TDOUBLE double
</pre><pre class="verbatim">_________________________________________________________________
int fits_write_subset(fitsfile *fptr, int datatype, long *fpixel,
long *lpixel, DTYPE *array, > int *status)
int fits_read_subset(fitsfile *fptr, int datatype, long *fpixel,
long *lpixel, long *inc, void *nulval, void *array,
int *anynul, int *status)
</pre><p>Read or write a rectangular section of the FITS image. These are very
similar to <span style="font-family:monospace">fits_write_pix</span> and <span style="font-family:monospace">fits_read_pix</span> except that
you specify the last pixel coordinate (the upper right corner of the
section) instead of the number of pixels to be read. The read routine
also has an <span style="font-family:monospace">inc</span> parameter which can be used to read only every
<span style="font-family:monospace">inc-th</span> pixel along each dimension of the image. Normally <span style="font-family:monospace">inc[0] = inc[1] = 1</span> to read every pixel in a 2D image. To read every
other pixel in the entire 2D image, set
</p><pre class="verbatim"> fpixel[0] = fpixel[1] = 1
lpixel[0] = {NAXIS1}
lpixel[1] = {NAXIS2}
inc[0] = inc[1] = 2
</pre><p>Or, to read the 8th row of a 2D image, set
</p><pre class="verbatim"> fpixel[0] = 1
fpixel[1] = 8
lpixel[0] = {NAXIS1}
lpixel[1] = 8
inc[0] = inc[1] = 1
</pre>
<h3 id="sec10" class="subsection">4.5  Table I/O Routines</h3>
<p>This section lists the most important CFITSIO routines which operate on
FITS tables.</p><pre class="verbatim">__________________________________________________________________________
int fits_create_tbl(fitsfile *fptr, int tbltype, long nrows, int tfields,
char *ttype[],char *tform[], char *tunit[], char *extname, int *status)
</pre><p>Create a new table extension by writing the required keywords that
define the table structure. The required null primary array
will be created first if the file is initially completely empty. <span style="font-family:monospace">tbltype</span> defines the type of table and can have values of <span style="font-family:monospace">ASCII_TBL or BINARY_TBL</span>. Binary tables are generally preferred
because they are more efficient and support a greater range of column
datatypes than ASCII tables.</p><p>The <span style="font-family:monospace">nrows</span> parameter gives the initial number of empty rows to be
allocated for the table; this should normally be set to 0. The <span style="font-family:monospace">tfields</span>
parameter gives the number of columns in the table (maximum = 999).
The <span style="font-family:monospace">ttype, tform</span>, and <span style="font-family:monospace">tunit</span> parameters give the name, datatype, and
physical units of each column, and <span style="font-family:monospace">extname</span> gives the name for the
table (the value of the <span style="font-family:monospace">EXTNAME</span> keyword).
The FITS Standard recommends that only
letters, digits, and the underscore character be used in column names
with no embedded spaces. It is recommended that all the column names
in a given table be unique within the first 8 characters.</p><p>The following table
shows the TFORM column format values that are allowed in ASCII tables
and in binary tables:
</p><pre class="verbatim"> ASCII Table Column Format Codes
-------------------------------
(w = column width, d = no. of decimal places to display)
Aw - character string
Iw - integer
Fw.d - fixed floating point
Ew.d - exponential floating point
Dw.d - exponential floating point
Binary Table Column Format Codes
--------------------------------
(r = vector length, default = 1)
rA - character string
rAw - array of strings, each of length w
rL - logical
rX - bit
rB - unsigned byte
rS - signed byte **
rI - signed 16-bit integer
rU - unsigned 16-bit integer **
rJ - signed 32-bit integer
rV - unsigned 32-bit integer **
rK - signed 64-bit integer
rE - 32-bit floating point
rD - 64-bit floating point
rC - 32-bit complex pair
rM - 64-bit complex pair
** The S, U and V format codes are not actual legal TFORMn values.
CFITSIO substitutes the somewhat more complicated set of
keywords that are used to represent unsigned integers or
signed bytes.
</pre><p>The <span style="font-family:monospace">tunit</span> and <span style="font-family:monospace">extname</span> parameters are optional and
may be set to NULL
if they are not needed. </p><p>Note that it may be easier to create a new table by copying the
header from another existing table with <span style="font-family:monospace">fits_copy_header</span> rather
than calling this routine.</p><pre class="verbatim">_______________________________________________________________
int fits_get_num_rows(fitsfile *fptr, long *nrows, int *status)
int fits_get_num_cols(fitsfile *fptr, int *ncols, int *status)
</pre><p>Get the number of rows or columns in the current FITS table. The
number of rows is given by the <span style="font-family:monospace">NAXIS2</span> keyword and the number of columns
is given by the <span style="font-family:monospace">TFIELDS</span> keyword in the header of the table.</p><pre class="verbatim">_______________________________________________________________
int fits_get_colnum(fitsfile *fptr, int casesen, char *template,
int *colnum, int *status)
int fits_get_colname(fitsfile *fptr, int casesen, char *template,
char *colname, int *colnum, int *status)
</pre><p>Get the column number (starting with 1, not 0) of the column whose
name matches the specified template name. The only difference in
these 2 routines is that the 2nd one also returns the name of the
column that matched the template string.</p><p>Normally, <span style="font-family:monospace">casesen</span> should
be set to <span style="font-family:monospace">CASEINSEN</span>, but it may be set to <span style="font-family:monospace">CASESEN</span> to force
the name matching to be case-sensitive.</p><p>The input <span style="font-family:monospace">template</span> string gives the name of the desired column and
may include wildcard characters: a ‘*’ matches any sequence of
characters (including zero characters), ‘?’ matches any single
character, and ‘#’ matches any consecutive string of decimal digits
(0-9). If more than one column name in the table matches the template
string, then the first match is returned and the status value will be
set to <span style="font-family:monospace">COL_NOT_UNIQUE</span> as a warning that a unique match was not
found. To find the next column that matches the template, call this
routine again leaving the input status value equal to <span style="font-family:monospace">COL_NOT_UNIQUE</span>. Repeat this process until <span style="font-family:monospace">status =
COL_NOT_FOUND</span> is returned.</p><pre class="verbatim">_______________________________________________________________
int fits_get_coltype(fitsfile *fptr, int colnum, int *typecode,
long *repeat, long *width, int *status)
int fits_get_eqcoltype(fitsfile *fptr, int colnum, int *typecode,
long *repeat, long *width, int *status)
</pre><p>Return the datatype, vector repeat count, and the width in bytes of a
single column element for column number <span style="font-family:monospace">colnum</span>. Allowed values
for the returned datatype in ASCII tables are: <span style="font-family:monospace">TSTRING, TSHORT,
TLONG, TFLOAT, and TDOUBLE</span>. Binary tables support these additional
types: <span style="font-family:monospace">TLOGICAL, TBIT, TBYTE, TINT32BIT, TCOMPLEX and TDBLCOMPLEX</span>. The
negative of the datatype code value is returned if it is a variable
length array column.</p><p>These 2 routines are similar, except that in the case of scaled
integer columns the 2nd routine, fit_get_eqcoltype, returns the
’equivalent’ datatype that is needed to store the scaled values, which
is not necessarily the same as the physical datatype of the unscaled values
as stored in the FITS table. For example if a ’1I’ column in a binary
table has TSCALn = 1 and TZEROn = 32768, then this column effectively
contains unsigned short integer values, and thus the returned value of
typecode will be TUSHORT, not TSHORT. Or, if TSCALn or TZEROn are not
integers, then the equivalent datatype will be returned as TFLOAT or
TDOUBLE, depending on the size of the integer.</p><p>The repeat count is always 1 in ASCII tables.
The ’repeat’ parameter returns the vector repeat count on the binary
table TFORMn keyword value. (ASCII table columns always have repeat
= 1). The ’width’ parameter returns the width in bytes of a single
column element (e.g., a ’10D’ binary table column will have width =
8, an ASCII table ’F12.2’ column will have width = 12, and a binary
table’60A’ character string column will have width = 60); Note that
this routine supports the local convention for specifying arrays of
fixed length strings within a binary table character column using
the syntax TFORM = ’rAw’ where ’r’ is the total number of
characters (= the width of the column) and ’w’ is the width of a
unit string within the column. Thus if the column has TFORM =
’60A12’ then this means that each row of the table contains
5 12-character substrings within the 60-character field, and thus
in this case this routine will return typecode = TSTRING, repeat =
60, and width = 12. The number of substings in any binary table
character string field can be calculated by (repeat/width).
A null pointer may be given for any of the output parameters that
are not needed.</p><pre class="verbatim">____________________________________________________________________________
int fits_insert_rows(fitsfile *fptr, long firstrow, long nrows, int *status)
int fits_delete_rows(fitsfile *fptr, long firstrow, long nrows, int *status)
int fits_delete_rowrange(fitsfile *fptr, char *rangelist, int *status)
int fits_delete_rowlist(fitsfile *fptr, long *rowlist, long nrows, int *stat)
</pre><p>Insert or delete rows in a table. The blank rows are inserted
immediately following row <span style="font-family:monospace">frow</span>. Set <span style="font-family:monospace">frow</span> = 0 to insert rows
at the beginning of the table. The first ’delete’ routine deletes <span style="font-family:monospace">nrows</span> rows beginning with row <span style="font-family:monospace">firstrow</span>. The 2nd delete routine
takes an input string listing the rows or row ranges to be deleted
(e.g., ’2,4-7, 9-12’). The last delete routine takes an input long
integer array that specifies each individual row to be deleted. The
row lists must be sorted in ascending order. All these routines update
the value of the <span style="font-family:monospace">NAXIS2</span> keyword to reflect the new number of rows
in the table.</p><pre class="verbatim">_________________________________________________________________________
int fits_insert_col(fitsfile *fptr, int colnum, char *ttype, char *tform,
int *status)
int fits_insert_cols(fitsfile *fptr, int colnum, int ncols, char **ttype,
char **tform, int *status)
int fits_delete_col(fitsfile *fptr, int colnum, int *status)
</pre><p>Insert or delete columns in a table. <span style="font-family:monospace">colnum</span> gives the position
of the column to be inserted or deleted (where the first column of the
table is at position 1). <span style="font-family:monospace">ttype</span> and <span style="font-family:monospace">tform</span> give the column
name and column format, where the allowed format codes are listed above
in the description of the <span style="font-family:monospace">fits_create_table</span> routine. The 2nd
’insert’ routine inserts multiple columns, where <span style="font-family:monospace">ncols</span> is the
number of columns to insert, and <span style="font-family:monospace">ttype</span> and <span style="font-family:monospace">tform</span> are
arrays of string pointers in this case.</p><pre class="verbatim">____________________________________________________________________
int fits_copy_col(fitsfile *infptr, fitsfile *outfptr, int incolnum,
int outcolnum, int create_col, int *status);
</pre><p>Copy a column from one table HDU to another. If <span style="font-family:monospace">create_col</span> = TRUE (i.e., not equal to zero),
then a new column will be inserted in the output table at position
<span style="font-family:monospace">outcolumn</span>, otherwise the values in the existing output column will be
overwritten. </p><pre class="verbatim">__________________________________________________________________________
int fits_write_col(fitsfile *fptr, int datatype, int colnum, long firstrow,
long firstelem, long nelements, void *array, int *status)
int fits_write_colnull(fitsfile *fptr, int datatype, int colnum,
long firstrow, long firstelem, long nelements,
void *array, void *nulval, int *status)
int fits_write_col_null(fitsfile *fptr, int colnum, long firstrow,
long firstelem, long nelements, int *status)
int fits_read_col(fitsfile *fptr, int datatype, int colnum, long firstrow,
long firstelem, long nelements, void *nulval, void *array,
int *anynul, int *status)
</pre><p>Write or read elements in column number <span style="font-family:monospace">colnum</span>, starting with row
<span style="font-family:monospace">firstsrow</span> and element <span style="font-family:monospace">firstelem</span> (if it is a vector
column). <span style="font-family:monospace">firstelem</span> is ignored if it is a scalar column. The <span style="font-family:monospace">nelements</span> number of elements are read or written continuing on
successive rows of the table if necessary. <span style="font-family:monospace">array</span> is the address
of an array which either contains the values to be written, or will
hold the returned values that are read. When reading, <span style="font-family:monospace">array</span> must
have been allocated large enough to hold all the returned values.</p><p>There are 3 different ’write’ column routines: The first simply writes
the input array into the column. The second is similar, except that it
substitutes the appropriate null pixel value in the column for any
input array values which are equal to <span style="font-family:monospace">*nulval</span> (note that this
parameter gives the address of the null pixel value, not the value
itself). The third write routine sets the specified table elements
to a null value. New rows will be automatical added to the table
if the write operation extends beyond the current size of the table.</p><p>When reading a column, CFITSIO will substitute the value given by <span style="font-family:monospace">nulval</span> for any undefined elements in the FITS column, unless <span style="font-family:monospace">nulval</span> or <span style="font-family:monospace">*nulval = NULL</span>, in which case no checks will be made
for undefined values when reading the column.</p><p><span style="font-family:monospace">datatype</span> specifies the datatype of the C <span style="font-family:monospace">array</span> in the program,
which need not be the same as the intrinsic datatype of the column in
the FITS table. The following symbolic constants are allowed for the
value of <span style="font-family:monospace">datatype</span>:</p><pre class="verbatim"> TSTRING array of character string pointers
TBYTE unsigned char
TSHORT signed short
TUSHORT unsigned short
TINT signed int
TUINT unsigned int
TLONG signed long
TLONGLONG signed 8-byte integer
TULONG unsigned long
TFLOAT float
TDOUBLE double
</pre><p>Note that <span style="font-family:monospace">TSTRING</span> corresponds to the C <span style="font-family:monospace">char**</span> datatype, i.e., a pointer to an array of pointers to an array
of characters.</p><p>Any column, regardless of it’s intrinsic datatype, may be read as a
<span style="font-family:monospace">TSTRING</span> character string. The display format of the returned
strings will be determined by the <span style="font-family:monospace">TDISPn</span> keyword, if it exists,
otherwise a default format will be used depending on the datatype of
the column. The <span style="font-family:monospace">tablist</span> example utility program (available from
the CFITSIO web site) uses this feature to display all the values in a
FITS table.</p><pre class="verbatim">_____________________________________________________________________
int fits_select_rows(fitsfile *infptr, fitsfile *outfptr, char *expr,
int *status)
int fits_calculator(fitsfile *infptr, char *expr, fitsfile *outfptr,
char *colname, char *tform, int *status)
</pre><p>These are 2 of the most powerful routines in the CFITSIO library. (See
the full CFITSIO Reference Guide for a description of several related
routines). These routines can perform complicated transformations on
tables based on an input arithmetic expression which is evaluated for
each row of the table. The first routine will select or copy rows of
the table for which the expression evaluates to TRUE (i.e., not equal
to zero). The second routine writes the value of the expression to a
column in the output table. Rather than supplying the expression
directly to these routines, the expression may also be written to a
text file (continued over multiple lines if necessary) and the name of
the file, prepended with a ’@’ character, may be supplied as the value
of the ’expr’ parameter (e.g. ’@filename.txt’).</p><p>The arithmetic expression may be a function of any column or keyword in
the input table as shown in these examples:</p><pre class="verbatim">Row Selection Expressions:
counts > 0 uses COUNTS column value
sqrt( X**2 + Y**2) < 10. uses X and Y column values
(X > 10) || (X < -10) && (Y == 0) used 'or' and 'and' operators
gtifilter() filter on Good Time Intervals
regfilter("myregion.reg") filter using a region file
@select.txt reads expression from a text file
Calculator Expressions:
#row % 10 modulus of the row number
counts/#exposure Fn of COUNTS column and EXPOSURE keyword
dec < 85 ? cos(dec * #deg) : 0 Conditional expression: evaluates to
cos(dec) if dec < 85, else 0
(count{-1}+count+count{+1})/3. running mean of the count values in the
previous, current, and next rows
max(0, min(X, 1000)) returns a value between 0 - 1000
@calc.txt reads expression from a text file
</pre><p>Most standard mathematical operators and functions are supported. If
the expression includes the name of a column, than the value in the
current row of the table will be used when evaluating the expression on
each row. An offset to an adjacent row can be specified by including
the offset value in curly brackets after the column name as shown in
one of the examples. Keyword values can be included in the expression
by preceding the keyword name with a ‘#’ sign. See Section 5 of this
document for more discussion of the expression syntax.</p><p><span style="font-family:monospace">gtifilter</span> is a special function which tests whether the <span style="font-family:monospace">TIME</span> column value in the input table falls within one or more Good
Time Intervals. By default, this function looks for a ’GTI’ extension
in the same file as the input table. The ’GTI’ table contains <span style="font-family:monospace">START</span>
and <span style="font-family:monospace">STOP</span> columns which define the range of
each good time interval. See section 5.4.3 for more details.</p><p><span style="font-family:monospace">regfilter</span> is another special function which selects rows based on
whether the spatial position associated with each row is located within
in a specified region of the sky. By default, the <span style="font-family:monospace">X</span> and <span style="font-family:monospace">Y</span>
columns in the input table are assumed to give the position of each row.
The spatial region is defined in an ASCII text file whose name is given
as the argument to the <span style="font-family:monospace">regfilter</span> function. See section 5.4.4 for
more details.</p><p>The <span style="font-family:monospace">infptr</span> and <span style="font-family:monospace">outfptr</span> parameters in these routines may
point to the same table or to different tables. In <span style="font-family:monospace">fits_select_rows</span>, if the input and output tables are the same then
the rows that do not satisfy the selection expression will be deleted
from the table. Otherwise, if the output table is different from the
input table then the selected rows will be copied from the input table
to the output table.</p><p>The output column in <span style="font-family:monospace">fits_calculator</span> may or may not already
exist. If it exists then the calculated values will be written to that
column, overwriting the existing values. If the column doesn’t exist
then the new column will be appended to the output table. The <span style="font-family:monospace">tform</span>
parameter can be used to specify the datatype of the new column (e.g.,
the <span style="font-family:monospace">TFORM</span> keyword value as in <span style="font-family:monospace">’1E’, or ’1J’</span>). If <span style="font-family:monospace">tform</span> = NULL then a default datatype will be used, depending on the
expression.</p><pre class="verbatim">_____________________________________________________________________
int fits_read_tblbytes(fitsfile *fptr, long firstrow, long firstchar,
long nchars, unsigned char *array, int *status)
int fits_write_tblbytes (fitsfile *fptr, long firstrow, long firstchar,
long nchars, unsigned char *array, int *status)
</pre><p>These 2 routines provide low-level access to tables and are mainly
useful as an efficient way to copy rows of a table from one file to
another. These routines simply read or write the specified number of
consecutive characters (bytes) in a table, without regard for column
boundaries. For example, to read or write the first row of a table,
set <span style="font-family:monospace">firstrow = 1, firstchar = 1</span>, and <span style="font-family:monospace">nchars = NAXIS1</span> where
the length of a row is given by the value of the <span style="font-family:monospace">NAXIS1</span> header
keyword. When reading a table, <span style="font-family:monospace">array</span> must have been declared at
least <span style="font-family:monospace">nchars</span> bytes long to hold the returned string of bytes.</p>
<h3 id="sec11" class="subsection">4.6  Header Keyword I/O Routines</h3>
<p>
The following routines read and write header keywords in the current HDU.
</p><pre class="verbatim">____________________________________________________________________
int fits_get_hdrspace(fitsfile *fptr, int *keysexist, int *morekeys,
int *status)
</pre><p>Return the number of existing keywords (not counting the mandatory END
keyword) and the amount of empty space currently available for more
keywords. The <span style="font-family:monospace">morekeys</span> parameter may be set to NULL if it’s value is
not needed.</p><pre class="verbatim">___________________________________________________________________________
int fits_read_record(fitsfile *fptr, int keynum, char *record, int *status)
int fits_read_card(fitsfile *fptr, char *keyname, char *record, int *status)
int fits_read_key(fitsfile *fptr, int datatype, char *keyname,
void *value, char *comment, int *status)
int fits_find_nextkey(fitsfile *fptr, char **inclist, int ninc,
char **exclist, int nexc, char *card, int *status)
int fits_read_key_unit(fitsfile *fptr, char *keyname, char *unit,
int *status)
</pre><p>These routines all read a header record in the current HDU. The first
routine reads keyword number <span style="font-family:monospace">keynum</span> (where the first keyword is
at position 1). This routine is most commonly used when sequentially
reading every record in the header from beginning to end. The 2nd and
3rd routines read the named keyword and return either the whole
record, or the keyword value and comment string. In each case any
non-significant trailing blank characters in the strings are truncated.</p><p>Wild card characters (*, ?, and #) may be used when specifying the name
of the keyword to be read, in which case the first matching keyword is
returned.</p><p>The <span style="font-family:monospace">datatype</span> parameter specifies the C datatype of the returned
keyword value and can have one of the following symbolic constant
values: <span style="font-family:monospace">TSTRING, TLOGICAL</span> (== int), <span style="font-family:monospace">TBYTE</span>, <span style="font-family:monospace">TSHORT</span>,
<span style="font-family:monospace">TUSHORT</span>, <span style="font-family:monospace">TINT</span>, <span style="font-family:monospace">TUINT</span>, <span style="font-family:monospace">TLONG</span>, <span style="font-family:monospace">TULONG</span>, <span style="font-family:monospace">TFLOAT</span>, <span style="font-family:monospace">TDOUBLE</span>, <span style="font-family:monospace">TCOMPLEX</span>, and <span style="font-family:monospace">TDBLCOMPLEX</span>. Data
type conversion will be performed for numeric values if the intrinsic
FITS keyword value does not have the same datatype. The <span style="font-family:monospace">comment</span>
parameter may be set equal to NULL if the comment string is not
needed.</p><p>The 4th routine provides an easy way to find all the keywords in the
header that match one of the name templates in <span style="font-family:monospace">inclist</span> and do not
match any of the name templates in <span style="font-family:monospace">exclist</span>. <span style="font-family:monospace">ninc</span> and <span style="font-family:monospace">nexc</span> are the number of template strings in <span style="font-family:monospace">inclist</span> and <span style="font-family:monospace">exclist</span>, respectively. Wild cards (*, ?, and #) may be used in the
templates to match multiple keywords. Each time this routine is called
it returns the next matching 80-byte keyword record. It returns status
= <span style="font-family:monospace">KEY_NO_EXIST</span> if there are no more matches.</p><p>The 5th routine returns the keyword value units string, if any.
The units are recorded at the beginning of the keyword comment field
enclosed in square brackets.
</p><pre class="verbatim">_______________________________________________________________
int fits_write_key(fitsfile *fptr, int datatype, char *keyname,
void *value, char *comment, int *status)
int fits_update_key(fitsfile *fptr, int datatype, char *keyname,
void *value, char *comment, int *status)
int fits_write_record(fitsfile *fptr, char *card, int *status)
int fits_modify_comment(fitsfile *fptr, char *keyname, char *comment,
int *status)
int fits_write_key_unit(fitsfile *fptr, char *keyname, char *unit,
int *status)
</pre><p>Write or modify a keyword in the header of the current HDU. The
first routine appends the new keyword to the end of the header, whereas
the second routine will update the value and comment fields of the
keyword if it already exists, otherwise it behaves like the first
routine and appends the new keyword. Note that <span style="font-family:monospace">value</span> gives the
address to the value and not the value itself. The <span style="font-family:monospace">datatype</span>
parameter specifies the C datatype of the keyword value and may have
any of the values listed in the description of the keyword reading
routines, above. A NULL may be entered for the comment parameter, in
which case the keyword comment field will be unmodified or left
blank.</p><p>The third routine is more primitive and simply writes the 80-character
<span style="font-family:monospace">card</span> record to the header. It is the programmer’s responsibility
in this case to ensure that the record conforms to all the FITS format
requirements for a header record.</p><p>The fourth routine modifies the comment string in an existing keyword,
and the last routine writes or updates the keyword units string for an
existing keyword. (The units are recorded at the beginning of the
keyword comment field enclosed in square brackets).</p><pre class="verbatim">___________________________________________________________________
int fits_write_comment(fitsfile *fptr, char *comment, int *status)
int fits_write_history(fitsfile *fptr, char *history, int *status)
int fits_write_date(fitsfile *fptr, int *status)
</pre><p>Write a <span style="font-family:monospace">COMMENT, HISTORY</span>, or <span style="font-family:monospace">DATE</span> keyword to the current
header. The <span style="font-family:monospace">COMMENT</span> keyword is typically used to write a comment
about the file or the data. The <span style="font-family:monospace">HISTORY</span> keyword is typically
used to provide information about the history of the processing
procedures that have been applied to the data. The <span style="font-family:monospace">comment</span> or
<span style="font-family:monospace">history</span> string will be continued over multiple keywords if it is
more than 70 characters long.</p><p>The <span style="font-family:monospace">DATE</span> keyword is used to record the date and time that the
FITS file was created. Note that this file creation date is usually
different from the date of the observation which obtained the data in
the FITS file. The <span style="font-family:monospace">DATE</span> keyword value is a character string in
’yyyy-mm-ddThh:mm:ss’ format. If a <span style="font-family:monospace">DATE</span> keyword already exists in
the header, then this routine will update the value with the current
system date.</p><pre class="verbatim">___________________________________________________________________
int fits_delete_record(fitsfile *fptr, int keynum, int *status)
int fits_delete_key(fitsfile *fptr, char *keyname, int *status)
</pre><p>Delete a keyword record. The first routine deletes a keyword at a
specified position (the first keyword is at position 1, not 0),
whereas the second routine deletes the named keyword.</p><pre class="verbatim">_______________________________________________________________________
int fits_copy_header(fitsfile *infptr, fitsfile *outfptr, int *status)
</pre><p>Copy all the header keywords from the current HDU associated with
infptr to the current HDU associated with outfptr. If the current
output HDU is not empty, then a new HDU will be appended to the output
file. The output HDU will then have the identical structure as the
input HDU, but will contain no data.</p>
<h3 id="sec12" class="subsection">4.7  Utility Routines</h3>
<p>This section lists the most important CFITSIO general utility routines.</p><pre class="verbatim">___________________________________________________________________
int fits_write_chksum( fitsfile *fptr, int *status)
int fits_verify_chksum(fitsfile *fptr, int *dataok, int *hduok, int *status)
</pre><p>These routines compute or validate the checksums for the currenrt
HDU. The <span style="font-family:monospace">DATASUM</span> keyword is used to store the numerical value of
the 32-bit, 1’s complement checksum for the data unit alone. The <span style="font-family:monospace">CHECKSUM</span> keyword is used to store the ASCII encoded COMPLEMENT of the
checksum for the entire HDU. Storing the complement, rather than the
actual checksum, forces the checksum for the whole HDU to equal zero.
If the file has been modified since the checksums were computed, then
the HDU checksum will usually not equal zero.</p><p>The returned <span style="font-family:monospace">dataok</span> and <span style="font-family:monospace">hduok</span> parameters will have a value
= 1 if the data or HDU is verified correctly, a value = 0 if the
<span style="font-family:monospace">DATASUM</span> or <span style="font-family:monospace">CHECKSUM</span> keyword is not present, or value = -1 if the
computed checksum is not correct.</p><pre class="verbatim">___________________________________________________________________
int fits_parse_value(char *card, char *value, char *comment, int *status)
int fits_get_keytype(char *value, char *dtype, int *status)
int fits_get_keyclass(char *card)
int fits_parse_template(char *template, char *card, int *keytype, int *status)
</pre><p><span style="font-family:monospace">fits_parse_value</span> parses the input 80-chararacter header keyword record, returning
the value (as a literal character string) and comment strings. If the
keyword has no value (columns 9-10 not equal to ’= ’), then a null
value string is returned and the comment string is set equal to column
9 - 80 of the input string.</p><p><span style="font-family:monospace">fits_get_keytype</span> parses the keyword value string to determine its
datatype. <span style="font-family:monospace">dtype</span> returns with a value of ’C’, ’L’, ’I’, ’F’ or
’X’, for character string, logical, integer, floating point, or
complex, respectively.</p><p><span style="font-family:monospace">fits_get_keyclass</span> returns a classification code that indicates
the classification type of the input keyword record (e.g., a required
structural keyword, a TDIM keyword, a WCS keyword, a comment keyword,
etc. See the CFITSIO Reference Guide for a list of the different
classification codes.</p><p><span style="font-family:monospace">fits_parse_template</span> takes an input free format keyword template
string and returns a formatted 80*char record that satisfies all the
FITS requirements for a header keyword record. The template should
generally contain 3 tokens: the keyword name, the keyword value, and
the keyword comment string. The returned <span style="font-family:monospace">keytype</span> parameter
indicates whether the keyword is a COMMENT keyword or not. See the
CFITSIO Reference Guide for more details.</p>
<hr>
<a href="quick004.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="quick006.html"><img src="next_motif.gif" alt="Next"></a>
</body>
</html>
|