 |
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 Silverlight implementation of the Worldwide Telescope has been deprecated.
For reference you can still find all the WWT SDK documentation for Silverlight here: WWT SDK documentation for Silverlight
Also please see this conversion tutorial to help you convert any Silverlight code to the new HTML5 implementation.
To develop WorldWide Telescope web control applications, ensure the following steps have been completed:
|
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 HTML5 canvas tag is used by the WorldWide Telescope object. The following shows how to incorporate the canvas tag and the WorldWide telescope object into your html page:
WWT simple client |
| WWTWebClientSimpleHtml5.html |
The WWTControl object is the principal object, the other objects are created on initialization of the 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 |
| Annotation | Used to describe the annotation for a Circle, Poly or PolyLine object. |
| Circle | Used to render a circle on the screen. |
| Poly | Used to render a polygon on the screen. |
| PolyLine | Used to render a polyline on the screen. |
| Settings | Used to specify a range of settings for a View object. |
| WWTControl | Used to manage the canvas view of WorldWide Telescope images. |
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 |
| ID | Contains a string for use by the web client. |
| Label | Contains descriptive text for the annotation. |
| Opacity | Specifies the opacity to be applied to the complete annotation. |
| ShowHoverLabel | Specifies whether to render the label if the mouse is hovering over the annotation. |
| Center | Specifies the center of the annotation. |
| Tag | Contains a string for use by the web client. |
The ID property contains a string for use by the web client.
Annotation.set_id([string])
[string] Annotation.get_id()
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 AnnotationClicked event.
// Draw a circle at the center of the constellation Sagittarius
circle.set_center(286.485, -27.5231666666667);
circle.set_id("Center of the Constellation Sagittarius");The Label property contains descriptive text for the annotation.
Annotation.set_label([string])
[string] Annotation.get_label()
The label text will be rendered if the ShowHoverLabel property is set to true.
// Draw a circle at the center of the constellation Sagittarius
circle.set_center(286.485, -27.5231666666667);
circle.set_id("Center of the Constellation Sagittarius");
circle.set_label("RA: 286.485, Dec: -27.5231666666667");The Opacity property specifies the opacity to be applied to the complete annotation.
Annotation.set_opacity([double])
[double] Annotation.get_opacity()
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.
// Set a solid fill color
circle.set_fillColor("red");
circle.set_fill(true);
// Apply a 50% transparency to the entire annotation
circle.set_opacity(0.5);The ShowHoverLabel property specifies whether to render the label if the mouse is hovering over the annotation.
Annotation.set_showHoverLabel([Bool])
[Bool] Annotation.get_showHoverLabel()
The default setting is false.
// Draw a circle at the center of the constellation Sagittarius
circle.set_center(286.485, -27.5231666666667);
circle.set_id("Center of the Constellation Sagittarius");
circle.set_label("RA: 286.485, Dec: -27.5231666666667");
circle.set_showHoverLabel(true);The Center property contains a Vector3d object for use by the web client.
Annotation.set_center([Vector3d])
[Vector3d] Annotation.get_center()
This Vector3d object is used to hold the center position of the annotation object used by the web client.
var vector3d = new wwtlib.Vector3d(x, y, z);
circle.set_center(vector3d);
The Tag property contains a string for use by the web client.
Annotation.set_tag([string])
[string] Annotation.get_tag()
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.
circle.set_tag("001");
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.
 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 |
