Keith Kinnan's Blog : VEShape

Clustering Pushpins with the Virtual Earth Map Control API

keithkin — Sun, 12 Oct 2008 19:14:00 GMT

One of the new features introduced in the Virtual Earth Map Control API is Pushpin Clustering. When there are hundreds of pushpin shapes on the map in a dense area, the map can become very cluttered. The pushpins can overlap each other and obscure the map view and make the map difficult to use. Previously, to solve this problem, developers using the Virtual Earth map control would have to either divide groups of pushpins into VEShapeLayers and manually control which layers to show and hide at different zoom levels, or just not show Pushpins at zoom levels if there were too many on the screen. With the v6.2 Virtual Earth Map Control API, this situation has gotten a lot easier to manage with the addition of the pushpin clustering feature.

In the v6.2 Virtual Earth Map Control API, we introduced two new methods on the VEShapeLayer to support pushpin clustering. In a previous blog post awhile back, I talked about the VEShapeLayer class which is designed to group a set of VEShapes so they can be managed as a collective group. The two new methods for pushpin clustering are VEShapeLayer.SetClusteringConfiguration and VEShapeLayer.GetClusteredShapes. The v6.2 Virtual Earth Map Control API is reverse compatible with the previous v6.1 and v6 APIs and does not cluster pushpins by default.

The SetClusteringConfiguration method allows you to specify how you want to cluster shapes in a shape layer. The first parameter is either a VEClusteringType enumeration specifying a known clustering algorithm supported by Virtual Earth, or it can be a reference to a custom function which does the clustering. Currently VEClusteringType can either be VEClusteringType.Grid to specify a grid-based clustering algorithm or VEClusteringType.None which turns off clustering. By default clustering is off if you do not call SetClusteringConfiguration on a VEShapeLayer.

So, you can turn on grid clustering with a single call to SetClusteringConfiguration. Assuming you have a VEShapeLayer reference called shapeLayer, here's the syntax:

shapeLayer.SetClusteringConfiguration(VEClusteringType.Grid);

The built-in grid based clustering algorithm divides the screen into equal-sized squares. If there are more than one VEShape pushpins in a square, they are combined into a cluster. So, at the highest altitude, you will see more clusters and at the lowest altitude (highest level of detail) you will see less clusters, but more individual shapes. So, as you zoom in on clusters to highest level of detail, they will eventually break up and show individual shapes. So, with one line of code, this simple algorithm now reduces clutter on the map significantly and divides shapes up into manageable chunks. By default, pushpin clusters will have a special cluster pushpin icon just like VEShape pushpins have their own default pin icon also. Each cluster will also have a default popup balloon with information about the cluster. The default popup shows the number of shapes in the cluster. In a future blog post, I will show you how to override some of these default settings to provide more advanced customization to pushpin clustering.

Figure 1 below shows a set of pushpins that are not clustered. Figure 2 shows the same set of pushpins clusterd with Grid clustering:

Figure 1. Unclustered Pushpins Figure 2. Clustered Pushpins

If you want to turn off pushpin clustering after you have turned it on, you just have to make the following call:

shapeLayer.SetClusteringConfiguration(VEClusteringType.None);

If you want to know what shapes are in each pushpin cluster, you can do so with the GetClusteredShapes method on the VEShapeLayer which also takes in a VEClusteringType parameter. For example:

var shapeClusters = shapeLayer.GetClusteredShapes(VEClusteringType.Grid);

This call returns an array of VEClusterSpecification objects representing the set of shape clusters with the passed in clustering type. Each VEClusterSpecification object in the array represents a cluster. The Shapes property on the object specifies the pushpins in the cluster. The LatLong property is a VELatLong and specifies the Latitude, Longitude location of the center of the cluster where the cluster icon is positioned. This provides all the information you have for a cluster, so no information is lost when pushpins are clustered. Also, this method works even when clustering is off. So, if you want to have a complete custom rendering for a cluster, or just know what shapes would be clustered if you turned clustering on, you can use this method.

Click on the link below to see a sample of pushpin clustering with Virtual Earth.

