WorldWide Telescope Web Control Script Reference

Note: This documentation is preliminary and subject to change.

Web Control scripts are used to customize the WorldWide Telescope web client.  This document describes the setup, development process, API set and samples to aid developers in building their own applications.

The customization scripts are written in JScript and embedded in an html file, and along with custom data files, can be used to do one or more of the following tasks:

Note that currently the SDK only applies to the Sky view of WorldWide Telescope, and not the Earth, Planet, Panorama or SolarSystem views.

The Aphelion Beta release is based on Silverlight 3, whereas the earlier versions of the web client were based on Silverlight 2. Support for Silverlight 2 applications has not been removed, however new applications should be written for Silverlight 3. To upgrade a script from Silverlight 2 to 3 involves changing just a few lines of code, which are pointed out in the Web Control Development section.

Table of Contents

See Also


Web Control Setup

To develop WorldWide Telescope web control applications, ensure the following steps have been completed:

  1. The minimum hardware and software requirements for WorldWide Telescope development are met by the client computer. Locate these by selecting the Windows System Requirements link on the WorldWide Telescope home page.
  2. Microsoft Silverlight 3.0+ has been installed.
  3. An appropriate html editing tool is available.
  4. Data preparation can be made a lot simpler by installing the WorldWide Telescope May 2009 ADK. Installing this will provide the use of several tools, available from the Programs menu as shown in the following image. Note that the Windows version of WorldWide Telescope has also been installed in this instance.
  5. To ensure that the setup is correct, try running the WWT Web Client Simple sample.

See Also


Web Control Development

Refer to the WWT Web Client Simple sample for the structure of a WorldWide Telescope web client. This section provides some additional notes for developers.

The Silverlight object for WorldWide Telescope is embedded in the web client html with an entry such as the following:

Silverlight object entry
    <object id="silverlightObject" 
        data="data:application/x-silverlight," 
        type="application/x-silverlight-2"             
        width="1000" height="800">

        <param name="source" value="http://www.worldwidetelescope.org/webclient/clientbin/WWTSL.xap"/>
        <param name="onload" value="pluginLoaded" />
        <param name="background" value="black" />
        <param name="minRuntimeVersion" value="3.0.40624.0" />
        <param name="autoUpgrade" value="true" />
        <param name="initParams" value="NoUI=false,webkey=AX2011Gqqu" />
        <param name="enableHtmlAccess" value="true" />
        <a href="http://go.microsoft.com/fwlink/?LinkID=149156&v=3.0.40624.0">
        <img src="http://go.microsoft.com/fwlink/?LinkId=108181" alt="Install Microsoft Silverlight" /></a>
    </object>
Notes

To Change from Silverlight 2 to Silverlight 3

Before installing Silverlight 3, uninstall Silverlight 2 (this includes uninstalling Microsoft Silverlight, Microsoft Silverlight 2 SDK, and Microsoft Silverlight Tools for Visual Studio 2008). Then install Silverlight 3 and the Silverlight 3 SDK and Silverlight 3 Tools for Visual Studio 2008 SP1.

In the source scripts for your applications, change the following in the Silverlight object entry:

Param
Change from
Change to
sourcehttp://www.worldwidetelescope.org/webclient/WWTSL.xaphttp://www.worldwidetelescope.org/webclient/clientbin/WWTSL.xap
minRuntimeVersion2.0.31005.03.0.40624.0
hreffwlink/?LinkID=124807fwlink/?LinkID=149156&v=3.0.40624.0

Note that the type does not change from x-silverlight-2. Also note the addition of the tour entry for initParams.

See Also


Web Control Objects

The View object is the principal object, the other objects are created on initialization of a View object, or can be created by the methods provided by this object.

Note that the Example Code listed for each property or method is not code that will run on its own, just an example of how to use the property or method within a script. Run-able samples are listed and linked to in the Web Control Samples section.

Object
Description
AnnotationUsed to describe the annotation for a Circle, Poly or PolyLine object.
CircleUsed to render a circle on the screen.
PolyUsed to render a polygon on the screen.
PolyLineUsed to render a polyline on the screen.
SettingsUsed to specify a range of settings for a View object.
ViewUsed to manage the current view of WorldWide Telescope images.

See Also


Annotation Object

The Annotation Object is inherited by the Circle object, the Poly object, and the PolyLine object, and is used to describe the annotation for these objects. An Annotation object is not used independently of these other objects, so this object should not be instantiated on its own.

Property
Description
IDContains a string for use by the web client.
LabelContains descriptive text for the annotation.
OpacitySpecifies the opacity to be applied to the complete annotation.
ShowHoverLabel Specifies whether to render the label if the mouse is hovering over the annotation.
TagContains a string for use by the web client.

See Also


Annotation.ID

The ID property contains a string for use by the web client.

Syntax

Annotation.ID [string]

Remarks

This string can be used to hold information (perhaps a URL or link to related information, reference string or number, credits, date, times, and so on) that is of use to the web client. The ID string is returned with a wwtAnootationclicked event.

Example Code

// Draw a circle at the center of the constellation Sagittarius
circle.SetCenter(286.485, -27.5231666666667);
circle.ID = "Center of the Constellation Sagittarius";

See Also


Annotation.Label

The Label property contains descriptive text for the annotation.

Syntax

Annotation.Label [string]

Remarks

The label text will be rendered if the ShowHoverLabel property is set to true.

Example Code

// Draw a circle at the center of the constellation Sagittarius
circle.SetCenter(286.485, -27.5231666666667);
circle.ID = "Center of the Constellation Sagittarius";
circle.Label = "RA: 286.485, Dec: -27.5231666666667";

See Also


Annotation.Opacity

The Opacity property specifies the opacity to be applied to the complete annotation.

Syntax

Annotation.Opacity [double]

Remarks

The default opacity setting is 1.0, which means that no transparency blending will be applied to the complete annotation. A value of 0.5, for example, will result in a 50% transparency blending being applied. Note that the color values for individual lines and fill color (which can include an alpha transparency value) are applied to the specific lines and shapes before the opacity value here is applied to the entire annotation.

Example Code

// Set a solid fill color
circle.FillColor = 0xFF556688;
circle.Fill = true;
// Apply a 50% transparency to the entire annotation
circle.Opacity = 0.5;

