WWTWeb/ShowImage.aspx

This API returns a WTML collection XML document that points to a single web-accessible image no larger than 2048×2048 pixels. The XML document is a fairly straightforward transcription of the URL parameters that are passed to the API call. Therefore this API is most useful when you are using some other web API that requires a URL to a WTML file — by passing it a URL involving this endpoint, you can point at a “virtual” WTML file that tells WWT how to show an image.

The WTML document returned by this API has the following structure, where the items enclosed in curly braces have textual substitutions applied:

<?xml version="1.0" encoding="UTF-8"?>
<Folder Name="{name}" Group="Goto">
  <Place Name="{name}" RA="{ra}" Dec="{dec}" ZoomLevel="{zoom}"
         DataSetType="Sky" Opacity="100" Thumbnail="{thumb}"
         Constellation="">
    <ForegroundImageSet>
      <ImageSet DataSetType="Sky" BandPass="Visible" Url="{url}"
                TileLevels="0" WidthFactor="2" Rotation="{rotation}"
                Projection="SkyImage" FileType=".tif" CenterY="{cy}"
                CenterX="{cx}" BottomsUp="{bottomsup}" OffsetX="{dx}"
                OffsetY="{dy}" BaseTileLevel="0"
                BaseDegreesPerTile="{scale}">
        <Credits>{credits}</Credits>
        <CreditsUrl>{creditsurl}</CreditsUrl>
      </ImageSet>
    </ForegroundImageSet>
  </Place>
</Folder>

Query Parameters

The WWTWeb/ShowImage.aspx endpoint processes the following URL query parameters:

Name

Type

Required?

Summary

credits

Free text

Brief description of where the image came from.

creditsUrl

URL

URL to a webpage with more information about the image.

debug

Existential

If set, response is delivered as text/plain with no HTTP headers.

dec

Degrees

Declination at which to center the view; nominally the image center.

imageurl

URL

The image to load.

name

Free text

yes

User-facing name for the image.

ra

Degrees

Right ascension at which to center the view; nominally the image center.

reverseparity

Existential

If provided, the image is flipped horizontally

rotation

Degrees

How much to rotate the image in an east-from-north sense, plus 180 degrees.

scale

Arcseconds

The angular size of each image pixel (assumed square).

thumb

URL

URL to a 96×45 pixel thumbnail image for this image.

wtml

Existential

If unset, the API returns a redirect to default.aspx rathern than XML.

x

Pixels

The horizontal offset of the image corner from the view center.

y

Pixels

The vertical offset of the image corner from the view center.

Some details:

debug

Do not use this parameter. It is only documented to point out that supplying it will change the behavior of the API call.

dec

Defaults to 0. Clipped to lie between -90 and 90.

imageurl

This parameter is technically not required, but the API call makes little sense without it.

name

Commas will be stripped out from this parameter.

ra

Defaults to 0. Clipped to lie between 0 and 360.

reverseparity

Causes the image to be mirrored left-right before any rotation is applied. To cause a mirror to be flipped top-bottom, which is usually what’s desired, combine this parameter with a rotation of 180°.

rotation

If left unspecified, the Rotation parameter in the resulting WTML file will be 1 degree. Otherwise, the parameter in the resulting WTML file will be whatever is passed in, minus 180 degrees. Therefore you should almost always specify this as 180.

scale

Mis-documented in the WTML reference, I think. Defaults to 1. The format only allows for square pixels.

wtml

Always set this parameter to true. Otherwise the API call will issue a redirect intended for user-facing applications.

x

Mis-documented in the WTML reference, I think. Defaults to 0, which means that the coordinate center of the image is taken to land on its left edge. A value equal to the image’s width in pixels means that the coordinate center lands on its right edge. Therefore, in the common case that you want the view to be centered on the image, x should be about half of the image width in pixels.

y

Mis-documented in the WTML reference, I think. Defaults to 0, which means that the coordinate center of the image is taken to land on its bottom edge. A value equal to the image’s height in pixels means that the coordinate center lands on its top edge. Therefore, in the common case that you want the view to be centered on the image, y should be about half of the image height in pixels.

The ZoomLevel of the <Place> element is set to scale * y / 360. When navigating the <Place> specified in a WTML file, the ZoomLevel is six times the height of the client FOV in degrees. In the baseline case that y is half of the image height, this means that the final client FOV will be 83% (5/6) of the image height. If y is not close to half of the image height, the discrepancy will be different.

Textual items are not XML-escaped before being inserted into the XML document, so callers of this API should do the necessary escaping themselves.

URLs are not validated in any way by the API, but it is safest if all passed-in URLs are absolute.