Virtual Earth Map Control API Clustering Sample

(Note: I have also published this post on the VE Platform Team Blog)

Microsoft Research Releases Tiled Vectors Demo

keithkin — Sat, 19 Jan 2008 01:57:00 GMT

Microsoft Research released a Tiled Vectors Demo which is available for download. The demo shows a way to solve the problem of showing extremely large mapping data sets in the web browser. If you have used the Virtual Earth AJAX/JavaScript Map Control or other web-based mapping controls or any web application with a large number of DOM elements/SVG/VML graphics, then you probably have seen that loading extremely large data sets (with thousands of points, lines, and polygons) can bring the browser to a crawl because of limitations in the browser DOM.

The Tiled Vectors Demo from MSR attempts to solve this problem by breaking up the shapepoints into constant-sized sets, similar to how MapCruncher breaks up images into image tiles. Since the data is broken into constant-sized sets, the original data set can be arbitrarily large -- so the solution scales really well to extremely large data sets. Regardless of which level of detail you are viewing the map from, the amount of data the map loads is always constant. This significantly improves performance. The vector data is still loaded using Virtual Earth VEShapeLayers in JavaScript -- so the shapes are still interactive and can be controlled from client code and respond to events.

You can see a demo page here:

Tiled Vectors Demo

For more detailed information regarding the Tiled Vectors approach and how you can apply it to your data sets, see:

Tiled Vectors Demo Information

Virtual Earth API: Implementing Drag and Drop in Virtual Earth

keithkin — Fri, 11 Jan 2008 00:15:40 GMT

Steve Lombardi posted some nice samples recently on the Virtual Earth Spaces blog showing how to implement drag and drop on shapes using the Virtual Earth map control API. You just need to add a custom event handler for the "onmousedown", "onmousemove", and "onmouseup" events.

Here's the links to the working samples:

Simple Drag and Drop Sample

Collections Drag and Drop Sample

Virtual Earth API: Bulk Adding Pushpins to a Layer to Improve Performance

keithkin — Tue, 20 Nov 2007 18:49:00 GMT

One of the new features from the Virtual Earth v6 Map Control API is the ability to bulk add groups of pushpins to the map in one step. This improves performance when putting a large number of pushpins on the map since the HTML markup of the pushpins is serialized and inserted in the map in one operation.

Bulk adding pushpins to the map consists of 3 steps:

Create an array of pushpins
Create an empty shape layer and add it to the map
Add the array of pushpins to the shape layer

For example:

1. Create an array with a large number of pushpins:

var center = map.GetCenter();
var shapes = new Array();
for (i=0 ; i < 150; ++i)
{
var shape = new VEShape(VEShapeType.Pushpin, new VELatLong(center.Latitude + Math.random()*20 - 10, center.Longitude + Math.random()*20 - 10));
shapes.push(shape);
}

2. Create an empty shape layer and add it to the map:

var shapeLayer = new VEShapeLayer();
map.AddShapeLayer(shapeLayer);

3. Add the array of pushpins to the shape layer:

shapeLayer.AddShape(shapes);

Here's a link to a working sample which adds pushpins to the map using the new bulk add approach. It has a checkbox which allows you to turn off the bulk add and add the pushpins in the normal manner so you can compare the performance improvement between bulk add and the traditional approach. The time to execute a bulk add operation tends to be about 1/2 the time of the traditional approach.

Virtual Earth API Bulk Add Pushpin Sample

Virtual Earth API: Setting Altitude of Shapes

keithkin — Wed, 14 Nov 2007 23:01:00 GMT

The Virtual Earth v6 map control API added support for setting altitude of VEShapes in Virtual Earth 3D. There is a new SetAltitude method on VEShape which takes in 2 parameters:

VEShape.SetAltitude(altitude, altitudeMode);

The altitude parameter is the altitude specified in meters. The altitudeMode parameter is an optional VEAltitudeMode enumeration specifying the mode of the altitude. If not specified, by default it is VEAltitudeMode.RelativeToGround which is meters above ground level. You can also specify VEAltitudeMode.Absolute which is meters above the WGS84 ellipsoid. When the VEShape is a pushpin, the altitude is a single floating point value. When the VEShape is a polyline or polygon, it is an array of floating point values specifying the altitude for each point in the shape.