| Fill | Specifies whether the circle should be filled or not. |
| FillColor | Specifies the fill color as an ARGB value. |
| LineColor | Specifies the line color as an ARGB value. |
| LineWidth | Specifies the line width in pixels. |
| Radius | Specifies the circle radius. |
| SkyRelative | Specifies whether the circle size is absolute or relative. |
Method | Description |
| SetCenter | Specifies the center coordinates of the circle. |
The Fill property specifies whether the circle should be filled or not.
Circle.set_fill([Bool])
[Bool] Circle.get_fill();
The default is false.
// Fill a circle with a transparent red
circle.set_fill(true);
circle.set_fillColor("0x55AA0000");The FillColor property specifies the fill color as an ARGB value.
Circle.set_fillColor([string])
[string] Circle.get_fillColor()
The default fill color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.
// Fill a circle with opaque green
circle.set_fill(true);
circle.set_fillColor("green");The LineColor property specifies the line color as an ARGB value.
Circle.set_lineColor([string])
[string] Circle.get_lineColor()
The default line color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.
// Draw a circle in opaque dark gray
circle.set_lineColor("0xFF555555");The LineWidth property specifies the line width in pixels.
Circle.set_lineWidth([double])
[double] Circle.get_lineWidth()
The default line width is 1 pixel.
// Double the default line width
circle.set_lineWidth(2);The Radius property specifies the circle radius.
Circle.set_radius([double])
[double] Circle.get_radius()
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.
// Draw a fixed circle with a radius of 25 pixels
circle.set_skyRelative(false);
circle.set_radius(25);The SkyRelative property specifies whether the circle size is absolute or relative.
Circle.set_skyRelative([Bool])
[Bool] Circle.get_skyRelative()
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.
// Draw a SkyRelative circle with a radius of 0.2 degrees of arc
circle.set_skyRelative(true);
circle.set_radius(0.2);The SetCenter method specifies the center coordinates of the circle.
Circle.setCenter(
ra [Double],
dec [Double]
)
This method does not return a value.
The default value for right ascension and declination is zero.
// Draw a circle at the center of the constellation Sagittarius
circle.setCenter(286.485, -27.5231666666667);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 |
| Fill | Specifies whether the polygon is filled or not. |
| FillColor | Specifies the fill color as an ARGB value. |
| LineColor | Specifies the line color as an ARGB value. |
| LineWidth | Specifies the line width in pixels. |
Method | Description |
| AddPoint | Adds a point to a polygon. |
The Fill property specifies whether the polygon is filled or not.
Poly.set_fill([Bool])
[Bool] Ploy.get_fill()
The default fill setting is false.
// Fill a polygon with a slightly transparent blue
poly.set_fill(true);
poly.set_fillColor("0xBB0000AA");The FillColor property specifies the fill color as an ARGB value.
Poly.set_fillColor([uint])
[uint] Poly.get_fillColor()
The default fill color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.
// Set a solid red fill color
poly.set_fill(true);
poly.set_fillColor("red");The LineColor property specifies the line color as an ARGB value.
Poly.set_lineColor([uint])
[uint] Poly.get_lineColor()
The default color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.
// Set a solid black line color
poly.set_lineColor("0xFF000000");The LineWidth property specifies the line width in pixels.
Poly.set_lineWidth([double])
[double] Poly.get_lineWidth()
The default line width is 1 pixel.
// Double the line width
poly.set_lineWidth(2 * poly.get_lineWidth());The AddPoint method adds a point to a polygon.
Poly.addPoint(
x [Double],
y [Double]
)
This method does not return a value.
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.
// 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);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 |
| LineColor | Specifies the line color as an ARGB value. |
| LineWidth | Specifies the line width in pixels. |
Method | Description |
| AddPoint | Adds a point to the polyline. |
The LineColor property specifies the line color as an ARGB value.
PolyLine.set_lineColor([uint])
[uint] PolyLine.get_lineColor()
The default color is white. The four bytes of the unsigned integer are the alpha, red, green and blue values respectively.
// Set a solid blue color
poly.set_fillColor("blue");The LineWidth property specifies the line width in pixels.
PolyLine.set_lineWidth([double])
[double] PolyLine.get_lineWidth()
The default line width is 1 pixel.
poly.set_lineWidth(3);The AddPoint method adds a point to a polyline.
PolyLine.addPoint(
x [Double],
y [Double]
)
This method does not return a value.
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.
// 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);The Settings object is used to specify a range of settings for a WWTControl object. The Settings object is created as part of the initialization of a WWTControl object.
The Settings object is referenced from the Settings property of the WWTControl object.
Property | Description |
| ConstellationBoundryColor | Specifies the constellation boundary color as an ARGB value. |
| ConstellationFigureColor | Specifies the constellation figure color as an ARGB value. |
| ConstellationSelectionColor | Specifies the constellation selection color as an ARGB value. |
| EclipticColor | Specifies the ecliptic color as an ARGB value. |
| GridColor | Specifies 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. |
| LocationLat | Specifies the view location latitude. |
| LocationLng | Specifies the view location longitude. |
| ShowClouds | Specifies whether to show the Earth's cloud layer. |
| ShowConstellationBoundries | Specifies whether to show constellation boundaries. |
| ShowConstellationFigures | Specifies whether to show constellation figures. |
| ShowConstellationSelection | Specifies whether to show only the selected constellation. |
| ShowCrosshairs | Specifies whether to show cross-hairs. |
| ShowEcliptic | Specifies whether to show the path of the Sun. |
| ShowElevationModel | Specifies whether to show the elevation model. |
| ShowFieldOfView | Specifies whether to show the field of view box. |
| ShowGrid | Specifies whether to show the equatorial grid. |
| ShowHorizon | Specifies whether to show the horizon. |
| ShowHorizonPanorama | Specifies whether to show the panorama horizon. |
| ShowMoonsAsPointSource | Specifies whether to show the moon as a point source. |
| ShowSolarSystem | Specifies whether to show the 3-D solar system view. |
| ShowUTCTime | Specifies whether to show the time as a UTC value. |
| SolarSystemCosmos | Specifies whether to show the solar system cosmos. |
| SolarSystemLighting | Specifies whether to show the lighting effect of the Sun on the solar system. |
| SolarSystemMilkyWay | Specifies whether to show the Milky Way when showing the solar system. |
| SolarSystemMultiRes | Specifies whether to show the multi-resolution textures for the planets. |
| SolarSystemOrbitColor | Specifies the solar system orbit color as an ARGB value. |
| SolarSystemOrbits | Specifies whether to show the solar system orbits. |
| SolarSystemOverlays | Specifies whether to show the solar system overlays. |
| SolarSystemScale | Specifies how to scale the size of the Sun and the planets. |
| SolarSystemStars | Specifies whether to render stars when showing the solar system. |
| UserID | Specifies the user ID as a Guid. |
The ConstellationBoundryColor property specifies the constellation boundary color as an ARGB value.
wwtControler.settings.set_constellationBoundryColor([uint])
[uint] wwtControler.settings.get_constellationBoundryColor()
The default boundary color is blue.
// set the constellation boundary color to green
wwtControl.settings.set_constellationBoundryColor("green");The ConstellationFigureColor property specifies the constellation figure color as an ARGB value.
wwtControl.settings.set_constellationFigureColor([uint])
[uint] wwtControl.settings.get_constellationFigureColor()
The default figure color is red.
// set the constellation figures color to blue
wwtControl.settings.set_constellationFigureColor("blue");The ConstellationSelectionColor property specifies the constellation selection color as an ARGB value.
wwtControl.settings.set_constellationSelectionColor([uint])
[uint] wwtControl.settings.get_constellationSelectionColor()
The default selection color is yellow.
// set the constellation selection color to red
wwtControl.settings.set_constellationSelectionColor("red");Note: This feature is not implemented.
The EclipticColor property specifies the ecliptic color as an ARGB value.
wwtControl.settings.set_eclipticColor([uint])
[uint] wwtControl.settings.get_eclipticColor()
The default ecliptic color is green.
// set the ecliptic color to transparent green
wwtControl.settings.set_eclipticColor("0xAA00FF00");Note: This feature is not implemented.
The GridColor property specifies the grid color as an ARGB value.
wwtControl.settings.set_gridColor([uint])
[uint]wwtControl.settings.get_gridColor()
The default equatorial grid color is gray.
// set the grid color to green
wwtControl.settings.set_gridColor("green");Note: This feature is not implemented.
The LocalHorizonMode property specifies that the view should be from a local lat/long/alt position (for example, a city, or landmark).
wwtControl.settings.set_localHorizonMode([Bool])
[Bool]wwtControl.settings.get_localHorizonMode()
This setting is equivalent to the View > View from this location checkbox, after setting up a local viewpoint.
wwtControl.settings.set_localHorizonMode(true);
 The view from New York of the Andromeda Constellation. Note the horizon and compass directions. |
 The view of Andromeda from the default viewing position, without any local horizon. |
