WorldWide Telescope

WorldWide Telescope Web Control Script Reference for HTML5

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.

Attention Silverlight users

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.

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. An appropriate html editing tool is available.
  3. 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.
  4. 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 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
Notes

Web Control Objects

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
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.
WWTControlUsed to manage the canvas 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.
Center Specifies the center of the annotation.
TagContains a string for use by the web client.

See Also


Annotation id property

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

Syntax

Annotation.set_id([string])
[string] Annotation.get_id()

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 AnnotationClicked event.

Example Code

// 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");

See Also


Annotation label property

The Label property contains descriptive text for the annotation.

Syntax

Annotation.set_label([string])
[string] Annotation.get_label()

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.set_center(286.485, -27.5231666666667);
circle.set_id("Center of the Constellation Sagittarius");
circle.set_label("RA: 286.485, Dec: -27.5231666666667");

See Also


Annotation opacity property

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

Syntax

Annotation.set_opacity([double])
[double] Annotation.get_opacity()

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.set_fillColor("red");
circle.set_fill(true);
// Apply a 50% transparency to the entire annotation
circle.set_opacity(0.5);

See Also


Annotation showHoverLabel property

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

Syntax

Annotation.set_showHoverLabel([Bool])
[Bool] Annotation.get_showHoverLabel()

Remarks

The default setting is false.

Example Code

// 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);

See Also


Annotation center property

The Center property contains a Vector3d object for use by the web client.

Syntax

Annotation.set_center([Vector3d])
[Vector3d] Annotation.get_center()

Remarks

This Vector3d object is used to hold the center position of the annotation object used by the web client.

Example Code

var vector3d = new wwtlib.Vector3d(x, y, z);
circle.set_center(vector3d);

See Also


Annotation tag property

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

Syntax

Annotation.set_tag([string])
[string] Annotation.get_tag()

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.set_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 property

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

Syntax

Circle.set_fill([Bool])
[Bool] Circle.get_fill();

Remarks

The default is false.

Example Code

// Fill a circle with a transparent red
circle.set_fill(true);
circle.set_fillColor("0x55AA0000");

See Also


Circle FillColor Property

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

Syntax

Circle.set_fillColor([string])
[string] Circle.get_fillColor()

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.set_fill(true);
circle.set_fillColor("green");

See Also


Circle LineColor Property

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

Syntax

Circle.set_lineColor([string])
[string] Circle.get_lineColor()

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.set_lineColor("0xFF555555");

See Also


Circle LineWidth Property

The LineWidth property specifies the line width in pixels.

Syntax

Circle.set_lineWidth([double])
[double] Circle.get_lineWidth()

Remarks

The default line width is 1 pixel.

Example Code

// Double the default line width
circle.set_lineWidth(2);

See Also


Circle Radius Property

The Radius property specifies the circle radius.

Syntax

Circle.set_radius([double])
[double] Circle.get_radius()

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.set_skyRelative(false);
circle.set_radius(25);

See Also


Circle SkyRelative Property

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

Syntax

Circle.set_skyRelative([Bool])
[Bool] Circle.get_skyRelative()

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.set_skyRelative(true);
circle.set_radius(0.2);

See Also


Circle SetCenter Method

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 Property

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

Syntax

Poly.set_fill([Bool])
[Bool] Ploy.get_fill()

Remarks

The default fill setting is false.

Example Code

// Fill a polygon with a slightly transparent blue
poly.set_fill(true);
poly.set_fillColor("0xBB0000AA");

See Also


Poly FillColor Property

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

Syntax

Poly.set_fillColor([uint])
[uint] Poly.get_fillColor()

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.set_fill(true);
poly.set_fillColor("red");

See Also


Poly LineColor Property

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

Syntax

Poly.set_lineColor([uint])
[uint] Poly.get_lineColor()

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.set_lineColor("0xFF000000");

See Also


Poly LineWidth Property

The LineWidth property specifies the line width in pixels.

Syntax

Poly.set_lineWidth([double])
[double] Poly.get_lineWidth()

Remarks

The default line width is 1 pixel.

Example Code

// Double the line width
poly.set_lineWidth(2 * poly.get_lineWidth());

See Also


Poly AddPoint Method

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.

ExampExample 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 Property

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

Syntax

PolyLine.set_lineColor([uint])
[uint] PolyLine.get_lineColor()

Remarks

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

