0
# Coordinate Transformations
1

2
Bidirectional coordinate transformation capabilities between pixel coordinates, sky coordinates, and different WCS reference frames. These tools provide full distortion correction and support both interactive use and batch processing of coordinate lists.
3

4
## Capabilities
5

6
### Pixel to Sky Coordinate Transformation
7

8
Convert pixel positions to sky coordinates (RA/Dec) with full distortion correction as appropriate for the instrument and observation.
9

10
```python { .api }
11
def xy2rd(input, x=None, y=None, coords=None, coordfile=None,
12
          colnames=None, separator=None, precision=10, output=None,
13
          verbose=True):
14
    """
15
    Convert pixel positions to sky coordinates.
16

17
    Parameters:
18
    - input: str, input image filename
19
    - x: float or list, X pixel coordinates
20
    - y: float or list, Y pixel coordinates
21
    - coords: str, coordinate string "x,y" format
22
    - coordfile: str, file containing pixel coordinates
23
    - colnames: list, column names for coordinate file
24
    - separator: str, delimiter for coordinate file
25
    - precision: int, decimal precision for output coordinates
26
    - output: str, output file name for results
27
    - verbose: bool, print coordinate transformations
28

29
    Returns:
30
    list, sky coordinates as [(ra, dec), ...] tuples
31
    """
32

33
def run(configObj):
34
    """
35
    Processing function for pixtosky task.
36

37
    Parameters:
38
    - configObj: ConfigObj, configuration with transformation parameters
39

40
    Returns:
41
    None (prints or saves coordinate results)
42
    """
43
```
44

45
### Sky to Pixel Coordinate Transformation
46

47
Convert sky positions (RA/Dec) to pixel positions in an image using the image's WCS information.
48

49
```python { .api }
50
def rd2xy(input, ra=None, dec=None, coordfile=None, colnames=None,
51
          precision=6, output=None, verbose=True):
52
    """
53
    Convert sky positions to pixel positions.
54

55
    Parameters:
56
    - input: str, input image filename
57
    - ra: float or list, Right Ascension coordinates (degrees)
58
    - dec: float or list, Declination coordinates (degrees)
59
    - coordfile: str, file containing sky coordinates
60
    - colnames: list, column names for coordinate file
61
    - precision: int, decimal precision for output coordinates (default: 6)
62
    - output: str, output file name for results
63
    - verbose: bool, print coordinate transformations (default: True)
64

65
    Returns:
66
    tuple, (x, y) arrays or single values in pixels
67
    """
68

69
def run(configObj):
70
    """
71
    Processing function for skytopix task.
72

73
    Parameters:
74
    - configObj: ConfigObj, configuration with transformation parameters
75

76
    Returns:
77
    None (prints or saves coordinate results)
78
    """
79
```
80

81
### Pixel-to-Pixel Coordinate Transformation
82

83
Transform pixel coordinates from one image to another, accounting for different WCS solutions, orientations, and scales.
84

85
```python { .api }
86
def tran(inimage, outimage, direction='forward', x=None, y=None,
87
         coords=None, coordfile=None, colnames=None, separator=None,
88
         precision=10, output=None, verbose=True):
89
    """
90
    Transform pixel coordinates between images.
91

92
    Parameters:
93
    - inimage: str, input image filename
94
    - outimage: str, output image filename or WCS reference
95
    - direction: str, transformation direction ('forward' or 'backward')
96
    - x: float or list, X pixel coordinates in input image
97
    - y: float or list, Y pixel coordinates in input image
98
    - coords: str, coordinate string "x,y" format
99
    - coordfile: str, file containing pixel coordinates
100
    - colnames: list, column names for coordinate file
101
    - separator: str, delimiter for coordinate file
102
    - precision: int, decimal precision for output coordinates
103
    - output: str, output file name for results
104
    - verbose: bool, print coordinate transformations
105

106
    Returns:
107
    list, transformed coordinates as [(x, y), ...] tuples
108
    """
109

110
def run(configObj):
111
    """
112
    Processing function for pixtopix task.
113

114
    Parameters:
115
    - configObj: ConfigObj, configuration with transformation parameters
116

117
    Returns:
118
    None (prints or saves coordinate results)
119
    """
120
```
121

122
## Usage Examples
123

124
### Interactive Coordinate Transformation
125

126
```python
127
from drizzlepac import pixtosky, skytopix, pixtopix
128

129
# Convert single pixel position to sky coordinates
130
ra, dec = pixtosky.xy2rd('j8bt06nyq_flt.fits[sci,1]', x=512, y=512)
131
print(f"RA: {ra[0]:.6f}, Dec: {dec[0]:.6f}")
132

133
# Convert sky position back to pixels
134
x, y = skytopix.rd2xy('j8bt06nyq_flt.fits[sci,1]', ra=ra[0], dec=dec[0])
135
print(f"X: {x[0]:.2f}, Y: {y[0]:.2f}")
136

137
# Transform pixels between different images
138
x_out, y_out = pixtopix.tran('input.fits[sci,1]', 'output.fits[sci,1]',
139
                            x=100, y=200)
140
print(f"Transformed: X={x_out[0]:.2f}, Y={y_out[0]:.2f}")
141
```
142