The LocationAltitude property specifies the view location altitude in meters.
wwtControl.settings.set_locationAltitude([double])
[double]wwtControl.settings.get_locationAltitude()
None.
// Set the view from London, UK
wwtControl.settings.set_locationLat(51.31);
wwtControl.settings.set_locationLng(-0.06);
wwtControl.settings.set_locationAltitude(21);
wwtControl.settings.set_localHorizonMode(true);The LocationLat property specifies the view location latitude.
wwtControl.settings.set_locationLat([double])
[double] wwtControl.settings.get_locationLat()
The default location latitude is 47.633.
// Set the view from Sydney, Australia
wwtControl.settings.set_locationLat(-33.52);
wwtControl.settings.set_locationLng(151.125);
wwtControl.settings.set_locationAltitude(34);
wwtControl.settings.set_localHorizonMode(true); |
The LocationLng property specifies the view location longitude.
wwtControl.settings.set_locationLng([double])
[double] wwtControl.settings.get_locationLng()
The default location longitude is 122.133333.
// Set the view from San Francisco, USA
wwtControl.settings.set_locationLat(37.455);
wwtControl.settings.set_locationLng(-122.262);
wwtControl.settings.set_locationAltitude(72);
wwtControl.settings.set_localHorizonMode(true);Note: This feature is not implemented.
The ShowClouds property specifies whether to show the Earth's cloud layer.
wwtControl.settings.set_showClouds([Bool])
[Bool] wwtControl.settings.get_showClouds()
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.
wwtContorl.settings.set_showClouds(true);
 | The Earth without its cloud layer. |
 | The Earth with its cloud layer. |
