0
# Registration and Alignment
1

2
Advanced algorithms for computing offsets between images and reference frames. TweakReg provides robust source-based alignment with multiple fitting algorithms and comprehensive quality assessment, replacing the legacy IRAF tweakshifts task with enhanced capabilities for HST data.
3

4
## Capabilities
5

6
### TweakReg - Image Registration
7

8
Computes offsets in WCS between images and a reference image or reference frame using source catalogs and various fitting algorithms.
9

10
```python { .api }
11
def TweakReg(files=None, editpars=False, configobj=None,
12
            imagefindcfg=None, refimagefindcfg=None, **input_dict):
13
    """
14
    Main interface for image registration and alignment.
15

16
    Parameters:
17
    - files: str or list, input images to align
18
    - editpars: bool, allow interactive parameter editing
19
    - configobj: ConfigObj, configuration object with parameters
20
    - imagefindcfg: ConfigObj, parameters for finding sources in input images
21
    - refimagefindcfg: ConfigObj, parameters for finding sources in reference
22
    - **input_dict: dict, parameter overrides
23

24
    Returns:
25
    None (updates image WCS headers)
26
    """
27

28
def run(configobj):
29
    """
30
    Primary Python interface for image registration.
31

32
    Parameters:
33
    - configobj: ConfigObj, configuration with all alignment parameters
34

35
    Returns:
36
    None (updates image WCS headers)
37
    """
38
```
39

40
### Source Detection and Catalog Generation
41

42
Automatic source detection and catalog creation for alignment purposes.
43

44
```python { .api }
45
def generateCatalog(wcs, mode='automatic', catalog=None, **kwargs):
46
    """
47
    Generate source catalogs from images for alignment.
48

49
    Parameters:
50
    - wcs: WCS object, world coordinate system for image
51
    - mode: str, detection mode ('automatic', 'manual')
52
    - catalog: str, external catalog file path
53
    - **kwargs: dict, source detection parameters
54

55
    Returns:
56
    Catalog object
57
    """
58

59
class Catalog:
60
    """
61
    Base catalog class for source management.
62
    """
63

64
class ImageCatalog(Catalog):
65
    """
66
    Image-derived source catalogs.
67
    """
68

69
class UserCatalog(Catalog):
70
    """
71
    User-provided source catalogs.
72
    """
73

74
class RefCatalog(UserCatalog):
75
    """
76
    Reference catalogs for alignment.
77
    """
78
```
79

80
### High-Level Alignment Interface
81

82
Enhanced alignment capabilities with quality assessment and multiple fitting methods.
83

84
```python { .api }
85
def perform_align(input_list, **pars):
86
    """
87
    Main alignment function with quality assessment.
88

89
    Parameters:
90
    - input_list: list, input images to align
91
    - **pars: dict, alignment parameters including:
92
        - catalog: str, reference catalog type
93
        - fit_mode: str, fitting algorithm
94
        - minobj: int, minimum sources required
95
        - searchrad: float, search radius in arcsec
96

97
    Returns:
98
    dict, alignment results and quality metrics
99
    """
100

101
def check_and_get_data(input_list, **pars):
102
    """
103
    Data validation and retrieval for alignment.
104

105
    Parameters:
106
    - input_list: list, input file specifications
107
    - **pars: dict, validation parameters
108

109
    Returns:
110
    list, validated and processed input data
111
    """
112

113
def determine_fit_quality(**kwargs):
114
    """
115
    Quality assessment for alignment solutions.
116

117
    Parameters:
118
    - **kwargs: dict, fit results and quality metrics
119

120
    Returns:
121
    dict, quality assessment results
122
    """
123

124
def generate_astrometric_catalog(imglist, **pars):
125
    """
126
    Generate reference catalogs for alignment.
127

128
    Parameters:
129
    - imglist: list, input image list
130
    - **pars: dict, catalog generation parameters
131

132
    Returns:
133
    str, reference catalog filename
134
    """
135
```
136

137
## Alignment Methods
138

139
### Default Fit (General Linear)
140

141
Standard linear transformation fitting suitable for most cases:
142

143
```python
144
# Configuration for default fitting
145
fit_mode = 'default'
146
fitgeometry = 'rscale'  # rotation + scale
147
minobj = 15  # minimum sources for fit
148
```
149

150
### Relative Fit
151

152
Relative alignment between images without external reference:
153

154
```python { .api }
155
def match_relative_fit(imglist, reference_catalog, **fit_pars):
156
    """
157
    Relative alignment between images.
158

159
    Parameters:
160
    - imglist: list, input images to align
161
    - reference_catalog: str, reference catalog for alignment
162
    - **fit_pars: dict, fitting parameters
163

164
    Returns:
165
    dict, alignment transformation parameters
166
    """
167
```
168

169
### 2D Histogram Fit
170

171
Advanced fitting method using 2D histograms for robust alignment:
172

173
```python { .api }
174
def match_2dhist_fit(imglist, reference_catalog, **fit_pars):
175
    """
176
    2D histogram-based alignment.
177

178
    Parameters:
179
    - imglist: list, input images to align
180
    - reference_catalog: str, reference catalog for alignment
181
    - **fit_pars: dict, fitting parameters including:
182
        - searchrad: float, search radius
183
        - tolerance: float, matching tolerance
184
        - use2dhist: bool, enable 2D histogram method
185

186
    Returns:
187
    dict, alignment transformation parameters
188
    """
189
```
190