ExampExample Code

// Set a solid blue color
poly.set_fillColor("blue");

See Also


PolyLine LineWidth Property

The LineWidth property specifies the line width in pixels.

Syntax

PolyLine.set_lineWidth([double])
[double] PolyLine.get_lineWidth()

Remarks

The default line width is 1 pixel.

ExampExample Code

poly.set_lineWidth(3);

See Also


PolyLine AddPoint Method

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.

ExampExample 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 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
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.
ShowElevationModelSpecifies whether to show the elevation model.
ShowFieldOfViewSpecifies whether to show the field of view box.
ShowGridSpecifies whether to show the equatorial grid.
ShowHorizonSpecifies whether to show the horizon.
ShowHorizonPanoramaSpecifies whether to show the panorama horizon.
ShowMoonsAsPointSourceSpecifies whether to show the moon as a point source.
ShowSolarSystem Specifies whether to show the 3-D solar system view.
ShowUTCTimeSpecifies whether to show the time as a UTC value.
SolarSystemCosmosSpecifies whether to show the solar system cosmos.
SolarSystemLighting Specifies whether to show the lighting effect of the Sun on the solar system.
SolarSystemMilkyWaySpecifies whether to show the Milky Way when showing the solar system.
SolarSystemMultiResSpecifies whether to show the multi-resolution textures for the planets.
SolarSystemOrbitColorSpecifies the solar system orbit color as an ARGB value.
SolarSystemOrbitsSpecifies whether to show the solar system orbits.
SolarSystemOverlaysSpecifies whether to show the solar system overlays.
SolarSystemScaleSpecifies how to scale the size of the Sun and the planets.
SolarSystemStarsSpecifies whether to render stars when showing the solar system.
UserIDSpecifies the user ID as a Guid.

See Also


Settings ConstellationBoundryColor Property

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

Syntax

wwtControler.settings.set_constellationBoundryColor([uint])
[uint] wwtControler.settings.get_constellationBoundryColor()

Remarks

The default boundary color is blue.

Example Code

// set the constellation boundary color to green
wwtControl.settings.set_constellationBoundryColor("green");

See Also


Settings ConstellationFigureColor Property

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

Syntax

wwtControl.settings.set_constellationFigureColor([uint])
[uint] wwtControl.settings.get_constellationFigureColor()

Remarks

The default figure color is red.

Example Code

// set the constellation figures color to blue
wwtControl.settings.set_constellationFigureColor("blue");

See Also


Settings ConstellationSelectionColor Property

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

Syntax

wwtControl.settings.set_constellationSelectionColor([uint])
[uint] wwtControl.settings.get_constellationSelectionColor()

Remarks

The default selection color is yellow.

Example Code

// set the constellation selection color to red
wwtControl.settings.set_constellationSelectionColor("red");

See Also


Settings EclipticColor Property

Note: This feature is not implemented.

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

Syntax

wwtControl.settings.set_eclipticColor([uint])
[uint] wwtControl.settings.get_eclipticColor()

Remarks

The default ecliptic color is green.

Example Code

// set the ecliptic color to transparent green
wwtControl.settings.set_eclipticColor("0xAA00FF00");

See Also


Settings GridColor Property

Note: This feature is not implemented.

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

Syntax

wwtControl.settings.set_gridColor([uint])
[uint]wwtControl.settings.get_gridColor()

Remarks

The default equatorial grid color is gray.

Example Code

// set the grid color to green
wwtControl.settings.set_gridColor("green");

See Also


Settings LocalHorizonMode Property

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).

Syntax

wwtControl.settings.set_localHorizonMode([Bool])
[Bool]wwtControl.settings.get_localHorizonMode()

Remarks

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

Example Code

wwtControl.settings.set_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 Property

The LocationAltitude property specifies the view location altitude in meters.

Syntax

wwtControl.settings.set_locationAltitude([double])
[double]wwtControl.settings.get_locationAltitude()

Remarks

None.

Example Code

// 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);

See Also


Settings LocationLat Property

The LocationLat property specifies the view location latitude.

Syntax

wwtControl.settings.set_locationLat([double])
[double] wwtControl.settings.get_locationLat()

Remarks

The default location latitude is 47.633.

Example Code

// 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);

See Also


Settings LocationLng Property

The LocationLng property specifies the view location longitude.

Syntax

