8.1. Understanding Render APIsThe Render Service end point is located at the RenderService.asmx, and the APIs available for it are exposed via the RenderServiceSoap class in the Web Service proxy (Reference.cs or Reference.vb). The RenderServiceSoap class contains methods related to render functionality , namely GetMap, GetBestMapView, ConvertToLatLong, and ConvertToPoint, which can be used to get maps, get map views, and to convert a point on a map to a pixel coordinate or vice versa. Table 8-1 describes the methods of the RenderServiceSoap class.
Before getting into the details of using the render-related methods, let's look at the essential basics to understand in rendering maps. 8.1.1. Introduction to ViewsA view defines a specific area that needs to be rendered on a map and can be expressed in four ways using MapPoint Web Service. 8.1.1.1. View by bounding locationsIn this case, a map view is defined using a set of locations, and the map is rendered to contain all of the locations on the map. Programmatically, this view is represented by the ViewByBoundingLocations class, which takes an array of Location objects to define the map view. All input Location objects must have a valid LatLong property. This view is useful if you want to render Location objects from different find calls on one map. When this view is requested, MapPoint Web Service calculates the best possible map view to fit all locations on the map. The following code shows how to define and use the ViewByBoundingLocation object to render a map: //Define an array of locations //In this case 4 has been randomly chosen Location[] myLocations = new Location[4]; //Obtain LatLong values for each Location object . . . //Define view by Location and assign locations ViewByBoundingLocations viewByBoundingLocations = new ViewByBoundingLocations( ); viewByBoundingLocations.Locations = myLocations; //Get a map MapSpecification mapSpec = new MapSpecification( ); mapSpec.Views = new MapView[] {viewByBoundingLocations}; . . . These four locations are rendered on the map shown in Figure 8-1. 8.1.1.2. View by height and widthIn this case, a map view is defined by the height and width of the area that you want to cover on the ground. The height and width you express essentially equal the ground distance in either miles or kilometers. It is important to keep in mind that this height and width is different from the height and width of the map image that you want to render. If you want to render 50 km of height and 100 km of width on the ground, you can do so on a 200 x 200 pixel map image. Although the height and width specified for the map are different from the height and width of the map image, they are related to each other via map scale, which we will look at in detail later in this chapter. Figure 8-1. View by bounding locations mapWhen a map is rendered using ground height and width, it is rendered to contain at least the requested area, which means that MapPoint Web Service may render more area than requested depending on the aspect ratio. Programmatically, this view is represented by the ViewByHeightWidth class, which defines the map view using height and width specifications as integers. When this view is requested, MapPoint Web Service calculates the best possible map view to fit the requested area on the map. The following code shows how to define a ViewByHeightWidth object to render a map: //Define a center point LatLong centerPoint = new LatLong( ); centerPoint.Latitude = centerLatitude; centerPoint.Longitude = centerLongitude; //Define view by height and width ViewByHeightWidth viewByHW = new ViewByHeightWidth( ); viewByHW.CenterPoint = centerPoint; //Define height and width on the ground //In this case area covering //200 km and //300 km //on the ground viewByHW.Height = 200; viewByHW.Width = 300; //Create map specification MapSpecification mapSpec = new MapSpecification( ); mapSpec.Views = new ViewByHeightWidth[] {viewByHW}; //Get a map . . . The rendered map requested in the previous code is shown in Figure 8-2. Figure 8-2. Map rendered with 200 x 300 KM in ground distanceThe same map rendered with 20 x 30 km height and width, respectively, is shown in Figure 8-3. Although the image (bitmap) size here is constant, a change in the map's height and width caused the scale to change, creating a "zoom in" effect. 8.1.1.3. View by scaleIn order to understand view by scale , you need to understand the notion of scale first. Scale can be defined as (map image size) / (map size in real world); so, if you have a map of the world as a globe rendered on a 1 inch map image, the scale is 1: 520,000,000, since the world's diameter is 520,000,000 inches. This means that one inch on the image represents 520,000,000 actual inches in the world. Remember though, that the image size (such as 400 x 600 pixels and 2,000 x 2,000 pixels) has no impact on the scale; to control the scale of a rendered map, you need to use view by scale. This view is represented by the ViewByScale object. To use this object, set a center point as LatLong object and scale value. The scale ranges are dependent on the MapPoint data sources. The following code shows how to use the ViewByScale object: Figure 8-3. Map rendered with 20 x 30 KM in ground distance//Define a center point LatLong centerPoint = new LatLong( ); centerPoint.Latitude = centerLatitude; centerPoint.Longitude = centerLongitude; //Define view by scale ViewByScale viewByScale = new ViewByScale( ); viewByScale.CenterPoint = centerPoint; //Define scale value viewByScale.MapScale = 20000; //Create map specification MapSpecification mapSpec = new MapSpecification( ); mapSpec.Views = new ViewByScale[] {viewByScale}; //Get a map . . . This view is extremely useful in controlling the zoom levels for rendered maps. Also, note that you can use this view for device-specific resolution map rendering ; by default, MapPoint Web Service renders maps at 96 dpi; however, you can alter this value to match your device-specific resolution, as shown below: //Define scale value viewByScale.MapScale = 20000 * 96/120; A resolution of 120 dpi is applied to the scale to match the device's dpi resolution. 8.1.1.4. View by bounding rectangleThis view defines the map area by a bounding rectangle. Unlike the view by bounding locations, there are only two LatLong objects involved in defining the rectangle: one for the northeast corner and one for the southwest corner. When a bounding rectangle is defined using a LatLongRectangle object, a map that covers the specified area is rendered. This view is useful if you want to render a specific area on the map (unlike the area dictated by the number of points, as in ViewByBoundingLocations). This view is programmatically represented by the ViewByBoundingRectangle object. The following code shows how to use this view: //Define northeast point LatLong northEastPoint = new LatLong( ); . . . //Define southwest point LatLong southWestPoint = new LatLong( ); . . . //Define view by bounding rectangle ViewByBoundingRectangle vbr = new ViewByBoundingRectangle( ); vbr.BoundingRectangle = new LatLongRectangle( ); vbr.BoundingRectangle.Northeast = northEastPoint; vbr.BoundingRectangle.Southwest = southWestPoint; //Create map specification MapSpecification mapSpec = new MapSpecification( ); mapSpec.Views = new ViewByBoundingRectangle[] {vbr}; //Get Map . . . This code generated the map shown in Figure 8-4. The map has covered the corners defined by the northeast and southwest latitude, longitude combinations. Now that you know what map views are, let's look at map styles before moving on to look at the Render APIs in detail. Figure 8-4. Map rendered for view by bounding rectangle8.1.2. Understanding Map StylesMap Style in MapPoint Web Service is a rendering -specific flag that indicates what kind of detail is rendered on the map. To that end, Map Style can be used to control which information is rendered on the maps. For example, when you use Road map style, the maps are rendered with full road data; however, when you choose to use Political map style, maps display only political entities (such as countries, and regions). Map Style in MapPoint Web Service is programmatically represented using the MapStyle enumeration. There are currently 31 Map Styles supported in MapPoint Web Service; it is important to keep in mind that Map Styles are data source-dependentnot all map styles are supported by all data sources. With this introduction to map views and map styles, let's next look at how Rendering APIs works. 8.1.3. Anatomy of Render APIsMapPoint Web Service provides Render APIs for you to render maps using the RenderServiceSoap.GetMap method. The GetMap method takes a MapSpecification object as an argument that defines the map to be rendered and returns an array of MapImage objects. The MapSpecification object defines the map to be rendered in terms of the view, data source, route (only for rendering a route), pushpins, or polygons (only to render polygons), along with optional map options that give you control over map features such as size and style. Table 8-2 shows the fields of the MapSpecification class, and Table 8-3 shows the MapOptions class fields.
The GetMap method returns an array of MapImage objects out of which the first MapImage contains the actual rendered map. The returned MapImage object contains either the map image serialized into a byte array or the URL to the map image stored on MapPoint Servers. The following code shows how to use MapSpecification object to get a map: //Find a place to render FindServiceSoap findService = new FindServiceSoap( ); //Assign credentials . . . //Find place FindSpecification findSpec = new FindSpecification( ); findSpec.DataSourceName = "MapPoint.NA"; findSpec.InputPlace = "Seattle, WA"; FindResults foundResults = findService.Find(findSpec); //Get the view ViewByHeightWidth view = foundResults.Results[0].FoundLocation.BestMapView.ByHeightWidth; //Create a RenderServiceSoap instance RenderServiceSoap renderService = new RenderServiceSoap( ); //Assign to credentials . . . //Define MapSpecification MapSpecification mapSpec = new MapSpecification( ); //Assign DataSource mapSpec.DataSourceName = "MapPoint.NA"; //Assign view mapSpec.Views = new MapView[] {view}; //Get Map MapImage[] mapImages = renderService.GetMap(mapSpec); //Get the map image stream System.IO.Stream streamImage = new System.IO.MemoryStream(mapImages[0].MimeData.Bits); //Load the image stream into a bitmap Bitmap bitmapImage = new Bitmap(streamImage); The MapImage instance returned by the GetMap method contains the map image as a byte array that can be used in your application, which works well for a Windows application. But what if you have a web application where you have an image tag and all you need is a URL to display the map? 8.1.4. Rendering for Windows Versus Rendering for the WebUsing the GetMap method, you can get either a map image as a byte array or a URL that contains the map image stored on MapPoint Web Service servers. Once you have the image URL, you can set it to an image tag for a web application. By default, the GetMap method returns the map image as a byte array, but you can use the MapOptions object to change this option to return the map URL by setting the ReturnType property: //Create map specification MapSpecification mapSpec = new MapSpecification( ); //Assign data source and views .. //Define map options mapSpec.Options = new MapOptions( ); //Request map URL mapSpec.Options.ReturnType = MapReturnType.ReturnUrl; //Get map MapImage[] mapImages = renderService.GetMap(mapSpec); //Get the URL string url = mapImages[0].Url; From this code, MapPoint Web Service returns a URL to the map image when the MapOptions.ReturnType is set to either the MapReturnType.ReturnUrl or the MapReturnType.ReturnSecureUrl enumeration. This method is very efficient since the SOAP message response from MapPoint Web Service contains only a URL instead of the entire image. However, keep in mind that a returned URL is valid for returning up to ten images within five minutes of the call to the GetMap method. After five minutes or ten images (whichever occurs first), accessing the URL returns a session time-out message. |