0
# Image Processing
1

2
Core functionality for astronomical image alignment, combination, and calibration using the drizzle algorithm. This provides the primary interface for processing Hubble Space Telescope observations with cosmic ray removal, distortion correction, and optimal image combination.
3

4
## Capabilities
5

6
### AstroDrizzle - Primary Image Processing
7

8
Automates the alignment, cosmic ray removal, distortion correction, and combination of HST images. AstroDrizzle is the main task for most DrizzlePac workflows, providing both interactive and pipeline processing modes.
9

10
```python { .api }
11
def AstroDrizzle(input=None, mdriztab=False, editpars=False,
12
                configobj=None, wcsmap=None, **input_dict):
13
    """
14
    Main command-line interface for AstroDrizzle processing.
15

16
    Parameters:
17
    - input: str or list, input images or association table
18
    - mdriztab: bool, use MDRIZTAB for parameters
19
    - editpars: bool, allow interactive parameter editing
20
    - configobj: ConfigObj, configuration object with parameters
21
    - wcsmap: function, custom WCS mapping function
22
    - **input_dict: dict, parameter overrides
23

24
    Returns:
25
    None (creates output files)
26
    """
27

28
def run(configobj, wcsmap=None, input_dict=None):
29
    """
30
    Core processing function for AstroDrizzle.
31

32
    Parameters:
33
    - configobj: ConfigObj, configuration with all processing parameters
34
    - wcsmap: function, optional custom WCS transformation function
35
    - input_dict: dict, optional parameter overrides
36

37
    Returns:
38
    None (creates output files)
39
    """
40
```
41

42
#### Usage Example
43

44
```python
45
from drizzlepac import astrodrizzle
46

47
# Basic usage with default parameters
48
astrodrizzle.AstroDrizzle('j8bt06nyq_flt.fits,j8bt06nzq_flt.fits',
49
                         output='combined',
50
                         clean=True,
51
                         driz_separate=True,
52
                         driz_sep_wcs=True,
53
                         median=True,
54
                         blot=True,
55
                         driz_cr=True,
56
                         driz_combine=True)
57

58
# Using configuration object for complex processing
59
from drizzlepac import util
60
configobj = util.build_configobj('astrodrizzle.cfg')
61
astrodrizzle.run(configobj)
62
```
63

64
### Multi-Drizzle Interface
65

66
Legacy MultiDrizzle interface provided for backward compatibility.
67

68
```python { .api }
69
def main():
70
    """
71
    Command-line entry point for mdriz script.
72

73
    Returns:
74
    None
75
    """
76
```
77

78
### Pipeline Processing
79

80
Automated pipeline processing interface for batch operations and systematic data reduction.
81

82
```python { .api }
83
def process(inFile, force=False, newpath=None, num_cores=None,
84
           inmemory=True, **kwargs):
85
    """
86
    Main processing function for pipeline operations.
87

88
    Parameters:
89
    - inFile: str, input association file or observation list
90
    - force: bool, force reprocessing of existing outputs
91
    - newpath: str, output directory path
92
    - num_cores: int, number of CPU cores to use
93
    - inmemory: bool, perform processing in memory when possible
94
    - **kwargs: dict, additional processing parameters
95

96
    Returns:
97
    bool, success status
98
    """
99

100
def run_driz(inlist, trlfile, calfiles, mode='default-pipeline', **kwargs):
101
    """
102
    Core drizzling function for pipeline mode.
103

104
    Parameters:
105
    - inlist: list, input file list
106
    - trlfile: str, trailer file name for logging
107
    - calfiles: list, calibrated input files
108
    - mode: str, processing mode ('default-pipeline', 'hap', etc.)
109
    - **kwargs: dict, processing parameters
110

111
    Returns:
112
    list, output file names
113
    """
114
```
115

116
## Processing Modes
117

118
### Standard AstroDrizzle Processing
119

120
Default processing with full cosmic ray removal and image combination:
121

122
1. **Separate Drizzling** - Individual exposure processing with distortion correction
123
2. **Median Creation** - Statistical combination for cosmic ray identification
124
3. **Blotting** - Transformation of median back to original image geometry
125
4. **Cosmic Ray Detection** - Identification and flagging of cosmic ray pixels
126
5. **Final Drizzling** - Combination of cleaned images into final product
127

128
### Pipeline Processing
129

130
Automated processing optimized for large datasets:
131

132
- Minimal user interaction required
133
- Standardized parameter sets
134
- Batch processing capabilities
135
- Quality assessment integration
136

137
### HAP Processing
138

139
Hubble Advanced Products processing with enhanced algorithms:
140

141
- Advanced astrometric solutions
142
- Multi-visit processing
143
- Automated quality control
144
- Standardized product formats
145

146
## Key Processing Parameters
147

148
### Geometric Parameters
149
- **output**: Output image root name
150
- **outnx/outny**: Output image dimensions
151
- **rot**: Rotation angle for output WCS
152
- **scale**: Output pixel scale
153
- **ra/dec**: Output image center coordinates
154

155
### Cosmic Ray Parameters
156
- **driz_cr**: Enable cosmic ray detection
157
- **driz_cr_corr**: Correlation threshold
158
- **driz_cr_snr**: Signal-to-noise ratio thresholds
159
- **driz_cr_grow**: Pixel growth radius around detected CRs
160

161
### Drizzling Parameters
162
- **pixfrac**: Linear size of drop in input pixels
163
- **kernel**: Drizzling kernel ('turbo', 'square', 'lanczos3')
164
- **fillval**: Value for output pixels with no input
165

166
### Quality Control
167
- **clean**: Remove intermediate files after processing
168
- **in_memory**: Perform processing in memory
169
- **num_cores**: Parallel processing configuration
170

171
## Output Products
172

173
AstroDrizzle creates several output files:
174

175
- **_drz.fits**: Final combined image
176
- **_wht.fits**: Weight map showing coverage
177
- **_ctx.fits**: Context image showing input contributions
178
- **_sci.fits**: Science extension from combined image
179
- **_err.fits**: Error extension from combined image
180

181
## Error Handling
182

183
Common error conditions and exceptions:
184

185
- **IOError**: Invalid input files or missing calibration references
186
- **ValueError**: Incompatible WCS solutions or parameter conflicts
187
- **MemoryError**: Insufficient memory for large image processing
188
- **RuntimeError**: Convergence failures in alignment or cosmic ray detection
189

190
Processing continues with warnings for non-critical errors, with full error details logged to trailer files (.tra).