wwtControl.settings.set_locationLng([double])
[double] wwtControl.settings.get_locationLng()

Remarks

The default location longitude is 122.133333.

Example Code

// 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);

See Also


Settings ShowClouds Property

Note: This feature is not implemented.

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

Syntax

wwtControl.settings.set_showClouds([Bool])
[Bool] wwtControl.settings.get_showClouds()

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

wwtContorl.settings.set_showClouds(true);
No clouds The Earth without its cloud layer.
Clouds The Earth with its cloud layer.

See Also


Settings ShowConstellationBoundries Property

The ShowConstellationBoundries property specifies whether to show constellation boundaries.

Syntax

wwtControl.settings.set_showConstellationBoundries([Bool])
[Bool]wwtControl.settings.get_showConstellationBoundries()

Remarks

This setting is equivalent to the View > Boundaries checkbox.

Example Code

wwtControl.settings.set_showConstellationBoundries(true);
Boundaries
The constellation boundaries are shown in blue, except for the selected constellation, with its boundary in yellow.

See Also


Settings ShowConstellationFigures Property

The ShowConstellationFigures property specifies whether to show constellation figures.

Syntax

wwtControl.settings.set_showConstellationFigures([Bool])
[Bool] wwtControl.settings.get_showConstellationFigures()

Remarks

This setting is equivalent to the View > Figures checkbox.

Example Code

wwtControl.settings.set_showConstellationFigures(true);
Figures
The constellation figures.

See Also


Settings ShowConstellationSelection Property

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

Syntax

wwtControl.settings.set_showConstellationSelection([Bool])
[Bool] wwtControl.settings.get_showConstellationSelection()

Remarks

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

Example Code

wwtControl.settings.set_showConstellationSelection(true);
Selection
The selected constellation.

See Also


Settings ShowCrosshairs Property

The ShowCrosshairs property specifies whether to show cross-hairs.

Syntax

wwtControl.settings.set_showCrosshairs([Bool])
[Bool] wwtControl.settings.set_showCrosshairs()

Remarks

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

Example Code

wwtControl.settings.set_showCrosshairs(true);
CrosshairsThe crosshairs, or reticle, shown with Mars in view.

See Also


Settings ShowEcliptic Property

Note: This feature is not implemented.

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

Syntax

wwtControl.settings.set_showEcliptic([Bool])
[Bool] wwtControl.settings.get_showEcliptic()

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

wwtControl.settings.set_showEcliptic(true);
Ecliptic

See Also


Settings ShowElevationModel Property

Note: This feature is not implemented.


The ShowElevationModel property specifies whether to show the elevation model.

Syntax

wwtControl.settings.set_showElevation([Bool])
[Bool] wwtControl.settings.get_showElevation()

Remarks

This setting is equivalent to the Settings > Show Elevation Model checkbox.

Example Code

wwtControl.settings.set_showElevationModel(true);
Himalayas flat The Himalayan mountains, shown without elevation data.
Himalayas model The Himalayan mountains, with elevation data.

See Also


Settings ShowFieldOfView Property

Note: This feature is not implemented.

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

Syntax

wwtControl.settings.set_showFieldOfView([Bool])
[Bool] wwtControl.settings.get_showFieldOfView()

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

wwtControl.settings.set_showFieldOfView(true);
FOV
Gamma Pegasi shown with the Field of View Indicator box.

See Also


Settings ShowGrid Property

Note: This feature is not implemented.

The ShowGrid property specifies whether to show the equatorial grid.

Syntax

wwtcontrol.settings.set_showGrid([Bool])
[Bool] wwtcontrol.settings.get_showGrid()

Remarks

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

Example Code

wwtControl.settings.set_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 Property

Note: This feature is not implemented.

The ShowHorizon property specifies whether to show the horizon.

Syntax

wwtControl.settings.set_showHorizon([Bool])
[Bool] wwtControl.settings.get_showHorizon()

Remarks

None.

Example Code

wwtControl.settings.set_showHorizon(true);

See Also


Settings ShowHorizonPanorama Property

Note: This feature is not implemented.

The ShowHorizonPanorama property specifies whether to show the horizon in panoramas.

Syntax

wwtControl.settings.set_showHorizonPanorama([Bool])
[Bool] wwtControl.settings.get_showHorizonPanorama()

Remarks

None.

Example Code

wwtControl.settings.set_showHorizonPanorama(true);

