.. sectionauthor:: Alice Jacques , Knut Olsen , Robert Nikutta *Version: 20230830* .. index:: simple image access, SIA, image cutout .. _sec_SimpleImageAccessSIA: ************************* Simple Image Access (SIA) ************************* The Simple Image Access (SIA) service provides capabilities for the discovery, description, access, and retrieval of multi-dimensional image datasets, including 2-D images as well as datacubes of three or more dimensions. Use of the SIA service requires the external PyVO package, and the URL of the SIA service endpoint that you will use. Data Lab has a general SIA service containing all available images from NOIRLab Science Archive (NSA), as well as a number of survey-specific services. The SIA service tool works to identify the set of images in an image collection that overlap the position at which an image cutout is desired. It returns a table of potential images containing information (metadata) typically found in the image headers (filter, exposure time, time of observation, etc.) as well as a URL pointing to the image cutout itself. Getting image cutouts is thus a three-step process: 1) choose an image collection 2) call the SIA service for that collection to retrieve information about images that overlap a position of interest 3) retrieve the image cutouts by accessing the URLs for the selected images in the table of information ============================ Choosing an image collection ============================ Choosing a specific image collection is done by selecting the URL that points to that collection. Here we list the SIA service endpoints for different image collections: ==================== ========================================== ====================================================== Name Description DEF_ACCESS_URL ==================== ========================================== ====================================================== calibrated/all All Instrument calibrated images ``https://datalab.noirlab.edu/sia/calibrated_all`` calibrated/des_y1 DES Year-1 calibrated images ``https://datalab.noirlab.edu/sia/calibrated/des_y1`` calibrated/des_y2 DES Year-2 calibrated images ``https://datalab.noirlab.edu/sia/calibrated/des_y2`` calibrated/des_y3 DES Year-3 calibrated images ``https://datalab.noirlab.edu/sia/calibrated/des_y3`` calibrated/des_y4 DES Year-4 calibrated images ``https://datalab.noirlab.edu/sia/calibrated/des_y4`` calibrated/nsa NSA calibrated images ``https://datalab.noirlab.edu/sia/calibrated/nsa`` calibrated/smash_dr1 SMASH DR1 calibrated images ``https://datalab.noirlab.edu/sia/calibrated/smash_dr1`` calibrated/smash_dr2 SMASH DR2 calibrated images ``https://datalab.noirlab.edu/sia/calibrated/smash_dr2`` calibrated/splus_dr1 S-Plus DR1 calibrated images ``https://datalab.noirlab.edu/sia/calibrated/splus_dr1`` coadd/all All coadded images ``https://datalab.noirlab.edu/sia/coadd_all`` coadd/decaps_dr1 DECaPS DR1 coadd images ``https://datalab.noirlab.edu/sia/coadd/decaps_dr1`` coadd/des_dr1 DES DR1 coadd images ``https://datalab.noirlab.edu/sia/coadd/des_dr1`` coadd/des_sva DES SVA coadd images ``https://datalab.noirlab.edu/sia/coadd/des_sva`` coadd/ls_dr8 DECaLS DR8 coadd images ``https://datalab.noirlab.edu/sia/coadd/ls_dr8`` coadd/ls_dr9 DECaLS DR9 coadd images ``https://datalab.noirlab.edu/sia/coadd/ls_dr9`` coadd/nsa NSA coadd images ``https://datalab.noirlab.edu/sia/coadd/nsa`` coadd/smash_dr1 SMASH DR1 coadd images ``https://datalab.noirlab.edu/sia/coadd/smash_dr1`` coadd/smash_dr2 SMASH DR2 coadd images ``https://datalab.noirlab.edu/sia/coadd/smash_dr2`` coadd/splus_dr1 S-PLUS DR1 coadd images ``https://datalab.noirlab.edu/sia/coadd/splus_dr1`` decaps_dr1 DECaPS DR1 images ``https://datalab.noirlab.edu/sia/decaps_dr1`` des_dr1 DES DR1 images ``https://datalab.noirlab.edu/sia/des_dr1`` des_dr2_se DES DR2 single-epoch images ``https://datalab.noirlab.edu/sia/des_dr2_se`` des_dr2 DES DR2 images ``https://datalab.noirlab.edu/sia/des_dr2`` des_sva1 DES SVA1 images ``https://datalab.noirlab.edu/sia/des_sva1`` des_y1 DES Year-1 images ``https://datalab.noirlab.edu/sia/des_y1`` des_y2 DES Year-2 images ``https://datalab.noirlab.edu/sia/des_y2`` des_y3 DES Year-3 images ``https://datalab.noirlab.edu/sia/des_y3`` des_y4 DES Year-4 images ``https://datalab.noirlab.edu/sia/des_y4`` gogreen_dr1 GOGREEN DR1 images ``https://datalab.noirlab.edu/sia/gogreen_dr1`` ls_dr8 DECaLS DR8 images ``https://datalab.noirlab.edu/sia/ls_dr8`` ls_dr9 DECaLS DR9 images ``https://datalab.noirlab.edu/sia/ls_dr9`` nsa NOIRLab Science Archive ``https://datalab.noirlab.edu/sia/nsa`` nsc_dr2 NOIRLab Source Catalog DR2 ``https://datalab.noirlab.edu/sia/nsc_dr2`` raw/all All Raw images ``https://datalab.noirlab.edu/sia/raw_all`` raw/nsa NSA Raw images ``https://datalab.noirlab.edu/sia/raw/nsa`` raw/smash_dr1 SMASH DR1 raw images ``https://datalab.noirlab.edu/sia/raw/smash_dr1`` raw/smash_dr2 SMASH DR2 raw images ``https://datalab.noirlab.edu/sia/raw/smash_dr2`` sdss_dr9 SDSS DR9 sky-subtracted images ``https://datalab.noirlab.edu/sia/sdss_dr9`` smash_dr1 SMASH DR1 images ``https://datalab.noirlab.edu/sia/smash_dr1`` smash_dr2 SMASH DR2 images ``https://datalab.noirlab.edu/sia/smash_dr2`` splus_dr1 S-PLUS DR1 images ``https://datalab.noirlab.edu/sia/splus_dr1`` splus_edr S-PLUS EDR images ``https://datalab.noirlab.edu/sia/splus_edr`` stripe82/calibrated Calibrated images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/calibrated`` stripe82/coadd Calibrated images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/coadd`` stripe82/decaps_dr1 DECAPS DR1 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/decaps_dr1`` stripe82/des_dr1 Calibrated images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/des_dr1`` stripe82/des_sva1 DES SVA images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/des_sva1`` stripe82/des_y1 DES Year-1 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/des_y1`` stripe82/des_y2 DES Year-2 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/des_y2`` stripe82/des_y3 DES Year-3 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/des_y3`` stripe82/des_y4 DES Year-4 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/des_y4`` stripe82/ls_dr8 DECaLS DR8 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/ls_dr8`` stripe82/ls_dr9 DECaLS DR9 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/ls_dr9`` stripe82/nsa NOIRLab Science Archive images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/nsa`` stripe82/nsc_dr2 NSC DR2 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/nsc_dr2`` stripe82/raw Raw images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/raw`` stripe82/sdss_dr9 SDSS DR9 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/sdss_dr9`` stripe82/smash_dr1 SMASH DR1 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/smash_dr1`` stripe82/smash_dr2 SMASH DR2 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/smash_dr2`` stripe82/splus_dr1 S-PLUS DR1 images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/splus_dr1`` stripe82/splus_edr S-PLUS EDR images in Stripe82 ``https://datalab.noirlab.edu/sia/stripe82/splus_edr`` ==================== ========================================== ====================================================== ============================ Retrieving image information ============================ We can use the ``search`` method of the SIA service object to perform a search within a specified field of view (fov) size. The ``search`` method takes the following as arguments: *(ra,dec)* - a tuple containing the RA and Dec of the object in decimal degrees *fov* - a tuple with the size of the cutout in each direction in degrees For example, we will pick a location in SDSS Stripe 82 in the subset of images from the NOIRLab Science Archive (nsa) that overlap with SDSS Stripe 82: :: > DEF_ACCESS_URL = "https://datalab.noirlab.edu/sia/stripe82/nsa" > svc_stripe82 = sia.SIAService(DEF_ACCESS_URL) We use the SDSS Stripe 82-specific SIA service above to retrieve the image information for an image cutout whose fov size is 6x6 arcmin (0.1x0.1 degrees). We want the result to be an Astropy table, so we add ``.to_table()`` at the end of the call: :: > ra = 335.0 > dec = 0.0 > fov = 0.1 > imgTable = svc_stripe82.search((ra,dec), (fov/np.cos(dec*np.pi/180), fov), verbosity=2).to_table() **NOTE** the ``search`` method works in RA and Dec in degrees, and does not account for the convergence of lines of RA toward the poles, so we divide by a ``cos(dec)`` term in the RA fov argument. The result is a table of metadata for images that overlap the search position. ======================== Retrieving image cutouts ======================== In the result table of metadata for images obtained above, the column ``access_url`` contains the link to retrieve the image cutout. We can filter the table on any of the columns to narrow down the list to just the cutouts we want. Here we'll select stacked images (``proctype=Stack`` and ``prodtype=image``) observed in the g filter (``obs_bandpass`` that contains the letter 'g'): :: > sel = (imgTable['proctype'].astype(str)=='Stack') & (imgTable['prodtype'].astype(str)=='image') & (startswith(imgTable['obs_bandpass'].astype(str),'g')) From the filtered table we will pick a row and retrieve the image: :: > row = imgTable[sel][1] > url = row['access_url'].decode() # get the download URL > filename = download_file(url,cache=True,show_progress=False,timeout=120) > hdu = fits.open(filename)[0] > image = hdu.data > hdr = hdu.header > wcs = WCS(hdr) # WCS info from header to convert pixel coords to world coords Then we'll display the image. Note that the image might not be square for a variety of reasons, such as that the image cutout ran into a chip edge along one axis. :: > fig = plt.figure(figsize=(10,10)) > ax = fig.add_subplot(projection=wcs) > ax.imshow(image,origin='lower',cmap='bone',vmin=image.min(),vmax=image.min()+(image.max()-image.min())/170.) .. figure:: SIA1.png :scale: 50 % :alt: SIA screenshot ======================== Resources and References ======================== See our `How To Use SIA Service Jupyter notebook `_ for example usage. For more background on the SIA protocol, see the `IVOA document `_ that describes it.