0
# WCS Transformations
1

2
World Coordinate System transformations between pixel and world coordinates for astronomical images, supporting the full FITS WCS standard.
3

4
## Capabilities
5

6
### WCS Class and Coordinate Transformations
7

8
Core WCS functionality for transforming between pixel and world coordinates in astronomical images.
9

10
```python { .api }
11
class WCS:
12
    """
13
    World Coordinate System transformation object.
14
    
15
    Parameters:
16
    - header: FITS header containing WCS keywords
17
    - fobj: file object or HDU
18
    - key: WCS key (single character, default ' ')
19
    - keysel: sequence of flags for selecting WCS keys
20
    - colsel: sequence of flags for selecting WCS axes
21
    - fix: apply standard fixes to WCS
22
    - translate_units: translate non-standard units
23
    - naxis: number of axes
24
    - relax: degree of WCS standard relaxation
25
    - hdukw: header-data unit keywords
26
    """
27
    def __init__(self, header=None, fobj=None, key=' ', keysel=None, colsel=None, 
28
                 fix=True, translate_units='', naxis=None, relax=True, hdukw=None): ...
29
    
30
    def pixel_to_world(self, *pixel_arrays):
31
        """
32
        Convert pixel coordinates to world coordinates.
33
        
34
        Parameters:
35
        - *pixel_arrays: pixel coordinate arrays
36
        
37
        Returns:
38
        tuple: world coordinate arrays or SkyCoord objects
39
        """
40
    
41
    def world_to_pixel(self, *world_arrays):
42
        """
43
        Convert world coordinates to pixel coordinates.
44
        
45
        Parameters:
46
        - *world_arrays: world coordinate arrays or SkyCoord objects
47
        
48
        Returns:
49
        tuple: pixel coordinate arrays
50
        """
51
    
52
    def all_pix2world(self, pixcrd, origin):
53
        """
54
        Convert pixel to world coordinates (lower-level interface).
55
        
56
        Parameters:
57
        - pixcrd: pixel coordinates
58
        - origin: pixel coordinate origin (0 or 1)
59
        
60
        Returns:
61
        ndarray: world coordinates
62
        """
63
    
64
    def all_world2pix(self, world, origin):
65
        """
66
        Convert world to pixel coordinates (lower-level interface).
67
        
68
        Parameters:
69
        - world: world coordinates
70
        - origin: pixel coordinate origin (0 or 1)
71
        
72
        Returns:
73
        ndarray: pixel coordinates
74
        """
75
    
76
    def footprint_to_file(self, filename='footprint.reg', color='green', width=2):
77
        """Write image footprint to DS9 region file."""
78
    
79
    def calc_footprint(self, header=None, undistort=True, axes=None, center=True):
80
        """Calculate image footprint in world coordinates."""
81
    
82
    @property
83
    def pixel_shape(self):
84
        """Shape of pixel grid."""
85
    
86
    @property
87
    def pixel_bounds(self):
88
        """Bounds of pixel coordinates."""
89
    
90
    @property
91
    def world_axis_names(self):
92
        """Names of world coordinate axes."""
93
    
94
    @property
95
    def world_axis_units(self):
96
        """Units of world coordinate axes."""
97
    
98
    @property
99
    def world_axis_physical_types(self):
100
        """Physical types of world coordinate axes."""
101
    
102
    @property
103
    def pixel_axis_names(self):
104
        """Names of pixel coordinate axes."""
105
    
106
    @property
107
    def array_shape(self):
108
        """Shape of associated data array."""
109
    
110
    def copy(self):
111
        """Create a copy of the WCS object."""
112
    
113
    def deepcopy(self):
114
        """Create a deep copy of the WCS object."""
115
    
116
    def to_header(self, relax=None, key=None):
117
        """Convert WCS to FITS header."""
118
```
119

120
### WCS Utilities and Helper Functions
121

122
Utility functions for working with WCS objects and coordinate system conversions.
123

124
```python { .api }
125
def find_all_wcs(header, relax=True, keysel=None):
126
    """
127
    Find all WCS transformations in a FITS header.
128
    
129
    Parameters:
130
    - header: FITS header
131
    - relax: degree of standard relaxation
132
    - keysel: key selection criteria
133
    
134
    Returns:
135
    list: list of WCS objects
136
    """
137

138
def wcs_to_celestial_frame(wcs):
139
    """
140
    Convert WCS to astropy coordinate frame.
141
    
142
    Parameters:
143
    - wcs: WCS object
144
    
145
    Returns:
146
    BaseCoordinateFrame: corresponding coordinate frame
147
    """
148

149
def celestial_frame_to_wcs(frame, projection='TAN'):
150
    """
151
    Convert astropy coordinate frame to WCS.
152
    
153
    Parameters:
154
    - frame: coordinate frame
155
    - projection: WCS projection type
156
    
157
    Returns:
158
    WCS: corresponding WCS object
159
    """
160

161
def proj_plane_pixel_scales(wcs):
162
    """
163
    Calculate pixel scales in projection plane.
164
    
165
    Parameters:
166
    - wcs: WCS object
167
    
168
    Returns:
169
    ndarray: pixel scales
170
    """
171

172
def proj_plane_pixel_area(wcs):
173
    """
174
    Calculate pixel area in projection plane.
175
    
176
    Parameters:
177
    - wcs: WCS object
178
    
179
    Returns:
180
    Quantity: pixel area
181
    """
182

183
def skycoord_to_pixel(coords, wcs, origin=0, mode='all'):
184
    """
185
    Convert SkyCoord to pixel coordinates.
186
    
187
    Parameters:
188
    - coords: SkyCoord object
189
    - wcs: WCS object
190
    - origin: pixel coordinate origin
191
    - mode: conversion mode
192
    
193
    Returns:
194
    tuple: pixel coordinates
195
    """
196

197
def pixel_to_skycoord(xp, yp, wcs, origin=0, mode='all', cls=None):
198
    """
199
    Convert pixel coordinates to SkyCoord.
200
    
201
    Parameters:
202
    - xp, yp: pixel coordinates
203
    - wcs: WCS object
204
    - origin: pixel coordinate origin
205
    - mode: conversion mode
206
    - cls: SkyCoord subclass
207
    
208
    Returns:
209
    SkyCoord: world coordinates
210
    """
211
```
212

