com.esri.arcgis.networkanalyst
Interface INAODCostMatrix

All Superinterfaces:

Serializable

All Known Implementing Classes:

NAODCostMatrixResult

public interface INAODCostMatrix
extends Serializable

Provides access to the OD cost matrix object.

Description

This interface is new at ArcGIS 9.3.

Remarks

The INAODCostMatrix interface provides access to origin-destination cost information associated with a set of NALocation instances.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Method Summary

int	findDestinationIndex(INALocation location, int curbApproach) Finds the destination corresponding to the given network location.
int	findOriginIndex(INALocation location, int curbApproach) Finds the origin corresponding to the given network location.
IStringArray	getCostAttributeNames() The names of the network cost attributes.
double	getDefaultValue(int attributeIndex) The value returned for un-populated matrix enteries.
int	getDestinationCount() The number of destination locations.
int	getDestinationIndexByRank(int originIndex, int rank) For a given origin, retrieves the index of the populated destination for a given rank.
IName	getNetworkDatasetName() The name of the network dataset.
int	getOriginCount() The number of origin locations.
int	getPopulatedDestinationCount(int originIndex) For a given origin, retrieves the number of destinations with populated matrix values.
int	getRankingAttributeIndex() The index of the cost attribute used to rank the populated destinations for each origin.
double	getValue(int originIndex, int destinationIndex, int attributeIndex) Retrieves the cost value for a given origin and destination.
boolean	isAreOriginsIdenticalToDestinations() Indicates if the origin set is identical to the destination set, i.e.
boolean	isHasRankingAttribute() Indicates if the matrix has an attribute for ranking values.
boolean	isPopulated(int originIndex, int destinationIndex) Indicates if the matrix entry for given origin, destination index is populated.
boolean	isSymmetric() Indicates if the matrix has symmetric values.
void	queryPopulatedDestinationIndices(int originIndex, ILongArray[] destinationIndices) For a given origin, retrieves the indices of populated destinations.
void	queryRankedDestinationIndices(int originIndex, ILongArray[] destinationIndices) For a given origin, retrieves the indices of the populated destinations in increasing rank.
void	queryValues(int originIndex, int destinationIndex, IDoubleArray[] values) Retrieves the cost values of all cost attributes for the given origin and destination.

Method Detail

getNetworkDatasetName

IName getNetworkDatasetName()
                            throws IOException,
                                   AutomationException

The name of the network dataset.

Remarks

Returns the IName interface of the underlying network dataset associated with the matrix object.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.system.IName

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCostAttributeNames

IStringArray getCostAttributeNames()
                                   throws IOException,
                                          AutomationException

The names of the network cost attributes.

Remarks

Returns the names of the cost attributes that are present in the matrix object.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A reference to a com.esri.arcgis.system.IStringArray

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getOriginCount

int getOriginCount()
                   throws IOException,
                          AutomationException

The number of origin locations.

Remarks

Returns the number of origin locations associated with the matrix object.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The count

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDestinationCount

int getDestinationCount()
                        throws IOException,
                               AutomationException

The number of destination locations.

Remarks

Returns the number of destination locations associated with the matrix object.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The count

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isAreOriginsIdenticalToDestinations

boolean isAreOriginsIdenticalToDestinations()
                                            throws IOException,
                                                   AutomationException

Indicates if the origin set is identical to the destination set, i.e. that every origin network location also exists as a destination network location.

Remarks

Returns True if the set of origin locations is identical to the set of destination locations in index sequence.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The areIdentical

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isSymmetric

boolean isSymmetric()
                    throws IOException,
                           AutomationException

Indicates if the matrix has symmetric values.

Remarks

Returns True if the INAODCostMatrix.AreOriginsIdenticalToDestinations property returns True and the matrix values are symmetric (i.e., for each cost attribute and each origin-destination pair of locations, the matrix value for traveling from the first location to the second is the same as the value for traveling from the second location to the first).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The isSymmetric

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

findOriginIndex

int findOriginIndex(INALocation location,
                    int curbApproach)
                    throws IOException,
                           AutomationException

Finds the origin corresponding to the given network location.

Remarks

Given a network location and curb approach, this method returns the internal index of a matching origin location. The internal index values range from 0 through INAODCostMatrix.OriginCount - 1. There may be more than one matching origin location, in which case an arbitrary index value is returned.

If a matching origin index cannot be determined, the integer value -1 is returned.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

location - A reference to a com.esri.arcgis.networkanalyst.INALocation (in)

curbApproach - A com.esri.arcgis.networkanalyst.esriNACurbApproachType constant (in)

Returns:

The index

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

findDestinationIndex

int findDestinationIndex(INALocation location,
                         int curbApproach)
                         throws IOException,
                                AutomationException