The ShowConstellationBoundries property specifies whether to show constellation boundaries.
wwtControl.settings.set_showConstellationBoundries([Bool])
[Bool]wwtControl.settings.get_showConstellationBoundries()
This setting is equivalent to the View > Boundaries checkbox.
wwtControl.settings.set_showConstellationBoundries(true);
 The constellation boundaries are shown in blue, except for the selected constellation, with its boundary in yellow. |
The ShowConstellationFigures property specifies whether to show constellation figures.
wwtControl.settings.set_showConstellationFigures([Bool])
[Bool] wwtControl.settings.get_showConstellationFigures()
This setting is equivalent to the View > Figures checkbox.
wwtControl.settings.set_showConstellationFigures(true);
 The constellation figures. |
The ShowConstellationSelection property specifies whether to show only the selected constellation.
wwtControl.settings.set_showConstellationSelection([Bool])
[Bool] wwtControl.settings.get_showConstellationSelection()
This setting is equivalent to the View > Focused Only checkbox.
wwtControl.settings.set_showConstellationSelection(true);
 The selected constellation. |
The ShowCrosshairs property specifies whether to show cross-hairs.
wwtControl.settings.set_showCrosshairs([Bool])
[Bool] wwtControl.settings.set_showCrosshairs()
This setting is equivalent to the View > Reticle/Crosshairs checkbox.
wwtControl.settings.set_showCrosshairs(true);
 | The crosshairs, or reticle, shown with Mars in view. |
Note: This feature is not implemented.
The ShowEcliptic property specifies whether to show the path of the Sun.
wwtControl.settings.set_showEcliptic([Bool])
[Bool] wwtControl.settings.get_showEcliptic()
This setting is equivalent to the View > Ecliptic/Orbits checkbox, which indicates that the path of the Sun should be rendered as a line.
wwtControl.settings.set_showEcliptic(true);
 |
Note: This feature is not implemented.
The ShowElevationModel property specifies whether to show the elevation model.
wwtControl.settings.set_showElevation([Bool])
[Bool] wwtControl.settings.get_showElevation()
This setting is equivalent to the Settings > Show Elevation Model checkbox.
wwtControl.settings.set_showElevationModel(true);
 | The Himalayan mountains, shown without elevation data. |
 | The Himalayan mountains, with elevation data. |
Note: This feature is not implemented.
The ShowFieldOfView property specifies whether to show the field of view box.
wwtControl.settings.set_showFieldOfView([Bool])
[Bool] wwtControl.settings.get_showFieldOfView()
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.
wwtControl.settings.set_showFieldOfView(true);
 Gamma Pegasi shown with the Field of View Indicator box. |
Note: This feature is not implemented.
The ShowGrid property specifies whether to show the equatorial grid.
wwtcontrol.settings.set_showGrid([Bool])
[Bool] wwtcontrol.settings.get_showGrid()
This setting is equivalent to the View > Equatorial Grid check box.
wwtControl.settings.set_showGrid(true);
 The Equatorial grid shown, looking North, with the Hydrogen Alpha Full Sky Map as the data source. |
