0
# WCS and Region Management
1

2
World Coordinate System utilities, region file mapping, and WCS solution management for complex astronomical workflows. These tools provide sophisticated coordinate system handling, region transformation capabilities, and WCS construction for HST observations.
3

4
## Capabilities
5

6
### WCS Solution Management
7

8
Apply updated WCS solutions from combined images back to constituent individual exposures with comprehensive headerlet management.
9

10
```python { .api }
11
def apply_tweak(drz_file, orig_wcs_name, output_wcs_name=None,
12
               input_files=None, **kwargs):
13
    """
14
    Apply WCS solutions from drizzled to individual images.
15

16
    Parameters:
17
    - drz_file: str, drizzled image with updated WCS
18
    - orig_wcs_name: str, original WCS solution name
19
    - output_wcs_name: str, name for updated WCS solution
20
    - input_files: list, specific input files to update
21
    - **kwargs: dict, additional WCS update parameters
22

23
    Returns:
24
    None (updates input file headers)
25
    """
26

27
def tweakback(drzfile, input=None, origwcs=None, newname=None,
28
              wcsname=None, extname='SCI', **kwargs):
29
    """
30
    Main interface for applying updated WCS solutions.
31

32
    Parameters:
33
    - drzfile: str, combined image filename with reference WCS
34
    - input: str or list, input exposures to update
35
    - origwcs: str, original WCS solution identifier
36
    - newname: str, name for new WCS solution
37
    - wcsname: str, WCS solution name in drizzled image
38
    - extname: str, extension name containing WCS
39
    - **kwargs: dict, processing parameters
40

41
    Returns:
42
    None (modifies input exposure headers)
43
    """
44

45
def run(configobj):
46
    """
47
    Processing function for tweakback task.
48

49
    Parameters:
50
    - configobj: ConfigObj, configuration with WCS update parameters
51

52
    Returns:
53
    None (applies WCS updates)
54
    """
55
```
56

57
### Region File Mapping
58

59
Map DS9 region files to multiple images based on WCS information, enabling region analysis across different observations and coordinate systems.
60

61
```python { .api }
62
def MapReg(input_reg, images, img_wcs_ext='sci', refimg='',
63
          ref_wcs_ext='sci', **kwargs):
64
    """
65
    Main interface for mapping DS9 regions to images.
66

67
    Parameters:
68
    - input_reg: str, input DS9 region filename
69
    - images: str or list, target images for region mapping
70
    - img_wcs_ext: str, WCS extension in target images
71
    - refimg: str, reference image for coordinate system
72
    - ref_wcs_ext: str, WCS extension in reference image
73
    - **kwargs: dict, mapping parameters
74

75
    Returns:
76
    list, output region filenames for each image
77
    """
78

79
def map_region_files(input_reg, images, img_wcs_ext='sci', **kwargs):
80
    """
81
    Core region mapping functionality.
82

83
    Parameters:
84
    - input_reg: str, DS9 region file to map
85
    - images: list, target image list
86
    - img_wcs_ext: str, WCS extension identifier
87
    - **kwargs: dict, transformation parameters
88

89
    Returns:
90
    dict, mapping results and statistics
91
    """
92

93
def run(configObj):
94
    """
95
    Processing function for mapreg task.
96

97
    Parameters:
98
    - configObj: ConfigObj, configuration with region mapping parameters
99

100
    Returns:
101
    None (creates mapped region files)
102
    """
103
```
104

105
### WCS Construction and Building
106

107
Build custom WCS solutions and reference frames for specialized processing requirements.
108

109
```python { .api }
110
def buildwcs(outwcs, configObj=None, editpars=False, **input_dict):
111
    """
112
    Main interface for WCS construction.
113

114
    Parameters:
115
    - outwcs: str, output WCS specification
116
    - configObj: ConfigObj, configuration object
117
    - editpars: bool, allow interactive parameter editing
118
    - **input_dict: dict, WCS construction parameters
119

120
    Returns:
121
    None (creates WCS solution)
122
    """
123

124
def build(outname, wcsname, refimage, undistort=False, **kwargs):
125
    """
126
    Core WCS building functionality.
127

128
    Parameters:
129
    - outname: str, output WCS filename
130
    - wcsname: str, WCS solution name
131
    - refimage: str, reference image for WCS construction
132
    - undistort: bool, remove distortion from WCS
133
    - **kwargs: dict, construction parameters
134

135
    Returns:
136
    WCS, constructed world coordinate system
137
    """
138

139
def run(configObj, wcsmap=None):
140
    """
141
    Processing function for buildwcs task.
142

143
    Parameters:
144
    - configObj: ConfigObj, configuration with WCS parameters
145
    - wcsmap: function, optional WCS mapping function
146

147
    Returns:
148
    None (creates WCS products)
149
    """
150
```
151