See Also


Annotation.ShowHoverLabel

The ShowHoverLabel property specifies whether to render the label if the mouse is hovering over the annotation.

Syntax

Annotation.ShowHoverLabel [Bool]

Remarks

The default setting is false.

Example Code

// Draw a circle at the center of the constellation Sagittarius
circle.SetCenter(286.485, -27.5231666666667);
circle.ID = "Center of the Constellation Sagittarius";
circle.Label = "RA: 286.485, Dec: -27.5231666666667";
circle.ShowHoverLabel = true;

See Also


Annotation.Tag

The Tag property contains a string for use by the web client.

Syntax

Annotation.Tag [string]

Remarks

This string can be used to hold information that is of use to the web client. The string is not used internally by WorldWide Telescope.

Example Code

circle.Tag = "001";

See Also


Circle Object

The Circle object is used to render a circle on the screen. It is created by the CreateCircle method.

The Circle object inherits the properties of the Annotation object.

Polys
The image shows a purple circle with a 2 pixel line, a green polygon and a light blue polyline. Note that the order in which the elements are drawn is significant in how they appear, if there is any overlap or transparency.
Property
Description
FillSpecifies whether the circle should be filled or not.
FillColorSpecifies the fill color as an ARGB value.
LineColorSpecifies the line color as an ARGB value.
LineWidthSpecifies the line width in pixels.
RadiusSpecifies the circle radius.
SkyRelativeSpecifies whether the circle size is absolute or relative.
Method
Description
SetCenterSpecifies the center coordinates of the circle.

See Also


Circle.Fill

The Fill property specifies whether the circle should be filled or not.

Syntax

Circle.Fill [Bool]

Remarks

The default is false.

Example Code

// Fill a circle with a transparent red
circle.Fill = true;
circle.FillColor = 0x55AA0000;

See Also


Circle.FillColor

The FillColor property specifies the fill color as an ARGB value.

Syntax

Circle.FillColor [uint]

Remarks

The default fill color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.

Example Code

// Fill a circle with opaque green
circle.Fill = true;
circle.FillColor = 0xFF00AA00;

See Also


Circle.LineColor

The LineColor property specifies the line color as an ARGB value.

Syntax

Circle.LineColor [uint]

Remarks

The default line color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.

Example Code

// Draw a circle in opaque dark gray
circle.LineColor = 0xFF555555;

See Also


Circle.LineWidth

The LineWidth property specifies the line width in pixels.

Syntax

Circle.LineWidth [double]

Remarks

The default line width is 1 pixel.

Example Code

// Double the default line width
circle.LineWidth = 2;

See Also


Circle.Radius

The Radius property specifies the circle radius.

Syntax

Circle.Radius [double]

Remarks

If the SkyRelative property is true, then the radius units are degrees of arc, if not then the units are pixels. The default radius is 10.

Example Code

// Draw a fixed circle with a radius of 25 pixels
circle.SkyRelative = false;
circle.Radius = 25;

See Also


Circle.SkyRelative

The SkyRelative property specifies whether the circle size is absolute or relative.

Syntax

Circle.SkyRelative [Bool]

Remarks

The default is false. If this property is true, then the radius of the circle is in degrees of arc, and the circle will resize with zooming. If it is false, then the circle radius is in pixels, and the circle will not change size as the view is zoomed.

Example Code

// Draw a SkyRelative circle with a radius of 0.2 degrees of arc
circle.SkyRelative = true;
circle.Radius = 0.2;

See Also


Circle.SetCenter

The SetCenter method specifies the center coordinates of the circle.

Syntax

Circle.SetCenter(
  ra  [Double],
  dec  [Double]
)

Parameters

ra
  Specifies the right ascension in decimal degrees.
dec
  Specifies the declination in decimal degrees.

Return Values

This method does not return a value.

Remarks

The default value for right ascension and declination is zero.

Example Code

// Draw a circle at the center of the constellation Sagittarius
circle.SetCenter(286.485, -27.5231666666667);

See Also


Poly Object

The Poly object is used to render a polygon on the screen. The polygon can be filled with color, or unfilled, but is always a closed shape -- the last point entered for the polygon is connected to the first. It is created by the CreatePolygon method.

The Poly object inherits the properties of the Annotation object.

Property
Description
FillSpecifies whether the polygon is filled or not.
FillColorSpecifies the fill color as an ARGB value.
LineColorSpecifies the line color as an ARGB value.
LineWidthSpecifies the line width in pixels.
Method
Description
AddPointAdds a point to a polygon.

See Also


Poly.Fill

The Fill property specifies whether the polygon is filled or not.

Syntax

Poly.Fill [Bool]

Remarks

The default fill setting is false.

Example Code

// Fill a polygon with a slightly transparent blue
poly.Fill = true;
poly.FillColor = 0xBB0000AA;

See Also


Poly.FillColor

The FillColor property specifies the fill color as an ARGB value.

Syntax

Poly.FillColor [uint]

Remarks

The default fill color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.

Example Code

// Set a solid red fill color
poly.Fill = true;
poly.FillColor = 0xFFFF0000;

See Also


Poly.LineColor

The LineColor property specifies the line color as an ARGB value.

Syntax

Poly.LineColor [uint]

Remarks

The default color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.

Example Code

// Set a solid black line color
poly.LineColor = 0xFF000000;

See Also


Poly.LineWidth

The LineWidth property specifies the line width in pixels.

Syntax

Poly.LineWidth [double]

Remarks

The default line width is 1 pixel.

Example Code

// Double the line width
poly.LineWidth = 2 * poly.LineWidth;

See Also


Poly.AddPoint

The AddPoint method adds a point to a polygon.

Syntax

Poly.AddPoint(
  x  [Double],
  y  [Double]
)

Parameters

x
  Specifies the x coordinate, right ascension if in space, longitude if on a planet surface.
y
  Specifies the y coordinate, declination if in space, latitude if on a planet surface.

Return Values

This method does not return a value.

Remarks

There is no theoretical limit to the number of points that can be added to a Poly object, however the number of points does affect performance -- so complex geometry should be simplified.

Example Code

// The following function will add any number of points [ra, dec] to a polygon.

