For the inaugural post in my new blog, I thought I’d cover one of the (many) issues that seems to have been generating some confusion following the release of the new v7 AJAX API – namely how to set altitude on a pushpin location, and the effects of doing so.
Before I get into any code, it’s worth making a couple of important observations about altitude:
– Although it may seem obvious, changing altitude will have no effect on the display of a pushpin if you’re using a two-dimensional, top-down map style.
– In contrast, when displaying maps in three-dimensional view (including oblique “birdseye” modes), considering altitude becomes essential in order to correctly position a pushpin in the display.
Under the old v6.x map control, you only generally needed to worry about setting the altitude of your pushpins if you were explicitly using the birdseye or (now deprecated) 3d mode. If you didn’t use those modes, you could set the EnableBirdseyeMode and showSwitch map options to false to prevent your users from accessing the birdseye and 3d map styles respectively, and then use only the road and aerial “top-down” styles, comfortably ignoring any implications of altitude. Every pushpin therefore needed only a latitude and longitude coordinate.
In version 7, the situation is slightly different for two reasons: firstly, there does not currently appear to be any way of limiting the range of map styles available – any style can be chosen from the main menu bar by the end user, including birdseye. Not only that, but the default Automatic map style is now a hybrid style that smoothly transitions from two-dimensional top-down road and aerial imagery at distant zoom levels into “tilted” three-dimensional birdseye at close zoom levels. The effect of these changes is that all Bing Maps developers should now consider what effect altitude has on the way their pushpins are displayed using the different map styles in v7.
Now, for an example: the following code listing creates two pushpins. The first, whose location is specified using only latitude and longitude coordinates, is positioned at the default ground level, at the base of Nelson’s column in Trafalgar Square. The second is positioned exactly 50m above the first, and is specified using both the altitude and the altitudereference of the location.
When viewing this map at zoom level 16, the Automatic map style chooses the flat 2d road map view, so the two pushpins are completely superimposed:
However, zoom in one level and the Automatic map style changes to enhanced birdseye view, so the two pushpins diverge to show the bottom and top of the column:
Since we are viewing at an oblique angle from the south, while the bottom pushpin (placed on the ground) appears to have remained in the same place the “top” pushpin appears to have shifted north up the map (whereas, in fact, it is directly above the bottom pushpin). Notice that the image above is taken at zoom level 17, which, in v6.x would still only be capable of showing a flat aerial map (the old “birdseye” mode only being available at the very highest level of zoom).
The enhanced birdseye mode in v7 that replaces the old “aerial” mode still demonstrates perceivable 3d and distinction between these two pushpin locations even when significantly zoomed out. The following image demonstrates that there is still a slight perceivable difference between the location of the pushpins at the top and bottom of Nelson’s column when viewed in birdseye mode at zoom level 14:
Personally, I think the enhanced birdseye style is great since you get the best of both worlds: the traditional aerial imagery view combined with an added sense of depth perception from the slightly oblique angle. However, many developers used to dealing only with the purely top-down “aerial” view of 6.x might not have thought of some of the implications that the new map styles create on the clarity of pushpin location. The Bing Maps default, if no altitude is specified, is to place a pushpin at terrain height of that location (i.e. on the ground). However, there appear to be cases where the underlying terrain elevation data is incorrect, in which case pushpins are incorrectly placed above or below the correct ground height. When viewed obliquely, this can make it appear that they are then misplaced laterally…. to demonstrate what I mean by this, consider the following image:
At first glance, this map might appear to be highlighting two street locations; one in Trafalgar Square and 10 Downing Street. However, it’s actually showing the same points as used earlier in this post – both placed at exactly the same latitude/longitude. The only difference is that this time the top point has been raised to an altitude of 500m. When viewed from this orientation, and combined with the expectation that both points lie on the same level, may lead a viewer to erroneously conclude that the two pushpins lie at different positions on the ground. So, if your pushpins appear to be displayed in the wrong place, be sure to check not only the latitude/longitude values, but also that you’ve specified the correct altitude.
Note: There is currently an error on the MSDN documentation concerning the location class. http://msdn.microsoft.com/en-us/library/gg427612.aspx should describe the property that determines the basis for stating an altitude of a location as altitudeReference, not altitudeMode.