There is also a new SetLineToGround method on the VEShape for polylines and polygon shapes which takes in a boolean to specify whether or not connect the points in the shape to the ground. By default it is false.

The following sample shows some custom VEShapes at different altitudes. It also demonstrates a polygon with points at different altitudes and the line to ground functionality:

Virtual Earth API Shape Altitude Sample

Virtual Earth API: Accurately Position Points in Birdseye

keithkin — Tue, 06 Nov 2007 02:42:00 GMT

In the Virtual Earth v6 API, one of the new features is improved Birdseye accuracy. The Virtual Earth v6 API has some new methods to more accurately position pushpins when in Birdseye view.

Satellite (Aerial/Hybrid) and Road imagery views are direct overhead views, so calculations to position a pushpin at an exact latitude and longitude are not as complex as in Birdseye. The camera is directly overhead the point and the elevation of that point on the Earth does not need to be taken into account in 2D. However, with Birdseye imagery taken from different angles, there are a lot more variables to consider when calculating where to position a point including the camera position and the elevation of the Earth in that scene.

In order to do this calculation efficiently in Birdseye, a service request is made from the client to the server to get more accurate positions. For some applications, the client-side, less-accurate, faster calculation may be enough to position points. Because of this, enhanced birdseye accuracy for pushpins is off by default in the Virtual Earth API.

To turn on enhanced Birdseye Accuracy for pushpins in the Virtual Earth API, you can make the following call (assuming you have a VEMap instance called "map"):

map.SetShapesAccuracy(VEShapeAccuracy.Pushpin);

To turn off enhanced Birdseye Accuracy for pushpins, you can make the following call:

map.SetShapesAccuracy(VEShapeAccuracy.None);

Here is a link to sample Virtual Earth application showing 3 points on Lombard Street in San Francisco with a checkbox which turns Birdseye Accuracy on and off:

Virtual Earth Birdseye Accuracy Sample

Notice in Aerial view, the 3 yellow dots are positioned at precise points along Lombard Street:

If you click on "Bird's eye" on the navigation panel and click on different orientations ("N", "W", "E", "S") on the compass in the navigation panel, you will notice the 3 yellow dots are still positioned rather accurately in Birdseye.

Here's a screenshot of the Birdseye scene looking toward the West with enhanced accuracy enabled:

Virtual Earth API: Creating Numbered Pushpins

keithkin — Wed, 16 May 2007 21:04:00 GMT

Many people have asked how to create numbered pushpins using the Virtual Earth API. One way to do this is to have custom pin images with numbers in the image. However, you can also do this in the v5 API using VEShape and custom HTML and CSS styles for the shape icon. The following example shows one way to do this.

You fist need to create custom CSS styles for a pin setting a background image, position, and font styles.

