In the latest release of Virtual Earth, version 6.2, client side clustering was included as a built in function for shape layers. You can assign a client side clustering algorithm to a shape layer so that it will automatically cluster the shapes when the map is zoomed. This is done by using the VEShapeLayer.SetClusteringConfiguration method. This method can take in two parameters. A clustering type and a VEClusteringOptions object. Currently there is only one built in clustering algorithm type available, grid clustering. Unfortunately there is limited flexibility in this algorithm in that the grid size can not be modified. This can be resolved by making a custom clustering algorithms. This post will show how to create a custom clustering algorithm that can be used with the VEShapeLayer.SetClusteringConfiguration method.

According to the documentation (http://msdn.microsoft.com/en-us/library/cc966716.aspx) a custom clustering algorithm must take in a VEShapeLayer and return an array of VEClusterSpecification objects.

A VEClusterSpecification objects has two properties. A Shapes property and a LatLong property. The Shapes object consists of an array shapes that are being clustered. The LatLong property is the coordinate used to place the clustered pushpin. (http://msdn.microsoft.com/en-us/library/cc966730.aspx)

The custom clustering algorithm that will be created in this blog post will implement a grid clustering algorithm and place the clustered pushpins in the mean average coordinate of the clustered pins. This algorithm is an improvement upon the clustering algorithm described here: http://msdn.microsoft.com/en-us/library/cc161072.aspx

Here is the custom clustering algorithm which grid clusters and places the clusters in the mean average coordinate of the clustered pins. You can modify the size of the grid used in the algorithm by changing the value of the gridSize variable.

The following code can be used to implement this customer clustering algorithm.

Using the Imagery service available in the Virtual Earth Web Services, it is possible to retrieve a map image for a specific location (as specified by specific latitude and longitude values). This method however, is not available to the Birds Eye imagery. Rather further functionality must be applied within the Web Services in order to retrieve accurate Birds Eye Imagery Metadata. The information on the Birds Eye scene for the desired location is present in the URI that is used to retrieve the map tiles which make up the Birds Eye scene. To return the tile in which the specified coordinate exits currently a tile id for the map image must first be provided. The extraction of the correct tile id for alternate map styles, using the Quad Key notation is described in the article, Virtual Earth Tile System (http://msdn.microsoft.com/en-us/library/bb259689.aspx).

The methodology described in the Virtual Earth Tile System article is unfortunately not applicable to Birds Eye imagery as a standard Birds Eye scene does not fit perfectly into a quad key frame (for example, a Birds Eye scene at zoom level 19 consists of 4 tiles in the x-axis and 6 tiles in the y-axis and at zoom level 20 there are 8 tiles in the x-axis and 12 tiles in the y-axis).  Furthermore the Birds Eye scenes do not populate the quad key format properly, rather tiles that are on the edge of a scene, only fill a portion of a standard map tile. This behavior is caused because the Birds Eye images are geo-referenced, high resolution images which are then overlayed onto the Virtual Earth map differently than a standard tile.

The following (figure 1), is a Birds Eye scene shown over a standard road view in Virtual Earth at zoom level 19. The red boxes represent the Birds Eye tiles, and the black boxes represent the VE road tiles over the same area. As is evident, the Birds Eye tiles do not properly line up with the edges of the Virtual Earth tiles, which are placed on the map according to the quad key notation. The Birds Eye imagery therefore must be retrieved using a difference methodology than would be used for a standard VE tile.

Figure 1 - Birds Eye over standard map tile at zoom level 19

The Birds Eye geo-referencing information is stored in a database that can only be extracted using the backend web services the Virtual Earth Map Control implements. The data is returned as JavaScript, and can be extracted from the feed using another step, such as regular expressions. With the information retrieved, it is possible to then geo-reference the Birds Eye tiles, or calculate the specific tile id that a coordinate falls into. Note that this is a hack and is completely unsupported as it's possible that a change on VE's side will cause this URL or method to break.

The following are the necessary steps to calculate the tile id based on an input coordinate:

1)      Retrieve the Birdseye Imagery Metadata for a coordinate using the Virtual Earth Web Services.

2)      Retrieve geo-referencing data for the Birdseye scene in which the coordinate resides using backend Virtual Earth web service.

3)      Extract geo-reference data from web service response using regular expressions.