Note: This feature is not implemented.
The ShowHorizon property specifies whether to show the horizon.
wwtControl.settings.set_showHorizon([Bool])
[Bool] wwtControl.settings.get_showHorizon()
None.
wwtControl.settings.set_showHorizon(true);
Note: This feature is not implemented.
The ShowHorizonPanorama property specifies whether to show the horizon in panoramas.
wwtControl.settings.set_showHorizonPanorama([Bool])
[Bool] wwtControl.settings.get_showHorizonPanorama()
None.
wwtControl.settings.set_showHorizonPanorama(true);
Note: This feature is not implemented.
The ShowMoonsAsPointSource property specifies whether to show the moon as a point source.
wwtControl.settings.set_showMoonsAsPointSource([Bool])
[Bool] wwtControl.settings.get_showMoonsAsPointSource()
None.
wwtControl.settings.set_showMoonsAsPointSource(true);
Note: This feature is not implemented.
The ShowSolarSystem property specifies whether to show the 3-D solar system view.
wwtControl.settings.set_showSolarSystem([Bool])
[Bool] wwtControl.settings.get_showSolarSystem()
This setting can also be changed from within Tours, enabling a tour to switch from a view of a distant object to a 3-D view of one of the objects in the Solar System.
wwtControl.settings.set_showSolarSystem(true);
Note: This feature is not implemented.
The ShowUTCTime property specifies whether to show the time as a UTC value.
wwtControl.settings.set_showUTCTime([Bool])
[Bool] wwtControl.settings.get_showUTCTime()
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.
wwtControl.settings.set_showUTCTime(true);
Note: This feature is not implemented.
The SolarSystemCosmos property specifies whether to show the solar system cosmos.
wwtControl.settings.set_solarSystemCosmos([Bool])
[Bool] wwtControl.settings.get_solarSystemCosmos()
None.
wwtControl.settings.set_solarSystemCosmos(true);
Note: This feature is not implemented.
The SolarSystemLighting property specifies whether to show the lighting effect of the Sun on the solar system.
wwtControl.settings.set_solarSystemLighting([Bool])
[Bool] wwtControl.settings.get_solarSystemLighting()
This setting is equivalent to the View > Lighting checkbox.
wwtControl.settings.set_solarSystemLighting(true);
 | The lighting of the Sun on Saturn. |
Note: This feature is not implemented.
The SolarSystemMilkyWay property specifies whether to show the Milky Way when showing the solar system.
wwtControl.settings.set_solarSystemMilkyWay([Bool])
[Bool] wwtControl.settings.get_solarSystemMilkyWay()
This setting is equivalent to the View > Milky Way checkbox.
wwtControl.settings.set_solarSystemMilkyWay(true);
 | The Milky Way appears to the left of Saturn. |
Note: This feature is not implemented.
The SolarSystemMultiRes property specifies whether to show the multi-resolution textures for the planets.
wwtControl.settings.set_solarSystemMultiRes([Bool])
[Bool] wwtControl.settings.get_solarSystemMultiRes()
Multi-resolution textures are very detailed images of a planet surface. If these are not enabled then it does not make sense to zoom close to the surface. If they are enabled then individual buildings, for example, can be located.
This setting is equivalent to the Settings > Multi-Res Solar System Bodies checkbox.
wwtControl.settings.set_solarSystemMultiRes(true);
 | The Caribbean in standard textures. |
 | The Caribbean with multi-resolution textures. |
Note: This feature is not implemented.
The SolarSystemOrbitColor property specifies the solar system orbit colors as an ARGB value.
wwtControl.settings.set_solarSystemOrbitColor([uint])
[uint] wwtControl.settings.get_solarSystemOrbitColor()
The default orbit color is dark gray.
// set the solar system orbit color to red
wwtControl.settings.set_solarSystemOrbitColor("red");Note: This feature is not implemented.
The SolarSystemOrbits property specifies whether to show the orbits when showing the solar system.
wwtControl.settings.set_solarSystemOrbits([Bool])
[Bool] wwtControl.settings.get_solarSystemOrbits()
This setting is equivalent to the View > Orbits checkbox.
wwtControl.settings.set_solarSystemOrbits(true);
 | The orbits of all the solar system planets are shown in the SolarSystemOrbitColor. |