function expandPolygon(poly, newPoints)
{
    for (var i in newPoints)
    {
       poly.AddPoint(newPoints[i][0], newPoints[i][1]);
    }
}

var poly1 = wwtView.CreatePolygon(true);

var points = [[20,-20], [20,-21], [21,-21], [21,-20]];

expandPolygon(poly1, points);
 

See Also


PolyLine Object

The PolyLine object is used to render a polyline on the screen. A polyline cannot be filled, and is not a closed shape -- the last point is not connected back to the first. It is created by the CreatePolyLine method.

The PolyLine object inherits the properties of the Annotation object.

Property
Description
LineColorSpecifies the line color as an ARGB value.
LineWidthSpecifies the line width in pixels.
Method
Description
AddPointAdds a point to the polyline.

See Also


PolyLine.LineColor

The LineColor property specifies the line color as an ARGB value.

Syntax

PolyLine.LineColor [uint]

Remarks

The default color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.

Example Code

// Set a solid blue color
poly.FillColor = 0xFF0000FF;

See Also


PolyLine.LineWidth

The LineWidth property specifies the line width in pixels.

Syntax

PolyLine.LineWidth [double]

Remarks

The default line width is 1 pixel.

Example Code

poly.LineWidth = 3;

See Also


PolyLine.AddPoint

The AddPoint method adds a point to a polyline.

Syntax

PolyLine.AddPoint(
  x  [Double],
  y  [Double]
)

Parameters

x
  Specifies the x coordinate, right ascension if in space, longitude if on a planet surface.
y
  Specifies the y coordinate, declination if in space, latitude if on a planet surface.

Return Values

This method does not return a value.

Remarks

There is no theoretical limit to the number of points that can be added to a PolyLine object, however the number of points does affect performance -- so complex geometry should be simplified.

Example Code

// The following function will add any number of points [ra, dec] to a polyline.

function expandPolyLine(polyline, newPoints)
{
    for (var i in newPoints)
    {
       polyline.AddPoint(newPoints[i][0], newPoints[i][1]);
    }
}

var polyline1 = wwtView.CreatePolyLine();

var points = [[20,-20], [21,-21]];

expandPolyLine(polyline1, points);
 

See Also


Settings Object

The Settings object is used to specify a range of settings for a View object. The Settings object is created as part of the initialization of a View object.

The Settings object is referenced from the Settings property of the View object.

Property
Description
ConstellationBoundryColorSpecifies the constellation boundary color as an ARGB value.
ConstellationFigureColorSpecifies the constellation figure color as an ARGB value.
ConstellationSelectionColorSpecifies the constellation selection color as an ARGB value.
EclipticColorSpecifies the ecliptic color as an ARGB value.
GridColorSpecifies the grid color as an ARGB value.
LocalHorizonMode Specifies that the view should be from a local lat/long/alt position (for example, a city, or landmark).
LocationAltitude Specifies the view location altitude in meters.
LocationLatSpecifies the view location latitude.
LocationLngSpecifies the view location longitude.
ShowCloudsSpecifies whether to show the Earth's cloud layer.
ShowConstellationBoundriesSpecifies whether to show constellation boundaries.
ShowConstellationFiguresSpecifies whether to show constellation figures.
ShowConstellationSelectionSpecifies whether to show only the selected constellation.
ShowCrosshairsSpecifies whether to show cross-hairs.
ShowEclipticSpecifies whether to show the path of the Sun.
ShowFieldOfViewSpecifies whether to show the field of view box.
ShowGridSpecifies whether to show the equatorial grid.
ShowHorizonSpecifies whether to show the horizon.
ShowUTCTimeSpecifies whether to show the time as a UTC value.
UserIDSpecifies the user ID as a Guid.

See Also


Settings.ConstellationBoundryColor

The ConstellationBoundryColor property specifies the constellation boundary color as an ARGB value.

Syntax

Settings.ConstellationBoundryColor [uint]

Remarks

The default boundary color is blue.

Example Code

//
wwtView.Settings.ConstellationBoundryColor = 0xAARRGGBB

See Also


Settings.ConstellationFigureColor

The ConstellationFigureColor property specifies the constellation figure color as an ARGB value.

Syntax

Settings.ConstellationFigureColor [uint]

Remarks

The default figure color is red.

Example Code

    wwtView.Settings.ConstellationFigureColor= 0xAARRGGBB;

See Also


Settings.ConstellationSelectionColor

The ConstellationSelectionColor property specifies the constellation selection color as an ARGB value.

Syntax

Settings.ConstellationSelectionColor [uint]

Remarks

The default selection color is yellow.

Example Code

    wwtView.Settings.ConstellationSelectionColor= 0xAARRGGBB;

See Also


Settings.EclipticColor

The EclipticColor property specifies the ecliptic color as an ARGB value.

Syntax

Settings.EclipticColor [uint]

Remarks

The default ecliptic color is green.

Example Code

    wwtView.Settings.EclipticColor= 0xAARRGGBB;

See Also


Settings.GridColor

The GridColor property specifies the grid color as an ARGB value.

Syntax

Settings.GridColor [uint]

Remarks

The default equatorial grid color is gray.

Example Code

    wwtView.Settings.GridColor= 0xAARRGGBB;

See Also


Settings.LocalHorizonMode

The LocalHorizonMode property specifies that the view should be from a local lat/long/alt position (for example, a city, or landmark).

Syntax

Settings.LocalHorizonMode [Bool]

Remarks

This setting is equivalent to the View > View from this location checkbox, after setting up a local viewpoint.

Example Code

    wwtView.Settings.LocalHorizonMode = true;
Andromeda from NY
The view from New York of the Andromeda Constellation. Note the horizon and compass directions.
Andromeda no horizon
The view of Andromeda from the default viewing position, without any local horizon.

See Also


Settings.LocationAltitude

The LocationAltitude property specifies the view location altitude in meters.

Syntax

Settings.LocationAltitude [double]

Remarks

None.

Example Code

// Set the view from London, UK
wwtView.Settings.LocationLat = 51.31;
wwtView.Settings.LocationLng = -0.06;
wwtView.Settings.LocationAltitude = 21;
wwtView.LocalHorizonMode = true;

See Also


Settings.LocationLat

The LocationLat property specifies the view location latitude.

Syntax

Settings.LocationLat [double]

