0
# Survey and Image Services
1

2
Services for accessing astronomical survey data, image cutouts, and all-sky survey information across multiple wavelengths. These services provide essential imaging data for source identification, morphological studies, and multi-wavelength analysis.
3

4
## Capabilities
5

6
### SkyView - All-Sky Survey Images
7

8
SkyView provides access to images from numerous all-sky surveys spanning radio to gamma-ray wavelengths, enabling comprehensive multi-wavelength studies of astronomical objects and regions.
9

10
```python { .api }
11
from astroquery.skyview import SkyView
12

13
def get_images(position: Union[SkyCoord, str], survey: Union[str, List[str]],
14
              coordinates: str = 'J2000', projection: str = 'Tan', 
15
              pixels: Union[int, List[int]] = 300, scaling: str = 'Linear',
16
              sampler: str = 'Spline', resolver: str = 'SIMBAD-NED',
17
              deedger: str = 'skyview.geometry.Deedger',
18
              lut: str = 'colortables/b-w-linear.bin', 
19
              grid: bool = False, gridlabels: bool = True,
20
              radius: Union[Quantity, str] = None, width: Union[Quantity, str] = None,
21
              height: Union[Quantity, str] = None) -> List:
22
    """
23
    Download survey images for a sky position.
24
    
25
    Parameters:
26
    - position: Target position as SkyCoord or string  
27
    - survey: Survey name(s) to query
28
    - coordinates: Coordinate system ('J2000', 'B1950', 'Galactic')
29
    - projection: Map projection ('Tan', 'Sin', 'Arc', etc.)
30
    - pixels: Image size in pixels (int or [width, height])
31
    - scaling: Intensity scaling ('Linear', 'Log', 'Sqrt', 'HistEq')
32
    - sampler: Resampling algorithm ('Spline', 'NN', 'Clip')
33
    - resolver: Name resolver service
34
    - deedger: Edge removal algorithm
35
    - lut: Color lookup table
36
    - grid: Overlay coordinate grid
37
    - gridlabels: Show grid labels
38
    - radius: Image radius (circular)
39
    - width: Image width (rectangular)
40
    - height: Image height (rectangular)
41
    
42
    Returns:
43
    List of HDUList objects with survey images
44
    """
45

46
def get_images_async(position: Union[SkyCoord, str], survey: Union[str, List[str]],
47
                    **kwargs) -> JobResults:
48
    """
49
    Submit asynchronous request for survey images.
50
    
51
    Parameters:
52
    - position: Target position
53
    - survey: Survey name(s)
54
    - **kwargs: Additional image parameters
55
    
56
    Returns:
57
    JobResults object for retrieving images
58
    """
59

60
def list_surveys() -> List[str]:
61
    """
62
    Get list of available surveys.
63
    
64
    Returns:
65
    List of survey names
66
    """
67

68
def survey_dict() -> Dict[str, Dict]:
69
    """
70
    Get detailed information about available surveys.
71
    
72
    Returns:
73
    Dictionary with survey metadata
74
    """
75

76
# Configuration
77
from astroquery.skyview import conf
78
conf.server: str              # SkyView server URL
79
conf.timeout: int = 600       # Connection timeout (images can be large)
80
```
81

82
Usage examples:
83

84
```python
85
from astroquery.skyview import SkyView
86
import astropy.units as u
87
from astropy.coordinates import SkyCoord
88

89
# Get optical image of M31
90
coords = SkyCoord('00h42m44s', '+41d16m09s', frame='icrs')
91
images = SkyView.get_images(coords, survey='DSS', pixels=800)
92
optical_image = images[0]  # First (and only) image
93
print(f"Image shape: {optical_image[0].data.shape}")
94

95
# Multi-wavelength images
96
surveys = ['DSS', '2MASS-J', 'WISE 3.4', 'ROSAT']
97
multi_images = SkyView.get_images('NGC 1068', survey=surveys, 
98
                                 pixels=400, radius=10*u.arcmin)
99
for i, survey in enumerate(surveys):
100
    print(f"{survey}: {multi_images[i][0].data.shape}")
101

102
# Radio survey image with custom parameters
103
radio_image = SkyView.get_images('Cas A', survey='1420MHz (Bonn)', 
104
                                pixels=[512, 512], scaling='Log',
105
                                width=2*u.deg, height=2*u.deg)
106

107
# List available surveys  
108
surveys = SkyView.list_surveys()
109
print(f"Available surveys: {len(surveys)}")
110
optical_surveys = [s for s in surveys if 'optical' in s.lower()]
111

112
# Get survey metadata
113
survey_info = SkyView.survey_dict()
114
print("DSS info:", survey_info['DSS'])
115
```
116