Note: This feature is not implemented.
The SolarSystemOverlays property specifies whether to show the solar system overlays.
wwtControl.settings.set_solarSystemOverlays([Bool])
[Bool] wwtControl.settings.get_solarSystemOverlays()
None.
wwtControl.settings.set_solarSystemOverlays(true);Note: This feature is not implemented.
The SolarSystemScale property specifies how to scale the size of the Sun and the planets.
wwtControl.settings.set_solarSystemScale([int])
[int] wwtControl.settings.get_solarSystemScale()
If this value is set to 1, then the Sun and planets will appear actual size in the Solar System view. To increase the scale, this value can be set to a number between 1 and 100. This setting is equivalent to the Planet Size slider.
wwtControl.settings.set_solarSystemScale(50);
 | The Sun shown actual size. |
 | The Sun with maximum scaling. |
Note: This feature is not implemented.
The SolarSystemStars property specifies whether to render stars when showing the solar system.
wwtControl.settings.set_solarSystemStars([Bool])
[Bool] wwtControl.settings.get_solarSystemStars()
This setting is equivalent to the View > Show Stars checkbox.
wwtControl.settings.set_solarSystemStars(true);
 | Saturn and the stars. |
Note: This feature is not implemented.
The UserID property is used to retrieve the user ID as a Guid.
wwtControl.settings.set_userID([Guid])
[Guid] wwtControl.settings.get_userID()
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.
// Assume an input tag has been set up in the html code
// Display the user ID in the "user" text box
document.getElementById("user").value = wwtControl.settings.get_userID();
The WWTControl 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 WWTControl object does not inherit any classes that have exposed properties or methods.
Property | Description |
| Fov | Contains the field of view in degrees. |
| Settings | Reference to the Settings object for the WWTControl. Note this object is created when the WWTControl 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 |
| AddAnnotation | Adds an Annotation object to the view. |
| ClearAnnotations | Removes all annotations from the view. |
| CreateCircle | Creates a Circle object, and returns a reference to the created object. |
| CreatePolygon | Creates a Poly object (a polygon), and returns a reference to the created object. |
| CreatePolyLine | Creates a PolyLine object, and returns a reference to the created object. |
| GetDec | Retrieves the declination for the view. |
| GetRA | Retrieves the right ascension for the view. |
| Goto | Used to go to a new viewing position. |
| HideUI | Specifies whether to hide the UI for the view. |
| LoadImageCollection |
Used to load a WTML collection file, containing links to foreground and background images. |
| LoadTour | Used to load and start a tour. |
| LoadVOTable | Used to load a VO (Virtual Observatory) table. |
| PlayTour | Used to restart a tour from the beginning. |
| RemoveAnnotation | Removes the specified annotation from the view. |
| SetBackgroundImageByName | Loads an image to use as the view background. |
| SetForegroundImageByName | Loads 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. |
| StopTour | Used to stop and exit a tour. |
Event | Description |
| AnnotationClicked | Fired when an Annotation object is clicked on. Note the spelling error! |
| wwtArrived | Fired when a change to the view from a drag, zoom, or goto comes to a halt. |
| wwtClick | Fired when the left mouse button is clicked. |
| wwtReady | Fired when the web client is initialized. |
Note: This feature is not implemented.
The Fov property contains the field of view in degrees.
[double] wwtControl.get_fov()
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.
// Function to increase the field of view (zoom out)
function FovInc() {
var newFov = 1.1 * wwtControl.get_fov();
if(newFov <= 60) {
wwtControl.goto(wwtControl.getRA(), wwtControl.getDec(), newFov, false);
}
}
// Function to decrease the field of view (zoom in)
function FovDec() {
var newFov = wwtControl.get_fov() / 1.1;
if(wwtControl.get_fov() >= 0.00022910934437488727) {
wwtControl.goto(wwtControl.getRA(), wwtControl.getDec(), newFov, false);
}
}
The Settings property references the Settings object for the WWTControl.
wwtControl.settings [Settings]
This property is read-only, though individual settings can have their values set (refer to the Settings object).
// show cross hairs and display a semi-transparent grid
wwtControl.settings.set_showCrosshairs(true);
wwtControl.settings.set_gridColor("0x88880000"); // Transparent red
wwtControl.settings.set_showGrid(true);
Note: This feature is not implemented.
The SmoothAnimation property specifies whether to pan smoothly or quickly to the new location.
wwtControl.set_smoothAnimation([Bool])
[Bool] wwtControl.get_smoothAnimation()
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.
wwtControl.set_smoothAnimation(true);The AddAnnotation method adds an Annotation object to the view.
wwtControl.addAnnotation(
annotation [Annotation]
)
This method does not return a value.
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.
// 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;
}
}The ClearAnnotations method removes all annotations from the view.
wwtControl.clearAnnotations()
This method takes no parameters.
This method does not return a value.
None.
wwtControl.clearAnnotations();The CreateCircle method creates a Circle object, and returns a reference to the created object.
wwtControl.createCircle(
fill [Bool]
)
This method returns a reference to a Circle object.
In addition to creating the circle an Annotation object (which is inherited by the Circle object) will be created to provide supporting text.
// Assume that a WWTControl object has been created, and named wwt
// 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 = wwt.createCircle(fill);
circle.set_lineColor(lineColor);
circle.set_fillColor(fillColor);
circle.set_lineWidth(lineWidth);
circle.set_opacity(opacity);
circle.set_radius(radius);
circle.set_skyRelative(skyRelative);
circle.setCenter(ra, dec);
return circle;
}
 In this image, circle objects filled with a transparent color have been used to identify point sources of light. |