Finds the destination corresponding to the given network location.

Remarks

Given a network location and curb approach, this method returns the internal index of a matching destination location. The internal index values range from 0 through INAODCostMatrix.DestinationCount - 1. There may be more than one matching destination location, in which case an arbitrary index value is returned.

If a matching destination index cannot be determined, the integer value -1 is returned.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

location - A reference to a com.esri.arcgis.networkanalyst.INALocation (in)

curbApproach - A com.esri.arcgis.networkanalyst.esriNACurbApproachType constant (in)

Returns:

The index

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDefaultValue

double getDefaultValue(int attributeIndex)
                       throws IOException,
                              AutomationException

The value returned for un-populated matrix enteries.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

attributeIndex - The attributeIndex (in)

Returns:

The value

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getPopulatedDestinationCount

int getPopulatedDestinationCount(int originIndex)
                                 throws IOException,
                                        AutomationException

For a given origin, retrieves the number of destinations with populated matrix values.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

originIndex - The originIndex (in)

Returns:

The count

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

queryPopulatedDestinationIndices

void queryPopulatedDestinationIndices(int originIndex,
                                      ILongArray[] destinationIndices)
                                      throws IOException,
                                             AutomationException

For a given origin, retrieves the indices of populated destinations.

Remarks

For a given origin (passed in by index), QueryPopulatedDestinationIndices retrieves the indices of the populated destinations in an ILongArray. "Populated destinations" are the destinations for which a valid network path from the specified origin to the specified destination has been determined.

An origin's index can be retrieved via the FindOriginIndex method.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

originIndex - The originIndex (in)

destinationIndices - A reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isPopulated

boolean isPopulated(int originIndex,
                    int destinationIndex)
                    throws IOException,
                           AutomationException

Indicates if the matrix entry for given origin, destination index is populated.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

originIndex - The originIndex (in)

destinationIndex - The destinationIndex (in)

Returns:

The isPopulated

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isHasRankingAttribute

boolean isHasRankingAttribute()
                              throws IOException,
                                     AutomationException

Indicates if the matrix has an attribute for ranking values.

Remarks

This returns True if the populated destinations for each origin are ranked by their values for some cost attributes. For example, the destinations may be ranked in increasing travel time away from the origin.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The value

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getRankingAttributeIndex

int getRankingAttributeIndex()
                             throws IOException,
                                    AutomationException

The index of the cost attribute used to rank the populated destinations for each origin.

Remarks

If the matrix has a ranking attribute then this returns the index of the cost attribute used to rank the populated destinations for each origin.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The index

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDestinationIndexByRank

int getDestinationIndexByRank(int originIndex,
                              int rank)
                              throws IOException,
                                     AutomationException

For a given origin, retrieves the index of the populated destination for a given rank. The index is returned only if the HasRankingAttribute is true.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

originIndex - The originIndex (in)

rank - The rank (in)

Returns:

The destinationIndex

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

queryRankedDestinationIndices

void queryRankedDestinationIndices(int originIndex,
                                   ILongArray[] destinationIndices)
                                   throws IOException,
                                          AutomationException

For a given origin, retrieves the indices of the populated destinations in increasing rank.

Remarks

For a given origin (passed in by index), QueryRankedDestinationIndices retrieves the indices of the populated destinations in increasing rank as an ILongArray. "Populated destinations" are the destinations for which a valid network path from the specified origin to the specified destination has been determined. The destinations are ranked increasingly from least to greatest total cost of the network path from the origin to the destination.

An origin's index can be retrieved via the FindOriginIndex method.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

originIndex - The originIndex (in)

destinationIndices - A reference to a com.esri.arcgis.system.ILongArray (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getValue

double getValue(int originIndex,
                int destinationIndex,
                int attributeIndex)
                throws IOException,
                       AutomationException

Retrieves the cost value for a given origin and destination. The attribute index is with respect to the array of cost attribute names returned by CostAttributeNames.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

originIndex - The originIndex (in)

destinationIndex - The destinationIndex (in)

attributeIndex - The attributeIndex (in)

Returns:

The value

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

queryValues

void queryValues(int originIndex,
                 int destinationIndex,
                 IDoubleArray[] values)
                 throws IOException,
                        AutomationException

Retrieves the cost values of all cost attributes for the given origin and destination.

Remarks

QueryValues populates an IDoubleArray with the values of all associated cost attributes for a given origin and destination. Each value is the total accumulated cost of travel along the network dataset from the origin to the destination for a specific cost attribute.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

originIndex - The originIndex (in)

destinationIndex - The destinationIndex (in)

values - A reference to a com.esri.arcgis.system.IDoubleArray (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.