191
### Default Fit
192

193
Standard alignment algorithm with general linear transformation:
194

195
```python { .api }
196
def match_default_fit(imglist, reference_catalog, **fit_pars):
197
    """
198
    Default alignment algorithm.
199

200
    Parameters:
201
    - imglist: list, input images to align
202
    - reference_catalog: str, reference catalog for alignment
203
    - **fit_pars: dict, fitting parameters
204

205
    Returns:
206
    dict, alignment transformation parameters
207
    """
208
```
209

210
## Parameter Configuration
211

212
### Image Source Finding Parameters
213

214
Configuration for detecting sources in input images:
215

216
```python { .api }
217
class imagefindpars:
218
    """
219
    Parameters for finding point sources in input images.
220

221
    Attributes:
222
    - computesig: bool, compute sigma from image data
223
    - skysigma: float, background sigma value
224
    - conv_width: float, convolution kernel width
225
    - threshold: float, detection threshold
226
    - dqbits: str, DQ bits to ignore
227
    - fwhm: float, expected FWHM of sources
228
    """
229
```
230

231
### Reference Source Finding Parameters
232

233
Configuration for detecting sources in reference images:
234

235
```python { .api }
236
class refimagefindpars:
237
    """
238
    Parameters for finding sources in reference images.
239

240
    Attributes:
241
    - computesig: bool, compute sigma from image data
242
    - skysigma: float, background sigma value
243
    - conv_width: float, convolution kernel width
244
    - threshold: float, detection threshold
245
    - dqbits: str, DQ bits to ignore
246
    - fwhm: float, expected FWHM of sources
247
    """
248
```
249

250
## Usage Examples
251

252
### Basic TweakReg Alignment
253

254
```python
255
from drizzlepac import tweakreg
256

257
# Align multiple images to first image
258
tweakreg.TweakReg(['j8bt06nyq_flt.fits', 'j8bt06nzq_flt.fits'],
259
                  refimage='j8bt06nyq_flt.fits[sci,1]',
260
                  fitgeometry='rscale',
261
                  minobj=15,
262
                  searchrad=1.0,
263
                  threshold=4.0,
264
                  interactive=False)
265
```
266

267
### Advanced Alignment with External Catalog
268

269
```python
270
from drizzlepac import tweakreg, align
271

272
# Use external astrometric catalog
273
align.perform_align(['image1.fits', 'image2.fits'],
274
                   catalog='GAIADR2',
275
                   clobber=True,
276
                   fitgeometry='rscale',
277
                   nclip=3,
278
                   sigma=3.0)
279
```
280

281
### Pipeline Alignment
282

283
```python
284
from drizzlepac.align import perform_align
285

286
# Automated alignment for pipeline processing
287
results = perform_align(input_files,
288
                       catalog='GAIADR3',
289
                       fit_mode='match_default_fit',
290
                       searchrad=250.0,  # milliarcsec
291
                       minobj=6,
292
                       fitgeometry='rscale',
293
                       nclip=3,
294
                       sigma=3.0)
295
```
296

297
## Alignment Quality Assessment
298

299
TweakReg provides comprehensive quality metrics:
300

301
### Fit Statistics
302
- **RMS**: Root mean square of residuals
303
- **NMATCHES**: Number of matched sources
304
- **FIT_RMS**: RMS of final fit
305
- **MAX_RESID**: Maximum residual
306

307
### Quality Flags
308
- **FIT_QUAL**: Overall fit quality assessment
309
- **MATCH_QUAL**: Source matching quality
310
- **WCS_UPD**: WCS update status
311

312
## WCS Update and Management
313

314
### Applying Alignment Results
315

316
```python { .api }
317
def update_image_wcs_info(tweakwcs_output, headerlet_filenames=None, **kwargs):
318
    """
319
    Update WCS information after alignment.
320

321
    Parameters:
322
    - tweakwcs_output: dict, alignment results from TweakWCS
323
    - headerlet_filenames: list, output headerlet file names
324
    - **kwargs: dict, update parameters
325

326
    Returns:
327
    None (updates image headers)
328
    """
329
```
330

331
### Alignment Tables
332

333
```python { .api }
334
class AlignmentTable:
335
    """
336
    Manage alignment solutions and transformations.
337

338
    Methods:
339
    - add_fit(): Add alignment fit results
340
    - get_fit(): Retrieve fit parameters
341
    - apply_fit(): Apply transformation to coordinates
342
    - write(): Save alignment table to file
343
    """
344
```
345

346
## Error Handling
347

348
Common alignment errors and exceptions:
349

350
- **ValueError**: Insufficient sources for alignment or incompatible parameters
351
- **RuntimeError**: Convergence failure in fitting algorithms
352
- **IOError**: Missing or corrupted input images
353
- **WCSError**: Invalid or incompatible WCS solutions
354

355
Quality assessment flags indicate alignment success and reliability for automated processing workflows.