The CreatePolygon method creates a Poly object (a polygon), and returns a reference to the created object.
wwtControl.CreatePolygon(
fill [Bool]
)
This method returns a reference to the created Poly object.
In addition to creating the polygon an Annotation object (which is inherited by the poly object) will be created to provide supporting text.
// Assume that a WWTControl object has been created, and named wwt
// 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 = wwt.createPolygon(fill);
poly.set_lineColor(lineColor);
poly.set_fillColor(fillColor);
poly.set_lineWidth(lineWidth);
poly.set_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);
 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. |
The CreatePolyLine method creates a PolyLine object, and returns a reference to the created object.
wwtControl.createPolyLine(
fill [Bool]
)
This method returns a reference to a PolyLine object.
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.
// Assume that a WWTControl object has been created, named wwt
// 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 = wwt.createPolyLine();
polyLine.set_lineColor(lineColor);
polyLine.set_lineWidth(lineWidth);
polyLine.set_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);
 This image shows some common variations of Polyline objects. |
The GetDec method retrieves the declination for the view.
wwtControl.getDec()
This method takes no parameters.
This method returns a double containing the declination in decimal degrees.
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.
// Save off the current view...
var savedRA = wwtControl.getRA();
var savedDec = wwtControl.getDec();
var savedFov = wwtControl.get_fov();
// Goto a new view...
wwtControl.goto(newRA, newDec, newFov, false);
// If the user selects a custom control to go back to the previous view...
wwtControl.goto(savedRA, savedDec, savedFov, false);
The GetRA method retrieves the right ascension for the view.
wwtControl.getRA()
This method takes no parameters.
This method returns a double containing the right ascension in decimal degrees.
Refer to the remarks for GetDec.
// Assume that a WWTControl object has been created, named wwt
// Function to zoom in....
function FovDec() {
var newFov = wwt.get_fov() / 1.1;
if(wwt.get_fov() >= 0.00022910934437488727) {
wwt.goto(wwt.getRA(), wwt.getDec(), newFov, false);
}
}
The Goto method is used to go to a new viewing position.
wwtControl.goto(
ra [Double],
dec [Double],
fov [Double],
instant [Bool]
)
This method does not return a value.
This method is one of the most used of the API set, controlling the changing of the views.
// 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;
}
wwtControl.goto(HMS(06, 25, 30), DMS(45, 00, 00), 30, false);
Note: This feature is not implemented.
The HideUI method specifies whether to hide the UI for the view.
wwtControl.hideUI(
hide [Bool]
)
This method does not return a value.
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.
var bShowUI = true;
function toggleSetting(text) {
switch (text) {
case 'ShowUI':
bShowUI = !bShowUI;
wwtControl.hideUI(!bShowUI);
break;
....
}
}
// The toggleSetting function should be used along with the following html input control
<input id="UI" type="checkbox" checked="checked" onclick="toggleSetting('ShowUI');"\>
The LoadImageCollection method is used to load a WTML
collection file,
containing links to foreground and background images.
wwtControl.loadImageCollection(
url [String]
)
This method does not return a value.
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.
// If the data file is in the same folder as the JScript Web Control.
wwt.loadImageCollection("imageFile.wtml");
// If the data file requires a full path
wwt.loadImageCollection("[path]//imageFile.wtml");
The LoadTour method is used to load and start a tour.
wwtControl.loadTour(
url [String]
)
This method does not return a value.
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.
wwtControl.loadTour("http://www.worldwidetelescope.org/docs/wtml/tourone.wtt");Note: This feature is not implemented.
The LoadVOTable method is used to load a VO (Virtual Observatory) table.
wwtControl.loadVOTable(
url [String],
useCurrentView [Bool]
)
This method does not return a value.
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.
wwtControl.loadVOTable("path.xml", true);The PlayTour method is used to restart a tour from the beginning.
wwtControl.playTour()
This method takes no parameters.
This method does not return a value.
Refer to the remarks for the LoadTour method.
function restartTour(){
wwtControl.playTour();
}The RemoveAnnotation method removes the specified annotation from the view.
wwtControl.removeAnnotation(
annotation [Annotation]
)
This method does not return a value.
None.
// 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) {
wwtControl.addAnnotation(circle1);
} else {
wwtControl.removeAnnotation(circle1);
}
break;
case 'ShowPolygon':
bShowPolygon = !bShowPolygon;
if(bShowPolygon) {
wwtControl.addAnnotation(polygon1);
} else {
wwtControl.removeAnnotation(polygon1);
}
break;
}
}The SetBackgroundImageByName method loads an image to use as the view background.
wwtControl.setBackgroundImageByName(
name [String]
)
This method does not return a value.
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.
 |
