Supported with: ArcGIS Engine with Network Extension, ArcGIS Desktop with Network Analyst, ArcGIS Server with Network Extension

Library dependencies: System, SystemUI, Geometry, Display, Server, Output, GeoDatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, GeoDatabaseDistributed, Carto

The Network Analyst library provides objects for working with network datasets. These objects allow you to perform network analysis in your applications. The following diagram gives you an overview of some of the objects in the Network Analyst library.

The objects that are used to perform network analysis can be categorized in the following subsystems:

• The Network Analysis Layer
• Locating and Loading
• Solvers
• Traversal Results
• Directions
• Server Objects

The Network Analysis Layer

The network analysis layer (NALayer) contains the problem you're trying to solve. It is responsible for holding the problem definition used during analysis. The main objects include NALayer, NAContext, NAClass, NALocationObject, and NAClassDefinition .

The NALayer is the topmost object in this set of objects. It is a true layer, capable of being persisted in ArcMap or on disk and accessed through ArcMap, ArcCatalog, or through Engine or Server. An NALayer is initially created by a solver through a call to INASolver::CreateLayer. The NALayer is the handle that other subsystems (ArcMap, Geoprocessing, ArcCatalog, Engine) use to reference a network analysis problem. From the NALayer it is possible the get the NAContext and the NALayer's sub-layers that reference NAClasses held by the NAContext .

The NAContext object is the most important object in this set of objects. As its name implies, it is the context that everything goes to for information. It has references to everything else that is used as part of the analysis. A context is generally created by calling INASolver::CreateContext on a solver and then binding the context to a network dataset. There are 3 main interfaces, INAContext, INAContextEdit, and INAContextEvents:

• INAContext allows you to access the other important parts of the analysis like the NAClasses, NASolver, NALocator, NetworkDataset, and NATraversalResult.
• INAContextEdit controls the initialization of the NAContext and the transaction methods for editing NAClasses.
• INAContextEvents notifies clients listening to events when the NAContext or NATraversalResult has been modified.

An NAClass is a specialized feature class. It holds features representing such things as Stops, Barriers, Incidents, Facilities, Routes, CFRoutes, SALines, SAPolygons, ODLines, etc. An NAClass's workspace is the NAContext and as such they are considered in-memory feature classes since they do not have a persistent source on disk other than when persisted within a layer file on disk. They can be retrieved in ways like INALayer::LayerByNAClassName(Stops)::FeatureClass or by INAContext::NAClasses::ItemByName(Stops) .

NAClasses serve up NALocationObjects and NALocationFeatures which are rows and features that may implement an additional interface, INALocationObject, which specifies the position where it is located on the network.

The NAClassDefinition object has additional information about the class that is useful to the extension. It is initially set up by the solver when it creates the NAContext and the contained NAClasses. It can be retrieved from the NAClass by calling INAClass::get_ClassDefinition. The NAClassDefinition has methods to determine the minimum/maximum number of rows required by the solver. It also specifies a type for each field, which can be any combination of input, output, not visible, and/or not editable.

You should not modify the NAClassDefinition properties except the CandidateFieldNames.

Locating and Loading

This subsystem represents objects used to load NAClasses representing NALocations such as Stops, Barriers , etc. Loading network locations entails starting with an input point, locating its position on the network by identifying the side and position along a feature in the network dataset, and creating a new feature in an NAClass with this network position information. There are objects that do the locating (NALocator, NALocatorFeatureAgent, NALocatorLocationFieldsAgent) and objects that bulk load into an NAClass based on an NALocator (NAClassLoader, NAClassFieldMap ).

If you have your own method for locating features and populating the NAClass with the appropriate location information, you do not need to utilize the objects in this subsystem to load objects for you.

The NALocation object simply holds where on the network its located. The network location fields are:

• The SourceID is the SourceID of the feature class in the network dataset that the location is on. You can get this ID from INetworkSource::ID.
• The SourceOID is the ObjectID of the feature that the location is on.
• The SideOfEdge is either right side or left side.
• The PosAlong specifies how far along the source feature (in the digitized direction) the network location is located.

A default NALocator is created on the NAContext by the solver when it creates the NAContext. You can access and change the default locator for the NAContext by setting the NALocator property on the INAContextEdit interface.

The NALocator has a series of locator agents. It is the job of the NALocator to iterate through the agents and determine which agent returned the best location. Most likely the agents will be NALocatorFeatureAgents. By default NALocatorFeatureAgents are created for each network dataset source. Currently only esriGeometryPartBoundary, esriGeometryPartMidpoint, and esriGeometryPartEndpoint are supported. The SnapType property specifies where along the geometry to snap to.