Remarks

The default location latitude is 47.633.

Example Code

// Set the view from Sydney, Australia
wwtView.Settings.LocationLat = -33.52;
wwtView.Settings.LocationLng = 151.125;
wwtView.Settings.LocationAltitude = 34;
wwtView.LocalHorizonMode = true;

See Also


Settings.LocationLng

The LocationLng property specifies the view location longitude.

Syntax

Settings.LocationLng [double]

Remarks

The default location longitude is 122.133333.

Example Code

// Set the view from San Francisco, USA
wwtView.Settings.LocationLat = 37.455;
wwtView.Settings.LocationLng = -122.262;
wwtView.Settings.LocationAltitude = 72;
wwtView.LocalHorizonMode = true;

See Also


Settings.ShowClouds

The ShowClouds property specifies whether to show the Earth's cloud layer.

Syntax

Settings.ShowClouds [Bool]

Remarks

This setting is equivalent to the Settings > Show Earth Cloud Layer checkbox. The viewer has to be a sufficient distance away from the surface of the Earth for the cloud cover to appear.

Example Code

    wwtView.Settings.ShowClouds = true;
No clouds The Earth without its cloud layer.
Clouds The Earth with its cloud layer.

See Also


Settings.ShowConstellationBoundries

The ShowConstellationBoundries property specifies whether to show constellation boundaries.

Syntax

Settings.ShowConstellationBoundries [Bool]

Remarks

This setting is equivalent to the View > Boundaries checkbox.

Example Code

    wwtView.Settings.ShowConstellationBoundries = true;
Boundaries
The constellation boundaries are shown in blue, except for the selected constellation, with its boundary in yellow.

See Also


Settings.ShowConstellationFigures

The ShowConstellationFigures property specifies whether to show constellation figures.

Syntax

Settings.ShowConstellationFigures [Bool]

Remarks

This setting is equivalent to the View > Figures checkbox.

Example Code

    wwtView.Settings.ShowConstellationFigures = true;
Figures
The constellation figures.

See Also


Settings.ShowConstellationSelection

The ShowConstellationSelection property specifies whether to show only the selected constellation.

Syntax

Settings.ShowConstellationSelection [Bool]

Remarks

This setting is equivalent to the View > Focused Only checkbox.

Example Code

    wwtView.Settings.ShowConstellationSelection = true;
Selection
The selected constellation.

See Also


Settings.ShowCrosshairs

The ShowCrosshairs property specifies whether to show cross-hairs.

Syntax

Settings.ShowCrosshairs [Bool]

Remarks

This setting is equivalent to the View > Reticle/Crosshairs checkbox.

Example Code

    wwtView.Settings.ShowCrosshairs = true;
CrosshairsThe crosshairs, or reticle, shown with Mars in view.

See Also


Settings.ShowEcliptic

The ShowEcliptic property specifies whether to show the path of the Sun.

Syntax

Settings.ShowEcliptic [Bool]

Remarks

This setting is equivalent to the View > Ecliptic/Orbits checkbox, which indicates that the path of the Sun should be rendered as a line.

Example Code

wwtView.Settings.ShowEcliptic = true;
Ecliptic

See Also


Settings.ShowFieldOfView

The ShowFieldOfView property specifies whether to show the field of view box.

Syntax

Settings.ShowFieldOfView [Bool]

Remarks

This setting is equivalent to the View > Field of View Indicator checkbox. The field of view box may not be visible in a view until the field of view is changed.

Example Code

    wwtView.Settings.ShowFieldOfView = true;
FOV
Gamma Pegasi shown with the Field of View Indicator box.

See Also


Settings.ShowGrid

The ShowGrid property specifies whether to show the equatorial grid.

Syntax

Settings.ShowGrid [Bool]

Remarks

This setting is equivalent to the View > Equatorial Grid check box.

Example Code

    wwtView.Settings.ShowGrid = true;
Equatorial Grid
The Equatorial grid shown, looking North, with the Hydrogen Alpha Full Sky Map as the data source.

See Also


Settings.ShowHorizon

The ShowHorizon property specifies whether to show the horizon.

Syntax

Settings.ShowHorizon [Bool]

Remarks

None.

Example Code

    wwtView.Settings.ShowHorizon = true;

See Also


Settings.ShowUTCTime

The ShowUTCTime property specifies whether to show the time as a UTC value.

Syntax

Settings.ShowUTCTime [Bool]

Remarks

If this value is true, the time shown will be Universal Coordinated Time (or Greenwich Mean Time), and if it is false the time displayed will be local time.

Example Code

wwtView.Settings.ShowUTCTime = true;

See Also


Settings.UserID

The UserID property is used to retrieve the user ID as a Guid.

Syntax

Settings.UserID [Guid]

Remarks

The Guid is in registry format, without the accompanying "{}" braces. When a user runs the client, a unique Guid is generated for them. The Guid is not persistent and will be different each time the same user runs the client. It can be used to identify a particular user during one session.

Example Code

// Assume an input statement has been set up in the html code, such as:
<input id="user" type="text" value="Unknown User"/>

// Display the user ID in the "user" text box
document.getElementById("user").value = wwtView.Settings.UserID;

See Also


View Object

The View object is used to manage the current view of WorldWide Telescope images. It is the principal object in the object model, and handles the creation of the other objects.

The View object does not inherit any classes that have exposed properties or methods.

Property
Description
FovContains the field of view in degrees.
SettingsReference to the Settings object for the view. Note this object is created when the View object is created, so there is no specific call to create a Settings object.
SmoothAnimation Specifies whether to pan smoothly or quickly to the new location.
Method
Description
AddAnnotationAdds an Annotation object to the view.
ClearAnnotations Removes all annotations from the view.
CreateCircleCreates a Circle object, and returns a reference to the created object.
CreatePolygonCreates a Poly object (a polygon), and returns a reference to the created object.
CreatePolyLineCreates a PolyLine object, and returns a reference to the created object.
GetDecRetrieves the declination for the view.
GetRARetrieves the right ascension for the view.
GotoUsed to go to a new viewing position.
HideUISpecifies whether to hide the UI for the view.
LoadImageCollection Used to load a WTML
 collection file, containing links to foreground and background images.