wwtControl.loadImageCollection("MyImageCollection.wtml");
wwtControl.setBackgroundImageByName("The Big Picture");
wwtControl.goto(45.5, 122.0, 2, false);
The SetForegroundImageByName method loads an image to use as the view foreground.
wwtControl.setForegroundImageByName(
name [String]
)
This method does not return a value.
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.
wwtControl.loadImageCollection("Serpens.wtml");
wwtControl.setForegroundImageByName("The Serpens Dark Cloud");
wwtControl.goto(277.274985, 0.545000, 1, false);
The "Serpens.wtml" file contains the following:
|
Note: This feature is not implemented.
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.
wwtControl.setForegroundOpacity(
opacity [Double]
)
This method does not return a value.
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.
wwtControl.setForegroundOpacity(0.8);The StopTour method is used to stop and exit a tour.
wwtControl.stopTour()
This method takes no parameters.
This method does not return a value.
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.
function loadTour(tourURL) {
wwtControl.loadTour(tourURL);
}
function stopTour() {
wwtControl.stopTour();
}The AnnotationClicked event is fired when an Annotation object is clicked.
function annotationClicked(obj, eventArgs){}
The obj parameter is the wwt object that originated the click event and the eventArgs object contains the click event arguments accessed by the methods get_id(), get_RA(), and get_dec().
function annotationClicked(obj, eventArgs) {
alert("Annotation ID:" + eventArgs.get_id().toString());
}
The wwtArrived event is fired when a change to the view from a drag, zoom, or goto comes to a halt.
function arrived(){}
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.
// Register the event to your arrived function
wwt.add_arrived(myArrivedEvent);
// create a function that will handle the arrived event
function myArrivedEvent(obj, eventArgs) {
// Show that we have arrived by drawing a red circle at the new ra, dec
// Create the circle.
var circle = wwt.createCircle(true);
circle.set_fillColor("red");
circle.set_opacity(3);
circle.set_radius(1.0);
circle.set_skyRelative(15);
circle.setCenter(eventArgs.get_RA(), eventArgs.get_dec());
wwt.addAnnotation(circle);
}
The wwtClick event is fired when the left mouse button is clicked.
function click(obj, eventArgs){}
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 in the eventArgs object are the location of the click, which will not usually be the same as the RA and Dec for the current view. The obj parameter is the wwt object that originated the click event and the eventArgs object contains the click event arguments accessed by the methods get_ra() and get_dec().
// Register the event to your clicked function
wwt.add_click(clicked);
function clicked(obj, eventArgs) {
alert("Clicked on: " + eventArgs.get_RA().toString() + ", " + eventArgs.get_dec().toString());
}
The wwtClick event is fired when the web client is initialized.
function ready(){}
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.
var wwt;
// Register the event to your wwtReady function
function initialize() {
wwt = wwtlib.WWTControl.initControl();
wwt.add_ready(wwtReady);
}
// here is where you can put custom code that runs when the
// WWTControl is ready
function wwtReady() {
wwt.settings.set_showCrosshairs(true);
wwt.settings.set_showConstellationFigures(false);
}
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 |
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 |