117
### HiPS2FITS - Hierarchical Progressive Survey Conversion
118

119
HiPS2FITS converts Hierarchical Progressive Survey (HiPS) data to FITS format, enabling access to large-scale survey data with arbitrary field sizes and resolutions.
120

121
```python { .api }
122
from astroquery.hips2fits import Hips2fitsClass
123

124
def query_with_wcs(hips: str, wcs, get_query_payload: bool = False,
125
                  format: str = 'fits', min_cut: float = 0.5, 
126
                  max_cut: float = 99.5, stretch: str = 'linear',
127
                  colormap: str = 'grayscale', **kwargs) -> HDUList:
128
    """
129
    Query HiPS data using a World Coordinate System specification.
130
    
131
    Parameters:
132
    - hips: HiPS survey identifier or URL
133
    - wcs: World Coordinate System object defining the output projection
134
    - get_query_payload: Return query parameters instead of executing
135
    - format: Output format ('fits', 'jpg', 'png')
136
    - min_cut: Minimum intensity percentile for scaling
137
    - max_cut: Maximum intensity percentile for scaling  
138
    - stretch: Intensity scaling ('linear', 'log', 'sqrt', 'asinh')
139
    - colormap: Color mapping for non-FITS formats
140
    - **kwargs: Additional query parameters
141
    
142
    Returns:
143
    HDUList with HiPS data in requested projection
144
    """
145

146
def query_with_circle(hips: str, center: Union[SkyCoord, str], 
147
                     radius: Union[Quantity, str], resolution: int = 512,
148
                     get_query_payload: bool = False, **kwargs) -> HDUList:
149
    """
150
    Query circular region from HiPS survey.
151
    
152
    Parameters:
153
    - hips: HiPS survey identifier
154
    - center: Center coordinates
155
    - radius: Circle radius
156
    - resolution: Output image resolution in pixels
157
    - get_query_payload: Return query parameters instead of executing
158
    - **kwargs: Additional parameters
159
    
160
    Returns:
161
    HDUList with circular HiPS cutout
162
    """
163

164
def query_with_polygon(hips: str, polygon: List[Tuple[float, float]],
165
                      resolution: int = 512, **kwargs) -> HDUList:
166
    """
167
    Query polygonal region from HiPS survey.
168
    
169
    Parameters:
170
    - hips: HiPS survey identifier
171
    - polygon: List of (ra, dec) coordinate pairs defining polygon
172
    - resolution: Output resolution
173
    - **kwargs: Additional parameters
174
    
175
    Returns:
176
    HDUList with polygonal HiPS region
177
    """
178

179
# Configuration
180
from astroquery.hips2fits import conf
181
conf.server: str              # HiPS2FITS server URL
182
conf.timeout: int = 600       # Connection timeout
183
```
184

185
Usage examples:
186

187
```python
188
from astroquery.hips2fits import Hips2fitsClass
189
from astropy.coordinates import SkyCoord
190
from astropy.wcs import WCS
191
import astropy.units as u
192

193
# Create custom WCS for large field
194
wcs = WCS(naxis=2)
195
wcs.wcs.crpix = [256, 256]
196
wcs.wcs.cdelt = [-0.01, 0.01]  # 0.01 degree pixels
197
wcs.wcs.crval = [180.0, 0.0]   # Center at (180, 0)
198
wcs.wcs.ctype = ['RA---TAN', 'DEC--TAN']
199

200
# Get DSS image with custom projection
201
dss_image = Hips2fitsClass.query_with_wcs('DSS', wcs, format='fits')
202
print(f"Custom DSS image: {dss_image[0].data.shape}")
203

204
# Circular cutout from 2MASS
205
coords = SkyCoord('12h30m43s', '+12d23m28s', frame='icrs')
206
twomass_cutout = Hips2fitsClass.query_with_circle(
207
    '2MASS:H', center=coords, radius=30*u.arcmin, resolution=1024)
208

209
# Large field from WISE survey
210
wise_field = Hips2fitsClass.query_with_circle(
211
    'WISE:W1', center='Orion Nebula', radius=2*u.deg, resolution=2048,
212
    stretch='asinh', min_cut=1, max_cut=99)
213
```
214

