> **FOCALCURVATURE**
>
> ![](media/image1.png)
>
> ![](media/image2.jpeg){width="3.248611111111111in"
> height="3.2083333333333335in"}
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurve_grid\>)**
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurv_grid\>**
>
> **{-a \<ave_slope_grid\>} {-na \<neg_ave_grid\>}**
>
> **{-pa \<pos_ave_grid\>} {-nc \<neg_count_grid\>}**
>
> **{-pc \<pos_count_grid\>})**
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurve_grid\>**
>
> **{-a \<ave_slope_grid\>} {-na \<neg_ave_grid\>}**
>
> **{-pa \<pos_ave_grid\>} {-nc \<neg_count_grid\>}**
>
> **{-pc \<pos_count_grid\>} RECTANGLE {width} {height})**
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurve_grid\>**
>
> **{-a \<ave_slope_grid\>} {-na \<neg_ave_grid\>}**
>
> **{-pa \<pos_ave_grid\>} {-nc \<neg_count_grid\>}**
>
> **{-pc \<pos_count_grid\>} CIRCLE {radius })**
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurve_grid\>**
>
> **{-a \<ave_slope_grid\>} {-na \<neg_ave_grid\>}**
>
> **{-pa \<pos_ave_grid\>} {-nc \<neg_count_grid\>}**
>
> **{-pc \<pos_count_grid\>} ANNULUS {inner_radius} {outer_radius})**
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurve_grid\>**
>
> **{-a \<ave_slope_grid\>} {-na \<neg_ave_grid\>}**
>
> **{-pa \<pos_ave_grid\>} {-nc \<neg_count_grid\>}**
>
> **{-pc \<pos_count_grid\>} WEDGE {radius} {N, S, E, W})**
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurve_grid\>**
>
> **{-a \<ave_slope_grid\>} {-na \<neg_ave_grid\>}**
>
> **{-pa \<pos_ave_grid\>} {-nc \<neg_count_grid\>}**
>
> **{-pc \<pos_count_grid\>} IRREGULAR \<kernel_file \>)**
>
> **FOCALCURVATURE (\<input_elev_grid\> \<focalcurve_grid\>**
>
> **{-a \<ave_slope_grid\>} {-na \<neg_ave_grid\>}**
>
> **{-pa \<pos_ave_grid\>} {-nc \<neg_count_grid\>}**
>
> **{-pc \<pos_count_grid\>} WEIGHT \<kernel_file \>)**
>
> **For each cell location on an input grid, sum the slope values within
> a specified neighborhood and divides by the number of neighbor cells
> then sends the value to the corresponding cell location on the
> focalcurve grid.**
>
> \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
>
> **Usages**
>
> Each usage listed above specifies a different type or shape of
> neighborhood in which to calculate values. The possible neighborhood
> shapes are the rectangle, circle, annulus, wedge, irregular and
> weighted irregular. Following each keyword are the necessary
> parameters, which further define the shape itself. If no neighborhood
> is specified (as is the case in the first usage), the default
> neighborhood is a 3 x 3 rectangle.
>
> There are five optional output grids:
>
> For the **ave_slope_grid** add the absolute slope values within a
> specified neighborhood and divide by the number of neighbor cells.
>
> For the **neg_ave_grid** add the negative slope values within a
> specified neighborhood and divide by the number of negative slope
> values.
>
> For the **pos_ave_grid** add the positive slope values within a
> specified neighborhood and divide by the number of positive slope
> values.
>
> For the **neg_count_grid** count the negative slope values within a
> specified neighborhood.
>
> For the **pos_count_grid** count the positive slope values within a
> specified neighborhood.
>
> focalcurvature \<input_elev_grid\> \<focalcurve_grid\>
>
> {-a \<ave_slope_grid\>}{-na \<neg_ave_grid\>}{-pa \<pos_ave_grid\>}
>
> {-nc \<neg_count_grid\>}{-pc \<pos_count_grid\>}
>
> {neighborhood size and shape options}
>
> **Arguments**
>
> **\< input_elev_grid \>** an input integer or floating point grid, or
> an expression resulting in a grid, that identifies the values of the
> focal or processing cell and the values of the cells in its specified
> neighborhood. When no neighborhood is specified, the default
> neighborhood is a 3 x 3 rectangle.
>
> **\< focalcurve_grid \>** an output floating point grid resulting from
> adding the slope values within a specified neighborhood and dividing
> by the number of cells in the specified neighborhood minus the center
> cell.
>
> **{-a \<ave_slope_grid\>}** an output floating point grid resulting
> from adding the absolute slope values within a specified neighborhood
> and dividing by the number of cells in the specified neighborhood
> minus the center cell.
>
> **{-na \<neg_ave_grid\>}** an output floating point grid resulting
> from adding the negative slope values within a specified neighborhood
> and dividing by the number of negative slope cells in the
> neighborhood.
>
> **{-pa \<neg_ave_grid\>}** an output floating point grid resulting
> from adding the positive slope values within a specified neighborhood
> and dividing by the number of positive slope cells in the
> neighborhood.
>
> **{-nc \<neg_count_grid\>}** an output floating point grid resulting
> from counting the negative slope values within a specified
> neighborhood.
>
> **{-pc \<pos_count_grid\>}** an output floating point grid resulting
> from counting the positive slope values within a specified
> neighborhood.
>
> **RECTANGLE** - defines the shape of a neighborhood to be a rectangle.
> The x, y position for the processing cell within the neighborhood,
> with respect to the upper-left corner of the neighborhood, is
> determined by the following equations:
>
> x = (width of the neighborhood + 1)/2
>
> y = (height of the neighborhood + 1)/2
>
> If the input number of cells is even, the x and y coordinates are
> computed using truncation.
>
> **{ width }** identifies the number of cells in the grid's x-direction
> that the neighborhood will encompass. If not specified, defaults to 3.
>
> **{ height }** identifies the number of cells in the grid's
> y-direction that the neighborhood will encompass. If not specified,
> defaults to width value.
>
> **CIRCLE** - defines the shape of a neighborhood to be a circle.
>
> **{ radius }** specifies the radius from the center of the processing
> cell that the circle or wedge neighborhood will span. The radius is
> identified in cells measured perpendicular to the x- or y- axis. Any
> cell center encompassed by the circle or wedge will be included in the
> processing of the neighborhood. If not specified, defaults to 2.
>
> **ANNULUS** - defines the shape of a neighborhood to be an annulus.
> The annulus shape comprises one smaller circle within a larger circle
> (a donut shape). Cells that fall outside the radius of the smaller
> circle but inside the radius of the larger circle will be included in
> the processing of the neighborhood.
>
> **{ inner_radius }** specifies the radius of the inner circle of the
> annulus from the center of the processing cell. The radius is
> identified in cells measured perpendicular to the x- or y- axis. Any
> cell center that falls within the radius will not be included in the
> processing of the neighborhood. If not specified, defaults to 1.
>
> **{ outer_radius }** specifies the radius of the outer circle of the
> annulus from the center of the processing cell. The outer circle
> defines the extent of the neighborhood. The radius is identified in
> cells measured perpendicular to the x- or y- axis. Any cell center
> that falls within the radius of the outer circle but outside the
> radius of the inner circle will be included in the processing of the
> neighborhood. If not specified, defaults to 3.
>
> **WEDGE** - defines the shape of a neighborhood to be a wedge. Cells
> that fall within the wedge will be included in the processing of the
> neighborhood.
>
> The wedge shape is created by (1) specifying the radius from the
> center of the processing cell in cells measured perpendicular to the x
> or y axis and (2) identifying the quadrant of the wedge as north (N),
> south(S), east(E) or west(W).
>
> **{ radius }** - specifies the radius from the center of the
> processing cell that the wedge neighborhood will span. The radius is
> identified in cells measured perpendicular to the x- or y- axis. Any
> cell center encompassed by the wedge will be included in the
> processing of the neighborhood. If not specified, defaults to 2.
>
> **{ N, S, E, W }** - specifies the quadrant of the wedge as north (N),
> south (S), east (E) or west (W). If not specified, defaults to east
> (E).
>
> ![](media/image3.wmf)
>
> **IRREGULAR** - allows for specifying an irregularly shaped
> neighborhood around the processing cell. The keyword IRREGULAR also
> defines the manner in which the values of the kernel file will be
> interpreted. The kernel file specifies which cell positions should be
> included within the neighborhood. The values in the kernel file should
> be either '0' or '1' (any value not equal to '0' will be interpreted
> as '1'). A value of '0' for a cell position indicates that the cell is
> not a member of the neighborhood; a value of '1' for a cell position
> indicates that its corresponding cell (and value) is a member of the
> neighborhood.
>
> **\< kernel_file \>** - defines the values and shape of an irregular
> neighborhood. When used with the IRREGULAR keyword any value not equal
> to '0' will identify the cells in a neighborhood that will be used for
> processing.
>
> When the keyword WEIGHT is used, the values of the cell locations
> within each neighborhood on the input grid will be multiplied by the
> values identified in the kernel file.
>
> The kernel file is an ASCII text file in which the first line
> specifies the number of cells in the x-direction, followed by a space
> and the number of cells in the y-direction (or the width and height of
> the neighborhood). The subsequent lines give the values of each
> position in the neighborhood. The values are input in the same
> configuration as appears in the neighborhood they represent. A space
> between each value is necessary.
>
> For a kernel file to be used with the IRREGULAR keyword, a
> neighborhood must be represented by 1s and 0s. The value of '0' (not
> blank spaces) will identify the cells in a neighborhood that will not
> be used for processing. The center cell must have a value of 1.
>
> 5 4
>
> 1 1 1 0 0
>
> 0 1 1 1 1
>
> 0 0 1 1 1
>
> 1 1 1 0 0
>
> When a kernel file is used with the keyword WEIGHT, the number of
> cells along the x and y axes (the width and height of the
> neighborhood) are listed on the first line. All weight values, which
> further define the neighborhood, are listed on subsequent lines. When
> processing the neighborhood of a cell on the input grid, the value at
> each cell position in the neighborhood is multiplied by the value of
> the corresponding cell position in the kernel file. The value of the
> center cell is multiplied by the value of the center cell in the
> kernel file. A '0' within the kernel file is treated like any other
> value in the file: the value of the cell on the input grid is
> multiplied by zero.
>
> 6 6
>
> 3 0 0 0 0 0
>
> 0 3 0 0 0 0
>
> 0 0 3 0 0 0
>
> 0 0 0 3 0 0
>
> 0 0 0 0 3 0
>
> 0 0 0 0 0 3
>
> **WEIGHT** - allows for defining an irregular neighborhood and for
> specifying which weights will be used to multiply the cell values on
> an input grid. See the \<kernel_file\> argument for the specifications
> of the kernel file as it applies to the keyword WEIGHT.
>
> **Notes**