.pinStyle1{ position:relative; background:url('pin1.gif') no-repeat 0 0; height:30px; width:25px; top:-15px; color:#fff; text-align:center; font: bold 12px Arial; cursor: pointer;}

.pinStyle1 .text{ position: relative; top: 2px; }

Then, to add the numbered pin to the map, you can create a VEShape and use the SetCustomIcon method to set the pin icon to custom HTML/CSS. In this example, the pin icon consists of two styled DIVs using the styles above and the text "1". The outer DIV is used to style the pushpin image and the inner DIV is used to style the pushpin text.

var shape = new VEShape(VEShapeType.Pushpin,new VELatLong(37.776, -122.426));
shape.SetCustomIcon("<div class='pinStyle1'><div class='text'>1</div></div>");
shape.SetTitle('Shape 1');
shape.SetDescription('This is Shape 1');
map.AddShape(shape);

This adds a numbered pin to the map using "pin1.gif" and the number "1". In this example, the pin image "pin1.gif" is 30 pixels x 25 pixels. By default pushpin icons are centered. However, "pin1.gif" is a pushpin which has a pointer on the bottom. So to get the bottom of the pin to point to the location, I set the top position to the negative of half of the image height (-15 pixels) to move the pin up and position it properly. Also, I set the text to be position 2 pixels from the top of the pin to position the text properly.

Using the above technique, you can now create numbered, lettered, or any kind of custom pushpin with custom text.

Here's a link to the complete example with several different examples of numbered and letter pushpins:

Virtual Earth API Numbered Pushpin Example

Virtual Earth API: Importing Virtual Earth Collections into VEShapeLayers

keithkin — Sat, 28 Apr 2007 12:27:00 GMT

The same way you can import GeoRSS Layers into VEShapeLayers, you can also import any public Virtual Earth Collection from Live Search Maps. It is very simple to do and is probably one of the easiest ways to create a Virtual Earth application.

Steve Lombardi posted a great post awhile back on the Virtual Earth Spaces Blog regarding the 10 Minute Map with steps how to create a user collection in Live Search Maps and then load it in the Virtual Earth API. Now, with the v5 Virtual Earth API you can still do this very easily, and now even provide more customization using VEShape and VEShapeLayer if you choose to do so.

To import a Virtual Earth Collection, you first need to create a VEShapeLayer and a VEShapeSourceSpecification. The VEShapeSourceSpecification allows you to specify the shape source type, the shape source, and the shape layer to load the data in. For a collection, you need to specify the source type as VEDataType.VECollection, specify the source as the Collection ID from Live Search Maps, and pass in a reference to the VEShapeLayer. Then you can call ImportShapeLayerData on the map with this specification, and you are done!

Here's the example code using a collection with information about the Lewis & Clark Expedition (for your collection, replace the collection ID with the ID of your collection):

var shapeLayer = new VEShapeLayer();
var shapeSpec = new VEShapeSourceSpecification(VEDataType.VECollection,"B41BBC2FFB8342CD!107", shapeLayer);
map.ImportShapeLayerData(shapeSpec);

To customize things further, you can pass in an optional callback to the ImportShapeLayerData call and customize the VEShapes.

Here's some sample code that changes the icon of the VEShapes when displaying the collection. Notice to iterate through the VEShapes in the collection, we do exactly what we did when importing GeoRSS layers. We can get iterate through the shapes and modify any of the VEShape properties that we want to customize.

function onFeedLoad(layer)
{
   var numShapes = layer.GetShapeCount();
   for(var i=0; i < numShapes; ++i)
   {
      var s = layer.GetShapeByIndex(i);
      s.SetCustomIcon("<img src='hiking_icon.gif'/>");
   }
}

var shapeLayer = new VEShapeLayer();
var shapeSpec = new VEShapeSourceSpecification(VEDataType.VECollection,"B41BBC2FFB8342CD!107", shapeLayer);
map.ImportShapeLayerData(shapeSpec, onFeedLoad);

Here's a link to the complete example:

Virtual Earth API Collections Example

For more information, see the Virtual Earth Interactive SDK.

Virtual Earth API: GeoRSS Layers

keithkin — Sat, 28 Apr 2007 10:53:00 GMT

The v5 Virtual Earth API has improved GeoRSS support. The Virtual Earth API now integrates GeoRSS Layer support with the VEShapeLayer. So, you can now load a GeoRSS layer feed and then access the items in that layer through the VEShapeLayer and VEShape interfaces. The Virtual Earth API supports both the W3C Basic Geo point format and Simple GeoRSS point format. The Virtual Earth v5 API also now supports GeoRSS lines and polygons (<georss:line>, <georss:polygon>).

In order to load a GeoRSS layer, you first have to create a VEShapeLayer and a VEShapeSourceSpecification. The VEShapeSourceSpecification allows you to specify the source type, the shape source, and the shape layer to load the data in. In this example, I set the source type to VEDataType.GeoRSS, specify the URL to the GeoRSS feed as the source, and pass in a reference to the VEShapeLayer:

var geoRssLayer1 = new VEShapeLayer();
var geoRssLayerSpec1 = new VEShapeSourceSpecification(VEDataType.GeoRSS, "1992hurricaneandrew.xml", geoRssLayer1);

Once the VEShapeLayer and VEShapeSourceSpecification are created, you can then call ImportShapeLayerData on the VEMap to load the data in the layer. The first parameter is the VEShapeSourceSpecification. The second parameter is an optional callback, and the third parameter is a boolean specifying whether or not to set the map view around the points in the layer when the feed loads. In this case, I do not want to change the map view when the feed loads, so I set it to false.

map.ImportShapeLayerData(geoRssLayerSpec1, onFeed1Load, false);

The callback specified to the ImportShapeLayerData will receive a reference to the VEShapeLayer that the feed is loaded in. In this example, I iterate through the VEShapes in the layer by using the GetShapeCount and the GetShapeByIndex methods on the VEShapeLayer, and then I set a custom icon for each of the VEShapes.

function onFeed1Load(layer)
{
     var numShapes = layer.GetShapeCount();
     for(var i=0; i < numShapes; ++i)
    {
        var s = layer.GetShapeByIndex(i);
        s.SetCustomIcon("http://krkinnan.members.winisp.net/samples/v5/georss/hurricane01.gif");
    }
}

And that's it! The GeoRSS feed will appear on the map after a few simple calls. And, once the feed loads, you can access the elements just like any other VEShape on the map.

Here is a link to a complete working example showing GeoRSS layers using two feeds. One feed in a W3C Basic Geo format with 2004 Hurricane Ivan Geo RSS data. The other feed is a Simple GeoRSS format with 1992 Hurricane Andrew GeoRSS data.

Virtual Earth API GeoRSS Example

For more information regarding the Virtual Earth APIs, see the Virtual Earth Interactive SDK.

Virtual Earth API: Simple VEShapeLayer Example

keithkin — Sat, 28 Apr 2007 08:44:00 GMT

One of the powerful features of the Virtual Earth v5 API is the new VEShapeLayer. The VEShapeLayer allows you to organize VEShapes into groups. In the previous VEShape example, the VEShapes were added directly to the map. When shapes are added directly to the map, those shapes are put in a default shape layer. In this post, I'll show you how to create some simple shape layers.

To add a VEShape to a specific VEShapeLayer, you just need to create a VEShapeLayer and some VEShapes, and then call AddShape on the layer.

The following code example shows you how to add a simple pushpin to a shape layer:

var shapeLayer1= new VEShapeLayer();
var shape1 = new VEShape(VEShapeType.Pushpin,new VELatLong(37.776, -122.426));
shapeLayer1.AddShape(shape1);

Once you have shape layer, you can add a shape layer to the VEMap using the AddShapeLayer method:

map.AddShapeLayer(shapeLayer1);

Each shape layer can hold multiple VEShapes, and they can be different types of VEShapes. You can have pushpins, polylines, and polygons shapes all in the same shape layer.

The following code example, adds a pushpin, polyline, and polygon all to the same shape layer:

//Create the shape layer
var shapeLayer1= new VEShapeLayer();

//Add a pushpin
var shape1 = new VEShape(VEShapeType.Pushpin,new VELatLong(37.776, -122.426));
shape1.SetTitle('Shape 1 (pushpin)');
shape1.SetDescription('in Layer 1');
shape1.SetCustomIcon('pin_blue.gif');
shapeLayer1.AddShape(shape1);
//Add a polyline
var shape2= new VEShape(VEShapeType.Polyline, [ new VELatLong(44.5, -122.5), new VELatLong(48.5, -112.3), new VELatLong(42.3, -114.7), new VELatLong(45.1, -100.4), new VELatLong(35.1, -104.2) ]);
shape2.SetTitle('Shape 2 (polyline)');
shape2.SetDescription('in Layer 1');
shape2.SetCustomIcon('pin_blue.gif');
shape2.SetLineColor(new VEColor(0,0,255,0.3));
shapeLayer1.AddShape(shape2);
//Add a Polygon
var shape3= new VEShape(VEShapeType.Polygon, [ new VELatLong(44.5, -90.8), new VELatLong(48.5, -75.3), new VELatLong(35.5, -80.4), new VELatLong(30.5, -95.8)]);
shape3.SetTitle('Shape 3 (polygon)');
shape3.SetDescription('in Layer 1');
shape3.SetCustomIcon('pin_blue.gif');
shape3.SetLineColor(new VEColor(0,0,255,0.3));
shape3.SetFillColor(new VEColor(0,0,255,0.3));
shapeLayer1.AddShape(shape3);

//Add the shape layer to the map
map.AddShapeLayer(shapeLayer1);

In the above code example, I used three additional optional methods on the VEShape objects. SetCustomIcon allows you to specify a custom icon for the VEShape. SetLineColor allows you to specify a VEColor of the lines in the shape. SetFillColor allows you to specify a VEColor to fill in the shape. The VEColor takes 3 arguments: a red, green, blue, and alpha transparency value. In the above sample, I set the line color to blue and the transparency to 0.3.

Once you create shape layers on the map, you can then choose to show and hide individual shape layers with the Show and Hide methods on the VEShapeLayer.

For example, the following code hides and then shows the shape layer:

shapeLayer1.Hide();
shapeLayer1.Show();

The following link has a complete working example showing two shape layers -- one using blue colors and one using green colors. I created a simple checkbox control in the top right which can be used to hide/show the individual shape layers.

Simple VEShapeLayer Example

For more information on VEShapeLayers and the v5 Virtual Earth API, see the Virtual Earth Interactive SDK.

Virtual Earth API: Simple VEShape Example

keithkin — Sat, 28 Apr 2007 08:12:00 GMT

The Virtual Earth v5 APIs added a new VEShape class to make it easier to create pushpins, polylines, and polygons. The new VEShape class gives these shapes a standard interface and a uniform way to create and access drawing elements on the map. VEShapes are powerful and have many settings you can customize. However, for this example, we are sticking with the basics to create simple pushpins, polylines, and polygons. Future examples will show more details and expand on the customizable attributes of these elements.

To create a simple pushpin with a VEShape, you just need pass the VEShapeType.Pushpin type and a VELatLong to the VEShape constructor. Then add it to the VEMap with the AddShape call.

For example:

var shape1 = new VEShape(VEShapeType.Pushpin,new VELa\tLong(37.776, -122.426));

To create a simple polyline with VEShape, you need to pass the VEShapeType.Polyline type and an array of VELatLongs to the VEShape constructor. Then add it to the map with the AddShape call.

For example:

var shape2= new VEShape(VEShapeType.Polyline, [ new VELatLong(44.5, -122.5), new VELatLong(48.5, -112.3), new VELatLong(42.3, -114.7), new VELatLong(45.1, -100.4), new VELatLong(35.1, -104.2) ]);

To create a simple polygon with VEShape, you need to pass the VEShapeType.Polygon and an array of VELatLongs to the VEShape constructor. Then add it to the map with the Add Shape call

For example:

var shape3= new VEShape(VEShapeType.Polygon, [ new VELatLong(44.5, -90.8), new VELatLong(48.5, -75.3), new VELatLong(35.5, -80.4), new VELatLong(30.5, -95.8)]);

You can also add content to the default pop-up info box for each VEShape by calling the SetTitle and SetDescription methods on the VEShape:

For example:

shape1.SetTitle('Shape 1');
shape1.SetDescription('Pushpin');

The pop-up info box by default will appear when mousing over the shape icon. (Note: The pop-up info box is very customizable as well, however for this example, we'll keep it simple. Future examples will show how to customize these elements.)

Once you have created your shapes, you can add them to the VEMap using the AddShape call:

map.AddShape(shape1);

map.AddShape(shape2);

map.AddShape(shape3);

When adding VEShapes directly to the VEMap, they will be a part of the default layer. In a future example, we will add shapes to multiple layers.

Here's a link to the complete sample for this mashup:

Simple VEShape Example

For more information on VEShapes, see the Virtual Earth Interactive SDK.


Figure 1. Unclustered Pushpins	Figure 2. Clustered Pushpins