CFITSIO User’s Reference Guide An Interface to FITS Format Files for C Programmers Version 3.3 HEASARC Code 662 Goddard Space Flight Center Greenbelt, MD 20771 USA February 2013 ii Contents 1 Introduction 1 1.1 ABriefOverview .................................. ... 1 1.2 Sources of FITS Software and Information . ........... 1 1.3 Acknowledgments................................. ..... 2 1.4 LegalStuff ....................................... 4 2 Creating the CFITSIO Library 5 2.1 BuildingtheLibrary .............................. ...... 5 2.1.1 UnixSystems................................... 5 2.1.2 VMS......................................... 7 2.1.3 WindowsPCs.................................... 7 2.1.4 MacintoshPCs .................................. 7 2.2 TestingtheLibrary............................... ...... 8 2.3 LinkingProgramswithCFITSIO . ....... 9 2.4 Using CFITSIO in Multi-threaded Environments . ............ 9 2.5 GettingStartedwithCFITSIO . ....... 10 2.6 ExampleProgram .................................. 10 3 A FITS Primer 13 4 Programming Guidelines 15 4.1 CFITSIODefinitions............................... ..... 15 4.2 Current Header Data Unit (CHDU) . ...... 17 4.3 Function Names and Variable Datatypes . .......... 18 4.4 Support for Unsigned Integers and Signed Bytes . ............ 20 4.5 Dealing with Character Strings . ......... 22 iii iv CONTENTS 4.6 ImplicitDataTypeConversion . ........ 23 4.7 DataScaling ..................................... 23 4.8 SupportforIEEESpecialValues . ........ 24 4.9 Error Status Values and the Error Message Stack . ............ 24 4.10 Variable-Length Arrays in Binary Tables . ............. 25 4.11 Multiple Access to the Same FITS File . .......... 26 4.12 When the Final Size of the FITS HDU is Unknown . ......... 27 4.13 CFITSIOSizeLimitations . ........ 27 5 Basic CFITSIO Interface Routines 29 5.1 CFITSIOErrorStatusRoutines . ....... 29 5.2 FITSFileAccessRoutines. ....... 30 5.3 HDUAccessRoutines ............................... 33 5.4 Header Keyword Read/Write Routines . ......... 35 5.4.1 KeywordReadingRoutines . 35 5.4.2 KeywordWritingRoutines . 38 5.5 Primary Array or IMAGE Extension I/O Routines . .......... 40 5.6 ImageCompression................................ ..... 44 5.7 ASCIIandBinaryTableRoutines . ....... 48 5.7.1 CreateNewTable ................................ 49 5.7.2 ColumnInformationRoutines. ...... 49 5.7.3 RoutinestoEditRowsorColumns . ..... 52 5.7.4 Read and Write Column Data Routines . ..... 54 5.7.5 Row Selection and Calculator Routines . ........ 56 5.7.6 Column Binning or Histogramming Routines . ........ 57 5.8 UtilityRoutines................................. ...... 60 5.8.1 FileChecksumRoutines . 60 5.8.2 Date and Time Utility Routines . ..... 61 5.8.3 General Utility Routines . ...... 62 6 The CFITSIO Iterator Function 73 6.1 TheIteratorWorkFunction . ....... 74 6.2 TheIteratorDriverFunction . ........ 76 6.3 Guidelines for Using the Iterator Function . ............. 77 CONTENTS v 6.4 Complete List of Iterator Routines . .......... 78 7 World Coordinate System Routines 81 7.1 Self-contained WCS Routines . ........ 82 8 Hierarchical Grouping Routines 85 8.1 GroupingTableRoutines . ...... 86 8.2 GroupMemberRoutines. .. .. .. .. .. .. .. .. ..... 88 9 Specialized CFITSIO Interface Routines 91 9.1 FITSFileAccessRoutines. ....... 91 9.2 HDUAccessRoutines ............................... 95 9.3 Specialized Header Keyword Routines . .......... 97 9.3.1 Header Information Routines . ...... 97 9.3.2 Read and Write the Required Keywords . ...... 97 9.3.3 WriteKeywordRoutines. 99 9.3.4 InsertKeywordRoutines . 101 9.3.5 ReadKeywordRoutines . 102 9.3.6 ModifyKeywordRoutines. 104 9.3.7 UpdateKeywordRoutines. 105 9.4 Define Data Scaling and Undefined Pixel Parameters . ............106 9.5 Specialized FITS Primary Array or IMAGE Extension I/O Routines . 107 9.6 Specialized FITS ASCII and Binary Table Routines . ............110 9.6.1 GeneralColumnRoutines . 110 9.6.2 Low-Level Table Access Routines . .......112 9.6.3 WriteColumnDataRoutines . 112 9.6.4 ReadColumnDataRoutines . 113 10 Extended File Name Syntax 117 10.1Overview ....................................... 117 10.2Filetype ....................................... 120 10.2.1 NotesaboutHTTPproxyservers. 120 10.2.2 Notes about the stream filetype driver . .........121 10.2.3 Notes about the gsiftp filetype . .......122 vi CONTENTS 10.2.4 Notesabouttherootfiletype . 122 10.2.5 Notes about the shmem filetype: . 124 10.3BaseFilename ................................... 124 10.4 Output File Name when Opening an Existing File . ...........126 10.5 Template File Name when Creating a New File . ..........128 10.6 Image Tile-Compression Specification . ............128 10.7 HDU Location Specification . ........128 10.8ImageSection................................... 130 10.9 ImageTransformFilters . ........131 10.10Column and Keyword Filtering Specification . .............132 10.11Row Filtering Specification . ..........135 10.11.1GeneralSyntax. .. .. .. .. .. .. .. .. 135 10.11.2BitMasks.................................... 138 10.11.3VectorColumns ............................... 139 10.11.4 Good Time Interval Filtering . ........140 10.11.5 Spatial Region Filtering . ........141 10.11.6ExampleRowFilters. 143 10.12 Binning or Histogramming Specification . .............144 11 Template Files 149 11.1 Detailed Template Line Format . .........149 11.2 Auto-indexingofKeywords . ........150 11.3 Template Parser Directives . .........151 11.4 FormalTemplateSyntax. .......151 11.5Errors ......................................... 152 11.6Examples ....................................... 152 12 Local FITS Conventions 155 12.1 64-BitLongIntegers .. .. .. .. .. .. .. .. .......155 12.2 LongStringKeywordValues. ........155 12.3 Arrays of Fixed-Length Strings in Binary Tables . ..............157 12.4 KeywordUnitsStrings. .......157 12.5 HIERARCH Convention for Extended Keyword Names . ..........158 12.6 Tile-CompressedImageFormat . .........158 CONTENTS vii 13 Optimizing Programs 161 13.1 HowCFITSIOManagesDataI/O . 161 13.2 Optimization Strategies . .........162 A Index of Routines 167 B Parameter Definitions 173 C CFITSIO Error Status Codes 179 viii CONTENTS Chapter 1 Introduction 1.1 A Brief Overview CFITSIO is a machine-independent library of routines for reading and writing data files in the FITS (Flexible Image Transport System) data format. It can also read IRAF format image files and raw binary data arrays by converting them on the fly into a virtual FITS format file. This library is written in ANSI C and provides a powerful yet simple interface for accessing FITS files which will run on most commonly used computers and workstations. CFITSIO supports all the features described in the official definition of the FITS format and can read and write all the currently defined types of extensions, including ASCII tables (TABLE), Binary tables (BINTABLE) and IMAGE extensions. The CFITSIO routines insulate the programmer from having to deal with the complicated formatting details in the FITS file, however, it is assumed that users have a general knowledge about the structure and usage of FITS files. CFITSIO also contains a set of Fortran callable wrapper routines which allow Fortran programs to call the CFITSIO routines. See the companion “FITSIO User’s Guide” for the definition of the Fortran subroutine calling sequences. These wrappers replace the older Fortran FITSIO library which is no longer supported. The CFITSIO package was initially developed by the HEASARC (High Energy Astrophysics Science Archive Research Center) at the NASA Goddard Space Flight Center to convert various existing and newly acquired astronomical data sets into FITS format and to further analyze data already in FITS format. New features continue to be added to CFITSIO in large part due to contributions of ideas or actual code from users of the package. The Integral Science Data Center in Switzerland, and the XMM/ESTEC project in The Netherlands made especially significant contributions that resulted in many of the new features that appeared in v2.0 of CFITSIO. 1.2 Sources of FITS Software and Information The latest version of the CFITSIO source code, documentation, and example programs are available on the Web or via anonymous ftp from: 1 2 CHAPTER 1. INTRODUCTION http://heasarc.gsfc.nasa.gov/fitsio ftp://legacy.gsfc.nasa.gov/software/fitsio/c Any questions, bug reports, or suggested enhancements related to the CFITSIO package should be sent to the primary author: Dr. William Pence Telephone: (301) 286-4599 HEASARC, Code 662 E-mail: [email protected] NASA/Goddard Space Flight Center Greenbelt, MD 20771, USA This User’s Guide assumes that readers already have a general understanding of the definition and structure of FITS format files. Further information about FITS formats is available from the FITS Support Office at http://fits.gsfc.nasa.gov. In particular, the ’FITS Standard’ gives the authoritative definition of the FITS data format. Other documents available at that Web site provide additional historical background and practical advice on using FITS files. The HEASARC also provides a very sophisticated FITS file analysis program called ‘Fv’ which can be used to display and edit the contents of any FITS file as well as construct new FITS files from scratch. Fv is freely available for most Unix platforms, Mac PCs, and Windows PCs. CFITSIO users may also be interested in the FTOOLS package of programs that can be used to manipulate and analyze FITS format files. Fv and FTOOLS are available from