Saturday, 01 November 2014
Whats new in Virtual Earth 6

Author: John O'Brien

The version 6 update of the Virtual Earth API builds on the existing API adding new functionality, new interface options and support for the Safari web browser. Critically there are no breaking changes from Version 5. So for your application to take advantage of these new features it may just be a matter of changing the version number to 6.

The Correct URL

First up there has been confusion over the correct URL for the API. The correct way to reference Version 6 is:

<script type="text/javascript" 
src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6"></script>

The new interface

On first glance you will immediately notice the new dashboard control and scale bar. Although the other optional sizes have remained the same (tiny and small) the normal dashboard is now identical to that on maps.live.com. I have spotted one difference though, the API for “road” uses the plain road tiles while maps.live.com uses the newer “hill shaded” style. Fortunately this is now available to developers as a map style:

map.SetMapStyle(VEMapStyle.Shaded);

New Zooming Option

Another interesting interactive option is to change from the default scroll wheel zooming on the centre of the screen to zoom on the mouse location – ala google maps. It is enabled with one line of code:

map.SetMouseWheelZoomToCenter(false);

Check out a demo here.

Birdseye in 3D

As we have seen in videos from maps.live.com the API also supports a “photosynth” style navigation of Birdseye images within 3D mode. Although currently there are a few JavaScript errors being thrown it shows the beginning of what could be a very exciting time for static images in Virtual Earth 3D. I recommend navigation with the keyboard arrow keys for a better experience.

While on the subject of birdseye two new methods have crept in to solve some outstanding issues. The first is:

VEBirdseyeScene.GetBoundingRectangle();

This returns oversized, approximate, bounds for the current birdseye view. For developers that load there data on demand for what is current visible this is a much welcomed addition and makes the many hacks and breaches of licensing redundant. A big thank you to the dev team for sorting this out.

The second addition is the ability to request a Birdseye view based on Latitude, Longitude and Zoomlevel:

VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel,
callback);

Traffic

For areas that support it developers can now add traffic flow overlays really simply. You just add the line:

map.LoadTraffic(true);

See a demo here

The API does note:

All use of traffic data is restricted to customers who have received explicit permission and instructions about traffic from Microsoft. For more information on terms for use of traffic, contact the Microsoft Virtual Earth Licensing Team

Geocoding Confidence

The map.Find() method has had some improvements also. The VEPlace class now contains:

  • VEPlace.LatLong Property
    Gets a VELatLong Class object that represents the location of the found result.
  • VEPlace.Name Property
    Gets the String object that represents Virtual Earth's unambiguous name for the location.
  • VEPlace.MatchCode Property
    A VEMatchCode Enumeration value specifying the match code from the geocoder.
  • VEPlace.MatchConfidence Property
    A VEMatchConfidence Enumeration value specifying the match confidence from the geocoder.

VEMatchCode has 5 levels:

  • None - No match was found
  • Good - The match was good
  • Ambiguous - The match was ambiguous
  • UpHierarchy - The match was found by a broader search
  • Modified - The match was found, but to a modified place

VEMatchConfidence has 3:

  • High - The confidence of a match is high
  • Medium - The confidence of a match is medium
  • Low - The confidence of a match is low

MultiPoint Routing

Finally the by far most requested feature has been implemented. Routing has now been overhauled to allow much more control. See a simple demo here. It deserves an entire article but to summarise you now pass an array of locations along with some options:

locations = new Array("Tacoma WA", "Seattle
WA", "Everett WA");
map.GetDirections(locations, options);

The options include:

  • KM or Miles
  • Draw the route
  • The callback function
  • Route Line colour
  • RouteOptimisation – logic that plans the best order to visit the locations, vey cool.
  • The Line weight (thinkness)
  • Line Zindex
  • Set the map to fit the route
  • Show Disambiguation dialog
  • Show error messages.

The function’s callback gets a rich set of information contained in the VERoute class. This has the total distance but also each segment has a distance and array of latlong, shape and text. Look out for a more detailed look at this soon.

Shapes

In Version 5 we saw pushpins, polylines and polygons become a more generic “shape”. In version 6 these shapes now get more goodies. First off we get methods for Zindex allow complete control over what is on top and below including the polyline/polygon separate from its pushpin:

VEShape.GetZIndex();
VEShape.GetZIndexPolyShape();
VEShape.SetZIndex(icon, polyshape);

Secondly we can now set altitude for 3D mode. This was undocumented in V5 and a little confusing, well they have sorted it out, you now set the altitude in meters and choose how that distance is applied through a mode:

VEShape.SetAltitude(altitude, altitudeMode);

Options are:

  • Default - The altitude is meters above ground level
  •   Absolute - The altitude is meters above the WGS 84 ellipsoid
  •   RelativeToGround - The altitude is meters above ground level

Additionally you can also draw a line from the shape to the ground, again it is a simple property:

VEShape.SetLineToGround(extrude);

This allows you to do some very cool 3D things:

The other major addition to Shapes surrounds accuracy and performance. Several new features have been introduced to help in this area. First up have the ability to set a maximum and minimum zoom level for shapes:

VEShape.SetMaxZoomLevel(level);
VEShape.SetMinZoomLevel(level);

Note: If the minimum and maximum zoom levels are equal, the shape is never visible.

Next up the AddShape method now accepts an array of shape objects.

Performance demo here

This allows us to bulk load shapes. What is the difference? This demo is a little inaccurate but repeating the test over and over clearly shows a large performance gain. On my laptop the difference is 3.8s to load 1000 pins separately versus 1.1s using the bulk method. Feel free to view source and play more, interestingly if the shapes are not in the current map view, pan away from Africa in the demo, the old method takes 0.5s while the bulk method still takes 1.1s.

VEShapeLayer.AddShape(shape);

Simply pass an array of shapes for great performance gains.

Lastly we can configure the shape accuracy for use in Birdseye mode. The documentation states:

When switching between aerial and birdseye views, pushpin accuracy is maintained, delivering a more seamless experience.

As usual it’s pretty simple and straight forward to configure, we have two settings, first:

map.SetShapesAccuracy(policy);

The policy is a new class VEShapeAccuracy that can be set to:

  • None - No shapes are accurately converted (default)
  •   Pushpin - Only pushpins are accurately converted
  •   All - All shapes are accurately converted

Secondly we can set a limit to how many will be accurately plotted.

map.SetShapesAccuracyRequestLimit(25);

The default value is 50.

Conclusion.

I’m very impressed with this release of Virtual Earth, many of new features I know have been asked for directly by customers and to integrate them into this release while not breaking version 5 code is very well done. Big congratulations to the VE team.

Of course there are some new features missing from what was unveiled on maps.live.com. Notably we see no new methods for 3D tours or recording, previous attempts trying to build 3D tours in Virtual Earth have been very stop start, a smooth experience was not achievable. We also see no mention of custom 3D models. There is a new method on shapes, VEShape.IsModel(), but no mention of how to add custom models.

I hope this article has highlighted the changes in Version 6 and will allow you to make the painless upgrade and start using the features today.

Copyright 2009. Sponsored by nsquared.   |  Terms Of Use  |  Privacy Statement
Content on this site is generated from the developer community and shared freely for your enjoyment and benefit. This site is run independently of Microsoft and does not express Microsoft's views in any way.