0
# fitsio
1

2
A comprehensive Python library for reading from and writing to FITS (Flexible Image Transport System) files using the cfitsio library. Built as a C extension with Python bindings, fitsio provides efficient access to FITS image, binary table, and ASCII table extensions while supporting advanced features like tile compression, variable-length table columns, and direct handling of compressed files.
3

4
## Package Information
5

6
- **Package Name**: fitsio
7
- **Language**: Python
8
- **Installation**: `pip install fitsio`
9

10
## Core Imports
11

12
```python
13
import fitsio
14
```
15

16
For convenience functions:
17

18
```python
19
from fitsio import FITS, read, read_header, write
20
```
21

22
For header operations:
23

24
```python
25
from fitsio import FITSHDR, FITSRecord
26
```
27

28
## Basic Usage
29

30
```python
31
import fitsio
32
import numpy as np
33

34
# Read data from a FITS file
35
data = fitsio.read('data.fits')
36

37
# Read a specific extension and columns
38
table_data = fitsio.read('data.fits', ext=1, columns=['x', 'y', 'flux'])
39

40
# Read header information
41
header = fitsio.read_header('data.fits')
42

43
# Write data to a new FITS file
44
image = np.random.random((100, 100))
45
fitsio.write('output.fits', image)
46

47
# Write a structured array as a table
48
records = np.zeros(10, dtype=[('id', 'i4'), ('x', 'f8'), ('y', 'f8')])
49
records['id'] = np.arange(10)
50
records['x'] = np.random.random(10)
51
records['y'] = np.random.random(10)
52
fitsio.write('table.fits', records)
53

54
# Using the FITS class for more control
55
with fitsio.FITS('data.fits', 'rw') as fits:
56
    # Read image data with slicing
57
    image_subset = fits[0][10:50, 20:80]
58
    
59
    # Read table rows and columns
60
    table_subset = fits[1]['x', 'y'][100:200]
61
    
62
    # Write new data
63
    fits.write(new_data, compress='rice')
64
```
65

66
## Architecture
67

68
fitsio uses a hierarchical structure that mirrors FITS file organization:
69

70
- **FITS class**: Top-level file interface managing HDU access and file operations
71
- **HDU classes**: Extension-specific handlers (ImageHDU, TableHDU, AsciiTableHDU) providing specialized read/write operations
72
- **FITSHDR class**: Header container managing keywords, comments, and metadata
73
- **Convenience functions**: High-level read/write functions for common operations
74

75
The library provides both high-level convenience functions for simple operations and low-level control through the FITS class for complex workflows. All operations leverage the bundled cfitsio library for performance and compatibility.
76

77
## Capabilities
78

79
### File Operations
80

81
Core FITS file handling including opening, closing, reading, and writing FITS files. Provides both convenience functions for simple operations and the FITS class for full control over file operations.
82

83
```python { .api }
84
class FITS:
85
    def __init__(self, filename, mode='r', **kwargs): ...
86
    def close(self): ...
87
    def write(self, data, **kwargs): ...
88

89
def read(filename, ext=None, **kwargs): ...
90
def write(filename, data, **kwargs): ...
91
def read_header(filename, ext=0, **kwargs): ...
92
def read_scamp_head(filename, header=None): ...
93
```
94

95
[File Operations](./file-operations.md)
96

97
### Header Operations
98

99
FITS header manipulation including reading, writing, and modifying header keywords, comments, and metadata. Supports complete header management with proper FITS formatting and validation.
100

101
```python { .api }
102
class FITSHDR:
103
    def __init__(self, record_list=None): ...
104
    def add_record(self, record): ...
105
    def __setitem__(self, key, value): ...
106
    def __getitem__(self, key): ...
107

108
class FITSRecord: ...
109
class FITSCard: ...
110
```
111

112
[Header Operations](./header-operations.md)
113

114
### Image Operations
115

116
Reading and writing FITS image data with support for subsets, compression, reshaping, and various data types. Includes numpy-style slicing for efficient access to image subregions without loading entire images into memory.
117

118
```python { .api }
119
class ImageHDU:
120
    def read(self, **kwargs): ...
121
    def write(self, img, start=0): ...
122
    def get_dims(self): ...
123
    def reshape(self, dims): ...
124
    def is_compressed(self): ...
125
    def __getitem__(self, slice): ...
126
```
127

128
[Image Operations](./image-operations.md)
129

130
### Table Operations
131

132
Reading and writing FITS table data (binary and ASCII tables) with support for column operations, row filtering, variable-length columns, and table modifications. Includes advanced features like WHERE clause filtering and efficient column-wise access.
133

134
```python { .api }
135
class TableHDU:
136
    def read(self, **kwargs): ...
137
    def read_column(self, col, **kwargs): ...
138
    def write(self, data, **kwargs): ...
139
    def append(self, data, **kwargs): ...
140
    def where(self, expression, **kwargs): ...
141
    def insert_column(self, name, data, **kwargs): ...
142
    def __getitem__(self, key): ...
143
```
144

145
[Table Operations](./table-operations.md)
146

147
## Constants
148

149
### File Access Modes
150

151
```python { .api }
152
READONLY = 0
153
READWRITE = 1
154
```
155

156
### Compression Types
157

158
```python { .api }
159
NOCOMPRESS = 0
160
RICE_1 = 11
161
GZIP_1 = 21
162
GZIP_2 = 22
163
PLIO_1 = 31
164
HCOMPRESS_1 = 41
165
```
166

167
### HDU Types
168

169
```python { .api }
170
ANY_HDU = -1
171
IMAGE_HDU = 0
172
ASCII_TBL = 1
173
BINARY_TBL = 2
174
```
175

176
### Dithering Methods
177

178
```python { .api }
179
NO_DITHER = -1
180
SUBTRACTIVE_DITHER_1 = 1
181
SUBTRACTIVE_DITHER_2 = 2
182
```
183

184
## Utility Functions
185

186
```python { .api }
187
def cfitsio_version(asfloat=False):
188
    """Get version of bundled cfitsio library."""
189

190
class FITSRuntimeWarning: ...
191
class FITSFormatError(Exception): ...
192
```