LoadTourUsed to load and start a tour.
LoadVOTableUsed to load a VO (Virtual Observatory) table.
PlayTourUsed to restart a tour from the beginning.
RemoveAnnotationRemoves the specified annotation from the view.
SetBackgroundImageByNameLoads an image to use as the view background.
SetForegroundImageByNameLoads an image to use as the view foreground.
SetForegroundOpacity Specifies the opacity of the entire foreground image, which can be useful when visually comparing the foreground and background images.
StopTourUsed to stop and exit a tour.
Event
Description
wwtAnootationclickedFired when an Annotation object is clicked on. Note the spelling error!
wwtArrivedFired when a change to the view from a drag, zoom, or goto comes to a halt.
wwtClickFired when the left mouse button is clicked.
wwtReadyFired when the web client is initialized.

See Also


View.Fov

The Fov property contains the field of view in degrees.

Syntax

View.Fov [double]

Remarks

This property is read-only. The maximum field of view is 60 degrees, the minimum is close to zero, at 0.00022910934437488727 degrees. Field of view can be considered to be the inverse of the zoom factor -- the smaller the field of view the greater the zoom factor.

Example Code

// Function to increase the field of view (zoom out)
function FovInc() {
   var newFov = 1.1 * wwtView.Fov;
   if (newFov <= 60) {
     wwtView.Goto(wwtView.GetRA(), wwtView.GetDec(), newFov, false);
   }
}

// Function to decrease the field of view (zoom in)
function FovDec() {
   var newFov = wwtView.Fov / 1.1;
   if (wwtView.Fov >= 0.00022910934437488727) {
      wwtView.Goto(wwtView.GetRA(), wwtView.GetDec(), newFov, false);
   }
}

Samples

See Also


View.Settings

The Settings property references the Settings object for the view.

Syntax

View.Settings [Settings]

Remarks

This property is read-only, though individual settings can have their values set (refer to the Settings object).

Example Code

    wwtView.Settings.ShowCrosshairs = true;
    wwtView.Settings.GridColor= 0x88880000; // Transparent red
    wwtView.Settings.ShowGrid = true;

Samples

See Also


View.SmoothAnimation

The SmoothAnimation property specifies whether to pan smoothly or quickly to the new location.

Syntax

View.SmoothAnimation [Bool]

Remarks

If this property is set to true the panning will be smoother but slower than if the property is false. This property is equivalent to the Settings/Smooth Panning checkbox in the UI, and the purpose of setting it to false is to improve CPU performance.

Example Code

wwtView.SmoothAnimation = true;

Samples

See Also


View.AddAnnotation

The AddAnnotation method adds an Annotation object to the view.

Syntax

View.AddAnnotation(
  annotation  [Annotation]
)

Parameters

annotation
  Specifies the Annotation object.

Return Values

This method does not return a value.

Remarks

An Annotation Object is inherited by the Circle object, the Poly object, and the PolyLine object, so adding an annotation will add one of these graphics to the view, in addition to providing the annotation text.

Typically one or more annotations are added to a view when a user clicks on a custom UI element such as a checkbox, and then those annotations are removed when the user deselects that UI element.

Example Code

// Global settings
var bShowCircle = false;
var bShowPolygon = false;

// Function to toggle the display of annotations

function toggleSetting(text) {

   switch (text) {

     case 'ShowCircle':

       bShowCircle = !bShowCircle;

       if (bShowCircle) {
         wwtView.AddAnnotation(circle1);
       } else {
         wwtView.RemoveAnnotation(circle1);
       }
       break;

     case 'ShowPolygon':

       bShowPolygon = !bShowPolygon;

       if (bShowPolygon) {
         wwtView.AddAnnotation(polygon1);
       } else {
         wwtView.RemoveAnnotation(polygon1);
       }
     break;
   }
}

Samples

See Also


View.ClearAnnotations

The ClearAnnotations method removes all annotations from the view.

Syntax

View.ClearAnnotations()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

None.

Example Code

wwtView.ClearAnnotations();

Samples

See Also


View.CreateCircle

The CreateCircle method creates a Circle object, and returns a reference to the created object.

Syntax

View.CreateCircle(
  fill  [Bool]
)

Parameters

fill
  True indicates the circle should be filled.

Return Values

This method returns a reference to a Circle object.

Remarks

In addition to creating the circle an Annotation object (which is inherited by the Circle object) will be created to provide supporting text.

Example Code

// Assume that a WWT view object has been created, and named wwtView
// The following function will add a circle to the view object, and
// return a reference to the created object.

function createWWTCircle(fill, lineColor, fillColor, lineWidth, opacity, radius, skyRelative, ra, dec)
{
    var circle = wwtView.CreateCircle(fill);
    circle.LineColor = lineColor;
    circle.FillColor = fillColor;
    circle.LineWidth = lineWidth;
    circle.Opacity = opacity;
    circle.Radius = radius;
    circle.SkyRelative = skyRelative;
    circle.SetCenter(ra, dec);
    return circle;
}
Circles
In this image,  circle objects filled with a transparent color have been used to identify point sources of light.

Samples

See Also


View.CreatePolygon

The CreatePolygon method creates a Poly object (a polygon), and returns a reference to the created object.

Syntax

View.CreatePolygon(
  fill  [Bool]
)

Parameters

fill
  True specifies the polygon should be filled.

Return Values

This method returns a reference to the created Poly object.

Remarks

In addition to creating the polygon an Annotation object (which is inherited by the poly object) will be created to provide supporting text.

Example Code

// Assume that a WWT view object has been created, and named wwtView
// The following function will add a polygon to the view object, and
// return a reference to the created polygon.

function createWWTPolygon(fill, lineColor, fillColor, lineWidth, opacity, points)
{
    var poly = wwtView.CreatePolygon(fill);
    poly.LineColor = lineColor;
    poly.FillColor = fillColor;
    poly.LineWidth = lineWidth;
    poly.Opacity = opacity;
    for (var i in points)
    {
       poly.AddPoint(polyPoints[i][0], polyPoints[i][1]);
    }
    return poly;
}
 
// Define a 2-D array of [ra,dec] points, and then create the polygon
var myPoints = [[25, -35], [15, -25], [25, -30], [30, -25]];
myPolygon = createWWTPolygon(true, 0x880000ff, 0x8800ff00, 2, 1.0, myPoints);
 