The NALocator has a property, SnapTolerance, which specifies the minimum search tolerance used when searching for network locations. If nothing is found within this tolerance, the search tolerance is doubled until a network location is found or the maximum search tolerance specified by MaxSnapTolerance is reached.

INALocator2::GeocodeLocation returns an NALocation based on the input address and address locator specified. INALocator2::ReverseGeocodeLocation returns the text address of an NALocation based on the address locator specified.

The NALocatorLocationFieldsAgent object can be used if the source class already has location fields populated and you wish to use these instead of spatially searching for the location on the network. Using pre-computed network location fields significantly speeds up the loading process.

The NAClassLoader and NAClassFieldMap objects are used together to bulk load INALocationObjects into an NAClass from an input feature class using an NALocator.

Solvers

A solver is a term used to describe an object that performs the actual network analysis. There are currently four solvers distributed with ArcGIS:

• NARouteSolver - This solver finds the best route between multiple stops.
• NAClosestFacilitySolver - This solver finds the best route between incidents and facilities.
• NAServiceAreaSolver - This solver finds what can be traversed within a specified cutoff.
• NAODCostMatrixSolver - This solver finds the minimum cost between origins and destinations.

Since it is the solver that knows what it requires to perform analysis (what type of network locations it needs, what input properties it needs, etc.), it is the job of the solver to create the NAContext and NALayer and to update them if any properties are changed. The general pattern to follow when creating a new analysis is to call INASolver::CreateContext, INASolver::Bind, and then INASolver::CreateLayer.

General solver properties can be set through the interface INASolverSettings such as impedance attribute, restriction attributes, etc. There are specific properties that can be set on each solver to configure how the analysis is performed such as INARouteSolver::FindBestSequence for NARouteSolver, INAClosestFacilitySolver::DefaultCutoff for NAClosestFacilitySolver, etc.

INASolver::Solve() performs network analysis based on the general and specific solver properties and network locations in the NAContext. It returns:

• True if a partial solution has been found (e.g., some stops are unreachable but a partial route exists).
• False if the whole solution has been found.

Additionally, INASolver::Solve(INAContext, IGPMessages, ITrackCancel) returns informational messages in the GPMessages object. Each GPMessage contains a description and may have an naError code. Message types returned are:

• esriGPMessageTypeError when the solve fails (the analysis problem is incorrectly defined or the problem is unsolvable).
• esriGPMessageTypeWarning when a partial solution is found.
• esriGPMessageTypeAbort when the user aborts the analysis by pressing the ESC key.

As output, the solver populates output NAClasses which contain the results of the analysis. The following output NAClasses are populated by the solver when a partial or complete solution is found:

• Routes for NARouteSolver.
• CFRoutes for NAClosestFacilitySolver.
• SALines and/or SAPolygons for NAServiceAreaSolver.
• ODLines for NAODCostMatrixSolver.

The solver may also create an NATraversalResult object accessed through INAResults that holds information about the network elements traversed during analysis. This information is necessary to perform post-processes such as generating driving directions after the route has been computed.

Traversal Results

NARouteSolver, NAClosestFacilitySolver, and NAServiceAreaSolver output an NATraversalResult object that holds the results of the analysis. At its base level, the traversal result can be viewed as three feature classes which hold all the connectivity information about how the network elements were traversed:

• Edges - Includes each edge traversed during analysis. There are fields specifying the FromJunction and the ToJunction.
• Junctions - Includes each junction and input network location traversed.
• Turns - Includes each turn traversed.

These three feature classes return specific types of features that also implement the INATraversalResultElement interface in addition to the normal IFeature and IRow interfaces.

The INAResult interface has methods to get the output properties and the context.

There is a level of indirection in the NATraversalResult. Because of this, you must use methods on the INATraversalResult interface to find the mapping between sources in the traversal result and the corresponding geodatabase or NAClass source.

INATraversalResultQuery is used to traverse from one traversal result element to another. You can call SearchConnected to find the NATraversalResultElement connected to a specific TraversalResultElement. Or, since these are just feature classes, you can get the feature class for all the traversal result elements of a specific type (e.g., edges) and simply open a search cursor on it.

The NATraversalResult is not persisted with the NAContext and it is your responsibility to persist it to an external data structure if this is required.

Directions

Directions read the NATraversalResults to construct driving directions as a post-process to solving the route. You can retrieve the NAStreetDirectionsAgent from INAContext::get_Agents::get_ItemByName("StreetDirectionsAgent"). Once you have the agent, call INAStreetDirectionsAgent::Execute passing in a set of the routes you want directions for and it will generate directions.