152
## Usage Examples
153

154
### Applying WCS Solutions
155

156
```python
157
from drizzlepac import tweakback
158

159
# Apply updated WCS from combined image to input exposures
160
tweakback.tweakback('combined_drz.fits',
161
                   input=['exp1_flt.fits', 'exp2_flt.fits'],
162
                   origwcs='OPUS',
163
                   newname='TWEAKREG',
164
                   wcsname='DRZWCS')
165

166
# Apply specific WCS solution
167
tweakback.apply_tweak('j8bt06_drz.fits',
168
                     orig_wcs_name='OPUS',
169
                     output_wcs_name='ALIGNED',
170
                     input_files=['j8bt06nyq_flt.fits', 'j8bt06nzq_flt.fits'])
171
```
172

173
### Mapping DS9 Regions
174

175
```python
176
from drizzlepac import mapreg
177

178
# Map regions to multiple images
179
region_files = mapreg.MapReg('source_regions.reg',
180
                            images=['image1.fits', 'image2.fits', 'image3.fits'],
181
                            img_wcs_ext='sci',
182
                            refimg='image1.fits')
183

184
# Map regions with custom parameters
185
mapreg.map_region_files('apertures.reg',
186
                       ['acs_1.fits[sci,1]', 'acs_2.fits[sci,1]'],
187
                       img_wcs_ext='sci',
188
                       tolerance=0.1)  # arcsec tolerance
189
```
190

191
### Building Custom WCS
192

193
```python
194
from drizzlepac import buildwcs
195

196
# Build WCS for custom mosaic
197
buildwcs.buildwcs('custom_wcs.fits',
198
                 configobj=None,
199
                 outnx=4096,
200
                 outny=4096,
201
                 scale=0.05,      # arcsec/pixel
202
                 rot=0.0,         # degrees
203
                 ra=83.633,       # degrees
204
                 dec=22.015)      # degrees
205

206
# Build undistorted WCS
207
buildwcs.build('undistorted_wcs.fits',
208
              'UNDIST',
209
              'reference_image.fits',
210
              undistort=True)
211
```
212

213
## DS9 Region Support
214

215
### Supported Region Types
216

217
DrizzlePac region mapping supports standard DS9 region formats:
218

219
- **Circle**: `circle(ra, dec, radius)`
220
- **Ellipse**: `ellipse(ra, dec, semi_major, semi_minor, angle)`
221
- **Box**: `box(ra, dec, width, height, angle)`
222
- **Polygon**: `polygon(ra1, dec1, ra2, dec2, ...)`
223
- **Point**: `point(ra, dec)`
224

225
### Coordinate Systems
226

227
Region mapping handles multiple coordinate systems:
228
- **FK5**: J2000.0 equatorial coordinates
229
- **FK4**: B1950.0 equatorial coordinates
230
- **Galactic**: Galactic longitude and latitude
231
- **Ecliptic**: Ecliptic coordinates
232
- **Image**: Pixel coordinates
233

234
### Example Region File
235

236
```
237
# Region file format: DS9 version 4.1
238
# Filename: source_apertures.reg
239
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman"
240
fk5
241
circle(83.633128, 22.014533, 2") # color=red
242
ellipse(83.630245, 22.012891, 3", 2", 45) # color=blue
243
box(83.628102, 22.015234, 4", 4", 0) # color=yellow
244
```
245

246
## WCS Headerlet Management
247

248
### Headerlet Operations
249

250
DrizzlePac integrates with STWCS headerlet functionality:
251

252
```python
253
# Create headerlet from current WCS
254
from stwcs import headerlet
255

256
# Extract WCS as headerlet
257
headerlet.extract_headerlet('image.fits', 'wcs_solution.fits')
258

259
# Apply headerlet to image
260
headerlet.apply_headerlet('image.fits', 'new_wcs.fits')
261

262
# Archive WCS solution
263
headerlet.archive_headerlet('image.fits', 'backup_wcs.fits')
264
```
265