215
### Image Cutout Services
216

217
Generic image cutout services for extracting subregions from large survey datasets, supporting various missions and surveys.
218

219
```python { .api }
220
from astroquery.image_cutouts import ImageCutoutService
221

222
def get_cutout(coordinates: Union[SkyCoord, str], size: Union[Quantity, str],
223
              survey: str, **kwargs) -> HDUList:
224
    """
225
    Get image cutout from survey data.
226
    
227
    Parameters:
228
    - coordinates: Target coordinates
229
    - size: Cutout size (square) or (width, height)
230
    - survey: Survey name
231
    - **kwargs: Survey-specific parameters
232
    
233
    Returns:
234
    HDUList with cutout image
235
    """
236

237
def get_cutouts(coordinates: Union[SkyCoord, List[SkyCoord]], 
238
               size: Union[Quantity, str], survey: str, **kwargs) -> List[HDUList]:
239
    """
240
    Get multiple image cutouts.
241
    
242
    Parameters:
243
    - coordinates: List of target coordinates
244
    - size: Cutout size for all targets
245
    - survey: Survey name
246
    - **kwargs: Additional parameters
247
    
248
    Returns:
249
    List of HDUList objects with cutouts
250
    """
251

252
# Configuration
253
from astroquery.image_cutouts import conf
254
conf.timeout: int = 300       # Connection timeout
255
```
256

257
Usage examples:
258

259
```python
260
from astroquery.image_cutouts import ImageCutoutService
261
from astropy.coordinates import SkyCoord
262
import astropy.units as u
263

264
# Single cutout
265
coords = SkyCoord('12h30m43s', '+12d23m28s', frame='icrs')
266
cutout = ImageCutoutService.get_cutout(coords, size=5*u.arcmin, 
267
                                      survey='SDSS-r')
268

269
# Multiple cutouts for source list
270
source_coords = [SkyCoord('12h30m43s', '+12d23m28s', frame='icrs'),
271
                 SkyCoord('13h15m22s', '+27d42m31s', frame='icrs')]
272
cutouts = ImageCutoutService.get_cutouts(source_coords, size=2*u.arcmin,
273
                                        survey='PanSTARRS-g')
274
print(f"Retrieved {len(cutouts)} cutouts")
275
```
276

277
## Common Types
278

279
```python { .api }
280
from astropy.io.fits import HDUList
281
from astropy.coordinates import SkyCoord  
282
from astropy.units import Quantity
283
from astropy.wcs import WCS
284
from typing import Union, List, Dict, Tuple, Optional
285

286
# Input types
287
position: Union[SkyCoord, str]              # Sky position
288
coordinates: Union[SkyCoord, str]           # Target coordinates  
289
survey: Union[str, List[str]]               # Survey name(s)
290
radius: Union[Quantity, str, None]          # Search/cutout radius
291
size: Union[Quantity, str]                  # Image size
292

293
# Image parameters
294
pixels: Union[int, List[int]] = 300         # Image size in pixels
295
projection: str = 'Tan'                     # Map projection
296
scaling: str = 'Linear'                     # Intensity scaling
297
resolution: int = 512                       # Output resolution
298
format: str = 'fits'                        # Output format
299

300
# Coordinate specifications  
301
width: Union[Quantity, str, None]           # Image width
302
height: Union[Quantity, str, None]          # Image height
303
polygon: List[Tuple[float, float]]          # Polygon vertices
304
wcs: WCS                                    # World coordinate system
305

306
# Return types
307
List[HDUList]                              # Survey images
308
HDUList                                    # Single image
309
JobResults                                 # Asynchronous results
310
List[str]                                  # Survey names
311
Dict[str, Dict]                            # Survey metadata
312
```