Once complete, use the NAStreetDirectionsContainer obtained from INAStreetDirectionsAgent::DirectionsContainer to get the computed directions. Each NAStreetDirections in the NAStreetDirectionsContainer holds the directions for one of the routes specified. You can use INAStreetDirection::String(index) to get the tokenized strings for that direction.

Driving direction can be saved in a XML file by calling INAStreetDirectionsContainer::SaveAsXML(XMLfilename).

Server Objects

The Network Analyst objects all work within the server environment. There are a couple of additional objects and interfaces designed specifically for the server environment. The Network Analyst server objects can be accessed though the GIS Server API, GIS Client, and through a WebService using WSDL.

The NAServer object is a MapServer server object extension that is capable of performing network analysis through a single stateless method call. It is used in conjunction with various NAServerSolverParams and NAServerSolverResults objects.

The general pattern when working with the server objects is:

• Get a reference to an NAServer object either through a MapServer that has an NAServer extension loaded or through an NAServer web service.
• Call INAServer::GetSolverParameters to get the INAServerSolverParams object holding the default parameters.
• Set properties on the NAServerSolverParams object to configure how you want the analysis to be performed.
• Set network locations (e.g., Stops) to use in the analysis.
• Call INAServer::Solve passing in the INAServerSolverParams object.
• Use the returned NAServerSolverResults object to get at the results of the analysis.

All NAServerSolverParams objects support INAServerSolverParams and INASolverSettings. The INAServerSolverParams interface allows you to specify general properties such as the MaxSnapTolerance, ReturnMap, and OutputSpatialReference. There are also specific interfaces for each type of solver. For example, NAServerRouteParams also supports INAServerRouteParams and INARouteSolver.

The network location properties on the various NAServerSolverParams objects (for example Stops, Barriers, Facilities, and Incidents) are of type INAServerLocations. The INAServerLocations interface is the base interface of two other more specialized interfaces:

• The INAServerPropertySets interface provides access to an array of PropertySet objects. Each PropertySet represents a network location. Each property name and value represent a field name and value.
• The INAServerRecordSet interface provides access to a RecordSet object representing network locations.

INAServer::Solve performs network analysis based on the NAServerSolverParams object (NAServerRouteParams, NAServerClosestFacilityParams, NAServerServiceAreaParams) that was passed in and returns its output through an NAServerSolverResults object (NAServerRouteResults, NAServerClosestFacilityResults, NAServerServiceAreaResults).

INAServerSolverResults provides methods on an NAServerSolverResults object (NAServerRouteResults, NAServerClosestFacilityResults, NAServerServiceAreaResults) returned by the Solve method on INAServer to retrieve the results of the network analysis. For example, there is a method to get the MapImage which will be populated if INAServerSolverParams::ReturnMap was set to True.

Different solvers return different NAServerSolverResults objects. For example, the results of route analysis will be an NAServerRouteResults object that supports the INAServerSolverResults and INAServerRouteResults interfaces.

Using Network Analyst in a server environment without NAServer

It is possible to create an application that bypasses NAServer and accesses the fine-grained Network Analyst objects on the server directly. When doing so, it is important to manage the state of the Network Analyst objects so other sessions aren't affected by changes to the objects. The NAContext can be serialized in order to store all Network Analyst state information from one request to the other. For example, once you have a route displayed on the map, you will want to continue to display that route even after the map has been panned or zoomed. For each request to your application, a process occurs to retrieve, store, copy or apply, serialize, and finally restore the NAContext which has this information. Typically, during each use of a map server object, i.e., each request from the Web browser, the following steps take place for each Network Analyst layer that you are working with.

There is an interface INALayer2 on the NALayer object that can be used within server applications to help manage the state of an NALayer between sessions if it is necessary to use the fine grain network analyst objects. You do not need to use this if you are using NAServer. The general pattern is as follows:

• Use INALayer::CopyContext to make a copy of the server's NALayer's NAContext. This is your local copy of the context that only your session will use.
• Prior to performing any network analysis, apply your local NAContext using INALayer::AttachContext. This will be used to attach the server's NALayer to the NAContext specified.
• Set properties and call methods on any of the fine grain network analysis objects. You can also call methods that draw, perform spatial searches, or anything else that requires your NAContext be attached to the server's NALayer.
• When done with the web request, restore the NALayer's original NAContext by calling INALayer::AttachContext passing in the original NAContext.