See Also


Settings ShowMoonsAsPointSource Property

Note: This feature is not implemented.

The ShowMoonsAsPointSource property specifies whether to show the moon as a point source.

Syntax

wwtControl.settings.set_showMoonsAsPointSource([Bool])
[Bool] wwtControl.settings.get_showMoonsAsPointSource()

Remarks

None.

Example Code

wwtControl.settings.set_showMoonsAsPointSource(true);

See Also


Settings ShowSolarSystem Property

Note: This feature is not implemented.

The ShowSolarSystem property specifies whether to show the 3-D solar system view.

Syntax

wwtControl.settings.set_showSolarSystem([Bool])
[Bool] wwtControl.settings.get_showSolarSystem()

Remarks

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.

Example Code

wwtControl.settings.set_showSolarSystem(true);

See Also


Settings ShowUTCTime Property

Note: This feature is not implemented.

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

Syntax

wwtControl.settings.set_showUTCTime([Bool])
[Bool] wwtControl.settings.get_showUTCTime()

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

wwtControl.settings.set_showUTCTime(true);

See Also


Settings SolarSystemCosmos Property

Note: This feature is not implemented.

The SolarSystemCosmos property specifies whether to show the solar system cosmos.

Syntax

wwtControl.settings.set_solarSystemCosmos([Bool])
[Bool] wwtControl.settings.get_solarSystemCosmos()

Remarks

None.

Example Code

wwtControl.settings.set_solarSystemCosmos(true);

See Also


Settings SolarSystemLighting Property

Note: This feature is not implemented.

The SolarSystemLighting property specifies whether to show the lighting effect of the Sun on the solar system.

Syntax

wwtControl.settings.set_solarSystemLighting([Bool])
[Bool] wwtControl.settings.get_solarSystemLighting()

Remarks

This setting is equivalent to the View > Lighting checkbox.

Example Code

wwtControl.settings.set_solarSystemLighting(true);
Saturn lighting The lighting of the Sun on Saturn.

See Also


Settings SolarSystemMilkyWay Property

Note: This feature is not implemented.

The SolarSystemMilkyWay property specifies whether to show the Milky Way when showing the solar system.

Syntax

wwtControl.settings.set_solarSystemMilkyWay([Bool])
[Bool] wwtControl.settings.get_solarSystemMilkyWay()

Remarks

This setting is equivalent to the View > Milky Way checkbox.

Example Code

wwtControl.settings.set_solarSystemMilkyWay(true);
Saturn Milky Way The Milky Way appears to the left of Saturn.

See Also


Settings SolarSystemMultiRes Property

Note: This feature is not implemented.

The SolarSystemMultiRes property specifies whether to show the multi-resolution textures for the planets.

Syntax

wwtControl.settings.set_solarSystemMultiRes([Bool])
[Bool] wwtControl.settings.get_solarSystemMultiRes()

Remarks

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.

Example Code

wwtControl.settings.set_solarSystemMultiRes(true);
Carribean lowres The Caribbean in standard textures.
Carribean hires The Caribbean with multi-resolution textures.

See Also


Settings SolarSystemOrbitColor Property

Note: This feature is not implemented.

The SolarSystemOrbitColor property specifies the solar system orbit colors as an ARGB value.

Syntax

wwtControl.settings.set_solarSystemOrbitColor([uint])
[uint] wwtControl.settings.get_solarSystemOrbitColor()

Remarks

The default orbit color is dark gray.

Example Code

// set the solar system orbit color to red
wwtControl.settings.set_solarSystemOrbitColor("red");

See Also


Settings SolarSystemOrbits Property

Note: This feature is not implemented.

The SolarSystemOrbits property specifies whether to show the orbits when showing the solar system.

Syntax

wwtControl.settings.set_solarSystemOrbits([Bool])
[Bool] wwtControl.settings.get_solarSystemOrbits()

Remarks

This setting is equivalent to the View > Orbits checkbox.

Example Code

wwtControl.settings.set_solarSystemOrbits(true);
Saturn Orbits The orbits of all the solar system planets are shown in the SolarSystemOrbitColor.

See Also


Settings SolarSystemOverlays Property

Note: This feature is not implemented.

The SolarSystemOverlays property specifies whether to show the solar system overlays.

Syntax

wwtControl.settings.set_solarSystemOverlays([Bool])
[Bool] wwtControl.settings.get_solarSystemOverlays()

