Section 2.6. Routing in MapPoint 2004


2.6. Routing in MapPoint 2004

MapPoint 2004 provides a simple but powerful API to calculate routes between locations. A route in MapPoint 2004 is represented as a MapPoint.Route object. You can access a Route object via the ActiveRoute property of a Map object (the Map object can be obtained either via the MapPoint.ApplicationClass object or MapPoint.axMapPointControl object using the ActiveMap property):

     MapPoint.Route route = axMappointControl1.ActiveMap.ActiveRoute;

After obtaining a valid route object, you can perform actions such as calculating, optimizing, and personalizing routes; let's see each one of these features in detail.

2.6.1. Specifying a Route

In MapPoint 2004 terms, a route is essentially a collection of locations connected in some wayvia street, ferry, or highway. These locations in a route are known as waypoints and are represented using the MapPoint.Waypoint class. A valid route always contains two or more waypoints. Waypoints in a route are represented in the Route.Waypoints collection, so you use the Waypoints collection to add new waypoints:

     //Get ahold of route object     MapPoint.Route route = axMappointControl1.ActiveMap.ActiveRoute;     //Add the location to the ActiveRoute     route.Waypoints.Add(loc, loc.Name);

You can access the waypoints using the same collection and the corresponding index value:

     //Obtain a waypoint from a given route     object index = 1;     MapPoint.Waypoint waypoint = route.Waypoints.get_Item(ref index);

You can use the MapPoint.Waypoint object in many ways to specify a new route or modify an existing route. To change the location represented by a Waypoint object, use the Waypoint.Anchor property. This property is of type object because it can be either a Location or a Pushpin. If you are assigning a new location to a waypoint, you can do it like this:

     //Obtain a waypoint from a given route     object index = 1;     MapPoint.Waypoint waypoint = route.Waypoints.get_Item(ref index);     //Assign a new location     waypoint.Anchor = newlocation;

You may have noticed that a Waypoint object also exposes the Location property, which returns the Location object that it corresponds to; however, keep in mind that this property is a read-only property, and you cannot change the location using it.

Using the Waypoint object's SegmentPreferences property, you can set the segment preference indicating whether you prefer a shorter route, a quicker route, and so on. This is useful if you have preferences for a segment in a route. This property is of MapPoint.GeoSegmentPreferences type, an enumeration which has the following values:


geoSegmentQuickest

Calculates a route based on the quickest route available between two locations.


geoSegmentShortest

Calculates a route based on shortest distance between two locations.


geoSegmentPreferred

Calculates a route based on the route preferences set using the DriverProfile object at the Route object level (which I will discuss shortly).

The default value is always geoSegmentQuickest, and you can set a different value:

     object index = 2;     MapPoint.Waypoint waypoint = route.Waypoints.get_Item(ref index);     waypoint.SegmentPreferences = MapPoint.GeoSegmentPreferences.geoSegmentShortest;

There is one last concept that you need to understand about waypoints and SegementPreferences; a waypoint represents only one location, but a route segment represents two locations. So, what happens if you set two different segment preferences for each location in a single segment? The answer is that the waypoint (location) at the beginning of the segment always decides the segment's route preference.

Waypoints are categorized into three types:

  • Start point

  • End point

  • Intermediate stop

You can access this information for a given Waypoint object using the Type property. This property is of MapPoint.GeoWayPointType enumeration. This property is useful in determining the type of waypoint when analyzing a route or processing driving directions. You can set a Waypoint's preferred arrival and departure times using the PreferredArrival and PreferredDeparture properties, respectively; MapPoint 2004 uses this information to adjust the itinerary when calculating driving directions. Finally, you can specify a stop time using the StopTime property, which is of Double type and expresses amount of hours as a fraction of a day (24 hours); for example, if you want to stop for 2 hours, you would assign the StopTime:

     waypoint.StopTime = 2/24;

Now that we know how to specify and set waypoints for a route, let's look at how to optimize a route.

2.6.2. Optimizing a Route

You can optimize a route if it has more than one waypoint as an intermediate stop. This is useful if you want to order waypoints (of Intermediate type stops) so that the total distance driven in a route is minimized. To optimize a route, call the Optimize method on the Waypoints collection:

     //Optimize the route     route.Waypoints.Optimize( );