4)      Convert LatLong to pixel coordinate, relative to top left corner of Birdseye scene.

5)      Calculate the x and y tile positions.

6)      Calculate tile id from x and y tile positions.

7)       Retrieve Birds Eye tile in which the coordinate resides.

Retrieve Birds Eye Imagery from Virtual Earth Web Services

Retrieving the Imagery Metadata for a Birds Eye Scene in which a coordinate exists can be accomplished using the following simple example on how to build the request;

The ImageryMetadataResult object contains several properties; the following variables will be needed in either the calculations that follow or in creating the URI to the map tile:

Additional information on how to use the Virtual earth web services can be found in the article, Developing a .NET Application Using Virtual Earth Web Services (http://msdn.microsoft.com/en-us/library/dd221354.aspx).

Retrieve Geo-Referencing Data for a Birds Eye scene

Geo-Referencing data for Birds Eye scenes is not available through the Virtual Earth Web Services rather the information needs to be retrieved from a backend web service. The following is an example web service request that can be used to access the service:

http://dev.virtualearth.net/services/v1/ImageryMetadataService/ImageryMetadataService.asmx/GetBirdsEyeSceneByLocation?latitude=40.77638178482896&longitude=-73.61663818359376&level=20&spinDirection=%22NoSpin%22&orientation=%22North%22&culture=%22en-us%22&format=json&rid=1227643110358&

This request contains multiple variables:

The following is an example of a response from the web service:

Extract Geo-Reference Data from Web Service Response

The web service response contains more information than necessary; the following is the only portion that is needed:

Each variable is defined with a variable name and value in the format:  “name”: value. An explanation as to what some variable names means is as follows:

These variables can be extracted using regular expressions similar to the following:

Convert Latitude & Longitude to Pixel Coordinate

The calculated pixel will be the pixel coordinates relative to the top left corner of the scene.  The first step in this calculation is to create a 1x3 matrix of the LatLong coordinate.

Once the LatLong matrix is created a second matrix is needed to store the geo-referencing data XA-XI. This will require a 3x3 matrix.

These matrices need to be multiplied together in the following fashion:

Before the pixel coordinates can be calculated a zoom factor constant is needed.

The following formula’s can then be used to calculate the pixel coordinates:

By expanding out the calculations the pixel coordinates can be calculated as follows:

Calculate X and Y Tile Positions

The X tile position can be calculated by dividing the x pixel location by the width of a tile and rounding this number down to an integer value.

The Y tile position can be calculated by dividing the y pixel location by the height of a tile and rounding this number down to an integer value.

Calculate tile id from x and y tile positions

The X and Y tile positions along with the tileId are calculated for zoom level 19 using the following grid pattern:

Zoom level 20 uses a similar method, however the grid is 8 tiles in the x-axis and 12 tiles in the y-axis. The number of tiles in the x-axis for a particular Birds Eye Scene is stored in the Hcx value and the number of tiles in the y-axis is stored in the Fcy value of the web response to the back end web service. The following formula calculates a tile id from the X and Y tile positions:

Retrieve Birds Eye tile

Here is an example of a URI to a hybrid Birds Eye tile that is provided by the ImageryMetadataResult.ImageUri property:

http://{subdomain}.staging.tiles.virtualearth.net/tiles/cmd/ObliqueHybrid?a=03201011031-7384-19-{tileId}&g=213&token={token}

There are three properties which have to be set; subdomain, tileId, and token.  The subdomain can be assigned any value that is in the ImageUriSubdomains array. The token value should be assigned as a valid client token. The tileId is the id of a specific tile in a Birds Eye scene.