Remarks

None.

Example Code

wwtControl.settings.set_solarSystemOverlays(true);

See Also


Settings SolarSystemScale Property

Note: This feature is not implemented.

The SolarSystemScale property specifies how to scale the size of the Sun and the planets.

Syntax

wwtControl.settings.set_solarSystemScale([int])
[int] wwtControl.settings.get_solarSystemScale()

Remarks

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.

Example Code

wwtControl.settings.set_solarSystemScale(50);
Sun actual The Sun shown actual size.
Sun full The Sun with maximum scaling.

See Also


Settings SolarSystemStars Property

Note: This feature is not implemented.

The SolarSystemStars property specifies whether to render stars when showing the solar system.

Syntax

wwtControl.settings.set_solarSystemStars([Bool])
[Bool] wwtControl.settings.get_solarSystemStars()

Remarks

This setting is equivalent to the View > Show Stars checkbox.

Example Code

wwtControl.settings.set_solarSystemStars(true);
Saturn Stars Saturn and the stars.

See Also


Settings UserID Property

Note: This feature is not implemented.

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

Syntax

wwtControl.settings.set_userID([Guid])
[Guid] wwtControl.settings.get_userID()

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 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();

See Also


WWTControl Object

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
FovContains the field of view in degrees.
SettingsReference 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
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
AnnotationClickedFired 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


WWTControl Fov Property

Note: This feature is not implemented.

The Fov property contains the field of view in degrees.

Syntax

[double] wwtControl.get_fov()

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 * 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);
    } 
}

Samples

See Also


WWTControl Settings Property

The Settings property references the Settings object for the WWTControl.

Syntax

wwtControl.settings [Settings]

Remarks

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

Example Code

// 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);

Samples

See Also


WWTControl SmoothAnimation Property

Note: This feature is not implemented.

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

Syntax

wwtControl.set_smoothAnimation([Bool])
[Bool] wwtControl.get_smoothAnimation()

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

wwtControl.set_smoothAnimation(true);

Samples

See Also


WWTControl AddAnnotation Method

The AddAnnotation method adds an Annotation object to the view.

Syntax

wwtControl.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


WWTControl ClearAnnotations Method

The ClearAnnotations method removes all annotations from the view.

Syntax

wwtControl.clearAnnotations()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

None.

Example Code

wwtControl.clearAnnotations();

Samples

See Also


WWTControl CreateCircle Method

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

Syntax

wwtControl.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 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;
}
Circles
In this image,  circle objects filled with a transparent color have been used to identify point sources of light.

Samples

See Also


WWTControl CreatePolygon Method

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

Syntax

wwtControl.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 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);
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


WWTControl CreatePolyLine Method

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

Syntax

wwtControl.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 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);
	
Polylines
This image shows some common variations of Polyline objects.

Samples

See Also


WWTContorl GetDec Method

The GetDec method retrieves the declination for the view.

Syntax

wwtControl.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 = 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);

Samples

See Also


WWTControl GetRA Method

The GetRA method retrieves the right ascension for the view.

Syntax

wwtControl.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

// 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); 
    } 
}

Samples

See Also


WWTControl Goto Method

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

Syntax

wwtControl.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;
}
wwtControl.goto(HMS(06, 25, 30), DMS(45, 00, 00), 30, false);

Samples

See Also


WWTControl HideUI Method

Note: This feature is not implemented.

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

Syntax

wwtControl.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;
            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');"\> 

Samples

See Also


WWTControl LoadImageCollection Method

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

Syntax

wwtControl.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.
wwt.loadImageCollection("imageFile.wtml");
// If the data file requires a full path
wwt.loadImageCollection("[path]//imageFile.wtml");

Samples

See Also


WWTControl LoadTour Method

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

Syntax

wwtControl.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

wwtControl.loadTour("http://www.worldwidetelescope.org/docs/wtml/tourone.wtt");

Samples

See Also


WWTControl LoadVOTable Method

Note: This feature is not implemented.

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

Syntax

wwtControl.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

wwtControl.loadVOTable("path.xml", true);

See Also


WWTControl PlayTour Method

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

Syntax

wwtControl.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(){
    wwtControl.playTour();
}

Samples

See Also


WWTControl RemoveAnnotation Method

The RemoveAnnotation method removes the specified annotation from the view.

Syntax