266
### WCS Solution Names
267

268
Standard WCS solution naming conventions:
269
- **OPUS**: Original pipeline WCS from calibration
270
- **DRZWCS**: WCS from drizzled image combination
271
- **TWEAKREG**: WCS updated by TweakReg alignment
272
- **TWEAK**: Updated alignment solution
273
- **HSC30**: Hubble Source Catalog astrometry
274

275
## Advanced WCS Operations
276

277
### Multi-Extension WCS
278

279
Handling WCS for multi-extension FITS files:
280

281
```python
282
from drizzlepac import tweakback
283

284
# Apply WCS to specific extensions
285
tweakback.tweakback('mosaic_drz.fits',
286
                   input='multi_ext.fits',
287
                   ext_list=[1, 2, 3, 4],  # Process extensions 1-4
288
                   newname='ALIGNED_WCS')
289
```
290

291
### WCS Transformation Chains
292

293
Complex coordinate transformations:
294

295
```python
296
# Chain multiple WCS transformations
297
from astropy import wcs
298
from drizzlepac import wcs_functions
299

300
# Load WCS solutions
301
wcs1 = wcs.WCS('image1.fits[sci,1]')
302
wcs2 = wcs.WCS('image2.fits[sci,1]')
303

304
# Transform coordinates through WCS chain
305
ra, dec = wcs1.all_pix2world(x, y, 1)
306
x_new, y_new = wcs2.all_world2pix(ra, dec, 1)
307
```
308

309
### Distortion Handling
310

311
WCS construction with distortion correction:
312

313
```python
314
from drizzlepac import buildwcs
315

316
# Build WCS preserving distortion
317
buildwcs.build('with_distortion.fits',
318
              'DISTORTED',
319
              'reference.fits',
320
              undistort=False)
321

322
# Build linearized WCS
323
buildwcs.build('linear_wcs.fits',
324
              'LINEAR',
325
              'reference.fits',
326
              undistort=True)
327
```
328

329
## Quality Control
330

331
### WCS Validation
332

333
Validation checks for WCS solutions:
334

335
```python
336
# Check WCS consistency
337
from drizzlepac import wcs_functions
338

339
def validate_wcs(image, tolerance=0.1):
340
    """
341
    Validate WCS solution quality.
342

343
    Parameters:
344
    - image: str, image with WCS to validate
345
    - tolerance: float, allowed coordinate deviation (arcsec)
346

347
    Returns:
348
    bool, WCS validation status
349
    """
350
    # Implementation checks coordinate accuracy,
351
    # distortion model validity, and transformation consistency
352
    pass
353
```
354

355
### Region Mapping Quality
356

357
Quality assessment for region mapping:
358

359
- **Coordinate Accuracy**: Verify transformed region positions
360
- **Coverage Validation**: Check region overlap with image boundaries
361
- **Distortion Effects**: Account for coordinate transformation accuracy
362

363
## Error Handling
364

365
### Common WCS Errors
366

367
- **WCSError**: Invalid or missing WCS information
368
- **HeaderletError**: Headerlet creation or application failures
369
- **RegionError**: Region file format or coordinate system issues
370
- **TransformationError**: Coordinate transformation failures
371

372
### Recovery Strategies
373

374
```python
375
from drizzlepac import tweakback
376

377
try:
378
    tweakback.tweakback('combined.fits', input='exposure.fits')
379
except Exception as e:
380
    print(f"WCS update failed: {e}")
381
    # Fall back to original WCS or alternative solution
382
```
383

384
## Best Practices
385

386
### WCS Management
387
1. **Backup original WCS** before applying updates
388
2. **Document WCS solution names** and provenance
389
3. **Validate WCS accuracy** after transformations
390
4. **Use appropriate coordinate systems** for scientific analysis
391

392
### Region Mapping
393
1. **Verify region coordinate systems** match expectations
394
2. **Account for distortion effects** in precise measurements
395
3. **Validate mapped regions** against expected positions
396
4. **Use appropriate tolerances** for coordinate matching
397

398
### Performance Optimization
399
1. **Cache WCS solutions** for repeated operations
400
2. **Process regions in batches** for efficiency
401
3. **Use appropriate coordinate precisions** for the analysis
402
4. **Minimize coordinate transformations** when possible