-   The center cell of the neighborhood is considered to be separate
    from other neighborhood cells in all calculations.

-   Regardless of the input grid data type, resultant grid will contain
    floating point values.

-   If the center cell is NODATA, the output cell is NODATA.

-   If a neighborhood cell is NODATA, it does not contribute to the
    calculation of the output center cell.

-   The algorithm for neighborhood processing is as follows:

    Each cell of the input grid is processed using the specified
    neighborhood. A neighborhood cell is considered within a specified
    shape if the center of the neighborhood cell is within the shape.

    If a center cell contains the NODATA value, the output grid cell
    will contain the NODATA value.

    Neighbor cells which contain the NODATA value are ignored. They are
    not counted in the totaling of neighbor cells.

    When the center cell is on the edge of the grid the neighbor cells
    are those which lie within the grid. Neighbor cells which would be
    lying off the grid are considered to contain the NODATA value.

    For each neighborhood cell calculate the rise (value of center cell
    minus value of neighbor cell) and run (horizontal distance between
    the center cell and the neighbor cell).

    The slope is the rise divided by the run.

    When the specified neighborhood does not have a true center cell,
    the center cell location will be determined by dividing the
    even-numbered rows and/or columns by 2 (odd-numbered rows and/or
    columns will always have a center). Thus, for a 6x8 rectangle, the
    center cell will be located at column 3, row 4.

    1 2 3 4 5 6

    1 N N N N N N

    2 N N N N N N N = neighborhood cell

    3 N N N N N N C = center cell

    4 N N C N N N

    5 N N N N N N

    6 N N N N N N

    7 N N N N N N

    8 N N N N N N

    The neighborhood can be weighted using a kernel file. The center
    cell will be multiplied by the center value of the kernel.

    Regardless of the input grid data type, the resultant grid will
    contain floating point values.