wwtControl.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) {
	            wwtControl.addAnnotation(circle1);
	        } else {
	            wwtControl.removeAnnotation(circle1);
	        }
	        break;

	    case 'ShowPolygon':
	        bShowPolygon = !bShowPolygon;
		    if(bShowPolygon) {
	            wwtControl.addAnnotation(polygon1);
	        } else {
	            wwtControl.removeAnnotation(polygon1);
	        }
	        break;
    }
}

Samples

See Also


WWTControl SetBackgroundImageByName Method

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

Syntax

wwtControl.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

wwtControl.loadImageCollection("MyImageCollection.wtml");
wwtControl.setBackgroundImageByName("The Big Picture");
wwtControl.goto(45.5, 122.0, 2, false);

Samples

See Also


WWTControl SetForegroundImageByName Method

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

Syntax

wwtControl.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

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:


<Folder 
	Name="My Places" 
	Group="Explorer" 
	Searchable="True" 
	Type="Sky"
	Thumbnail="C:\~\Images\T_Earth.jpg">

  	<VersionDependent>false</VersionDependent>

  <Place 
    Name="Serpens Dark Cloud" 
    DataSetType="Sky" 
    RA="16.5496517733333" 
    Dec="-23.25002666" 
    Constellation="AND" 
    Classification="Unfiltered" 
    Magnitude="0" 
    Distance="0" 
    ZoomLevel="61.76666816142" 
    Rotation="0" 
    Angle="0" 
    Opacity="100" 
    AngularSize="1">

    <Target>Undefined</Target>
    <ForegroundImageSet>
      <ImageSet 
        Generic="False" 
        DataSetType="Sky" 
        BandPass="Visible" 
        Url="http://www.cfa.harvard.edu/~gmuench/wwtimages/161419573/{1}/{3}/{3}_{2}.png" 
        TileLevels="4" 
        WidthFactor="2" 
        Sparse="True" 
        Rotation="0" 
        QuadTreeMap="" 
        Projection="Tangent" 
        Name="1120 micron  image of the Serpens Dark Cloud;Serpens;Serpens Dark Cloud" 
        FileType=".png" 
        CenterY="-23.25002666" 
        CenterX="248.2447766" 
        BottomsUp="False" 
        OffsetX="-0.0013888889225" 
        OffsetY="-0.0013888889225" 
        BaseTileLevel="0" 
        BaseDegreesPerTile="11.37777805312">

        <Credits>Enoch/COMPLETE/CSO1120 micron  image of the Serpens Dark Cloud.  Data were taken May-June 2003 and 2005. Flux units are in mJy per 31 arcsecond beam. 

Reference:  Melissa Enoch et al., Comparing Star Formation on Large Scales in the c2d Legacy Clouds: Bolocam 1.1 mm Dust Continuum Surveys of Serpens, Perseus, and Ophiuchus, ApJ, 2007, 666, 982 
        </Credits>
        <CreditsUrl>http://www.cfa.harvard.edu/COMPLETE/data_html_pages/SerA_1120uBolo_F.html</CreditsUrl>
        <ThumbnailUrl>http://www.cfa.harvard.edu/~gmuench/wwtimages/161419573.jpg</ThumbnailUrl>
      </ImageSet>
    </ForegroundImageSet>
  </Place>
</Folder>

Samples

See Also


WWTControl SetForegroundOpacity Method

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.

Syntax

wwtControl.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

wwtControl.setForegroundOpacity(0.8);

Samples

See Also


WWTControl StopTour Method

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

Syntax

wwtControl.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) {
    wwtControl.loadTour(tourURL);
}

function stopTour() {
    wwtControl.stopTour();
}

Samples

See Also


WWTControl AnnotationClicked Event

The AnnotationClicked event is fired when an Annotation object is clicked.

Syntax

function annotationClicked(obj, eventArgs){}

Remarks

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().

Example Code


function annotationClicked(obj, eventArgs) {
    alert("Annotation ID:" + eventArgs.get_id().toString());
}

Samples

See Also


WWTControl Arrived Event

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

Syntax

function arrived(){}

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

// 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);
}

Samples

See Also


WWTControl Click Event

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

Syntax

function click(obj, eventArgs){}

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 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().

Example Code

// 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());
}

Samples

See Also


WWTControl Ready Event

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

Syntax

function ready(){}

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 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);
}

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

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