Polygons
This image shows the use of Polygon objects to identify a hierarchy of areas. If these areas are annotated, then increasingly detailed descriptions of the stellar sources can be given.

Samples

See Also


View.CreatePolyLine

The CreatePolyLine method creates a PolyLine object, and returns a reference to the created object.

Syntax

View.CreatePolyLine(
  fill  [Bool]
)

Parameters

fill
  This parameter should be removed, has no effect.

Return Values

This method returns a reference to a PolyLine object.

Remarks

In addition to creating the polyline, an Annotation object (which is inherited by the polyline object) will be created to provide supporting text.

The rendering of a polyline will simply take each point in the list and draw a line to the next. In order to have a more complex polyline, for example with forks with two or more lines coming from a single point, then there are two main options, either create several polyline objects sharing a single point, or backtrack over points after reaching the end of one fork, and then continuing to add points along the second fork, and so on.

Example Code

// Assume that a WWT view object has been created, named wwtView
// The following function will add a polyline to the view object, and
// return a reference to the created object.

function createWWTPolyLine(lineColor, lineWidth, opacity, points)
{
    var polyLine = wwtView.CreatePolyLine();
    polyLine.LineColor = lineColor;
    polyLine.LineWidth = lineWidth;
    polyLine.Opacity = opacity;
    for (var i in points)
    {
        polyline.AddPoint(points[i][0], points[i][1]);
    }
    return polyLine;
}
//
// Then to use this function create a two-dimensional array of [ra,dec] points
//
var points = [[20, -29], [22, -22], [16, -11], [12, -10], [15,-25]];
//
// ....and call the function appropriately
//
var myPolyline = createWWTPolyLine(0x8800FFFF, 2, 1.0, points);

Polylines
This image shows some common variations of Polyline objects.

Samples

See Also


View.GetDec

The GetDec method retrieves the declination for the view.

Syntax

View.GetDec()

Parameters

This method takes no parameters.

Return Values

This method returns a double containing the declination in decimal degrees.

Remarks

The declination of an object is how many degrees it is north or south of the celestial equator. It is used in conjunction with right ascension, which is measured eastward from a prime meridian on the sky. The prime meridian passes through the position of the Sun at the time of the vernal equinox, so its position changes slowly over the years, due to the precession of the equinoxes. The position of the celestial poles also changes with precession, so to locate an object from its right ascension and declination, you must also know the date for which those coordinates are valid; that date is called the epoch of the coordinates. WorldWide Telescope requires the epoch to be J2000.

Example Code

// Save off the current view...
var savedRA = wwtView.GetRA();
var savedDec = wwtView.GetDec();
var savedFov = wwtView.Fov;

// Goto a new view...
wwtView.Goto(newRA, newDec, newFov, false);

// If the user selects a custom control to go back to the previous view...
wwtView.Goto(savedRA, savedDec, savedFov, false);

Samples

See Also


View.GetRA

The GetRA method retrieves the right ascension for the view.

Syntax

View.GetRA()

Parameters

This method takes no parameters.

Return Values

This method returns a double containing the right ascension in decimal degrees.

Remarks

Refer to the remarks for GetDec.

Example Code

// Function to zoom in....

function FovDec() {
   var newFov = wwtView.Fov / 1.1;
   if (wwtView.Fov >= 0.00022910934437488727) {
      wwtView.Goto(wwtView.GetRA(), wwtView.GetDec(), newFov, false);
   }
}

Samples

See Also


View.Goto

The Goto method is used to go to a new viewing position.

Syntax

View.Goto(
  ra  [Double],
  dec  [Double],
  fov  [Double],
  instant  [Bool]
)

Parameters

ra
  Specifies the right ascension in decimal degrees.
dec
  Specifies the declination in decimal degrees.
fov
  Specifies the field of view. Maximum is 60 degrees, minimum is 0.00022910934437488727 of a degree.
instant
  True indicates that the view should change instantly, false that the view should slew through space to the new location. Currently the wwtArrived event is not being sent if this value is set to True.

Return Values

This method does not return a value.

Remarks

This method is one of the most used of the API set, controlling the changing of the views.

Example Code

// The following code shows how to convert from hours, minutes and seconds
// to a right ascension and degrees, minutes and seconds to a declination.

function HMS(h, m, s) {
   h = h + (m/60) + (s/3600);
   var d = h * 15; // Convert from hours to degrees (360/24 = 15)
   return d;
}

function DMS(d, m, s) {
   if (d < 0) {
      m = -m;
      s = -s;
   }
   d = d + (m/60) + (s/3600);
   return d;
}

wwtView.Goto(HMS(06, 25, 30), DMS(45, 00, 00), 30, false);

Samples

See Also


View.HideUI

The HideUI method specifies whether to hide the UI for the view.

Syntax

View.HideUI(
  hide  [Bool]
)

Parameters

hide
  True indicates the UI should be hidden.

Return Values

This method does not return a value.

Remarks

If the UI is hidden, the main menu, thumbnails, collections, tours and so on will not be visible, giving an uninterrupted view. This can be helpful when control of the view is being handled by a custom client UI.

Example Code

var bShowUI = true;

function toggleSetting(text) {
  switch (text) {
     case 'ShowUI':
       bShowUI = !bShowUI;
       wwtView.HideUI(!bShowUI);
     break;
     ....
   }
}

\\ The toggleSetting function should be used along with the following control
<input id="UI" type="checkbox" checked="checked" onclick="toggleSetting('ShowUI');"/>

Samples

See Also


View.LoadImageCollection

The LoadImageCollection method is used to load a WTML
 collection file, containing links to foreground and background images.

Syntax

View.LoadImageCollection(
  url  [String]
)

Parameters

url
  Specifies the URL of the image collection file (a .WTML
 file).

Return Values

This method does not return a value.

Remarks

For a description of the content of image collection files, refer to the WorldWide Telescope Data Files Reference document.

After the collection is loaded, the images can be referenced by their string name using the SetBackgroundImageByName and SetForegroundImageByName methods.

Example Code

// If the data file is in the same folder as the JScript Web Control.
wwtView.LoadImageCollection("imageFile.wtml");

// If the data file requires a full path
wwtView.LoadImageCollection("path//imageFile.wtml");

