Adding a Buffer Around a MapPoint Web Service Map

IMPORTANT: MapPoint Web Service was retired on November 18, 2011. Please see Bing Maps for a list of current Bing Maps APIs.

Joe D. Como
Microsoft Corporation

July 2004

Applies to:
   Microsoft MapPoint Web Service, Version 3.5

Summary: Learn how to use the ViewByBoundingRectangle class to prevent icons from being truncated on maps returned by MapPoint Web Service. (6 printed pages)

Contents

Introduction
Why Icons Are Truncated
Using the ViewByBoundingRectangle Class
Adding a Buffer
Conclusion

Introduction

When a user requests a map containing a certain set of points, you can use one of four classes to return a map view: ViewByBoundingLocations, ViewByHeightWidth, ViewByScale, or ViewByBoundingRectangle. Only one of these classes, ViewByBoundingLocations, provides a buffer. This buffer is meant to prevent the icon images from being truncated and from appearing on the edges of the map. The default buffer, which is fixed, can usually prevent icons from being truncated. However, in certain situations, the default buffer may not work.

This article describes how to use the ViewByBoundingRectangle class to add a buffer around MapPoint Web Service maps, ensuring that all map icons are shown in their entirety.

Why Icons Are Truncated

An icon might be truncated if it is larger than the recommended size (16 × 16 pixels), or if the portion of the icon that falls on the latitude and longitude coordinates it represents (such as the tip of an arrow icon) is at one of the four sides of the icon image instead of at the center. Most of the stock icons provided by MapPoint Web Service for use on maps are smaller than or equal to the standard, but users can create and upload custom icons for use with MapPoint Web Service that exceed the recommended bounds. For example, in Figure 1, the flag icon to the right of Woodbridge is truncated. In this case, the icon is larger than the recommended size (24 × 27 pixels rather than 16 × 16) and the bottom of the image (the base of the flagpole) falls on the latitude and longitude coordinates that the icon represents.

Figure 1. Map view with a truncated icon

Using the ViewByBoundingRectangle Class

One way to overcome the rigid buffer value of the ViewByBoundingLocations class is to use the ViewByBoundingRectangle class to get your map view. The ViewByBoundingRectangle class has no default or settable buffer, but it is easier than the ViewByBoundingLocations class to manipulate if you want to add a buffer around the icons shown on a map.

The BoundingRectangle property (a LatLongRectangle object) of the ViewByBoundingRectangle class consists of latitude and longitude coordinates that represent the southwest and northeast corners of a minimum bounding rectangle. To set the BoundingRectangle property so that it encompasses all of your locations, iterate through the latitude and longitude values of your icons and determine the northernmost and southernmost latitude values and the easternmost and westernmost longitude values. Combine the southernmost latitude point with the westernmost longitude point, and you have the southwest coordinate for the BoundingRectangle property. Do the same for the northernmost latitude value and easternmost longitude value, and you have the northeast coordinate for the BoundingRectangle property.

The following code example shows how to test your latitude and longitude values to determine the coordinates for the BoundingRectangle property. This code is for buffering the display of maps that consist of points north of the equator, west of the prime meridian, and east of the International Date Line. This code will not work for most European, African, Asian, Australian, or South American locations.

