ArcObjects Library Reference (SpatialAnalyst)  

IDistanceOp2.PathDistance Method

Calculates for each cell the least-accumulative-path distance over a path surface to a source cell or a set of source cells.

[Visual Basic .NET]
Public Function PathDistance ( _
    ByVal sourceData As IGeoDataset, _
    [ByRef costRaster As Object], _
    [ByRef surfaceRaster As Object], _
    [ByRef horizRaster As Object], _
    [ByRef horizFactor As Object], _
    [ByRef vertRaster As Object], _
    [ByRef vertFactor As Object], _
    [ByRef maxDistance As Object], _
    [ByRef valueRaster As Object] _
) As IGeoDataset
[C#]
public IGeoDataset PathDistance (
    IGeoDataset sourceData,
    ref object costRaster,
    ref object surfaceRaster,
    ref object horizRaster,
    ref object horizFactor,
    ref object vertRaster,
    ref object vertFactor,
    ref object maxDistance,
    ref object valueRaster
);
[C#]

Optional Values

costRaster   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
surfaceRaster   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
horizRaster   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
horizFactor   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
vertRaster   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
vertFactor   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
maxDistance   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
valueRaster   To indicate that this parameter is undefined, first define a variable object Missing = Type.Missing; then pass this in as ref Missing.
[C++]
HRESULT PathDistance(
  IGeoDataset* sourceData,
  VARIANT* costRaster,
  VARIANT* surfaceRaster,
  VARIANT* horizRaster,
  VARIANT* horizFactor,
  VARIANT* vertRaster,
  VARIANT* vertFactor,
  VARIANT* maxDistance,
  VARIANT* valueRaster,
  IGeoDataset** distance
);
[C++]

Parameters

sourceData [in]

  sourceData is a parameter of type IGeoDataset

costRaster [optional]
  costRaster is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

surfaceRaster [optional]
  surfaceRaster is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

horizRaster [optional]
  horizRaster is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

horizFactor [optional]
  horizFactor is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

vertRaster [optional]
  vertRaster is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

vertFactor [optional]
  vertFactor is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

maxDistance [optional]
  maxDistance is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

valueRaster [optional]
  valueRaster is a parameter of type VARIANT

  To indicate this parameter is undefined pass a reference to a VARIANT with type VT_ERROR and scode value of DISP_E_PARAMNOTFOUND.

distance [out, retval]

  distance is a parameter of type IGeoDataset

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires Spatial Analyst Extension.

Remarks

sourceData

An input Raster, RasterDataset, RasterBand, or RasterDescriptor that identifies those cells to which the least accumulated cost distances for every cell is calculated

The input value types can be either integer, string type or floating-point type

[costRaster]

An input Raster, RasterDataset, RasterBand, or RasterDescriptor defining the impedance or cost to move planimetrically through each cell

The value at each cell location represents the cost per unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution (while also compensating for diagonal movement) to obtain the total cost of passing through the cell. The values on the costRaster can be integer or floating point, but they cannot be negative (you cannot have a negative cost).

[surfaceRaster]

A raster identifying the z values at each cell location." " The values are used to calculate the actual surface distance that will be covered when passing between cells.

[horizRaster]

A raster defining the horizontal direction at each cell

[horizFactor]

Defines the relationship between the horizontal cost factor and the horizontal relative moving angle (HRMA)." " The input parameter may be one of several keywords (and modifiers) identifying a defined horizontal factor graph or an ASCII file that creates a custom graph. The graphs are used to identify the horizontal factor that will be used in calculating the total cost for moving into a neighboring cell. If the parameter is used with any modifier, the string must be double quoted.

The format for the horizontal parameter is:

"keyword {modifier_1 ... modifier_n}"

Spaces must be used to separate the keyword and modifiers.

The format for the horizontal parameter modifiers is:

modifier_name=value or table_name

There is an equal sign (=) between the modifier name and its value, but there are no spaces between any of the three.

If no keyword is specified, the default horizontal parameter is BINARY.

Two acronyms are used in the explanations of the horizontal factor keywords and modifiers:

HF stands for the horizontal factor defining the horizontal difficulty that is encountered in moving from one cell to the next.

HRMA stands for the horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction.

Horizontal-factor keywords

BINARY - indicates that if the HRMA is less than the cut angle, the HF is set to the value associated with the zerofactor; otherwise, it is infinity.

FORWARD - establishes that only forward movement is allowed. The HRMA must be greater or equal to 0 and less than 90 (0 <= HRMA < 90). If the HRMA is greater than 0 and less than 45 degrees, the HF for the cell is set to the value associated with the zerofactor. If the HRMA is greater than or equal to 45 degrees, then the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity.

LINEAR - defines that the HF is a linear function of the HRMA.

INVERSE_LINEAR - specifies that the HF is an inverse linear function of the HRMA.

TABLE - identifies that an ASCII file will be used to define the horizontal-factor graph used to determine the HFs. The name of the table is entered as a modifier after a blank space following the keyword.

Modifiers to the horizontal keywords

ZEROFACTOR - establishes the horizontal factor to be used when the HRMA is 0. This factor positions the y-intercept for any of the horizontal-factor functions.

CUTANGLE - defines the HRMA angle beyond which the HF will be set to infinity.

SLOPE - establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR horizontal-factor keywords. The slope is specified as a fraction of rise over run (i.e., 45 percent slope is 1/45, which is input as 0.02222).

SIDEVALUE - establishes the HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees for the FORWARD horizontal-factor keyword that is specified.

table_name - identifies the name of the ASCII table defining the HF. It is used in conjunction with the TABLE horizontal-factor keyword.

Default Values for Horizontal Factor Modifiers

Keywords         Zerofactor          Cutangle          Slope          Sidevalue
Binary               1.0                 45              -                -
Forward              0.5                 45(fixed)       -               1.0
Linear               0.5                 181            1/90              -
Inverse_linear       2.0                 180           -1/90              -

[vertRaster]

A raster defining the z value for each cell

[vertFactor]

Defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA)
The input parameter may be one of several keywords (and modifiers) identifying a defined vertical factor graph or an ASCII file creating a custom graph. The graphs are used to identify the vertical factor that will be used in calculating the total cost for moving into a neighboring cell. If the parameter is used with any modifier, the string must be double quoted. The format for the vertical parameter is:

"keyword {modifier_1 ... modifier_n}"

Spaces must be used to separate the keyword and modifiers.

The format for the vertical parameter modifiers is:

modifier_name=value or table_name

There is an equal sign (=) between the modifier name and its value, but there are no spaces between any of the three.

If no keyword is specified, the default vertical parameter is SEC.

Two acronyms are used in the explanations of the vertical-factor keywords and modifiers:

VF stands for the vertical factor defining the vertical difficulty that is encountered moving from one cell to the next.
VRMA stands for the vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell.

Vertical-factor keywords

BINARY - specifies that if the VRMA is greater than the low-cut angle and less than the high-cut angle then the VF is set to the value associated with the zerofactor; otherwise, it is infinity.

LINEAR - indicates that the VF is a linear function of the VRMA.

SYM_LINEAR - defines that the VF is a linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis.

INVERSE_LINEAR - indicates that the VF is an inverse linear function of the VRMA.

SYM_INVERSE_LINEAR - identifies that the VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis.

COS - defines the VF as the cosine-based function of the VRMA.

SEC - identifies the VF as the secant-based function of the VRMA.

COS-SEC - indicates that the VF is the cosine-based function of the VRMA when the VRMA is negative and the secant-based function of the VRMA when the VRMA is nonnegative.

SEC-COS - specifies that the VF is the secant-based function of the VRMA when the VRMA is negative and the cosine-based function of the VRMA when the VRMA is nonnegative.

TABLE - identifies that an ASCII file will be used to define the VFs. The name of the table is entered as a modifier after a blank space following the keyword.

Modifiers to the vertical-factor keywords

ZEROFACTOR - establishes the vertical factor to be used when the VRMA is 0. This factor positions the y-intercept of the specified function. By definition, the zerofactor is not applicable to any of the trigonometric vertical functions (COS, SEC, COS_SEC, or SEC_COS). The y-intercept is defined by these functions.

LCUTANGLE - defines the VRMA angle below which the VF will be set to infinity.

HCUTANGLE - defines the VRMA angle above which the VF will be set to infinity.

SLOPE - establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR vertical-factor keyword. The slope is specified as a fraction of rise over run (e.g., 45 percent slope is 1/45, which is input as 0.02222).

table_name - identifies the name of the ASCII file defining the VF. It is used in conjunction with the TABLE vertical-factor keyword.

Default Values for Vertical Factor Modifiers

Keywords                    Zerofactor     Lcutangle     Hcutangle     Slope     Cospower     Secpower
Binary                          1.0           -30            30          -           -           -
Linear                          1.0           -90            90         1/90         -           -
Sym_linear                      1.0           -90            90         1/90         -           -
Inverse_linear                  1.0           -45            45        -1/45         -           -
Sym_inverse_linear              1.0           -45            45        -1/44         -           - 
Cos                              -            -90            90          -          1.0          - 
Sec                              -            -90            90          -           -          1.0
Cos_sec                          -            -90            90          -          1.0         1.0
Sec_cos                          -            -90            90          -          1.0         1.0

[maxDistance]

Defines the threshold that the accumulative cost values cannot exceed

If an accumulative cost distance value exceeds the maxDistance, the output value for the cell location will be NoData. The maxDistance defines the extent which the accumulative cost distances are calculated. If no maxDistance is specified the distance will be to the edge of the output raster. The data type for maxDistance can be either integer or floating point.

[valueRaster]

An optional input Raster that identifies the zone values that should be used for each cell on the sourceData

The value defined by the valueRaster for each source cell will be assigned to all cells that will be allocated to the source cell in the cost allocation computations. If no valueRaster is specified, the zone value for a source cell is the value on the sourceData.

This parameter is particularly important if the sourceRaster was created by the ILogicalOp::Test or a ILogicalOp::Boolean methods that will only output 1 and 0 or if alternative values or zones are to be used instead of the existing ones, on the input source. The data type for the valueRaster can be any Raster object that supports IGeoDataset (e.g., Raster, Raster band, etc.)

 

See Also

IDistanceOp2 Interface