143
### Batch Coordinate Processing
144

145
```python
146
from drizzlepac import pixtosky
147

148
# Process coordinate file
149
pixtosky.xy2rd('image.fits[sci,1]',
150
              coordfile='pixels.txt',
151
              colnames=['X_IMAGE', 'Y_IMAGE'],
152
              separator=',',
153
              output='skycoords.txt')
154
```
155

156
### Using Multiple Extensions
157

158
```python
159
from drizzlepac import pixtosky
160

161
# Transform coordinates for multiple chip extensions
162
for ext in range(1, 5):
163
    ra, dec = pixtosky.xy2rd(f'acs_image.fits[sci,{ext}]',
164
                            x=512, y=512)
165
    print(f"Chip {ext}: RA={ra[0]:.6f}, Dec={dec[0]:.6f}")
166
```
167

168
## Coordinate File Formats
169

170
### Input File Format
171

172
Coordinate files can be ASCII text with customizable delimiters:
173

174
```
175
# X_pixel  Y_pixel
176
100.5     200.3
177
250.1     150.7
178
400.0     300.0
179
```
180

181
### Output File Format
182

183
Results include original coordinates and transformed values:
184

185
```
186
# Input coordinates and transformed sky positions
187
# X_pixel  Y_pixel  RA_deg      Dec_deg
188
100.5     200.3    83.633128   22.014533
189
250.1     150.7    83.630245   22.012891
190
400.0     300.0    83.628102   22.015234
191
```
192

193
## Supported Extensions and Formats
194

195
### FITS Extensions
196

197
All coordinate transformation tasks support:
198
- **Science extensions**: `[SCI,n]`
199
- **Primary extensions**: `[0]`
200
- **Named extensions**: `[EXTNAME,EXTVER]`
201

202
### Multi-Extension FITS (MEF)
203

204
For instruments with multiple detectors:
205
- **ACS/WFC**: Extensions 1 and 2 for WFC1 and WFC2
206
- **WFC3/UVIS**: Extensions 1 and 2 for UVIS1 and UVIS2
207
- **WFPC2**: Extensions 1-4 for PC1, WF2, WF3, WF4
208

209
## WCS Distortion Correction
210

211
### Distortion Models Supported
212

213
- **Simple Imaging Polynomial (SIP)**: Standard HST distortion correction
214
- **Lookup Tables**: Pixel-based distortion corrections
215
- **Polynomial**: Classical polynomial distortion models
216
- **Paper IV**: Advanced distortion conventions
217

218
### Instrument-Specific Corrections
219

220
Each HST instrument has specialized distortion handling:
221
- **ACS**: CTE corrections and filter-dependent distortions
222
- **WFC3**: UVIS and IR channel-specific corrections
223
- **WFPC2**: Historic distortion models with geometric corrections
224
- **STIS**: Spectroscopic distortion corrections
225
- **NICMOS**: IR-specific geometric distortions
226

227
## Error Handling
228

229
### Common Exceptions
230

231
- **IOError**: Missing or unreadable input images
232
- **ValueError**: Invalid coordinate values or file formats
233
- **WCSError**: Corrupted or missing WCS information
234
- **KeyError**: Missing required FITS header keywords
235

236
### Error Recovery
237

238
```python
239
from drizzlepac import pixtosky
240

241
try:
242
    ra, dec = pixtosky.xy2rd('image.fits', x=512, y=512)
243
except Exception as e:
244
    print(f"Coordinate transformation failed: {e}")
245
    # Handle error or use alternative method
246
```
247

248
### Validation Checks
249

250
- Coordinate bounds checking against image dimensions
251
- WCS validity verification
252
- Extension existence validation
253
- Coordinate format validation
254

255
## Advanced Usage
256

257
### Custom Column Names
258

259
```python
260
from drizzlepac import skytopix
261

262
# Use custom column names in input file
263
skytopix.rd2xy('image.fits',
264
              coordfile='catalog.txt',
265
              colnames=['RA', 'DEC'],
266
              separator='\t',
267
              output='pixel_coords.txt')
268
```
269

270
### High Precision Transformations
271

272
```python
273
from drizzlepac import pixtosky
274

275
# Maximum precision output
276
ra, dec = pixtosky.xy2rd('image.fits', x=512.123, y=512.456,
277
                        precision=12)
278
```
279

280
### Coordinate System Transformations
281

282
DrizzlePac coordinate transformations automatically handle:
283
- **Epoch conversions** between observation epochs
284
- **Reference frame transformations** (FK5, ICRS)
285
- **Proper motion corrections** when available in headers
286
- **Distortion corrections** specific to each observation