A client application that utilizes TerraExplorer COM capabilities can be developed using scripting languages in an HTML page. This article demonstrates how to initialize SGWorld and create a basic HTML with JavaScript that interacts with the TerraExplorer COM.
TerraExplorer Desktop interfaces can only be used in a web browser that supports ActiveX controls, primarily Internet Explorer and Microsoft Edge, when used within one of TerraExplorer's built-in containers. There is limited support for display in a standalone web page in the Internet Explorer's legacy IE Mode.
TerraExplorer COM capabilities are incorporated into a web page using the SGWorld object that gives you access to all of its main interfaces. This integration involves two main steps: first, adding the initSGWorld function to your code, and second, instantiating the SGWorld object by calling this function.
Note: TerraExplorer must be installed to use the API. Download and install TerraExplorer >
-
Include initSGWorld Function: Copy the initSGWorld function below into your web page's script to enable the instantiation of the SGWorld object. Note that this init function works cross-platform, enabling your tool to be supported on all TerraExplorer clients. A simplified version of this init function can be used when developing a tool that will only be used on TerraExplorer Fusion. See Create a Custom Tool for more information.
<script language="javascript">
var SGWorld = initSGWorld();
function initSGWorld() {
if(SGWorld != null)
return SGWorld;
//Fusion -> use parent's instance (parent of IFrame)
if (parent && parent.SGWorld) {
SGWorld = parent.SGWorld;
return SGWorld;
}
//Desktop -> create an instance
try{
SGWorld = new ActiveXObject("TerraExplorerX.SGWorld80"); //IE
}
catch(e){
if(SGWorld == undefined)
{
SGWorld = __sgworld__.SetParamEx(9970, 80); //EDGE
}
};
return SGWorld;
}
</script> -
Instantiate SGWorld: Once initSGWorld is included, call the function to create an instance of SGWorld. It is recommended to pass an empty string "" to get the latest version of SGWorld. For a specific version of SGWorld, consult that version's user guide for the correct clsid. TerraExplorer Fusion will always return the latest version regardless of the clsid passed.
var SGWorld = initSGWorld("");
- Access the main interfaces: The SGWorld object exposes an ISGWorld interface based on the parameter passed to initSGWorld. Using this interface you can access all the main TerraExplorer interfaces. For example, to zoom in you will need to call the INavigate80.ZoomIn method.
- Create a button and a script tag, and create the CreatePolygons function:
<button class="button" onclick = "CreatePolygons();" style = "position: absolute;top: 10%; left:22.5%">Create Polygons</button>
<script type="text/javascript">
function CreatePolygons()
{
//Place your code here.
}
</script> -
Add the TerraExplorer API code into the function:
function CreatePolygons() {
var pointsUtah = SGWorld.Creator.GeometryCreator.CreateGeometryFromWKT("POLYGON((-114.03822 41.99547,-111.04795 41.99626,-111.05028 40.99663,-109.04763 40.99847,-109.04782 36.99664,-114.04313 36.99656,-114.03822 41.99547))");
// 2 in AltitudeTypeCode means on terrain, "" means add to root
var polyUtah = SGWorld.Creator.CreatePolygon(pointsUtah, "#ff0000", SGWorld.Creator.CreateColor(0, 255, 255, 40), 2, "", "Utah");
polyUtah.LineStyle.Width = 5000; // 5000m (5km)
var pointsWyoming = SGWorld.Creator.GeometryCreator.CreateGeometryFromWKT("POLYGON((-111.05265 44.99576,-104.05934 44.99734,-104.05120 41.00322,-111.05028 40.99663,-111.05265 44.99576))");
// 2 in AltitudeTypeCode means on terrain, "" means add to root
var polyWyoming = SGWorld.Creator.CreatePolygon(pointsWyoming, SGWorld.Creator.CreateColor(255, 255, 0, 10), null, 2, "", "Wyoming");
polyWyoming.LineStyle.Width = 20000; // 20000m (20km)
polyWyoming.Position.Distance = 1600000;
SGWorld.Navigate.FlyTo(polyWyoming);
} -
The full code:
<html lang="en">
<head>
<meta charset="UTF-8">
<title>TerraExplorer Web Integration Example</title>
</head>
<body>
<button class="button" onclick="CreatePolygons();" style="position: absolute;top: 10%; left:22.5%">Create Polygons</button>
<script type="text/javascript">
var SGWorld = initSGWorld("");
function initSGWorld() {
if(SGWorld != null) return SGWorld;
//Fusion -> use parent's instance (parent of IFrame)
if (parent && parent.SGWorld) {
SGWorld = parent.SGWorld;
returnSGWorld;
}
//Desktop -> create an instance
try{
SGWorld = new ActiveXObject("TerraExplorerX.SGWorld80");//IE
}
catch(e){
if(SGWorld == undefined)
{
SGWorld = __sgworld__.SetParamEx(9970, 80);//EDGE
}
};
return SGWorld;
}
function CreatePolygons() {
var pointsUtah = SGWorld.Creator.GeometryCreator.CreateGeometryFromWKT("POLYGON((-114.03822 41.99547,-111.04795 41.99626,-111.05028 40.99663,-109.04763 40.99847,-109.04782 36.99664,-114.04313 36.99656,-114.03822 41.99547))");
// 2 in AltitudeTypeCode means on terrain, "" means add to root
var polyUtah = SGWorld.Creator.CreatePolygon(pointsUtah, "#ff0000", SGWorld.Creator.CreateColor(0, 255, 255, 40), 2, "", "Utah");
polyUtah.LineStyle.Width = 5000; // 5000m (5km)
var pointsWyoming = SGWorld.Creator.GeometryCreator.CreateGeometryFromWKT("POLYGON((-111.05265 44.99576,-104.05934 44.99734,-104.05120 41.00322,-111.05028 40.99663,-111.05265 44.99576))");
// 2 in AltitudeTypeCode means on terrain, "" means add to root
var polyWyoming = SGWorld.Creator.CreatePolygon(pointsWyoming, SGWorld.Creator.CreateColor(255, 255, 0, 10), null, 2, "", "Wyoming");
polyWyoming.LineStyle.Width = 20000; // 20000m (20km)
polyWyoming.Position.Distance = 1600000;
SGWorld.Navigate.FlyTo(polyWyoming);
}
</script>
</body>
</html> - To launch the tool in a container, inside TerraExplorer:
- Launch TerraExplorer and open a project (e.g., USBaseTerrain.tbp@cloud.skylineglobe.com$/SG/demos).
- Project Settings (F8) > Layout > Container Settings > Add...
- You can also launch the tool in Internet Explorer (IE), while TerraExplorer Pro is running:
- Launch TerraExplorer and open a project (i.e., USBaseTerrain.tbp@cloud.skylineglobe.com$/SG/demos).
- Run IE and paste the HTML path in the URL field.
You can expand your HTML tool and add it as an add-on to the TerraExplorer application. More about: Creating and distributing add-ons >