0
# DrizzlePac
1

2
DrizzlePac is a comprehensive Python library for astronomical image processing and combination, specifically designed for Hubble Space Telescope (HST) data. It implements sophisticated algorithms for aligning and combining astronomical images using the drizzle algorithm, which preserves intrinsic resolution while reducing noise, correcting geometric distortion, removing cosmic rays, and improving overall data fidelity.
3

4
## Package Information
5

6
- **Package Name**: drizzlepac
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install drizzlepac`
10
- **Documentation**: https://drizzlepac.readthedocs.io/en/latest/
11
- **Source**: https://github.com/spacetelescope/drizzlepac
12

13
## Core Imports
14

15
```python
16
import drizzlepac
17
```
18

19
Common imports for specific tasks:
20

21
```python
22
from drizzlepac import astrodrizzle, tweakreg, tweakback
23
from drizzlepac import pixtosky, skytopix, pixtopix
24
from drizzlepac import resetbits, updatenpol
25
```
26

27
For HAP (Hubble Advanced Products) processing:
28

29
```python
30
from drizzlepac import haputils
31
from drizzlepac.haputils import catalog_utils, align_utils
32
```
33

34
## Basic Usage
35

36
```python
37
import drizzlepac
38
from drizzlepac import astrodrizzle
39

40
# Display available help information
41
drizzlepac.help()
42

43
# Basic AstroDrizzle processing - align and combine HST images
44
astrodrizzle.AstroDrizzle('input_files.txt', output='combined',
45
                         clean=True, driz_separate=True,
46
                         driz_sep_wcs=True, median=True,
47
                         blot=True, driz_cr=True,
48
                         driz_combine=True)
49

50
# Alternative: using Python interface directly
51
from drizzlepac.astrodrizzle import run
52
from drizzlepac import util
53
configobj = util.build_configobj('config.cfg')
54
run(configobj)
55
```
56

57
## Architecture
58

59
DrizzlePac is built around a modular architecture supporting multiple workflow patterns:
60

61
### Task-Based Processing
62
- **Primary Tasks**: Core image processing functions (astrodrizzle, tweakreg, etc.)
63
- **Coordinate Tasks**: Bidirectional coordinate transformations
64
- **Utility Tasks**: Data quality management, calibration, and region mapping
65

66
### HAP (Hubble Advanced Products) Framework
67
- **Product Classes**: Hierarchical product management (Total, Filter, Exposure products)
68
- **Catalog System**: Advanced source detection and catalog management
69
- **Quality Assessment**: Comprehensive flagging and diagnostic systems
70

71
### Configuration System
72
- **Parameter Files**: Standardized .cfg files for reproducible processing
73
- **TEAL Integration**: Interactive parameter editing through TEAL interface
74
- **Pipeline Mode**: Automated processing with minimal user intervention
75

76
## Capabilities
77

78
### Primary Image Processing
79

80
Core functionality for astronomical image alignment, combination, and calibration using the drizzle algorithm for optimal preservation of image resolution and removal of artifacts.
81

82
```python { .api }
83
def AstroDrizzle(input=None, mdriztab=False, editpars=False,
84
                configobj=None, wcsmap=None, **input_dict): ...
85
```
86

87
[Image Processing](./image-processing.md)
88

89
### Image Registration and Alignment
90

91
Advanced algorithms for computing offsets between images and reference frames, with support for multiple alignment methods and quality assessment.
92

93
```python { .api }
94
def TweakReg(files=None, editpars=False, configobj=None,
95
            imagefindcfg=None, refimagefindcfg=None, **input_dict): ...
96
```
97

98
[Registration and Alignment](./registration-alignment.md)
99

100
### Coordinate Transformations
101

102
Bidirectional coordinate transformation capabilities between pixel coordinates, sky coordinates, and different WCS reference frames with full distortion correction.
103

104
```python { .api }
105
def xy2rd(input, x=None, y=None, coords=None, coordfile=None, **kwargs): ...
106
def rd2xy(input, ra=None, dec=None, coordfile=None, **kwargs): ...
107
def tran(inimage, outimage, direction='forward', x=None, y=None, **kwargs): ...
108
```
109

110
[Coordinate Transformations](./coordinate-transformations.md)
111

112
### Data Quality and Calibration
113

114
Tools for managing data quality flags, photometric equalization, and applying calibration corrections to HST observations.
115

116
```python { .api }
117
def reset_dq_bits(input, bits, extver=None, extname='dq'): ...
118
def photeq(files='*_flt.fits', sciext='SCI', errext='ERR', **kwargs): ...
119
def update(input, refdir="jref$", local=None, interactive=False): ...
120
```
121

122
[Data Quality and Calibration](./data-quality-calibration.md)
123

124
### HAP Processing Framework
125

126
Advanced processing capabilities for Hubble Advanced Products including sophisticated catalog management, source detection, and automated quality assessment.
127

128
```python { .api }
129
class HAPProduct: ...
130
class HAPCatalogs: ...
131
def perform_align(input_list, catalog_list, num_sources, **pars): ...
132
```
133

134
[HAP Processing](./hap-processing.md)
135

136
### WCS and Region Management
137

138
World Coordinate System utilities, region file mapping, and WCS solution management for complex astronomical workflows.
139

140
```python { .api }
141
def apply_tweak(drz_file, orig_wcs_name, output_wcs_name=None, input_files=None, **kwargs): ...
142
def MapReg(input_reg, images, img_wcs_ext='sci', refimg='', ref_wcs_ext='sci', **kwargs): ...
143
def buildwcs(outwcs, configObj=None, editpars=False, **input_dict): ...
144
```
145

146
[WCS and Region Management](./wcs-region-management.md)
147

148
## Command-Line Tools
149

150
DrizzlePac provides several command-line scripts for common operations:
151

152
- `mdriz` - MultiDrizzle interface
153
- `resetbits` - Reset DQ bits in FLT files
154
- `updatenpol` - Update NPOL distortion corrections
155
- `runastrodriz` - Pipeline AstroDrizzle processing
156
- `runsinglehap` - Process single HAP observations
157
- `runmultihap` - Process multiple HAP observations
158

159
## Error Handling
160

161
DrizzlePac functions typically raise standard Python exceptions:
162

163
- `ValueError` - Invalid parameter values or incompatible inputs
164
- `IOError` - File access or format issues
165
- `RuntimeError` - Processing failures or convergence issues
166
- Custom exceptions defined in individual modules for specific error conditions
167

168
Common error patterns include validation of input file formats, WCS compatibility checks, and memory management for large image processing operations.