-   The algorithm for the focalcurve grid is as follows:

    Accumulate the slope values for all the cells in the neighborhood
    and divide by the number of neighbor cells. Place this value in the
    focalcurve_grid in the same location as the input cell.

-   The algorithm for the ave_slope_grid is as follows:

    Accumulate the absolute slope values for all the cells in the
    neighborhood and divide by the number of neighbor cells. Place this
    value in the ave_slope_grid in the same location as the input cell.

-   The algorithm for the neg_ave_grid is as follows:

    Accumulate the negative slope values for all the cells in the
    neighborhood. Divide the accumulated negative slope by the number of
    negative slope neighbor cells. Place this value in the neg_ave_grid
    in the same location as the input cell. Note that a zero slope is
    not considered as negative or positive.

    If the number of negative slope values is zero, the neg_count_grid
    cell will contain zero. Otherwise all values in the neg_ave_grid
    will be negative.

-   The algorithm for the pos_ave_grid is as follows:

    Accumulate the positive slope values for all the cells in the
    neighborhood. Divide the accumulated positive slope by the number of
    positive slope neighbor cells. Place this value in the pos_ave_grid
    in the same location as the input cell. Note that a zero slope is
    not considered as negative or positive.

    If the number of positive slope values is zero, the pos_ave_grid
    cell will contain zero.