Samples

See Also


View.LoadTour

The LoadTour method is used to load and start a tour.

Syntax

View.LoadTour(
  url  [String]
)

Parameters

url
  Specifies the complete URL for the tour (a .wtt file).

Return Values

This method does not return a value.

Remarks

Tours are a sequence of tour stops. Each tour stop describes a viewing position, with accompanying audio (music or speech), and graphics (text, shapes or images). The amount of time a tour should spend at each stop is specified, along with how the transition should be made (instant or slewing) to the next stop. Obviously when the last tour stop has been visited, the tour is completed. On completion the end tour dialog will appear.

Tours can be stand-alone, or part of collections. For more information on tours refer to the WorldWide Telescope User Guide, and also to the WorldWide Telescope Data Files Reference document.

Example Code

wwtView.LoadTour("http://www.worldwidetelescope.org/docs/wtml/tourone.wtt");

Samples

See Also


View.LoadVOTable

The LoadVOTable method is used to load a VO (Virtual Observatory) table.

Syntax

View.LoadVOTable(
  url  [String],
  useCurrentView  [Bool]
)

Parameters

url
  Specifies the URL of the VO table file (usually a .xml file).
useCurrentView
  True indicates that a new right ascension, declination and radius are not included as parameters of the URL -- so a cone search calculating these values will be carried out. False indicates that the right ascension, declination and radius are included as parameters within the URL.

Return Values

This method does not return a value.

Remarks

The VO data will appear as a spreadsheet in its own window. For details on the VO standard for storing data, refer to us-vo.org.

Example Code

wwtView.LoadVOTable("path.xml", true);

See Also


View.PlayTour

The PlayTour method is used to restart a tour from the beginning.

Syntax

View.PlayTour()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

Refer to the remarks for the LoadTour method.

Example Code

function restartTour()
{
    wwtView.PlayTour();
}

Samples

See Also


View.RemoveAnnotation

The RemoveAnnotation method removes the specified annotation from the view.

Syntax

View.RemoveAnnotation(
  annotation  [Annotation]
)

Parameters

annotation
  The Annotation object to be removed.

Return Values

This method does not return a value.

Remarks

None.

Example Code

// Global settings
var bShowCircle = false;
var bShowPolygon = false;

// Function to toggle the display of annotations

function toggleSetting(text) {

   switch (text) {

     case 'ShowCircle':

       bShowCircle = !bShowCircle;

       if (bShowCircle) {
         wwtView.AddAnnotation(circle1);
       } else {
         wwtView.RemoveAnnotation(circle1);
       }
       break;

     case 'ShowPolygon':

       bShowPolygon = !bShowPolygon;

       if (bShowPolygon) {
         wwtView.AddAnnotation(polygon1);
       } else {
         wwtView.RemoveAnnotation(polygon1);
       }
     break;
   }
}

Samples

See Also


View.SetBackgroundImageByName

The SetBackgroundImageByName method loads an image to use as the view background.

Syntax

View.SetBackgroundImageByName(
  name  [String]
)

Parameters

name
  Specifies the name of the image.

Return Values

This method does not return a value.

Remarks

The string used as the name parameter for this method should be present as a Place name in the .WTML
 file loaded by the LoadImageCollection method. Typically background images come from Survey data, such as visible light, x-ray, infrared, ultraviolet, gamma, and so on. In the UI of WorldWide Telescope, the background image is selected with the Imagery entry, and if there is a foreground image, the Image Crossfade slider will appear.

A background image need not cover the whole sky, and can in fact be a simple study of one object in space. In this case the rest of the sky will be dark and empty, except for the solar system which is not considered foreground or background.

Example Code

    wwtView.LoadImageCollection("MyImageCollection.wtml");
    wwtView.SetBackgroundImageByName("The Big Picture");
    wwtView.Goto(45.5, 122.0, 2, false);

Samples

See Also


View.SetForegroundImageByName

The SetForegroundImageByName method loads an image to use as the view foreground.

Syntax

View.SetForegroundImageByName(
  name  [String]
)

Parameters

name
  Specifies the name of the image.

Return Values

This method does not return a value.

Remarks

The string used as the name parameter for this method should be present as a Place name in the .WTML
 file loaded by the LoadImageCollection method. There can be only one foreground image and only one background image rendered at any one time. The typical use is to render studies as foreground images on top of a survey as a background image.

If the opacity of the foreground image is solid, the background image will not be visible underneath. However if the SetForegroundOpacity method is used to add some transparency, then both foreground and background images will be visible, and can be compared. Typical use of these two layers is to load a visual survey as either foreground or background, and then to compare it with an x-ray, heat or image of another non-visible wavelength, enabling a visual comparison between the two.

In the UI of WorldWide Telescope the Explore > Open > Collection menu selection is typically used to load foreground images. If the WTML
 collection file explicitly defines a study as a background, or a survey as foreground, then this menu selection can be used to reverse the normal process. However, by default, studies loaded this way are treated as foreground, surveys as background.

To load a survey as a foreground image, or a study as a background image, use Folder entries with the following structures. Note all the extra information needed in the Place entry for a study image.

<?xml version="1.0"?>
<Folder>
<Folder Name="Background Studies" Group="View" Searchable="True" Type="Sky">
  
  <Place Name="Study One" DataSetType="Sky" RA="0" Dec="0" Constellation="0" Classification="0" Magnitude="0" 
     Distance="0" ZoomLevel="0" Rotation="0" Angle="0" Opacity="100" AngularSize="1">
    <Target>Undefined</Target>
    <BackgroundImageSet>
    <!-- Enter the study image set here
          <ImageSet 

          </ImageSet>
    -->
    </BackgroundImageSet>
  </Place>
</Folder>
<!--
-->

<Folder Name="Foreground Surveys" Group="Explorer">
  <Place Name="Survey One">
    <ForegroundImageSet>
      <!-- Enter the survey image set here
    <ImageSet 
    

        </ImageSet>
       -->
    </ForegroundImageSet>
  </Place>
</Folder>
</Folder>

The Sun and solar system planets and moons are not considered either foreground or background, and will be present in any sky view.

Note that the images used for both foreground and background are tiled image pyramids. Refer to the tools documentation WorldWide Telescope Data Tools Guide for details on how to create these image pyramids, and to the WorldWide Telescope Data Files Reference for details on the data file formats.

