Simple Image Access (SIA) Service
Overview
The Simple Image Access (SIA) service provides a Virtual Observatory (VO) compliant standard interface to access imaging data hosted at Data Central.
Queries may be submitted through an HTTP GET request to the service. Results of the query are returned in VOTABLE format that includes image metadata and links to generate image cutouts.
The SIA service currently extracts FITS image cutouts from the large multi-wavelength mosaics of the GAMA and Devils surveys hosted at Data Central. It opens up new ways to interact with the data not provided by the existing Cutout service. Image cutouts may be accessed from custom Python scripts or VO enabled software (e.g. Aladin). The query logic of the SIA service also allows for advanced filtering of query results with minimal effort.
Access to the SIA service is provided via synchronous web resources available from the following links:
- Interface to send queries: https://datacentral.org.au/vo/sia2/query
- Availability information: https://datacentral.org.au/vo/sia2/availability
- Capabilities of the service: https://datacentral.org.au/vo/sia2/capabilities
The implementation meets the requirements of the SIA Version 2.0 specifications.
The SIA Examples page contains details of more advanced usage of the SIA service (e.g. access from Python).
Workflow
The intended workflow of the SIA service is as follows:
- The user supplies an HTTP GET query to the query interface URL.
- A query is performed using the query parameters, producing a shortlist of image mosaics.
- A VOTABLE with the query results is returned with each row containing an access_url link.
- The access_url is a Datalink-enabled service that generates (on request) an image cutout from each mosaic in the shortlist.
- Image cutouts may be returned as FITS or PNG format, or as a VOTABLE with embedded links to FITS cutouts.
Query Parameters
The following parameters are supported. Only the POS parameter is mandatory, unless MAXREC=0 is specified, in which case only metadata is returned. Multiple values for each parameter may be specified in a query. Example values are listed below and usage is elaborated further below with example queries.
Difficulties viewing the table? Try Firefox or download the PDF of the table here: SIA2 Parameters Table
| Parameter | Description | Format | Units/Default value | Example values |
|---|---|---|---|---|
| POS | Position with CIRCLE constraint; returns square image cutouts | CIRCLE ra dec radius | Decimal degrees (ICRS) for ra, dec and radius. The radius must be between 0.00139 and 0.16667 deg (5 and 600 arcsec). | POS=CIRCLE 150 2.2 0.1 |
| BAND | Wavelength range to overlap data wavelength range. Image cutout wavelength ranges are defined by min and max wavelength of filter transmission profiles. | single wavelength or an interval: wave1 wave2 | metres | Images overlapping 440nm: BAND=440e-9; Images bluer than 300 nm: BAND=-Inf 300e-9; Images redder than 800 nm: BAND=800e-9 +Inf; Images covering 300-800 nm: BAND=300e-9 800e-9 |
| FILTER | Name of the image filter. Alternative custom parameter to BAND. | string | FILTER=2070;FILTER=520;FILTER=570;FILTER=FUV;FILTER=H;FILTER=IRAC1;FILTER=IRAC2;FILTER=IRAC3;FILTER=IRAC4;FILTER=J;FILTER=K;FILTER=Ks;FILTER=MIPS160;FILTER=MIPS24;FILTER=MIPS70;FILTER=NUV;FILTER=P100;FILTER=P160;FILTER=S250;FILTER=S350;FILTER=S500;FILTER=W1;FILTER=W2;FILTER=W3;FILTER=W4;FILTER=Y;FILTER=Z;FILTER=g;FILTER=i;FILTER=r;FILTER=u;FILTER=z; | |
| ID | Internal identifier of image mosaic to extract cutout from; Matches the Obscore obs_publisher_did field. | string | See obs_publisher_did field in VOTABLE output for values unique to each mosaic. | Example: ID=ivo://datacentral.org.au/surveys?devils/dr0/9 |
| COLLECTION | Name of data collection | string | Devils Data Release 0: COLLECTION=devils_dr0; Gama Panchromatic Data Release: COLLECTION=gama_pdr | |
| FACILITY | Name of facility used to take data | string | FACILITY=CFHT; FACILITY=Chandra; FACILITY=GALEX; FACILITY=Herschel; FACILITY=SDSS; FACILITY=Spitzer; FACILITY=SpitzerSED; FACILITY=VISTA; FACILITY=VST; FACILITY=WISE; FACILITY=UKIRT | |
| DPTYPE | Type of data to be searched. Currently all are 'image' type. | string | image | DPTYPE=image; DPTYPE=cube |
| CALIB | Calibration level of the data; Currently all data are level '3' (enhanced data product). | integer | 3 | CALIB=0; CALIB=1; CALIB=2; CALIB=3 |
| FORMAT | Format of the image cutout returned by the service linked to in the access_url field. | string | fits | FITS: FORMAT=application/fits; FORMAT=fits. PNG: FORMAT=image/png; FORMAT=png. VOTABLE: FORMAT=application/x-FORMAT=votable+xml; FORMAT=text/xml; FORMAT=votable. |
| MAXREC | Maximum number of records to return in query. Results are truncated to MAXREC rows. | integer | Special case to return only metadata about SIA service: MAXREC=0 | |
| PNG_SCALE | Scale to apply to the data. PNG_SCALE and all other PNG_ parameters only apply to PNG format output. | string | log | PNG_SCALE=log; PNG_SCALE=linear; PNG_SCALE=asinh; PNG_SCALE=atan; PNG_SCALE=sqrt |
| PNG_LOCUT | Low limit to clip the data before applying the scaling. | float; Must be between 0.0 and 1.0; PNG_LOCUT must be less than PNG_MAXCUT. | 0.4 | |
| PNG_MAXCUT | High limit to clip the data before applying the scaling. | float; Must be between 0.0 and 1.0; PNG_MAXCUT must be more than PNG_LOCUT. | 0.995 | |
| PNG_STRETCH | Number to multiply the data before applying the scaling. | string "auto"; float otherwise | auto | PNG_STRETCH=auto; PNG_STRETCH=1.5 |
| PNG_CMAP | Colour map | string | PNG_CMAP=gist_gray; PNG_CMAP=afmhot; PNG_CMAP=viridis; PNG_CMAP=plasma; PNG_CMAP=inferno; PNG_CMAP=magma | |
| PNG_INV | Invert colour map? | boolean; case-insensitive | True | True may be expressed as: PNG_INV=T; PNG_INV=1; PNG_INV=True. False may be expressed as: PNG_INV=F; PNG_INV=0; PNG_INV=False |
| PNG_AXSTYLE | Axis style | string | basic | PNG_AXSTYLE=basic; PNG_AXSTYLE=none |
| PNG_AXUNIT | Axis units; Decimal or sexagesimal degrees | string | deg | PNG_AXUNIT=deg; PNG_AXUNIT=hmsdms |
| PNG_TITLE | Display image survey and filter? | boolean | False | As for PNG_INV above |
| PNG_POS | Display central source position marker? | boolean | False | As for PNG_INV above |
| PNG_GRID | Display coordinate grid overlay? | boolean | False | As for PNG_INV above |
Example queries
The following clickable links demonstrate access to the SIA service from a web browser.
The VOTABLE results are easily displayed by browsers such as Firefox or Chrome.
These queries highlight a small range of the flexibility of the SIA service.
The SIA Examples page has more advanced examples covering access from Python and other applications.
For more information on each parameter, see above or you may consult the SIA documentation.
A position in one of the Devils fields with a 0.05 deg (180 arcsec) radius cutout:
https://datacentral.org.au/vo/sia2/query?POS=CIRCLE 150 2.2 0.05
A position in one of the GAMA fields:
https://datacentral.org.au/vo/sia2/query?POS=CIRCLE 217.38 0.25 0.05
Images whose filters overlap 370 to 900 nm:
https://datacentral.org.au/vo/sia2/query?POS=CIRCLE 150 2.2 0.05&BAND=370e-9 900e-9
Images whose filters are outside the optical 370 to 900 nm:
https://datacentral.org.au/vo/sia2/query?POS=CIRCLE 150 2.2 0.05&BAND=-Inf 370e-9&BAND=900e-9 +Inf
Only images from mid-infrared facilities:
Generate FITS and PNG output; Default values for all PNG_ parameters are assumed.
https://datacentral.org.au/vo/sia2/query?POS=CIRCLE 150 2.2 0.05&FORMAT=fits&FORMAT=png
Generate only PNG output; Altering some PNG_ parameters of interest
Error and Warning messages
The VOTABLE returned by the SIA service contains a RESOURCE element (tag) with the attribute type="results". This element contains an INFO element with the attribute name="QUERY_STATUS" which may have one of three values:
- OK - Query executed successfully. The INFO element contents reports with the number of results returned.
- ERROR - Query did not complete successfully. Most frequently an invalid format of a parameter value is the cause. The INFO element contents reports the nature of the error.
- OVERFLOW - Query was successful but the number of results was truncated to MAXREC rows.
Warning messages are conveyed as additional INFO elements in the same RESOURCE element mentioned above.
A warning will be produced if an input parameter is not recognised or if an unsupported parameter is used (see Unsupported Query Parameters section below).
For example, a parameter CHICKEN would generate:
<INFO name="WARNING">Warning: Input parameter CHICKEN not valid</INFO>
The Python script on the SIA Examples page that parses the VOTABLE with astropy prints out any errors or warnings.
The sia2 access provided by the pyvo module incorporates handling of error messages.
Output VOTABLE columns
The VOTABLE includes tabular data in the TABLEDATA element. Each column represents a different ObsCore parameter, but there may be additional custom parameters.
A summary of the most important columns may be found below.
For all others please consult the ObsCore documentation.
| ObsCore parameter | Description |
|---|---|
| access_url | Link to retrieve image cutout |
| s_ra | Right Ascension (degrees) |
| s_dec | Declination (degrees) |
| obs_collection | Survey name and data release (e.g. gama_dr2) |
| facility_name | Facility used to take the image data |
| band_name | Custom parameter. Usually the image filter or bandpass. |
| em_min, em_max | Minimum, maximum wavelength of image filter (metres) |
| s_fov | Estimated diameter of the image cutout (degrees) |
| obs_id, obs_publisher_id | Internal identifiers for the mosaic used to generate the image cutout |
Limitations of the current implementation
- Not all parameters are supported (see Unsupported Query Parameters below).
- In some instances, especially if the mosaic is relatively small, selecting a relatively large radius (e.g. > 0.1 deg) may reduce the number of visible mosaics, thus making them unavailable for the cutout generation. If you anticipate an image to be available but not visible in your query results, try reducing the radius size in the query.
- Devils imaging taken by the Subaru facility is currently unavailable.
Unsupported Query Parameters
As the current SIA service generates image cutouts from larger mosaics, several of the SIA2 parameters are not applicable. This may change in the future as more data are incorporated into the service. A warning is added to the VOTABLE results if any of the following parameters are used. If a parameter is used and its value has an invalid format, then an error will also be added and no query will be performed.
| Parameter | Description |
|---|---|
| POS (POLYGON) | Position with POLYGON constraint. Square cutouts are adequate for most users. |
| POS (RANGE) | Position with RANGE constraint. We are still testing rectangular cutouts for the SIA service. Rectangular cutouts with extreme aspect ratios may result in images that do not fully reach the requested corner coordinates. |
| TIME | Image mosaics currently hosted are composed of images taken over several years, meaning TIME is ill-defined for each image. |
| POL | Polarization state. None of the data currently hosted are applicable. |
| FOV | Instrument Field of View (degrees). However, the ObsCore parameter s_fov is set to the approximate cutout image size in the VOTABLE results. |
| SPATRES | Spatial resolution (FWHM) of the imaging data. |
| SPECRP | Spectral resolving power. None of the data currently hosted are applicable. |
| EXPTIME | Exposure time (seconds). See note for TIME parameter above. |
| TIMERES | Range of temporal resolution. None of the data currently hosted are applicable. |
| INSTRUMENT | None of the data currently hosted are applicable. |
| TARGET | None of the data currently hosted are applicable. |
| UPLOAD | Not supported by SIA v2.0 specifications. |