Note that the Optimize method does not alter the start and end points; it reorders only the intermediate stops. If you do not have more than three waypoints, calling this method does not effect on the waypoint order.

You can find out whether a Waypoints collection is optimized by using the WayPoints.IsOptimized property. When the Optimize method is called and a route is successfully optimized, the RouteAfterOptimize event is fired; the following code shows how to wire up this event:

     this.axMappointControl1.RouteAfterOptimize         +=new AxMapPoint._IMappointCtrlEvents_RouteAfterOptimizeEventHandler(                                 axMappointControl1_RouteAfterOptimize);

The following code shows how a simple implementation of this event handler:

     private void axMappointControl1_RouteAfterOptimize(object sender,         AxMapPoint._IMappointCtrlEvents_RouteAfterOptimizeEvent e)     {         //Now display the waypoints in correct order         MyMethodToDisplayCorrectRouteOrder(e.pRoute);     }

You can use this event to record or display the new order of the waypoints.

Remember that calling the Optimize method does not calculate driving directions; it only reorders the intermediate stop waypoints. So, in order to get driving directions, you need to calculate the route as a separate step.

2.6.3. Calculating a Route

You can calculate a route for a given set of waypoints using the Route object's Calculate method:

     //Calculate the route     route.Calculate( );

As you can see, this method does not take any parameters. However, when you call it, you need to make sure that you have at least two waypoints added to the Route object; otherwise an exception is thrown. Additionally, it is important to note that this method also throws an exception when two waypoints are not connected by any routable means. When this method is successfully completed, the RouteAfterCalculate event is fired; this event has several functions, including displaying driving directions, storing route cost into a database, and so on. The following code shows how to wire up the RouteAfterCalculate event:

     this.axMappointControl1.RouteAfterCalculate+=              new AxMapPoint._IMappointCtrlEvents_RouteAfterCalculateEventHandler(                                            axMappointControl1_RouteAfterCalculate);

This code snippet shows a sample implementation of the event handler method:

     private void axMappointControl1_RouteAfterCalculate(object sender,             AxMapPoint._IMappointCtrlEvents_RouteAfterCalculateEvent e)     {         //Display diriving directions         DisplayDrivingDirections(e.pRoute);     }

After calculating driving directions, you can get the detailed instructions from the directions using the Route object's Directions property:

     foreach(MapPoint.Direction direction in route.Directions)     {          . . .     }

The Directions property is a collection of Direction objects. The Direction class has several properties , including driving instructions, starting time, distance, and so forth. Table 2-4 shows some key properties that are exposed on the Direction class.

Table 2-4. Key Properties of the Direction class

Property name

Description

Waypoint

Represents the starting point for the route segment

Distance

Returns the total distance of the current segment

Location

Returns the location that represents the best map view for the current segment

Instruction

Returns the directions text for the current segment

StartTime

Returns the calculated start time for the current segment


Along with these properties, the Direction object also provides the FindNearby method to locate nearby points of interest; since a Direction object connects two locations, FindNearby works as a "find along route" method instead of a finding locations around a specific point. This method is useful in route-planning tasks, such as figuring out where to stop for gas and food along a route.

2.6.4. Personalizing Route Calculations

Personalizing a route is possible with the MapPoint 2004 API using the Route object's DriverProfile property. This property is an instance of the DriverProfile class and can be used to set a preferred start time, end time, speed, road type, and so on. Table 2-5 shows some key properties of the DriverProfile class.

Table 2-5. Key properties for the DriverProfile class

Property name

Description

StartTime

Gets or sets the time to start driving each day

EndTime

Gets or sets the time to end driving each day

Speed

Gets or sets the speed at which the user prefers to drive on different road types


To set preferred roads for your route, use the set_PreferredRoads method to indicate the road type and preference setting on a scale of zero to one (least preferred to most preferred) as follows:

     //Really hate arterial roads     route.DriverProfile.set_PreferredRoads(                             MapPoint.GeoRoadType.geoRoadArterial, 0);     //Prefer Interstates     route.DriverProfile.set_PreferredRoads(                             MapPoint.GeoRoadType.geoRoadInterstate, 1);

Finally, keep in mind that you need to set the driver profile settings before calculating the route.




Programming MapPoint in  .NET
Programming MapPoint in .NET
ISBN: 0596009062
EAN: 2147483647
Year: 2005
Pages: 136
Authors: Chandu Thota

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net