~ubuntu-branches/debian/stretch/cfitsio/stretch : revision 1

1

\documentclass[11pt]{article}

2

\input{html.sty}

3

\htmladdtonavigation

4

{\begin{rawhtml}

5

<A HREF="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html">FITSIO Home</A>

6

\end{rawhtml}}

7

8

\oddsidemargin=0.20in

9

\evensidemargin=0.20in

10

\textwidth=15.5truecm

11

\textheight=21.5truecm

12

13

\title{CFITSIO Quick Start Guide}

14

\author{William Pence \thanks{HEASARC, NASA Goddard Space Flight Center,

15

{\it pence@tetra.gsfc.nasa.gov}}}

16

17

\date{January 2002}

18

19

\begin{document}

20

21

\maketitle

22

\tableofcontents

23

24

% ===================================================================

25

\section{Introduction}

26

27

This document is intended to help you quickly start writing C programs

28

to read and write FITS files using the CFITSIO library. It covers the

29

most important CFITSIO routines that are needed to perform most types

30

of operations on FITS files. For more complete information about these

31

and all the other available routines in the library please refer to

32

the ``CFITSIO User's Reference Guide'', which is available from the

33

CFITSIO Web site at {\tt http://heasarc.gsfc.nasa.gov/fitsio}.

34

35

For more general information about the FITS data format, refer to the

36

following web page:

37

http://heasarc.gsfc.nasa.gov/docs/heasarc/fits.html

38

% ===================================================================

39

\section{A FITS Format Primer}

40

41

FITS stands for Flexible Image Transport System and is the standard

42

file format used to store most astronomical data files. There are 2

43

basic types of FITS files: images and tables. FITS images often

44

contain a 2-dimensional array of pixels representing an image of a

45

piece of the sky, but FITS images can also contain 1-D arrays (i.e,

46

a spectrum or light curve), or 3-D arrays (a data cube), or

47

even higher dimensional arrays of data. An image may also have zero

48

dimensions, in which case it is referred to as a null or empty array.

49

The supported datatypes for the image arrays are 8, 16, and 32-bit

50

integers, and 32 and 64-bit floating point real numbers. Both signed

51

and unsigned integers are supported.

52

53

FITS tables contain rows and columns of data, similar to a

54

spreadsheet. All the values in a particular column must have the same

55

datatype. A cell of a column is not restricted to a single number, and

56

instead can contain an array or vector of numbers. There are actually

57

2 subtypes of FITS tables: ASCII and binary. As the names imply, ASCII

58

tables store the data values in an ASCII representation whereas binary

59

tables store the data values in a more efficient machine-readable

60

binary format. Binary tables are generally more compact and support

61

more features (e.g., a wider range of datatypes, and vector columns)

62

than ASCII tables.

63

64

A single FITS file many contain multiple images or tables. Each table

65

or image is called a Header-Data Unit, or HDU. The first HDU in a FITS

66

file must be an image (but it may have zero axes) and is called the

67

Primary Array. Any additional HDUs in the file (which are also

68

referred to as `extensions') may contain either an image or a table.

69

70

Every HDU contains a header containing keyword records. Each keyword

71

record is 80 ASCII characters long and has the following format:

72

73

\begin{verbatim}

74

KEYWORD = value / comment string

75

\end{verbatim}

76

77

The keyword name can be up to 8 characters long (all uppercase). The

78

value can be either an integer or floating point number, a logical

79

value (T or F), or a character string enclosed in single quotes. Each

80

header begins with a series of required keywords to describe the

81

datatype and format of the following data unit, if any. Any number of

82

other optional keywords can be included in the header to provide other

83

descriptive information about the data. For the most part, the CFITSIO

84

routines automatically write the required FITS keywords for each HDU,

85

so you, the programmer, usually do not need to worry about them.

86

87

% ===================================================================

88

\section{Installing and Using CFITSIO}

89

90

First, you should download the CFITSIO software and the set of example

91

FITS utility programs from the web site at

92

http://heasarc.gsfc.nasa.gov/fitsio. The example programs illustrate

93

how to perform many common types of operations on FITS files using

94

CFITSIO. They are also useful when writing a new program because it is

95

often easier to take a copy of one of these utility programs as a

96

template and then modify it for your own purposes, rather than writing

97

the new program completely from scratch.

98

99

To build the CFITSIO library on Unix platforms, `untar' the source code

100

distribution file and then execute the following 2 commands in the

101

directory containing the source code:

102

103

\begin{verbatim}

104

> ./configure

105

> make

106

\end{verbatim}

107

108

Pre-compiled versions of the CFITSIO DLL library are available for

109

PCs. On Macintosh machines, refer to the README.MacOS file for

110

instructions on building CFITSIO using CodeWarrior.

111

112

Any programs that use CFITSIO must of course be linked with the CFITSIO

113

library when creating the executable file. The exact procedure for

114

linking a program depends on your software environment, but on Unix

115

platforms, the command line to compile and link a program will look

116

something like this:

117

118

\begin{verbatim}

119

gcc -o myprog myprog.c -L. -lcfitsio -lm -lnsl -lsocket

120

\end{verbatim}

121

122

You may not need to include all of the 'm', 'nsl', and 'socket' system

123

libraries on your particular machine. To find out what libraries are

124

required on your (Unix) system, type {\tt'make testprog'} and see what

125

libraries are then included on the resulting link line.

126

127

\newpage

128

% ===================================================================

129

\section{Example Programs}

130

131

Before describing the individual CFITSIO routines in detail, it is

132

instructive to first look at an actual program. The names of the

133

CFITSIO routines are fairly descriptive (they all begin with {\tt

134

fits\_}, so it should be reasonably clear what this program does:

135

136

\begin{verbatim}

137

----------------------------------------------------------------

138

#include <string.h>

139

#include <stdio.h>

140

#include "fitsio.h"

141

142

int main(int argc, char *argv[])

143

{

144

fitsfile *fptr;

145

char card[FLEN_CARD];

146

int nkeys, ii, status = 0; /* MUST initialize status */

147

148

fits_open_file(&fptr, argv[1], READONLY, &status);

149

150

fits_get_hdrspace(fptr, &nkeys, NULL, &status);

151

152

for (ii = 1; ii <= nkeys; ii++) {

153

fits_read_record(fptr, ii, card, &status); /* read keyword */

154

printf("%s\n", card);

155

}

156

printf("END\n\n"); /* terminate listing with END */

157

158

fits_close_file(fptr, &status);

159

160

if (status) /* print any error messages */

161

fits_report_error(stderr, status);

162

return(status);

163

}

164

----------------------------------------------------------------

165

\end{verbatim}

166

167

This program opens the specified FITS file and prints

168

out all the header keywords in the current HDU.

169

Some other points to notice about the program are:

170

\begin{itemize}

171

172

\item

173

The {\tt fitsio.h} header file must be included to define the

174

various routines and symbols used in CFITSIO.

175

176

\item

177

Almost every CFITSIO routine has a {\tt status} parameter as the last

178

argument. The status value is also usually returned as the value of the

179

function itself. Normally status = 0, and a positive status value

180

indicates an error of some sort. The status variable must always be

181

initialized to zero before use, because if status is greater than zero

182

on input then the CFITSIO routines will simply return without doing

183

anything. This `inherited status' feature, where each CFITSIO routine

184

inherits the status from the previous routine, makes it unnecessary to

185

check the status value after every single CFITSIO routine call.

186

Generally you should check the status after an especially important or

187

complicated routine has been called, or after a block of

188

closely related CFITSIO calls. This example program has taken this

189

feature to the extreme and only checks the status value at the

190

very end of the program.

191

192

\item

193

194

The {\tt fitsfile} parameter is the first argument in almost every

195

CFITSIO routine. It is a pointer to a structure (defined in {\tt

196

fitsio.h}) that stores information about the particular FITS file that

197

the routine will operate on. Memory for this structure is

198

automatically allocated when the file is first opened or created, and

199

is freed when the file is closed.

200

201

\item

202

203

In this example program the file name to be opened is given as an

204

argument on the command line ({\tt arg[1]}). If the file contains more

205

than 1 HDU or extension, you can specify which particular HDU to be

206

opened by enclosing the name or number of the HDU in square brackets

207

following the root name of the file. For example, {\tt file.fts[0]}

208

opens the primary array, while {\tt file.fts[2]} will move to and open

209

the 2nd extension in the file, and {\tt file.fit[EVENTS]} will open the

210

extension that has a {\tt EXTNAME = 'EVENTS'} keyword in the header.

211

Note that on the Unix command line you must enclose the file name in

212

single or double quote characters if the name contains special

213

characters such as `[' or `]'.

214

215

All of the CFITSIO routines which read or write header keywords,

216

image data, or table data operate only within the currently opened

217

HDU in the file. To read or write information in a different HDU you must

218

first explicitly move to that HDU (see the {\tt fits\_movabs\_hdu} and

219

{\tt fits\_movrel\_hdu} routines in section 5.3).

220

221

\item

222

223

The {\tt fits\_report\_error} routine provides a convenient way to print out

224

diagnostic messages about any error that may have occurred.

225

226

\end{itemize}

227

228

A set of example FITS utility programs are available from the CFITSIO

229

web site at \newline

230

http://heasarc.gsfc.nasa.gov/docs/software/fitsio/cexamples.html.

231

These are real working programs which illustrate how to read, write,

232

and modify FITS files using the CFITSIO library. Most of these

233

programs are very short, containing only a few 10s of lines of

234

executable code or less, yet they perform quite useful operations on

235

FITS files. Running each program without any command line arguments

236

will produce a short description of how to use the program.

237

The currently available programs are:

238

\begin{quote}

239

fitscopy - copy a file

240

\newline

241

listhead - list header keywords

242

\newline

243

liststruc - show the structure of a FITS file.

244

\newline

245

modhead - write or modify a header keyword

246

\newline

247

imarith - add, subtract, multiply, or divide 2 images

248

\newline

249

imlist - list pixel values in an image

250

\newline

251

imstat - compute mean, min, and max pixel values in an image

252

\newline

253

tablist - display the contents of a FITS table

254

\newline

255

tabcalc - general table calculator

256

\end{quote}

257

258

259

\newpage

260

261

% ===================================================================

262

\section{CFITSIO Routines}

263

264

This chapter describes the main CFITSIO routines that can be used to

265

perform most of the common types of operations on FITS files.

266

267

% ===================================================================

268

\subsection{Error Reporting}

269

270

\begin{verbatim}

271

void fits_report_error(FILE *stream, status)

272

\end{verbatim}

273

274

This routine prints out information about any error that

275

has occurred. Whenever any CFITSIO routine encounters an error it

276

usually writes a message describing the nature of the error to an

277

internal error message stack and then returns with a positive integer

278

status value. Passing the error status value to this routine will

279

cause a generic description of the error and all the messages

280

from the internal CFITSIO error stack to be printed to the specified

281

stream. The {\tt stream} parameter is usually set equal to

282

{\tt "stdout"} or {\tt "stderr"}.

283

284

% ===================================================================

285

\subsection{File-level I/O Routines}

286

287

\begin{verbatim}

288

int fits_open_file(fitsfile **fptr, char *filename, int mode, int *status)

289

int fits_create_file(fitsfile **fptr, char *filename, int *status)

290

int fits_close_file(fitsfile *fptr, int *status)

291

\end{verbatim}

292

293

These routines open or close a file. The first {\tt fitsfile}

294

parameter in these and nearly every other CFITSIO routine is a pointer

295

to a structure that CFITSIO uses to store relevant parameters about

296

each opened file. You should never directly read or write any

297

information in this structure. Memory for this structure is allocated

298

automatically when the file is opened or created,

299

and is freed when the file is closed.

300

301

The mode parameter in {\tt fits\_open\_file} can be set to either {\tt

302

READONLY} or {\tt READWRITE} to select the type of file access that

303

will be allowed. These symbolic constants are defined in {\tt

304

fitsio.h}.

305

306

In {\tt fits\_create\_file}, the {\tt filename} is simply the root name of

307

the file to be created. You can overwrite an existing file by

308

prefixing the name with a `!' character (on the Unix command line this

309

must be prefixed with a backslash, as in \verb+`\!file.fit'+). If the

310

filename is {\tt stdout} or {\tt "-"} (a single dash character)

311

then the output file will be piped to the stdout stream. You can

312

chain several tasks together by writing the output from the first task

313

to {\tt stdout} and then reading the input file in the 2nd task from

314

{\tt stdin}.

315

316

When opening an existing file with {\tt fits\_open\_file}, the {\tt filename}

317

can include optional arguments, enclosed in square brackets, giving the

318

name or index number of a particular HDU to be opened, and/or other

319

filtering operations that should be applied to the input file.

320

See section 6 for more examples of these powerful filtering capabilities.

321

Here are some examples:

322

323

\begin{verbatim}

324

myfile.fit[EVENTS] - opens the file then moves to the EVENTS extension.

325

myfile.fit[3] - opens the 3rd extension in the file

326

myfile.fit[3][counts > 0] - opens the table in the 3rd extension and creates

327

a virtual table by selects only those rows

328

where the COUNTS column value is greater than 0.

329

\end{verbatim}

330

331

332

% ===================================================================

333

\subsection{HDU-level I/O Routines:}

334

335

The routines listed in this section operate on Header-Data Units (HDUs) in a file.

336

337

\begin{verbatim}

338

_______________________________________________________________

339

int fits_get_num_hdus(fitsfile *fptr, int *hdunum, int *status)

340

int fits_get_hdu_num(fitsfile *fptr, int *hdunum)

341

\end{verbatim}

342

343

The first routines returns the total number of HDUs in the FITS file,

344

and the 2nd routine returns the position of the currently opened HDU in

345

the FITS file (starting with 1, not 0).

346

347

\begin{verbatim}

348

__________________________________________________________________________

349

int fits_movabs_hdu(fitsfile *fptr, int hdunum, int *hdutype, int *status)

350

int fits_movrel_hdu(fitsfile *fptr, int nmove, int *hdutype, int *status)

351

\end{verbatim}

352

353

These 2 routines enable you to move to a different HDU in the file.

354

Most of the CFITSIO functions which read or write keywords or data

355

operate only on the currently opened HDU in the file. The first

356

routine moves to the specified absolute HDU number in the FITS

357

file (the first HDU = 1), whereas the second routine moves a relative

358

number of HDUs forward or backward from the currently open HDU. The

359

{\tt hdutype} parameter returns the type of the newly opened HDU, and will

360

be equal to one of these symbolic constant values: {\tt IMAGE\_HDU,

361

ASCII\_TBL, or BINARY\_TBL}. {\tt hdutype} may be set to NULL

362

if it is not needed.

363

364

\begin{verbatim}

365

_________________________________________________________________

366

int fits_get_hdu_type(fitsfile *fptr, int *hdutype, int *status)

367

\end{verbatim}

368

369

Get the type of the current HDU in the FITS file: {\tt IMAGE\_HDU,

370

ASCII\_TBL, or BINARY\_TBL}.

371

372

\begin{verbatim}

373

____________________________________________________________________

374

int fits_copy_hdu(fitsfile *infptr, fitsfile *outfptr, int morekeys,

375

int *status)

376

\end{verbatim}

377

378

Copy the current HDU from the FITS file associated with infptr and

379

append it to the end of the FITS file associated with outfptr. Space

380

may be reserved for {\tt morekeys} additional keywords in the output

381

header.

382

383

\begin{verbatim}

384

_______________________________________________________________________

385

int fits_copy_header(fitsfile *infptr, fitsfile *outfptr, int *status)

386

\end{verbatim}

387

388

Copy all the header keywords from the current HDU associated with

389

infptr to the current HDU associated with outfptr. If the current

390

output HDU is not empty, then a new HDU will be appended to the output

391

file. The output HDU will then have the identical structure as the

392

input HDU, but will contain no data.

393

394

\newpage

395

% ===================================================================

396

\subsection{Image I/O Routines}

397

398

This section lists the more important CFITSIO routines which operate on

399

FITS images.

400

401

\begin{verbatim}

402

_______________________________________________________________

403

int fits_get_img_type(fitsfile *fptr, int *bitpix, int *status)

404

int fits_get_img_dim( fitsfile *fptr, int *naxis, int *status)

405

int fits_get_img_size(fitsfile *fptr, int maxdim, long *naxes,

406

int *status)

407

int fits_get_img_param(fitsfile *fptr, int maxdim, int *bitpix,

408

int *naxis, long *naxes, int *status)

409

\end{verbatim}

410

411

Get information about the currently opened image HDU. The first routine

412

returns the datatype of the image as (defined by the {\tt BITPIX}

413

keyword), which can have symbolic constant values of {\tt BYTE\_IMG

414

(8), SHORT\_IMG (16), LONG\_IMG (32), FLOAT\_IMG (-32), and DOUBLE\_IMG

415

(-64)}. The 2nd and 3rd routines return the number of dimensions in

416

the image (from the {\tt NAXIS} keyword), and the sizes of each

417

dimension (from the {\tt NAXIS1, NAXIS2}, etc. keywords). The last

418

routine simply combines the function of the first 3 routines. The

419

input {\tt maxdim} parameter gives the maximum number dimensions to be

420

returned.

421

422

\begin{verbatim}

423

__________________________________________________________

424

int fits_create_img(fitsfile *fptr, int bitpix, int naxis,

425

long *naxes, int *status)

426

\end{verbatim}

427

428

Create an image HDU by writing the required keywords which define the

429

structure of the image. The 2nd through 4th parameters specified the

430

datatype, the number of dimensions, and the sizes of the dimensions.

431

The allowed values of the {\tt bitpix} parameter are listed above in

432

the description of the {\tt fits\_get\_img\_type} routine. If the FITS

433

file pointed to by {\tt fptr} is empty (previously created with

434

{\tt fits\_create\_file}) then this routine creates a primary array in

435

the file, otherwise a new IMAGE extension is appended to end of the

436

file following the other HDUs in the file.

437

438

\begin{verbatim}

439

______________________________________________________________

440

int fits_write_pix(fitsfile *fptr, int datatype, long *fpixel,

441

long nelements, void *array, int *status);

442

443

int fits_read_pix(fitsfile *fptr, int datatype, long *fpixel,

444

long nelements, void *nulval, void *array,

445

int *anynul, int *status)

446

\end{verbatim}

447

448

Read or write all or part of the FITS image. {\tt fpixel} is an array

449

which gives the coordinate in each dimension of the first pixel to be

450

read or written, and {\tt nelements} is the total number of pixels to

451

read or write. {\tt array} is the address of an array which either

452

contains the pixel values to be written, or will hold the values of the

453

pixels that are read. When reading, {\tt array} must have been

454

allocated large enough to hold all the returned pixel values. This

455

routine starts at the {\tt fpixel} location and then reads or writes

456

the {\tt nelements} pixels, continuing on successive rows of the image

457

if necessary. For example, to write an entire 2D image, set {\tt

458

fpixel[0] = fpixel[1] = 1}, and {\tt nelements = NAXIS1 * NAXIS2}. Or

459

to read just the 10th row of the image, set {\tt fpixel[0] = 1,

460

fpixel[1] = 10}, and {\tt nelements = NAXIS1}. The {\tt datatype}

461

parameter specifies the datatype of {\tt array}, which need not be the

462

same as the datatype of the FITS image itself. If the datatypes differ

463

then CFITSIO will convert the data as it is read or written. The

464

following symbolic constants are allowed for the value of {\tt

465

datatype: TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TULONG, TFLOAT,

466

and TDOUBLE}.

467

468

FITS images can in principle contain undefined pixels which have no

469

assigned value; CFITSIO will substitute the value given by {\tt

470

nulval} for any undefined pixels in the image, unless {\tt nulval =

471

NULL}, in which case no checks will be made for undefined pixels when

472

reading the FITS image. Note that {\tt nulval} gives the address of the

473

value, not the value itself.

474

475

\begin{verbatim}

476

_________________________________________________________________

477

int fits_write_subset(fitsfile *fptr, int datatype, long *fpixel,

478

long *lpixel, DTYPE *array, > int *status)

479

480

int fits_read_subset(fitsfile *fptr, int datatype, long *fpixel,

481

long *lpixel, long *inc, void *nulval, void *array,

482

int *anynul, int *status)

483

\end{verbatim}

484

485

Read or write a rectangular section of the FITS image. These are very

486

similar to {\tt fits\_write\_pix} and {\tt fits\_read\_pix} except that

487

you specify the last pixel coordinate (the upper right corner of the

488

section) instead of the number of pixels to be read. The read routine

489

also has an {\tt inc} parameter which can be used to read only every

490

{\tt inc-th} pixel along each dimension of the image. Normally {\tt

491

inc[0] = inc[1] = 1} to read every pixel in a 2D image. To read every

492

other pixel in the entire 2D image, set {\tt fpixel[0] = fpixel[1] = 1,

493

lpixel[0] = NAXIS1, lpixel[1] = NAXIS2}, and {\tt inc[0] = inc[1] =

494

2}. Or, to read the 8th row of a 2D image, set {\tt fpixel[0] = 1,

495

fpixel[1] = 8, lpixel[0] = NAXIS1, lpixel[1] = 8, and inc[0] = inc[1] =

496

1}.

497

498

\newpage

499

% ===================================================================

500

\subsection{Table I/O Routines}

501

502

This section lists the most important CFITSIO routines which operate on

503

FITS tables.

504

505

\begin{verbatim}

506

__________________________________________________________________________

507

int fits_create_tbl(fitsfile *fptr, int tbltype, long nrows, int tfields,

508

char *ttype[],char *tform[], char *tunit[], char *extname, int *status)

509

\end{verbatim}

510

511

Create a new table extension by writing the required keywords that

512

define the table structure. A dummy primary array containing no data

513

will be created first, if the file is initially completely empty. {\tt

514

tbltype} defines the type of table and can have values of {\tt

515

ASCII\_TBL or BINARY\_TBL}. Binary tables are generally preferred

516

because they are more efficient and support a greater range of column

517

datatypes than ASCII tables.

518

519

The {\tt nrows} parameter gives the initial number of empty rows to be

520

allocated for the table; this should normally be set to 0. The {\tt

521

ttype, tform}, and {\tt tunit} parameters give the name, datatype, and

522

physical units of each column, and {\tt extname} gives the name for the

523

table (the value of the {\tt EXTNAME} keyword). The {\tt

524

tunit} and {\tt extname} parameters may be set to NULL

525

if they are not needed. The FITS Standard recommends that only

526

letters, digits, and the underscore character be used in column names

527

with no embedded spaces. It is recommended that all the column names

528

in a given table be unique within the first 8 characters.

529

530

Note that it is often easier to create a new table by copying the

531

header from another existing table with {\tt fits\_copy\_header} rather

532

than calling this routine.

533

534

\begin{verbatim}

535

_______________________________________________________________

536

int fits_get_num_rows(fitsfile *fptr, long *nrows, int *status)

537

int fits_get_num_cols(fitsfile *fptr, int *ncols, int *status)

538

\end{verbatim}

539

540

Get the number of rows or columns in the current FITS table. The

541

number of rows is given by the {\tt NAXIS2} keyword and the number of columns

542

is given by the {\tt TFIELDS} keyword in the header of the table.

543

544

\begin{verbatim}

545

_______________________________________________________________

546

int fits_get_colnum(fitsfile *fptr, int casesen, char *colname,

547

int *colnum, int *status)

548

\end{verbatim}

549

550

Get the column number (starting with 1, not 0) of the column whose

551

name matches the specified column name. Normally, {\tt casesen} should

552

be set to {\tt CASEINSEN}, but it may be set to {\tt CASESEN} to force

553

the name matching to be case-sensitive.

554

555

The input {\tt colname} string gives the name of the desired column and

556

may include wildcard characters: a `*' matches any sequence of

557

characters (including zero characters), `?' matches any single

558

character, and `\#' matches any consecutive string of decimal digits

559

(0-9). If more than one column name in the table matches the template

560

string, then the first match is returned and the status value will be

561

set to {\tt COL\_NOT\_UNIQUE} as a warning that a unique match was not

562

found. To find the next column that matches the template, call this

563

routine again leaving the input status value equal to {\tt

564

COL\_NOT\_UNIQUE}. Repeat this process until {\tt status =

565

COL\_NOT\_FOUND} is returned.

566

567

\begin{verbatim}

568

_______________________________________________________________

569

int fits_get_coltype(fitsfile *fptr, int colnum, int *typecode,

570

long *repeat, long *width, int *status)

571

\end{verbatim}

572

573

Return the datatype, vector repeat count, and the width in bytes of a

574

single column element for column number {\tt colnum}. Allowed values

575

for the returned datatype in ASCII tables are: {\tt TSTRING, TSHORT,

576

TLONG, TFLOAT, and TDOUBLE}. Binary tables support these additional

577

types: {\tt TLOGICAL, TBIT, TBYTE, TCOMPLEX and TDBLCOMPLEX}. The

578

negative of the datatype code value is returned if it is a variable

579

length array column. The repeat count is always 1 in ASCII tables.

580

581

\begin{verbatim}

582

____________________________________________________________________________

583

int fits_insert_rows(fitsfile *fptr, long firstrow, long nrows, int *status)

584

int fits_delete_rows(fitsfile *fptr, long firstrow, long nrows, int *status)

585

\end{verbatim}

586

587

Insert or delete rows in a table.

588

The blank rows are

589

inserted immediately following row {\tt frow}. Set {\tt frow} = 0 to

590

insert rows at the beginning of the table. The rows

591

are deleted beginning with row {\tt frow}. These routines update the

592

value of the {\tt NAXIS2} keyword to reflect the new number of rows in

593

the table.

594

595

\begin{verbatim}

596

_________________________________________________________________________

597

int fits_insert_col(fitsfile *fptr, int colnum, char *ttype, char *tform,

598

int *status)

599

int fits_delete_col(fitsfile *fptr, int colnum, int *status)

600

\end{verbatim}

601

602

Insert or delete a column in a table. {\tt colnum} gives the position of the

603

column to be inserted or deleted (where the first column of the table is

604

at position 1).

605

606

\begin{verbatim}

607

____________________________________________________________________

608

int fits_copy_col(fitsfile *infptr, fitsfile *outfptr, int incolnum,

609

int outcolnum, int create_col, int *status);

610

\end{verbatim}

611

612

Copy a column from one table HDU to another. If {\tt create\_col} = TRUE,

613

then a new column will be inserted in the output table at position

614

{\tt outcolumn}, otherwise the values in the existing output column will be

615

overwritten.

616

617

\begin{verbatim}

618

__________________________________________________________________________

619

int fits_read_col(fitsfile *fptr, int datatype, int colnum, long firstrow,

620

long firstelem, long nelements, void *nulval, void *array,

621

int *anynul, int *status)

622

int fits_write_col(fitsfile *fptr, int datatype, int colnum, long firstrow,

623

long firstelem, long nelements, void *array, int *status)

624

\end{verbatim}

625

626

Read or write elements in column number {\tt colnum}, starting with row

627

{\tt firstsrow} and element {\tt firstelem} (if it is a vector

628

column). {\tt firstelem} is ignored if it is a scalar column. The {\tt

629

nelements} number of elements are read or written in successive rows of

630

the table. {\tt array} is the address of an array which either

631

contains the values to be written, or will hold the returned values

632

that are read. When reading, {\tt array} must have been allocated

633

large enough to hold all the returned values. {\tt datatype} specifies

634

the datatype of {\tt array}, which need not be the same as the

635

intrinsic datatype of the column in the FITS table. The following

636

symbolic constants are allowed for the value of {\tt datatype:

637

TSTRING, TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TULONG, TFLOAT,

638

and TDOUBLE}. Note that {\tt TSTRING} corresponds to the C {\tt

639

char**} datatype, i.e., a pointer to an array of pointers to an array

640

of characters.

641

642

FITS tables can in principle contain undefined elements which have no

643

assigned value. CFITSIO will substitute the value given by the {\tt

644

nulval} parameter for any undefined elements in the column, unless

645

{\tt nulval = NULL}, in which case no checks will be made for undefined

646

values. Note that {\tt nulval} gives the address of the value, not the

647

value itself.

648

649

Any column, regardless of it's intrinsic datatype, may be read as a

650

{\tt TSTRING} character string. The display format of the returned

651

strings will be determined by the {\tt TDISPn} keyword, if it exists,

652

otherwise a default format will be used depending on the datatype of

653

the column. The {\tt tablist} example utility program (available from

654

the CFITSIO web site) uses this feature to display all the values in a

655

FITS table.

656

657

\begin{verbatim}

658

_____________________________________________________________________

659

int fits_select_rows(fitsfile *infptr, fitsfile *outfptr, char *expr,

660

int *status)

661

int fits_calculator(fitsfile *infptr, char *expr, fitsfile *outfptr,

662

char *colname, char *tform, int *status)

663

\end{verbatim}

664

665

These are 2 of the most powerful routines in the CFITSIO library. They

666

can perform complicated transformations on tables based on an input

667

arithmetic expression which is evaluated for each row of the table.

668

The first routine will select or copy rows of the table for which the

669

expression evaluates to TRUE ($ \neq 0$). The second routine writes

670

the value of the expression to a column in the output table. The

671

arithmetic expression may be a function of any column or keyword in the

672

input table as shown in these examples:

673

674

\begin{verbatim}

675

Row Selection Expressions:

676

counts > 0 uses COUNTS column value

677

sqrt( X**2 + Y**2) < 10. uses X and Y column values

678

(X > 10) || (X < -10) && (Y == 0) used 'or' and 'and' operators

679

gtifilter() filter on Good Time Intervals

680

regfilter("myregion.reg") filter using a region file

681

@select.txt reads expression from a text file

682

Calculator Expressions:

683

#row % 10 modulus of the row number

684

counts/#exposure Fn of COUNTS column and EXPOSURE keyword

685

dec < 85 ? cos(dec * #deg) : 0 Conditional expression: evaluates to

686

cos(dec) if dec < 85, else 0

687

(count{-1}+count+count{+1})/3. running mean of the count values in the

688

previous, current, and next rows

689

max(0, min(X, 1000)) returns a value between 0 - 1000

690

@calc.txt reads expression from a text file

691

\end{verbatim}

692

693

Most standard mathematical operators and functions are supported. If

694

the expression includes the name of a column, than the value in the

695

current row of the table will be used when evaluating the expression on

696

each row. An offset to an adjacent row can be specified by including

697

the offset value in curly brackets after the column name as shown in

698

one of the examples. Keyword values can be included in the expression

699

by preceding the keyword name with a `\#' sign. See Section 6 of this

700

document for more discussion of the expression syntax.

701

702

{\tt gtifilter} is a special function which tests whether the {\tt

703

TIME} column value in the input table falls within one or more Good

704

Time Intervals. By default, this function looks for a 'GTI' extension

705

in the same file as the input table. The 'GTI' table contains {\tt START} and {\tt STOP} columns which define the range of

706

each good time interval. See section 6.3.3 for more details.

707

708

{\tt regfilter} is another special function which selects rows based on

709

whether the spatial position associated with each row is located within

710

in a specified region of the sky. By default, the {\tt X} and {\tt Y}

711

columns in the input table are assumed to give the position of each row.

712

The spatial region is defined in an ASCII text file whose name is given

713

as the argument to the {\tt regfilter} function. See section 6.3.4 for

714

more details.

715

716

The {\tt infptr} and {\tt outfptr} parameters in these routines may

717

point to the same table or to different tables. In {\tt

718

fits\_select\_rows}, if the input and output tables are the same then

719

the rows that do not satisfy the selection expression will be deleted

720

from the table. Otherwise, if the output table is different from the

721

input table then the selected rows will be copied from the input table

722

to the output table.

723

724

The output column in {\tt fits\_calculator} may or may not already

725

exist. If it exists then the calculated values will be written to that

726

column, overwriting the existing values. If the column doesn't exist

727

then the new column will be appended to the output table. The {\tt tform}

728

parameter can be used to specify the datatype of the new column (e.g.,

729

the {\tt TFORM} keyword value as in {\tt '1E', or '1J'}). If {\tt

730

tform} = NULL then a default datatype will be used, depending on the

731

expression.

732

733

\begin{verbatim}

734

_____________________________________________________________________

735

int fits_read_tblbytes(fitsfile *fptr, long firstrow, long firstchar,

736

long nchars, unsigned char *array, int *status)

737

int fits_write_tblbytes (fitsfile *fptr, long firstrow, long firstchar,

738

long nchars, unsigned char *array, int *status)

739

\end{verbatim}

740

741

These 2 routines provide low-level access to tables and are mainly

742

useful as an efficient way to copy rows of a table from one file to

743

another. These routines simply read or write the specified number of

744

consecutive characters (bytes) in a table, without regard for column

745

boundaries. For example, to read or write the first row of a table,

746

set {\tt firstrow = 1, firstchar = 1}, and {\tt nchars = NAXIS1} where

747

the length of a row is given by the value of the {\tt NAXIS1} header

748

keyword. When reading a table, {\tt array} must have been declared at

749

least {\tt nchars} bytes long to hold the returned string of bytes.

750

751

\newpage

752

% ===================================================================

753

\subsection{Header Keyword I/O Routines}

754

\nopagebreak

755

The following routines read and write header keywords in the current HDU.

756

\nopagebreak

757

758

\begin{verbatim}

759

____________________________________________________________________

760

int fits_get_hdrspace(fitsfile *fptr, int *keysexist, int *morekeys,

761

int *status)

762

\end{verbatim}

763

\nopagebreak

764

Return the number of existing keywords (not counting the mandatory END

765

keyword) and the amount of empty space currently available for more

766

keywords. The {\tt morekeys} parameter may be set to NULL if it's value is

767

not needed.

768

769

\begin{verbatim}

770

___________________________________________________________________________

771

int fits_read_record(fitsfile *fptr, int keynum, char *record, int *status)

772

int fits_read_card(fitsfile *fptr, char *keyname, char *record, int *status)

773

int fits_read_key(fitsfile *fptr, int datatype, char *keyname,

774

void *value, char *comment, int *status)

775

\end{verbatim}

776

777

These routines all read a header record in the current HDU. The

778

first routine reads keyword number {\tt keynum} (where the first

779

keyword is at position 1). This routine is most commonly used when

780

sequentially reading every record in the header from beginning to end.

781

782

The 2nd and 3rd routines read the named keyword and return either the

783

whole record, or the keyword value and comment string. Wild card

784

characters may be used when specifying the name of the keyword. The

785

{\tt datatype} parameter specifies the datatype of the returned keyword

786

value and can have one of the following symbolic constant values: {\tt

787

TSTRING, TLOGICAL} (== int), {\tt TBYTE, TSHORT, TUSHORT, TINT, TUINT,

788

TLONG, TULONG, TFLOAT}, {\tt TDOUBLE, TCOMPLEX}, and {\tt

789

TDBLCOMPLEX}. Data type conversion will be performed for numeric

790

values if the intrinsic FITS keyword value does not have the same

791

datatype. The {\tt comment} parameter may be set equal to NULL if the

792

comment string is not needed.

793

794

\begin{verbatim}

795

_______________________________________________________________

796

int fits_write_key(fitsfile *fptr, int datatype, char *keyname,

797

void *value, char *comment, int *status)

798

int fits_update_key(fitsfile *fptr, int datatype, char *keyname,

799

void *value, char *comment, int *status)

800

int fits_write_record(fitsfile *fptr, char *card, int *status)

801

\end{verbatim}

802

803

Write a keyword into the header of the current HDU. The first routine

804

appends the new keyword to the end of the header, whereas the second

805

routine will update the value and comment fields of the keyword if it

806

already exists, otherwise it behaves like the first routine and appends

807

the new keyword. Note that {\tt value} gives the address to the value

808

and not the value itself. The {\tt datatype} parameter specifies the

809

datatype of the keyword value and may have any of the values listed in

810

the description of the keyword reading routines, above. A NULL may be

811

entered for the comment parameter, in which case the keyword comment

812

field will be unmodified or left blank.

813

814

The third routine is more primitive and simply writes the 80-character

815

{\tt card} record to the header. It is the programmer's responsibility

816

in this case to ensure that the record conforms to all the FITS format

817

requirements for a header record.

818

819

\begin{verbatim}

820

___________________________________________________________________

821

int fits_write_comment(fitsfile *fptr, char *comment, int *status)

822

int fits_write_history(fitsfile *fptr, char *history, int *status)

823

int fits_write_date(fitsfile *fptr, int *status)

824

\end{verbatim}

825

826

Write a {\tt COMMENT, HISTORY}, or {\tt DATE} keyword to the current

827

header. The {\tt COMMENT} keyword is typically used to write a comment

828

about the file or the data. The {\tt HISTORY} keyword is typically

829

used to provide information about the history of the processing

830

procedures that have been applied to the data. The {\tt comment} or

831

{\tt history} string will be continued over multiple keywords if it is

832

more than 70 characters long.

833

834

The {\tt DATE} keyword is used to record the date and time that the

835

FITS file was created. Note that this file creation date is usually

836

different from the date of the observation which obtained the data in

837

the FITS file. The {\tt DATE} keyword value is a character string in

838

'yyyy-mm-ddThh:mm:ss' format. If a {\tt DATE} keyword already exists in

839

the header, then this routine will update the value with the current

840

system date.

841

842

\begin{verbatim}

843

___________________________________________________________________

844

int fits_delete_record(fitsfile *fptr, int keynum, int *status)

845

int fits_delete_key(fitsfile *fptr, char *keyname, int *status)

846

\end{verbatim}

847

848

Delete a keyword record. The first routine deletes a keyword at a

849

specified position (the first keyword is at position 1, not 0),

850

whereas the second routine deletes the named keyword.

851

852

\newpage

853

\section{CFITSIO File Names and Filters}

854

855

\subsection{Creating New Files}

856

857

When creating a new output file on magnetic disk with {\tt

858

fits\_create\_file}, if the filename is preceded by an exclamation

859

point (!) then if that file already exists it will be deleted prior to

860

creating the new FITS file. Otherwise if there is an existing file

861

with the same name, CFITSIO will not overwrite the existing file and

862

will return an error status code. Note that the exclamation point is

863

a special UNIX character, so if it is used on the command line rather

864

than entered at a task prompt, it must be preceded by a backslash to

865

force the UNIX shell to pass it verbatim to the application program.

866

867

If the output disk file name ends with the suffix '.gz', then CFITSIO

868

will compress the file using the gzip compression algorithm before

869

writing it to disk. This can reduce the amount of disk space used by

870

the file. Note that this feature requires that the uncompressed file

871

be constructed in memory before it is compressed and written to disk,

872

so it can fail if there is insufficient available memory.

873

874

One can also specify that any images written to the output file should

875

be compressed using the newly developed `tile-compression' algorithm by

876

appending `[compress]' to the name of the disk file (as in

877

`myfile.fits[compress]'). Refer to the CFITSIO User's Reference Guide

878

for more information about this new image compression format.

879

880

\subsection{Opening Existing Files}

881

882

When opening a file with {\tt fits\_open\_file}, CFITSIO can read a

883

variety of different input file formats and is not restricted to only

884

reading FITS format files from magnetic disk. The following types of

885

input files are all supported:

886

887

\begin{itemize}

888

\item FITS files compressed with {\tt zip, gzip} or {\tt compress}

889

890

If CFITSIO cannot find the specified file to open it will automatically

891

look for a file with the same rootname but with a {\tt .zip, .gz}, or

892

{\tt .Z} extension. If it finds such a compressed file, it will

893

allocate a block of memory and uncompress the file into that memory

894

space. The application program will then transparently open this

895

virtual FITS file in memory.

896

897

\item FITS files on the internet, using {\tt ftp} or {\tt http}

898

899

Simply provide the full URL as the name of the file that you want to open. For example,\linebreak

900

{\tt ftp://legacy.gsfc.nasa.gov/software/fitsio/c/testprog.std}\linebreak

901

will open the CFITSIO test FITS file that is located on the {\tt legacy} machine.

902

903

\item FITS files on {\tt stdin} or {\tt stdout} file streams

904

905

If the name of the file to be opened is {\tt 'stdin'} or {\tt '-'} (a

906

single dash character) then CFITSIO will read the file from the

907

standard input stream. Similarly, if the output file name is {\tt

908

'stdout'} or {\tt '-'}, then the file will be written to the standard

909

output stream. This mechanism can be used to pipe FITS files from one task

910

to another without having to write an intermediary FITS file on magnetic disk.

911

912

\item FITS files that exist only in memory, or shared memory.

913

914

In some applications, such as real time data acquisition, you may want

915

to have one process write a FITS file into a certain section of

916

computer memory, and then be able to open that file in memory with

917

another process. There is a specialized CFITSIO open routine called

918

{\tt fits\_open\_memfile} that can be used for this purpose. See the

919

``CFITSIO User's Reference Guide'' for more details.

920

921

\item IRAF format images (with {\tt .imh} file extensions)

922

923

CFITSIO supports reading IRAF format images by converting them on the

924

fly into FITS images in memory. The application program then reads

925

this virtual FITS format image in memory. There is currently no

926

support for writing IRAF format images, or for reading or writing IRAF

927

tables.

928

929

\item Image arrays in raw binary format

930

931

If the input file is a raw binary data array, then CFITSIO will convert

932

it on the fly into a virtual FITS image with the basic set of required

933

header keywords before it is opened by the application program. In

934

this case the data type and dimensions of the image must be specified

935

in square brackets following the filename (e.g. {\tt

936

rawfile.dat[ib512,512]}). The first character inside the brackets

937

defines the datatype of the array:

938

939

\begin{verbatim}

940

b 8-bit unsigned byte

941

i 16-bit signed integer

942

u 16-bit unsigned integer

943

j 32-bit signed integer

944

r or f 32-bit floating point

945

d 64-bit floating point

946

\end{verbatim}

947

An optional second character specifies the byte order of the array

948

values: b or B indicates big endian (as in FITS files and the native

949

format of SUN UNIX workstations and Mac PCs) and l or L indicates

950

little endian (native format of DEC OSF workstations and IBM PCs). If

951

this character is omitted then the array is assumed to have the native

952

byte order of the local machine. These datatype characters are then

953

followed by a series of one or more integer values separated by commas

954

which define the size of each dimension of the raw array. Arrays with

955

up to 5 dimensions are currently supported.

956

957

Finally, a byte offset to the position of the first pixel in the data

958

file may be specified by separating it with a ':' from the last

959

dimension value. If omitted, it is assumed that the offset = 0. This

960

parameter may be used to skip over any header information in the file

961

that precedes the binary data. Further examples:

962

963

\begin{verbatim}

964

raw.dat[b10000] 1-dimensional 10000 pixel byte array

965

raw.dat[rb400,400,12] 3-dimensional floating point big-endian array

966

img.fits[ib512,512:2880] reads the 512 x 512 short integer array in a

967

FITS file, skipping over the 2880 byte header

968

\end{verbatim}

969

970

\end{itemize}

971

\newpage

972

973

\subsection{Image Filtering}

974

975

\subsubsection{Extracting a subsection of an image}

976

977

When specifying the name of an image to be opened, you can select a

978

rectangular subsection of the image to be extracted and opened by the

979

application program. The application program then opens a virtual

980

image that only contains the pixels within the specified subsection.

981

To do this, specify the the range of pixels (start:end) along each axis

982

to be extracted from the original image enclosed in square brackets.

983

You can also specify an optional pixel increment (start:end:step) for

984

each axis of the input image. A pixel step = 1 will be assumed if it

985

is not specified. If the starting pixel is larger then the end pixel,

986

then the image will be flipped (producing a mirror image) along that

987

dimension. An asterisk, '*', may be used to specify the entire range

988

of an axis, and '-*' will flip the entire axis. In the following

989

examples, assume that {\tt myfile.fits} contains a 512 x 512 pixel 2D

990

image.

991

992

\begin{verbatim}

993

myfile.fits[201:210, 251:260] - opens a 10 x 10 pixel subimage.

994

995

myfile.fits[*, 512:257] - opens a 512 x 256 image consisting of

996

all the columns in the input image, but only rows 257

997

through 512. The image will be flipped along the Y axis

998

since the starting row is greater than the ending

999

row.

1000

1001

myfile.fits[*:2, 512:257:2] - creates a 256 x 128 pixel image.

1002

Similar to the previous example, but only every other row

1003

and column is read from the input image.

1004

1005

myfile.fits[-*, *] - creates an image containing all the rows and

1006

columns in the input image, but flips it along the X

1007

axis.

1008

\end{verbatim}

1009

1010

If the array to be opened is in an Image extension, and not in the

1011

primary array of the file, then you need to specify the extension

1012

name or number in square brackets before giving the subsection range,

1013

as in {\tt myfile.fits[1][-*, *]} to read the image in the

1014

first extension in the file.

1015

1016

\subsubsection{Create an Image by Binning Table Columns}

1017

1018

You can also create and open a virtual image by binning the values in a

1019

pair of columns of a FITS table (in other words, create a 2-D histogram

1020

of the values in the 2 columns). This technique is often used in X-ray

1021

astronomy where each detected X-ray photon during an observation is

1022

recorded in a FITS table. There are typically 2 columns in the table

1023

called {\tt X} and {\tt Y} which record the pixel location of that

1024

event in a virtual 2D image. To create an image from this table, one

1025

just scans the X and Y columns and counts up how many photons were

1026

recorded in each pixel of the image. When table binning is specified,

1027

CFITSIO creates a temporary FITS primary array in memory by computing

1028

the histogram of the values in the specified columns. After the

1029

histogram is computed the original FITS file containing the table is

1030

closed and the temporary FITS primary array is opened and passed to the

1031

application program. Thus, the application program never sees the

1032

original FITS table and only sees the image in the new temporary file

1033

(which has no extensions).

1034

1035

The table binning specifier is enclosed in square brackets following

1036

the root filename and table extension name or number and begins with

1037

the keyword 'bin', as in: \newline

1038

{\tt 'myfile.fits[events][bin (X,Y)]'}. In

1039

this case, the X and Y columns in the 'events' table extension are

1040

binned up to create the image. The size of the image is usually

1041

determined by the {\tt TLMINn} and {\tt TLMAXn} header keywords which

1042

give the minimum and maximum allowed pixel values in the columns. For

1043

instance if {\tt TLMINn = 1} and {\tt TLMAXn = 4096} for both columns, this would

1044

generate a 4096 x 4096 pixel image by default. This is rather large,

1045

so you can also specify a pixel binning factor to reduce the image

1046

size. For example specifying , {\tt '[bin (X,Y) = 16]'} will use a

1047

binning factor of 16, which will produce a 256 x 256 pixel image in the

1048

previous example.

1049

1050

If the TLMIN and TLMAX keywords don't exist, or you want to override

1051

their values, you can specify the image range and binning factor

1052

directly, as in {\tt '[bin X = 1:4096:16, Y=1:4096:16]'}. You can also

1053

specify the datatype of the created image by appending a b, i, j, r, or

1054

d (for 8-bit byte, 16-bit integers, 32-bit integer, 32-bit floating

1055

points, or 64-bit double precision floating point, respectively) to

1056

the 'bin' keyword (e.g. {\tt '[binr (X,Y)]'} creates a floating point

1057

image). If the datatype is not specified then a 32-bit integer image

1058

will be created by default.

1059

1060

If the column name is not specified, then CFITSIO will first try to use

1061

the 'preferred column' as specified by the CPREF keyword if it exists

1062

(e.g., 'CPREF = 'DETX,DETY'), otherwise column names 'X', 'Y' will be

1063

assumed for the 2 axes.

1064

1065

Note that this binning specifier is not restricted to only 2D images

1066

and can be used to create 1D, 3D, or 4D images as well. It is also

1067

possible to specify a weighting factor that is applied during the

1068

binning. Please refer to the ``CFITSIO User's Reference Guide'' for

1069

more details on these advanced features.

1070

\newpage

1071

1072

\subsection{Table Filtering}

1073

1074

\subsubsection{Column and Keyword Filtering}

1075

1076

The column or keyword filtering specifier is used to modify the

1077

column structure and/or the header keywords in the HDU that was

1078

selected with the previous HDU location specifier. It can

1079

be used to perform the following types of operations.

1080

1081

\begin{itemize}

1082

\item

1083

Append a new column to a table by giving the column name, optionally

1084

followed by the datatype in parentheses, followed by an equals sign and

1085

the arithmetic expression to be used to compute the value. The

1086

datatype is specified using the same syntax that is allowed for the

1087

value of the FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for

1088

binary tables, and 'I8', F12.3', 'E20.12', etc. for ASCII tables). If

1089

the datatype is not specified then a default datatype will be chosen

1090

depending on the expression.

1091

1092

\item

1093

Create a new header keyword by giving the keyword name, preceded by a

1094

pound sign '\#', followed by an equals sign and an arithmetic

1095

expression for the value of the keyword. The expression may be a

1096

function of other header keyword values. The comment string for the

1097

keyword may be specified in parentheses immediately following the

1098

keyword name.

1099

1100

\item

1101

Overwrite the values in an existing column or keyword by giving the

1102

name followed by an equals sign and an arithmetic expression.

1103

1104

\item

1105

Select a set of columns to be included in the filtered file by

1106

listing the column names separated with semi-colons. Any other

1107

columns in the input table will not appear in the filtered file.

1108

1109

\item

1110

Delete a column or keyword by listing the name preceded by a minus sign

1111

or an exclamation mark (!)

1112

1113

\item

1114

Rename an existing column or keyword with the syntax 'NewName ==

1115

OldName'.

1116

1117

\end{itemize}

1118

1119

The column filtering specifier is enclosed in square brackets and

1120

begins with the string 'col '. Multiple operations can be performed

1121

by separating them with semi-colons. For complex or commonly used

1122

operations, you can write the column filter to a text file, and then

1123

use it by giving the name of the text file, preceded by a '@'

1124

character.

1125

1126

Some examples:

1127

1128

\begin{verbatim}

1129

[col PI=PHA * 1.1 + 0.2] - creates new PI column from PHA values

1130

1131

[col rate = counts/exposure] - creates or overwrites the rate column by

1132

dividing the counts column by the

1133

EXPOSURE keyword value.

1134

1135

[col TIME; X; Y] - only the listed columns will appear

1136

in the filtered file

1137

1138

[col -TIME; Good == STATUS] - deletes the TIME column and

1139

renames the STATUS column to GOOD

1140

1141

[col @colfilt.txt] - uses the filtering expression in

1142

the colfilt.txt text file

1143

\end{verbatim}

1144

1145

The original file is not changed by this filtering operation, and

1146

instead the modifications are made on a temporary copy of the input

1147

FITS file (usually in memory), which includes a copy of all the other

1148

HDUs in the input file. The original input file is closed and the

1149

application program opens the filtered copy of the file.

1150

1151

\subsubsection{Row Filtering}

1152

1153

The row filter is used to select a subset of the rows from a table

1154

based on a boolean expression. A temporary new FITS file is created on

1155

the fly (usually in memory) which contains only those rows for which

1156

the row filter expression evaluates to true (i.e., not equal to zero).

1157

The primary array and any other extensions in the input file are also

1158

copied to the temporary file. The original FITS file is closed and the

1159

new temporary file is then opened by the application program.

1160

1161

The row filter expression is enclosed in square brackets following the

1162

file name and extension name. For example, {\tt

1163

'file.fits[events][GRADE==50]'} selects only those rows in the EVENTS

1164

table where the GRADE column value is equal to 50).

1165

1166

The row filtering expression can be an arbitrarily complex series of

1167

operations performed on constants, keyword values, and column data

1168

taken from the specified FITS TABLE extension. The expression

1169

also can be written into a text file and then used by giving the

1170

filename preceded by a '@' character, as in

1171

{\tt '[@rowfilt.txt]'}.

1172

1173

Keyword and column data are referenced by name. Any string of

1174

characters not surrounded by quotes (ie, a constant string) or

1175

followed by an open parentheses (ie, a function name) will be

1176

initially interpreted as a column name and its contents for the

1177

current row inserted into the expression. If no such column exists,

1178

a keyword of that name will be searched for and its value used, if

1179

found. To force the name to be interpreted as a keyword (in case

1180

there is both a column and keyword with the same name), precede the

1181

keyword name with a single pound sign, '\#', as in '\#NAXIS2'. Due to

1182

the generalities of FITS column and keyword names, if the column or

1183

keyword name contains a space or a character which might appear as

1184

an arithmetic term then inclose the name in '\$' characters as in

1185

\$MAX PHA\$ or \#\$MAX-PHA\$. The names are case insensitive.

1186

1187

To access a table entry in a row other than the current one, follow

1188

the column's name with a row offset within curly braces. For

1189

example, 'PHA{-3}' will evaluate to the value of column PHA, 3 rows

1190

above the row currently being processed. One cannot specify an

1191

absolute row number, only a relative offset. Rows that fall outside

1192

the table will be treated as undefined, or NULLs.

1193

1194

Boolean operators can be used in the expression in either their

1195

Fortran or C forms. The following boolean operators are available:

1196

1197

\begin{verbatim}

1198

"equal" .eq. .EQ. == "not equal" .ne. .NE. !=

1199

"less than" .lt. .LT. < "less than/equal" .le. .LE. <= =<

1200

"greater than" .gt. .GT. > "greater than/equal" .ge. .GE. >= =>

1201

"or" .or. .OR. || "and" .and. .AND. &&

1202

"negation" .not. .NOT. ! "approx. equal(1e-7)" ~

1203

\end{verbatim}

1204

1205

Note that the exclamation point, '!', is a special UNIX character, so

1206

if it is used on the command line rather than entered at a task

1207

prompt, it must be preceded by a backslash to force the UNIX shell to

1208

ignore it.

1209

1210

The expression may also include arithmetic operators and functions.

1211

Trigonometric functions use radians, not degrees. The following

1212

arithmetic operators and functions can be used in the expression

1213

(function names are case insensitive):

1214

1215

1216

\begin{verbatim}

1217

"addition" + "subtraction" -

1218

"multiplication" * "division" /

1219

"negation" - "exponentiation" ** ^

1220

"absolute value" abs(x) "cosine" cos(x)

1221

"sine" sin(x) "tangent" tan(x)

1222

"arc cosine" arccos(x) "arc sine" arcsin(x)

1223

"arc tangent" arctan(x) "arc tangent" arctan2(x,y)

1224

"exponential" exp(x) "square root" sqrt(x)

1225

"natural log" log(x) "common log" log10(x)

1226

"modulus" i % j "random # [0.0,1.0)" random()

1227

"minimum" min(x,y) "maximum" max(x,y)

1228

"if-then-else" b?x:y

1229

\end{verbatim}

1230

1231

1232

There is also a function for testing if two values are close to

1233

each other, i.e., if they are "near" each other to within a user

1234

specified tolerance. The arguments, value\_1 and value\_2 can be

1235

integer or real and represent the two values who's proximity is

1236

being tested to be within the specified tolerance, also an integer

1237

or real:

1238

1239

\begin{verbatim}

1240

near(value_1, value_2, tolerance)

1241

\end{verbatim}

1242

1243

When a NULL, or undefined, value is encountered in the FITS table,

1244

the expression will evaluate to NULL unless the undefined value is

1245

not actually required for evaluation, e.g. "TRUE .or. NULL"

1246

evaluates to TRUE. The following two functions allow some NULL

1247

detection and handling: ISNULL(x) and DEFNULL(x,y). The former

1248

returns a boolean value of TRUE if the argument x is NULL. The

1249

later "defines" a value to be substituted for NULL values; it

1250

returns the value of x if x is not NULL, otherwise it returns the

1251

value of y.

1252

1253

The following type casting operators are available, where the

1254

inclosing parentheses are required and taken from the C language

1255

usage. Also, the integer to real casts values to double precision:

1256

1257

\begin{verbatim}

1258

"real to integer" (int) x (INT) x

1259

"integer to real" (float) i (FLOAT) i

1260

\end{verbatim}

1261

1262

Bit masks can be used to select out rows from bit columns ({\tt TFORMn =

1263

\#X}) in FITS files. To represent the mask, binary, octal, and hex

1264

formats are allowed:

1265

1266

\begin{verbatim}

1267

binary: b0110xx1010000101xxxx0001

1268

octal: o720x1 -> (b111010000xxx001)

1269

hex: h0FxD -> (b00001111xxxx1101)

1270

\end{verbatim}

1271

1272

In all the representations, an x or X is allowed in the mask as a

1273

wild card. Note that the x represents a different number of wild

1274

card bits in each representation. All representations are case

1275

insensitive.

1276

1277

To construct the boolean expression using the mask as the boolean

1278

equal operator described above on a bit table column. For example,

1279

if you had a 7 bit column named flags in a FITS table and wanted

1280

all rows having the bit pattern 0010011, the selection expression

1281

would be:

1282

1283

1284

\begin{verbatim}

1285

flags == b0010011

1286

or

1287

flags .eq. b10011

1288

\end{verbatim}

1289

1290

It is also possible to test if a range of bits is less than, less

1291

than equal, greater than and greater than equal to a particular

1292

boolean value:

1293

1294

1295

\begin{verbatim}

1296

flags <= bxxx010xx

1297

flags .gt. bxxx100xx

1298

flags .le. b1xxxxxxx

1299

\end{verbatim}

1300

1301

Notice the use of the x bit value to limit the range of bits being

1302

compared.

1303

1304

It is not necessary to specify the leading (most significant) zero

1305

(0) bits in the mask, as shown in the second expression above.

1306

1307

Bit wise AND, OR and NOT operations are also possible on two or

1308

more bit fields using the '\&'(AND), '$|$'(OR), and the '!'(NOT)

1309

operators. All of these operators result in a bit field which can

1310

then be used with the equal operator. For example:

1311

1312

1313

\begin{verbatim}

1314

(!flags) == b1101100

1315

(flags & b1000001) == bx000001

1316

\end{verbatim}

1317

1318

Bit fields can be appended as well using the '+' operator. Strings

1319

can be concatenated this way, too.

1320

1321

In addition, several constants are built in for use in numerical

1322

expressions:

1323

1324

1325

\begin{verbatim}

1326

#pi 3.1415... #e 2.7182...

1327

#deg #pi/180 #row current row number

1328

#null undefined value #snull undefined string

1329

\end{verbatim}

1330

1331

A string constant must be enclosed in quotes as in 'Crab'. The

1332

"null" constants are useful for conditionally setting table values to

1333

a NULL, or undefined, value (For example, {\tt "col1==-99 ? \#NULL :

1334

col1"}).

1335

1336

\subsubsection{Good Time Interval Filtering}

1337

1338

A common filtering method involves selecting rows which have a time

1339

value which lies within what is called a Good Time Interval or GTI.

1340

The time intervals are defined in a separate FITS table extension

1341

which contains 2 columns giving the start and stop time of each

1342

good interval. The filtering operation accepts only those rows of

1343

the input table which have an associated time which falls within

1344

one of the time intervals defined in the GTI extension. A high

1345

level function, gtifilter(a,b,c,d), is available which evaluates

1346

each row of the input table and returns TRUE or FALSE depending

1347

whether the row is inside or outside the good time interval. The

1348

syntax is

1349

1350

\begin{verbatim}

1351

gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] )

1352

\end{verbatim}

1353

where each "[]" demarks optional parameters. Note that the quotes

1354

around the gtifile and START/STOP column are required. The gtifile,

1355

if specified, can be blank ("") which will mean to use the first

1356

extension with the name "*GTI*" in the current file, a plain

1357

extension specifier (eg, "+2", "[2]", or "[STDGTI]") which will be

1358

used to select an extension in the current file, or a regular

1359

filename with or without an extension specifier which in the latter

1360

case will mean to use the first extension with an extension name

1361

"*GTI*". Expr can be any arithmetic expression, including simply

1362

the time column name. A vector time expression will produce a

1363

vector boolean result. STARTCOL and STOPCOL are the names of the

1364

START/STOP columns in the GTI extension. If one of them is

1365

specified, they both must be.

1366

1367

In its simplest form, no parameters need to be provided -- default

1368

values will be used. The expression {\tt "gtifilter()"} is equivalent to

1369

1370

\begin{verbatim}

1371

gtifilter( "", TIME, "*START*", "*STOP*" )

1372

\end{verbatim}

1373

This will search the current file for a GTI extension, filter the

1374

TIME column in the current table, using START/STOP times taken from

1375

columns in the GTI extension with names containing the strings

1376

"START" and "STOP". The wildcards ('*') allow slight variations in

1377

naming conventions such as "TSTART" or "STARTTIME". The same

1378

default values apply for unspecified parameters when the first one

1379

or two parameters are specified. The function automatically

1380

searches for TIMEZERO/I/F keywords in the current and GTI

1381

extensions, applying a relative time offset, if necessary.

1382

1383

\subsubsection{Spatial Region Filtering}

1384

1385

Another common filtering method selects rows based on whether the

1386

spatial position associated with each row is located within a given

1387

2-dimensional region. The syntax for this high-level filter is

1388

1389

\begin{verbatim}

1390

regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] )

1391

\end{verbatim}

1392

where each "[ ]" demarks optional parameters. The region file name

1393

is required and must be enclosed in quotes. The remaining

1394

parameters are optional. The region file is an ASCII text file

1395

which contains a list of one or more geometric shapes (circle,

1396

ellipse, box, etc.) which defines a region on the celestial sphere

1397

or an area within a particular 2D image. The region file is

1398

typically generated using an image display program such as fv/POW

1399

(distribute by the HEASARC), or ds9 (distributed by the Smithsonian

1400

Astrophysical Observatory). Users should refer to the documentation

1401

provided with these programs for more details on the syntax used in

1402

the region files.

1403

1404

In its simpliest form, (e.g., {\tt regfilter("region.reg")} ) the

1405

coordinates in the default 'X' and 'Y' columns will be used to

1406

determine if each row is inside or outside the area specified in

1407

the region file. Alternate position column names, or expressions,

1408

may be entered if needed, as in

1409

1410

\begin{verbatim}

1411

regfilter("region.reg", XPOS, YPOS)

1412

\end{verbatim}

1413

Region filtering can be applied most unambiguously if the positions

1414

in the region file and in the table to be filtered are both give in

1415

terms of absolute celestial coordinate units. In this case the

1416

locations and sizes of the geometric shapes in the region file are

1417

specified in angular units on the sky (e.g., positions given in

1418

R.A. and Dec. and sizes in arcseconds or arcminutes). Similarly,

1419

each row of the filtered table will have a celestial coordinate

1420

associated with it. This association is usually implemented using

1421

a set of so-called 'World Coordinate System' (or WCS) FITS keywords

1422

that define the coordinate transformation that must be applied to

1423

the values in the 'X' and 'Y' columns to calculate the coordinate.

1424

1425

Alternatively, one can perform spatial filtering using unitless

1426

'pixel' coordinates for the regions and row positions. In this

1427

case the user must be careful to ensure that the positions in the 2

1428

files are self-consistent. A typical problem is that the region

1429

file may be generated using a binned image, but the unbinned

1430

coordinates are given in the event table. The ROSAT events files,

1431

for example, have X and Y pixel coordinates that range from 1 -

1432

15360. These coordinates are typically binned by a factor of 32 to

1433

produce a 480x480 pixel image. If one then uses a region file

1434

generated from this image (in image pixel units) to filter the

1435

ROSAT events file, then the X and Y column values must be converted

1436

to corresponding pixel units as in:

1437

1438

\begin{verbatim}

1439

regfilter("rosat.reg", X/32.+.5, Y/32.+.5)

1440

\end{verbatim}

1441

Note that this binning conversion is not necessary if the region

1442

file is specified using celestial coordinate units instead of pixel

1443

units because CFITSIO is then able to directly compare the

1444

celestial coordinate of each row in the table with the celestial

1445

coordinates in the region file without having to know anything

1446

about how the image may have been binned.

1447

1448

The last "wcs cols" parameter should rarely be needed. If supplied,

1449

this string contains the names of the 2 columns (space or comma

1450

separated) which have the associated WCS keywords. If not supplied,

1451

the filter will scan the X and Y expressions for column names.

1452

If only one is found in each expression, those columns will be

1453

used, otherwise an error will be returned.

1454

1455

These region shapes are supported (names are case insensitive):

1456

1457

\begin{verbatim}

1458

Point ( X1, Y1 ) <- One pixel square region

1459

Line ( X1, Y1, X2, Y2 ) <- One pixel wide region

1460

Polygon ( X1, Y1, X2, Y2, ... ) <- Rest are interiors with

1461

Rectangle ( X1, Y1, X2, Y2, A ) | boundaries considered

1462

Box ( Xc, Yc, Wdth, Hght, A ) V within the region

1463

Diamond ( Xc, Yc, Wdth, Hght, A )

1464

Circle ( Xc, Yc, R )

1465

Annulus ( Xc, Yc, Rin, Rout )

1466

Ellipse ( Xc, Yc, Rx, Ry, A )

1467

Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout )

1468

Sector ( Xc, Yc, Amin, Amax )

1469

\end{verbatim}

1470

where (Xc,Yc) is the coordinate of the shape's center; (X\#,Y\#) are

1471

the coordinates of the shape's edges; Rxxx are the shapes' various

1472

Radii or semimajor/minor axes; and Axxx are the angles of rotation

1473

(or bounding angles for Sector) in degrees. For rotated shapes, the

1474

rotation angle can be left off, indicating no rotation. Common

1475

alternate names for the regions can also be used: rotbox = box;

1476

rotrectangle = rectangle; (rot)rhombus = (rot)diamond; and pie

1477

= sector. When a shape's name is preceded by a minus sign, '-',

1478

the defined region is instead the area *outside* its boundary (ie,

1479

the region is inverted). All the shapes within a single region

1480

file are OR'd together to create the region, and the order is

1481

significant. The overall way of looking at region files is that if

1482

the first region is an excluded region then a dummy included region

1483

of the whole detector is inserted in the front. Then each region

1484

specification as it is processed overrides any selections inside of

1485

that region specified by previous regions. Another way of thinking

1486

about this is that if a previous excluded region is completely

1487

inside of a subsequent included region the excluded region is

1488

ignored.

1489

1490

The positional coordinates may be given either in pixel units,

1491

decimal degrees or hh:mm:ss.s, dd:mm:ss.s units. The shape sizes

1492

may be given in pixels, degrees, arcminutes, or arcseconds. Look

1493

at examples of region file produced by fv/POW or ds9 for further

1494

details of the region file format.

1495

1496

\subsubsection{Example Row Filters}

1497

1498

\begin{verbatim}

1499

[double && mag <= 5.0] - Extract all double stars brighter

1500

than fifth magnitude

1501

1502

[#row >= 125 && #row <= 175] - Extract row numbers 125 through 175

1503

1504

[abs(sin(theta * #deg)) < 0.5] - Extract all rows having the

1505

absolute value of the sine of theta

1506

less than a half where the angles

1507

are tabulated in degrees

1508

1509

[@rowFilter.txt] - Extract rows using the expression

1510

contained within the text file

1511

rowFilter.txt

1512

1513

[gtifilter()] - Search the current file for a GTI

1514

extension, filter the TIME

1515

column in the current table, using

1516

START/STOP times taken from

1517

columns in the GTI extension

1518

1519

[regfilter("pow.reg")] - Extract rows which have a coordinate

1520

(as given in the X and Y columns)

1521

within the spatial region specified

1522

in the pow.reg region file.

1523

\end{verbatim}

1524

1525

\newpage

1526

\subsection{Combined Filtering Examples}

1527

1528

The previous sections described all the individual types of filters

1529

that may be applied to the input file. In this section we show

1530

examples which combine several different filters at once. These

1531

examples all use the {\tt fitscopy} program that is distributed with

1532

the CFITSIO code. It simply copies the input file to the output file.

1533

1534

\begin{verbatim}

1535

fitscopy rosat.fit out.fit

1536

\end{verbatim}

1537

1538

This trivial example simply makes an identical copy of the input

1539

rosat.fit file without any filtering.

1540

1541

\begin{verbatim}

1542

fitscopy 'rosat.fit[events][col Time;X;Y][#row < 1000]' out.fit

1543

\end{verbatim}

1544

1545

The output file contains only the Time, X, and Y columns, and only

1546

the first 999 rows from the 'EVENTS' table extension of the input file.

1547

All the other HDUs in the input file are copied to the output file

1548

without any modification.

1549

1550

\begin{verbatim}

1551

fitscopy 'rosat.fit[events][PI < 50][bin (Xdet,Ydet) = 16]' image.fit

1552

\end{verbatim}

1553

1554

This creates an output image by binning the Xdet and Ydet columns of

1555

the events table with a pixel binning factor of 16. Only the rows

1556

which have a PI energy less than 50 are used to construct this image.

1557

The output image file contains a primary array image without any

1558

extensions.

1559

1560

\begin{verbatim}

1561

fitscopy 'rosat.fit[events][gtifilter() && regfilter("pow.reg")]' out.fit

1562

\end{verbatim}

1563

1564

The filtering expression in this example uses the {\tt gtifilter}

1565

function to test whether the TIME column value in each row is within

1566

one of the Good Time Intervals defined in the GTI extension in the same

1567

input file, and also uses the {\tt regfilter} function to test if the

1568

position associated with each row (derived by default from the values

1569

in the X and Y columns of the events table) is located within the area

1570

defined in the {\tt pow.reg} text region file (which was previously

1571

created with the {\tt fv/POW} image display program). Only the rows

1572

which satisfy both tests are copied to the output table.

1573

1574

\begin{verbatim}

1575

fitscopy 'r.fit[evt][PI<50]' stdout | fitscopy stdin[evt][col X,Y] out.fit

1576

\end{verbatim}

1577

1578

In this somewhat convoluted example, fitscopy is used to first select

1579

the rows from the evt extension which have PI < 50 and write the

1580

resulting table out to the stdout stream. This is piped to a 2nd

1581

instance of fitscopy (with the Unix `|' pipe command) which reads that

1582

filtered FITS file from the stdin stream and copies only the X and Y

1583

columns from the evt table to the output file.

1584

1585

\begin{verbatim}

1586

fitscopy 'r.fit[evt][col RAD=sqrt((X-#XCEN)**2+(Y-#YCEN)**2)][rad<100]' out.fit

1587

\end{verbatim}

1588

1589

This example first creates a new column called RAD which gives the

1590

distance between the X,Y coordinate of each event and the coordinate

1591

defined by the XCEN and YCEN keywords in the header. Then, only those

1592

rows which have a distance less than 100 are copied to the output

1593

table. In other words, only the events which are located within 100

1594

pixel units from the (XCEN, YCEN) coordinate are copied to the output

1595

table.

1596

1597

\begin{verbatim}

1598

fitscopy 'ftp://heasarc.gsfc.nasa.gov/rosat.fit[events][bin (X,Y)=16]' img.fit

1599

\end{verbatim}

1600

1601

This example bins the X and Y columns of the hypothetical ROSAT file

1602

at the HEASARC ftp site to create the output image.

1603

1604

\begin{verbatim}

1605

fitscopy 'raw.fit[i512,512][101:110,51:60]' image.fit

1606

\end{verbatim}

1607

1608

This example converts the 512 x 512 pixel raw binary 16-bit integer

1609

image to a FITS file and copies a 10 x 10 pixel subimage from it to the

1610

output FITS image.

1611

1612

\newpage

1613

\section{CFITSIO Error Status Codes}

1614

1615

The following table lists all the error status codes used by CFITSIO.

1616

Programmers are encouraged to use the symbolic mnemonics (defined in

1617

the file fitsio.h) rather than the actual integer status values to

1618

improve the readability of their code.

1619

1620

\begin{verbatim}

1621

Symbolic Const Value Meaning

1622

-------------- ----- -----------------------------------------

1623

0 OK, no error

1624

PREPEND_PRIMARY -9 used in ffiimg to prepend a new primary array

1625

SAME_FILE 101 input and output files are the same

1626

TOO_MANY_FILES 103 tried to open too many FITS files at once

1627

FILE_NOT_OPENED 104 could not open the named file

1628

FILE_NOT_CREATED 105 could not create the named file

1629

WRITE_ERROR 106 error writing to FITS file

1630

END_OF_FILE 107 tried to move past end of file

1631

READ_ERROR 108 error reading from FITS file

1632

FILE_NOT_CLOSED 110 could not close the file

1633

ARRAY_TOO_BIG 111 array dimensions exceed internal limit

1634

READONLY_FILE 112 Cannot write to readonly file

1635

MEMORY_ALLOCATION 113 Could not allocate memory

1636

BAD_FILEPTR 114 invalid fitsfile pointer

1637

NULL_INPUT_PTR 115 NULL input pointer to routine

1638

SEEK_ERROR 116 error seeking position in file

1639

1640

BAD_URL_PREFIX 121 invalid URL prefix on file name

1641

TOO_MANY_DRIVERS 122 tried to register too many IO drivers

1642

DRIVER_INIT_FAILED 123 driver initialization failed

1643

NO_MATCHING_DRIVER 124 matching driver is not registered

1644

URL_PARSE_ERROR 125 failed to parse input file URL

1645

1646

SHARED_BADARG 151 bad argument in shared memory driver

1647

SHARED_NULPTR 152 null pointer passed as an argument

1648

SHARED_TABFULL 153 no more free shared memory handles

1649

SHARED_NOTINIT 154 shared memory driver is not initialized

1650

SHARED_IPCERR 155 IPC error returned by a system call

1651

SHARED_NOMEM 156 no memory in shared memory driver

1652

SHARED_AGAIN 157 resource deadlock would occur

1653

SHARED_NOFILE 158 attempt to open/create lock file failed

1654

SHARED_NORESIZE 159 shared memory block cannot be resized at the moment

1655

1656

HEADER_NOT_EMPTY 201 header already contains keywords

1657

KEY_NO_EXIST 202 keyword not found in header

1658

KEY_OUT_BOUNDS 203 keyword record number is out of bounds

1659

VALUE_UNDEFINED 204 keyword value field is blank

1660

NO_QUOTE 205 string is missing the closing quote

1661

BAD_KEYCHAR 207 illegal character in keyword name or card

1662

BAD_ORDER 208 required keywords out of order

1663

NOT_POS_INT 209 keyword value is not a positive integer

1664

NO_END 210 couldn't find END keyword

1665

BAD_BITPIX 211 illegal BITPIX keyword value

1666

BAD_NAXIS 212 illegal NAXIS keyword value

1667

BAD_NAXES 213 illegal NAXISn keyword value

1668

BAD_PCOUNT 214 illegal PCOUNT keyword value

1669

BAD_GCOUNT 215 illegal GCOUNT keyword value

1670

BAD_TFIELDS 216 illegal TFIELDS keyword value

1671

NEG_WIDTH 217 negative table row size

1672

NEG_ROWS 218 negative number of rows in table

1673

COL_NOT_FOUND 219 column with this name not found in table

1674

BAD_SIMPLE 220 illegal value of SIMPLE keyword

1675

NO_SIMPLE 221 Primary array doesn't start with SIMPLE

1676

NO_BITPIX 222 Second keyword not BITPIX

1677

NO_NAXIS 223 Third keyword not NAXIS

1678

NO_NAXES 224 Couldn't find all the NAXISn keywords

1679

NO_XTENSION 225 HDU doesn't start with XTENSION keyword

1680

NOT_ATABLE 226 the CHDU is not an ASCII table extension

1681

NOT_BTABLE 227 the CHDU is not a binary table extension

1682

NO_PCOUNT 228 couldn't find PCOUNT keyword

1683

NO_GCOUNT 229 couldn't find GCOUNT keyword

1684

NO_TFIELDS 230 couldn't find TFIELDS keyword

1685

NO_TBCOL 231 couldn't find TBCOLn keyword

1686

NO_TFORM 232 couldn't find TFORMn keyword

1687

NOT_IMAGE 233 the CHDU is not an IMAGE extension

1688

BAD_TBCOL 234 TBCOLn keyword value < 0 or > rowlength

1689

NOT_TABLE 235 the CHDU is not a table

1690

COL_TOO_WIDE 236 column is too wide to fit in table

1691

COL_NOT_UNIQUE 237 more than 1 column name matches template

1692

BAD_ROW_WIDTH 241 sum of column widths not = NAXIS1

1693

UNKNOWN_EXT 251 unrecognizable FITS extension type

1694

UNKNOWN_REC 252 unknown record; 1st keyword not SIMPLE or XTENSION

1695

END_JUNK 253 END keyword is not blank

1696

BAD_HEADER_FILL 254 Header fill area contains non-blank chars

1697

BAD_DATA_FILL 255 Illegal data fill bytes (not zero or blank)

1698

BAD_TFORM 261 illegal TFORM format code

1699

BAD_TFORM_DTYPE 262 unrecognizable TFORM datatype code

1700

BAD_TDIM 263 illegal TDIMn keyword value

1701

BAD_HEAP_PTR 264 invalid BINTABLE heap pointer is out of range

1702

1703

BAD_HDU_NUM 301 HDU number < 1 or > MAXHDU

1704

BAD_COL_NUM 302 column number < 1 or > tfields

1705

NEG_FILE_POS 304 tried to move to negative byte location in file

1706

NEG_BYTES 306 tried to read or write negative number of bytes

1707

BAD_ROW_NUM 307 illegal starting row number in table

1708

BAD_ELEM_NUM 308 illegal starting element number in vector

1709

NOT_ASCII_COL 309 this is not an ASCII string column

1710

NOT_LOGICAL_COL 310 this is not a logical datatype column

1711

BAD_ATABLE_FORMAT 311 ASCII table column has wrong format

1712

BAD_BTABLE_FORMAT 312 Binary table column has wrong format

1713

NO_NULL 314 null value has not been defined

1714

NOT_VARI_LEN 317 this is not a variable length column

1715

BAD_DIMEN 320 illegal number of dimensions in array

1716

BAD_PIX_NUM 321 first pixel number greater than last pixel

1717

ZERO_SCALE 322 illegal BSCALE or TSCALn keyword = 0

1718

NEG_AXIS 323 illegal axis length < 1

1719

1720

NOT_GROUP_TABLE 340 Grouping function error

1721

HDU_ALREADY_MEMBER 341

1722

MEMBER_NOT_FOUND 342

1723

GROUP_NOT_FOUND 343

1724

BAD_GROUP_ID 344

1725

TOO_MANY_HDUS_TRACKED 345

1726

HDU_ALREADY_TRACKED 346

1727

BAD_OPTION 347

1728

IDENTICAL_POINTERS 348

1729

BAD_GROUP_ATTACH 349

1730

BAD_GROUP_DETACH 350

1731

1732

NGP_NO_MEMORY 360 malloc failed

1733

NGP_READ_ERR 361 read error from file

1734

NGP_NUL_PTR 362 null pointer passed as an argument.

1735

Passing null pointer as a name of

1736

template file raises this error

1737

NGP_EMPTY_CURLINE 363 line read seems to be empty (used

1738

internally)

1739

NGP_UNREAD_QUEUE_FULL 364 cannot unread more then 1 line (or single

1740

line twice)

1741

NGP_INC_NESTING 365 too deep include file nesting (infinite

1742

loop, template includes itself ?)

1743

NGP_ERR_FOPEN 366 fopen() failed, cannot open template file

1744

NGP_EOF 367 end of file encountered and not expected

1745

NGP_BAD_ARG 368 bad arguments passed. Usually means

1746

internal parser error. Should not happen

1747

NGP_TOKEN_NOT_EXPECT 369 token not expected here

1748

1749

BAD_I2C 401 bad int to formatted string conversion

1750

BAD_F2C 402 bad float to formatted string conversion

1751

BAD_INTKEY 403 can't interpret keyword value as integer

1752

BAD_LOGICALKEY 404 can't interpret keyword value as logical

1753

BAD_FLOATKEY 405 can't interpret keyword value as float

1754

BAD_DOUBLEKEY 406 can't interpret keyword value as double

1755

BAD_C2I 407 bad formatted string to int conversion

1756

BAD_C2F 408 bad formatted string to float conversion

1757

BAD_C2D 409 bad formatted string to double conversion

1758

BAD_DATATYPE 410 illegal datatype code value

1759

BAD_DECIM 411 bad number of decimal places specified

1760

NUM_OVERFLOW 412 overflow during datatype conversion

1761

DATA_COMPRESSION_ERR 413 error compressing image

1762

DATA_DECOMPRESSION_ERR 414 error uncompressing image

1763

1764

BAD_DATE 420 error in date or time conversion

1765

1766

PARSE_SYNTAX_ERR 431 syntax error in parser expression

1767

PARSE_BAD_TYPE 432 expression did not evaluate to desired type

1768

PARSE_LRG_VECTOR 433 vector result too large to return in array

1769

PARSE_NO_OUTPUT 434 data parser failed not sent an out column

1770

PARSE_BAD_COL 435 bad data encounter while parsing column

1771

PARSE_BAD_OUTPUT 436 Output file not of proper type

1772

1773

ANGLE_TOO_BIG 501 celestial angle too large for projection

1774

BAD_WCS_VAL 502 bad celestial coordinate or pixel value

1775

WCS_ERROR 503 error in celestial coordinate calculation

1776

BAD_WCS_PROJ 504 unsupported type of celestial projection

1777

NO_WCS_KEY 505 celestial coordinate keywords not found

1778

APPROX_WCS_KEY 506 approximate wcs keyword values were returned

1779

\end{verbatim}

1780

1781

\end{document}