Example Code

    wwtView.LoadImageCollection("Serpens.wtml");
    wwtView.SetForegroundImageByName("The Serpens Dark Cloud");
    wwtView.Goto(277.274985, 0.545000, 1, false);

The "Serpens.wtml" file contains the following:

Samples

See Also


View.SetForegroundOpacity

The SetForegroundOpacity method specifies the opacity of the foreground image, which can be useful when visually comparing the foreground and background images.

This method is not currently implemented.

Syntax

View.SetForegroundOpacity(
  opacity  [Double]
)

Parameters

opacity
  Specifies opacity, in the range 0.0 to 1.0.

Return Values

This method does not return a value.

Remarks

This setting enables some see-through in the foreground image, to enable a comparison with the background image. Note that if the foreground image is a .png file, then some transparency information is usually held within the file. The SetForegroundImageByName method sets the foreground opacity to 1.0 each time a new image is loaded.

Example Code

wwtView.SetForegroundOpacity(0.8);

Samples

See Also


View.StopTour

The StopTour method is used to stop and exit a tour.

Syntax

View.StopTour()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

After a tour has been stopped with this call, it cannot be restarted from the position it was stopped at. PlayTour (which restarts a tour) will not work after a tour has been stopped. Also refer to the remarks for LoadTour.

Example Code

function loadTour(tourURL) {
    wwtView.LoadTour(tourURL);
}

function stopTour() {
    wwtView.StopTour();
}

Samples

See Also


wwtAnootationclicked

The wwtAnootationclicked event is fired when an Annotation object is clicked on. Note the spelling error!.

Syntax

function wwtAnootationclicked(ra, dec, id){}

Remarks

The id parameter contains the string set in the Annotation.ID property.

Example Code

function wwtAnootationclicked(ra, dec, id) {
   alert("Annotation: " + id.toString());
}

Samples

See Also


wwtArrived

The wwtArrived event is fired when a change to the view from a drag, zoom, or goto comes to a halt.

Syntax

function wwtArrived(){}

Remarks

When the view is to change following a drag, zoom, or goto, normally there will be an animated slew across space until the new view comes to rest. It is on the completion of the slew that this event is fired.

Currently this event is not being sent if the instant parameter of the Goto method is set to True.

Example Code

function wwtArrived() {
// Show that we have arrived by drawing a red circle at the new ra, dec

// Create the circle (see the CreateCircle example code for a listing
// of the createWWTCircle function).

  var circle1 = createWWTCircle(false, 0x88FF0000, 0x00000000, 3, 1.0, 15, false,
                                wwtView.GetRA(), wwtView.GetDec());
  wwtView.AddAnnotation(circle1);
}

Samples

See Also


wwtClick

The wwtClick event is fired when the left mouse button is clicked.

Syntax

function wwtClick(ra, dec){}

Remarks

This event is not fired for all mouse clicks, only those when the view is stationary and the mouse click is not part of a zoom or drag procedure. In other words, it is evident that the user is clicking on an object. The RA and Dec provided as parameters are the location of the click, which will not usually be the same as the RA and Dec for the current view.

Example Code

function wwtClick(ra, dec) {
   alert("Clicked on: " + ra.toString() + ", " + dec.toString());
}

Samples

See Also


wwtReady

The wwtClick event is fired when the web client is initialized.

Syntax

function wwtReady(){}

Remarks

This event is fired only once, and should be responded to by all clients. Use it to initialize internal variables appropriately, in particular the reference to the View object, shown in the example code.

Example Code

var wwtView;

function wwtReady() {
   wwtView = document.getElementById("silverlightObject").content.WWT;

   wwtView.Settings.ShowCrosshairs = true;
   wwtView.Settings.ShowConstellationFigures = false;
}

Samples

See Also


Web Control Samples

The following table lists the samples that can be used as a starting point for WorldWide Telescope web client development.

Click on the Sample Name to view the source. Note that paths may need to be changed for the samples to work, these paths are highlighted by comments in the sample code.

Sample Name
Description
Link
Sky samples
WWT Web Client Simple Performs the basic steps of opening up a client, and provide a few UI controls to select one of two constellations, and change a few settings.
Run
WWT Web Client Poly Adds the creation of two circle, one polygon and one polyline annotation objects to the simple client.
Run
WWT Web Client Arrived Shows the use of the Arrived event, drawing a red circle on the new view when the event is received.
Run
WWT Web Client Click Event Shows the use of the Click event, drawing a circle or an alert box giving the location of the click.
Run
WWT Web Client Fov Shows the current Field of View, with buttons to zoom in and out.
Run
WWT Web Client Local View Shows the view from a number of cities around the world.
Run
WWT Web Client Images Loads a sample image collection, enabling the selection of one of three foreground images.
Run
WWT Web Client Tours Loads and runs one of two simple tours of the Solar System.
Run
Earth samples
WWT Web Client Earth City Search Change the view to the Earth, then locate cities and lat/long locations.
Run
Planet samples
WWT Web Client Mars Explorer Change the view to Planets and the Imagery to Mars, then scroll through a range of surface features from the Valles Marineris canyon to the Happy Face crater.
Run

Note that for samples to run correctly they must be located from a web address (http://...) and not from a local file address.

See Also


Web Control Demos

The following table lists some demonstration programs that have been created using the SDK.

Demo Name
Description
Link
WWT Web Client Hi-Def Planet Explorer Provides a range of options for exploring the surfaces of our Moon and Mars. Thousands of surface features, including craters, mountains, valleys, seas, plains, ridges and depressions, are available to step through, sort, search and view.

Make sure to select the correct planet or moon in the Look At and Imagery drop down lists, after starting the program.
Run
WWT Web Client Distant Planet Explorer Provides a range of options for exploring the surfaces of Mercury, Venus, and the four main moons of Jupiter: IO, Ganymede, Europa and Callisto. Hundreds of surface features, are available to step through, sort, search and view.

Make sure to select the correct planet or moon in the Look At and Imagery drop down lists, after starting the program.
Run
WWT Web Client Messier Catalog All 110 objects in this famous catalog can be viewed, displayed as a slide show, sorted and searched.
Run

See Also