213
## Usage Examples
214

215
### Basic WCS Operations
216

217
```python
218
from astropy.wcs import WCS
219
from astropy.io import fits
220
import numpy as np
221

222
# Load WCS from FITS header
223
with fits.open('image.fits') as hdul:
224
    wcs = WCS(hdul[0].header)
225
    data = hdul[0].data
226

227
# Convert pixel to world coordinates
228
x_pix, y_pix = 100, 200
229
world_coords = wcs.pixel_to_world(x_pix, y_pix)
230
print(f"Pixel ({x_pix}, {y_pix}) -> World {world_coords}")
231

232
# Convert world to pixel coordinates
233
pixel_coords = wcs.world_to_pixel(world_coords)
234
print(f"World {world_coords} -> Pixel {pixel_coords}")
235
```
236

237
### Working with Arrays
238

239
```python
240
# Convert arrays of coordinates
241
x_pixels = np.array([10, 50, 100, 150])
242
y_pixels = np.array([20, 60, 120, 180])
243

244
# Pixel to world (returns SkyCoord for celestial coordinates)
245
world_coords = wcs.pixel_to_world(x_pixels, y_pixels)
246
print(f"RA: {world_coords.ra}")
247
print(f"Dec: {world_coords.dec}")
248

249
# Lower-level interface for more control
250
world_array = wcs.all_pix2world(np.column_stack([x_pixels, y_pixels]), 0)
251
ra_deg = world_array[:, 0]
252
dec_deg = world_array[:, 1]
253
```
254

255
### Integration with Coordinates
256

257
```python
258
from astropy.coordinates import SkyCoord
259
from astropy.wcs.utils import skycoord_to_pixel, pixel_to_skycoord
260
import astropy.units as u
261

262
# Create SkyCoord objects
263
coords = SkyCoord(ra=[10.1, 20.2, 30.3]*u.degree, 
264
                  dec=[40.4, 50.5, 60.6]*u.degree)
265

266
# Convert to pixel coordinates
267
x_pix, y_pix = skycoord_to_pixel(coords, wcs)
268
print(f"Pixel coordinates: x={x_pix}, y={y_pix}")
269

270
# Convert back to SkyCoord
271
coords_back = pixel_to_skycoord(x_pix, y_pix, wcs)
272
print(f"Round-trip check: {coords.separation(coords_back).to(u.arcsec)}")
273
```
274

275
### WCS Properties and Information
276

277
```python
278
# Examine WCS properties
279
print(f"Pixel shape: {wcs.pixel_shape}")
280
print(f"World axis names: {wcs.world_axis_names}")
281
print(f"World axis units: {wcs.world_axis_units}")
282
print(f"Physical types: {wcs.world_axis_physical_types}")
283

284
# Calculate pixel scales
285
from astropy.wcs.utils import proj_plane_pixel_scales, proj_plane_pixel_area
286
pixel_scales = proj_plane_pixel_scales(wcs)
287
pixel_area = proj_plane_pixel_area(wcs)
288

289
print(f"Pixel scales: {pixel_scales * 3600} arcsec/pixel")
290
print(f"Pixel area: {pixel_area.to(u.arcsec**2)}")
291
```
292

293
### Creating Custom WCS
294

295
```python
296
from astropy.coordinates import ICRS
297
from astropy.wcs.utils import celestial_frame_to_wcs
298

299
# Create WCS from coordinate frame
300
frame = ICRS()
301
custom_wcs = celestial_frame_to_wcs(frame, projection='TAN')
302

303
# Set reference pixel and coordinate
304
custom_wcs.wcs.crpix = [512, 512]  # Reference pixel
305
custom_wcs.wcs.crval = [180.0, 45.0]  # Reference coordinate (RA, Dec)
306
custom_wcs.wcs.cdelt = [-0.1/3600, 0.1/3600]  # Pixel scale (degrees)
307
custom_wcs.wcs.ctype = ['RA---TAN', 'DEC--TAN']  # Coordinate types
308

309
# Use custom WCS
310
test_coord = custom_wcs.pixel_to_world(512, 512)
311
print(f"Reference coordinate: {test_coord}")
312
```