-   The algorithm for the neg_count_grid is as follows:

    Count the negative slope values for all the cells in the
    neighborhood. Note that a zero slope is not considered as negative
    or positive. Place this value in the neg_count_grid in the same
    location as the input cell.

-   The algorithm for the pos_count_grid is as follows:

    Count the positive slope values for all the cells in the
    neighborhood. Note that a zero slope is not considered as negative
    or positive. Place this value in the pos_count_grid in the same
    location as the input cell.

> **Examples**

-   Valid uses of focalcurvature are:

    Arc: focalcurvature \<input DEM grid\> \<output focalcurvature
    grid\>

    Arc: focalcurvature \<input\> \<output\> -a \<output ave. slope
    grid\>

    Arc: focalcurvature \<input\> \<output\> -pc \<output positive slope
    grid\>

    Arc: focalcurvature \<input\> \<output\> rectangle 5 5

    Arc: focalcurvature \<input\> \<output\> circle 8

    Arc: focalcurvature \<input\> \<output\> annulus 3 7

    Arc: focalcurvature \<input\> \<output\> wedge 10 s

    Arc: focalcurvature \<input\> \<output\> irregular \<kernel file\>

    Arc: focalcurvature \<input\> \<output\> weight \<kernel file\>

    Arc: focalcurvature \<input\> \<output\> -nc \<neg. count grid\> -pc
    \<pos. count grid\> -pa \<pos. average grid\> rectangle 10 12

**Examples**

> The Neighborhood Function on an Individual Neighborhood. (Cell width
> 10)
>
> *input_elevation_grid* *focalcurve_grid*
>
> *input_elevation_grid* *average_slope_grid*
>
> *input_elevation_grid* *negative_average_grid*
>
> *input_elavation_grid* *positive_average_grid*
>
> *input_elevation_grid* *negative_count_grid*
>
> *input_elevation_grid* *positive_count_grid*

**The code for the FOCALCURVATURE program was written by Logicon
Geodynamics Services, Inc. under contract with BLM National Applied
Resource Sciences Center (NARSC), under the direction of and based on an
algorithm developed by Jacek S. Blaszczynski, Physical Scientist, BLM
NARSC in 1995-96, and published in Journal of Photogrammetric
Engineering and Remote Sensing, February 1997. The software was
finalized in December, 1998, under sub-contract 02845HLV5S to TRW, Inc.
as part of the Bureau of Land Management Technical Support Services
Contract, N652C5001, task order B814.**