[C#]
// Set the initial northernmost value to lowest possible value 
// (the equator). This will ensure that the value is overwritten by any 
// of the icon values. Icons will have latitutde values that are 
// greater than zero.
double highestNorthLat = 0.00;
// Set the initial southernmost value to the highest possible value 
// (North Pole). This will ensure that the value is overwritten by any 
// of the icon values.Icons will have latitude values that are less 
// than 90. 
double lowestSouthLat = 90.00;
// Set the initial easternmost value to the lowest possible value 
// (the International Date Line). This will ensure that the value is 
// overwritten by any of the icon values. Icons will have longitude 
// values that are greater (closer to zero) than -180.
double lowestEastLon = -180.00;
// Set the initial westernmost value to the highest possible value 
// (the prime meridian--Greenwich, England). This will ensure that the 
// value is overwritten by any of the icon values.Icon will have 
// longitudes values that are lower (closer to -180) than zero.
double highestWestLon = 0.00;

for (int i = 0; i < pointsOnMapLength; i++) 
         {
double thisLat = pointsOnMap[i].LatLong.Latitude;
double thisLon = pointsOnMap[i].LatLong.Longitude;

// Test the latitude value to determine if it is most northerly point.
if (thisLat > highestNorthLat) 
{
      highestNorthLat = thisLat;
}
// Test the latitude value to determine if it is most southerly point.
if (thisLat < lowestSouthLat) 
{
      lowestSouthLat = thisLat;
}
// Test the longitude value to determine if it is most easterly point.
if (thisLon > lowestEastLon) 
{
      lowestEastLon = thisLon;
}
// Test the longitude value to determine if it is most westerly point.
if (thisLon < highestWestLon) 
{
      highestWestLon = thisLon;
}
} // end for

Now that you have a BoundingRectangle property that encompasses all of your points, you must add a buffer to the BoundingRectangle property to prevent icons from being truncated.

Adding a Buffer

To add a buffer, expand the area that the BoundingRectangle property covers by adjusting the corners of the rectangle:

• Adjust the northeastern corner by increasing the latitude value of the northern point and decreasing the longitude value of the eastern point.
• Adjust the southwestern corner by decreasing the latitude value of the southern point and increasing the longitude value of the western point.

You can add static values to your latitude and longitude coordinates, such as one-tenth of a degree to the northernmost latitude value. That won't work in all cases, however, because each map has a different scale and, therefore, adjusting latitude by one-tenth of a degree might not prevent icons from being truncated on a map with a large scale.

To accommodate all map-scale scenarios, it is best to have an idea of the size of the area bounded by your locations. You can infer this size by subtracting the southernmost latitude value from the northernmost latitude value and the easternmost longitude value from the westernmost longitude value, as in the following example code. The greater the resulting values of these calculations, the greater the physical area of the Earth your locations encompass.

[C#]
double northSouthDiff = highestNorthLat - lowestSouthLat;
double eastWestDiff = Math.Abs(highestWestLon) -Math.Abs(lowestEastLon);

These values are the basis for your buffer, but they are too large to use as a buffer themselves (using the difference values to determine a buffer would double the area that your map covers and group your icons in the center of the map). Therefore, you must divide these difference values by another value. The lower the value you use as a divisor, the larger the buffer around your map. For example, if you divide the difference values by two and add the results to the two corners of the BoundingRectangle property, you will create a buffer that adds 50 percent to the area that your map covers. If you divide the difference values by four, your buffer size is reduced to 25 percent.

The following code example divides the difference values by six, which results in a buffer of approximately 16 percent. There is nothing special about a 16 percent buffer other than that it works for this particular set of icons, with their larger than normal size and bottom-aligned latitude and longitude coordinates. If you have larger icons, you might want to divide by a lower number to increase the size of your buffer. If the width of your icons is greater than their height, you might want to use a larger divisor value on the difference between the north and south latitudes (producing a smaller buffer on the top and bottom), and a smaller divisor value on the difference between the east and west longitudes.

After you determine what your divisor value (or values) should be, use them to divide the latitude and longitude difference values. Use the results of those calculations to adjust your four corner points as appropriate.

[C#]
int mapBufferDivisor = 6 
highestNorthLat += northSouthDiff / mapBufferDivisor; 
lowestSouthLat -= northSouthDiff / mapBufferDivisor;
lowestEastLon += eastWestDiff / mapBufferDivisor;
highestWestLon -= eastWestDiff / mapBufferDivisor;

Next, create your LatLongRectangle object, which now will contain a buffered space around your map icons.

[C#]
LatLong mostNorthEastPoint = new LatLong();
mostNorthEastPoint.Latitude = highestNorthLat;
mostNorthEastPoint.Longitude = lowestEastLon;

LatLong mostSouthWestPoint = new LatLong();
mostSouthWestPoint.Latitude = lowestSouthLat;
mostSouthWestPoint.Longitude = highestWestLon;

// Create a LatLongRectangle from the northeast and southwest points.
LatLongRectangle bufferedRectangle = new LatLongRectangle();
bufferedRectangle.Northeast = mostNorthEastPoint;
bufferedRectangle.Southwest = mostSouthWestPoint;

The LatLongRectangle object that you created will be the value for the BoundingRectangle property of your ViewByBoundingRectangle class. The new map that results from this code (Figure 2) shows the icon in its entirety without compromising the look and usability of the map.

Figure 2. Map with buffer

Conclusion

Preventing icons from being truncated is important from a usability standpoint, because a location may be missed entirely by the consumers of your maps if the icon for the location isn't fully shown. Adding a buffer to the map view around your locations gives you the freedom to use larger map icons, and to ensure that all your points appear on the map in full view.

Joe D. Como is a Web Development Engineer in the Microsoft MapPoint Business Unit and is a member of the Professional Services team.