This topic deals with:
Neighbourhood operations are a special spatial analysis in ILWIS. They are calculations on pixels in which the outcome depends on the neighbouring pixels. Neighbourhood operations may be performed on user-selected pixels as well as on whole maps. Just as in filtering procedures, neighbourhood operations make use of a filter. This window of 3 by 3 cells is moved over the raster map. Each cell of the output map is calculated according to the specified neighbourhood expression. The cell numbers in the moving window are coded as follows:
| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 7 | 8 | 9 |
Fig. 1: The 3x3 neighbourhood matrix with the identifiers for the positions of the neighbour pixels (1, 2, 3, 4, 6, 7, 8, 9) with respect to a central pixel (5).
This means that the left neighbour of the central pixel is coded number 4 and the lower right pixel number 9. By definition the central pixel itself is included and has value 5. The result of the calculation is stored in the central pixel.
Note:
If a neighbourhood operation is performed on a pixel on the top or bottom line or on the very first or last column of a raster map, new neighbours are created by duplicating this boundary line or column. In the case of the neighbour position variable: NBPOS, the outer lines or rows added will have value 0.
Neighbourhood expressions have to be typed on the command line of the Main window, like MapCalc formulas.
1. Calculating with the value of a single neighbour:
The simplest neighbourhood expression retrieves the value of a single user-selected neighbour:
Syntax
Outmap = Map#[Neighbour]
where:
Outmap |
is the name of the output raster map. |
Map# |
is the syntax to specify the name of the input raster map Map over which a neighbourhood matrix will be moved. |
[Neighbour] |
is the syntax to select a single neighbour from the map over which the neighbourhood matrix is moved. Neighbour is a number between 1 and 9 which indicates the position of a certain pixel in the neighbourhood matrix as numbered as in Figure 1; the value of the selected neighbour will be retrieved. In fact, for Neighbour, any expression may be used that results in a number between 1 and 9. |
Notes:
Examples:
The following examples show how you can calculate altitude differences in X and Y directions using neighbourhood expressions in their simplest form. Maps DX and DY are the output maps; a Digital Elevation Model (DEM) is used as input map.
DX = DEM#[4] - DEM#[6]
DEM |
DX |
||||||||||||||||||||||||||||||||
|
|
In words: subtract the value of the neighbour to the right of the central pixel (i.e. neighbour pixel on position 6) from the value of the neighbour to the left of the central pixel (i.e. neighbour pixel on position 4) and store the result in the central pixel in output map DX.
DY = DEM#[2] - DEM#[8]
DEM |
DY |
||||||||||||||||||||||||||||||||
|
|
In words: subtract the value of the neighbour below the central pixel (i.e. neighbour pixel on position 8) from the value of the neighbour above the central pixel (i.e. neighbour pixel on position 2) and store the result in the central pixel in output map DY.
2. Using neighbourhood functions on multiple neighbours:
This paragraph deals with neighbourhood functions. A neighbourhood function can calculate with all values found by a neighbourhood matrix, or only with the values of some selected neighbours in the matrix.
Syntax
Outmap = NbFunction(NbExpression)
Outmap = NbFunction[neighbour, neighbour, ...](NbExpression)
where:
Outmap |
is the name of the output raster map. |
|
NbFunction |
is a neighbourhood function to be used on the values as found by a neighbourhood matrix. The available functions are: NBMIN, NBMAX, NBAVG, NBSUM, NBPRD, NBSTD, NBCNT, NBMINP, NBMAXP, NBPRDP and NBCNDP. For more information, see the list of Available neighbourhood functions below. |
|
[neighbour, neighbour, ...] |
||
|
in case the neighbourhood function is followed by a list of neighbours [neighbour, neighbour, ...], then the neighbourhood function will only work on the values of these selected neighbours. As in the paragraph 'Calculating with the value of a single neighbour', neighbour is a number between 1 and 9 which indicates the position of a certain pixel in the neighbourhood matrix (refer to Figure 1). For certain combinations of specific neighbours, the [neighbour, neighbour, ...] syntax can be simplified, see Aliases for specific multiple neighbours below. |
|
(NbExpression) |
is a neighbourhood expression: a neighbourhood expression is any expression which contains the name(s) of the input map(s) and which contains at least one neighbour operator #.
NbExpression may read for instance:
|
|
Map# |
a neighbourhood matrix will move over input map Map; the values of all neighbours found by the matrix will be 'retrieved'. The neighbourhood function will then return the minimum, maximum, average, sum, etc. of these values. |
|
Map# > 40 |
a neighbourhood matrix will move over input map Map; the values of the neighbours found by the matrix will be 'retrieved' when a neighbour has a value greater than 40. The neighbourhood function will then return the minimum, maximum, average, sum, etc. of these values. |
NbFunction, list of available neighbourhood functions:
|
returns the smallest value of the values found by a neighbourhood matrix. |
|
|
returns the largest value of the values found by a neighbourhood matrix. |
|
|
returns the average value of the values found by a neighbourhood matrix. |
|
|
returns the sum of the values found by a neighbourhood matrix; neighbours that have value Undefined are ignored; when all neighbours and the central pixel have value Undefined, value 0 is returned. |
|
|
returns the predominant value of the values found by a neighbourhood matrix. |
|
|
returns the standard deviation of the values found by a neighbourhood matrix. |
|
|
counts the number of neighbour pixels, as found by a neighbourhood matrix, which do NOT have value Undefined nor value False. |
|
|
returns the position of the neighbour that has the smallest value (i.e. as a number between 1 and 9); when multiple neighbour pixels have the same smallest value, then the precedence is: central pixel number 5, and then 1, 2, 3, 4, 6, 7, 8, 9. |
|
|
returns the position of the neighbour that has the largest value (i.e. as a number between 1 and 9); when multiple neighbour pixels have the same largest value, then the precedence is: central pixel number 5, and then 1, 2, 3, 4, 6, 7, 8, 9. |
|
|
returns the position of the neighbour with the predominant value (i.e. as a number between 1 and 9); when multiple neighbour pixels have this predominant value, then the precedence is: central pixel number 5, and then 1, 2, 3, 4, 6, 7, 8, 9. |
|
|
returns the position of the neighbouring pixel for which the outcome of a certain condition is NOT Undefined nor False (thus returns a number between 1 and 9); when multiple neighbour pixels satisfy the condition, then the precedence is: central pixel number 5, and then 1, 2, 3, 4, 6, 7, 8, 9; when none of the neighbours satisfies the specified condition the outcome value is undefined. |
Aliases for specific multiple neighbours:
Instead of specifying a list of neighbours as [neighbour, neighbour, ...], you may use a shorter syntax for some combinations of specific neighbours.
|
Regular syntax |
Alias |
Explanation |
|
NbFunction[2,4,6,8] |
NbFunction4 |
to calculate only with the neighbours on positions 2, 4, 6, 8 and thus excluding the central pixel, use NbFunction with suffix 4, e.g. NBAVG4. |
|
NbFunction[2,4,5,6,8] |
NbFunction5 |
to calculate only with the neighbours on positions 2, 4, 5, 6, 8 and thus including the central pixel, i.e. the 4-connected pixels, use NbFunction with suffix 5, e.g. NBAVG5. |
|
NbFunction[1,2,3,4,6,7,8,9] |
NbFunction8 |
to calculate only with the neighbours on positions 1, 2, 3, 4, 6, 7, 8, 9 and thus excluding the central pixel, use NbFunction with suffix 8, e.g. NBAVG8. |
Examples
NBMIN Example:
OutMap = NBMIN(InMap#)
In words: return the minimum value of each 9 values found by a neighbourhood matrix which moves over InMap.
NBMAX Example:
OutMap = NBMAX(InMap#)
In words: return the maximum value of each 9 values found by a neighbourhood matrix which moves over InMap.
NBAVG Examples:
OutMap1 = NBAVG(InMap#)
In words: calculate the average of each 9 values found by a neighbourhood matrix which moves over InMap.
Note:
Using this function is the same as using the AVG3X3 filter in the Filter operation.
OutMap2 = NBAVG[2,4,5,6,8](InMap#)
OutMap2 = NBAVG5(InMap#)
In words: calculate the average of the values of the neighbours on position 2, 4, 5, 6 and 8 (i.e. the 4-connected pixels) as found by a neighbourhood matrix which moves over InMap.
NBSUM Examples:
OutMap = NBSUM(InMap#)
In words: return the sum of the values found by a neighbourhood matrix which moves over InMap.
OutMap = NBSUM(InMap#)/9
In words: return the sum of the values found by a neighbourhood matrix and divide the sum by the number of neighbours (i.e. return the mean of the pixel values of all neighbours).
OutMap = NBSUM[2,4,5,6,8](InMap#)/5
OutMap = NBSUM5(InMap#)/5
In words: return the mean of the pixel values of all 4-connected neighbours.
NBPRD Example:
OutMap = NBPRD(InMap#)
In words: return the predominant value of all neighbour pixel found by a neighbourhood matrix which moves over InMap.
NBSTD Example:
OutMap = NBSTD(InMap#)
In words: return the standard deviation of the values found by a neighbourhood matrix which moves over InMap.
NBCNT Examples
OutMap1 = NBCNT(InMap1#)
In words: count the number of neighbour pixels, as found by a neighbourhood matrix that moves over InMap1, which do NOT have an undefined value.
An area is considered to be flat when in the moving window of 3 by 3 pixels all pixels have the same value. By using one of the following expression you can check which pixels have 8 neighbours with the same altitude as the central pixel.
Flat = NBCNT(DEM#=DEM)=9
In words: return True in map Flat if all pixels examined by the neighbourhood matrix moving over map DEM (Dem#) have the same value (=9) as the central pixel in that map DEM. This expression can be used to identify flat areas in your Digital Elevation Model (DEM). You may wish to add additional contour lines inside the flat areas and perform the Contour Interpolation operation again to improve your DEM.
Flat = NBCNT(DEM#=DEM)=8
In words: return True in map Flat if 8 of the 8 selected neighbours in map DEM have the same value as the central pixel in map DEM.
Streams = NBCNT(DEM#>DEM)>=5
In words: return True in map Streams if 5 or more of all neighbour pixels in map DEM have a value greater than the central pixel.
Streams2 = IFF(NBCNT(DEM#>DEM)>=5,NBMAXP(DEM#),?)
In words: return the position of the neighbour that has the largest value in map Streams if 5 or more of all neighbour pixels in map DEM have a value greater than the central pixel. Return undefined if less than 5 of all neighbour pixels in map DEM have a value greater than the central pixel.
NBMINP Examples
Aspect = NBMINP(DEM#)
In words: return in map Aspect, the position of the neighbour with the smallest value of each 9 values as found by a neighbourhood matrix which moves over map DEM. The returned position will be a value between 1 and 9; these values can be interpreted as the aspect of the slopes in your Digital Elevation Model (DEM). For more information, refer to How to calculate a classified aspect map.
Pit = NBMINP(DEM#)=5
In words: return True in map Pit if the central pixel has the smallest value of all neighbour pixels as found by a neighbourhood matrix which moves over DEM.
Note:
This expression can be used to identify local pits in your Digital Elevation Model (DEM).
NBMAXP Example
OutMap = NBMAXP(InMap#)
In words: return the position of the neigbour that has the largest value as found by a neighbourhood matrix which moves over InMap.
NBPRDP Example
OutMap = NBPRDP(InMap#)
In words: return the position of the neighbour with the predominant value as found by a neighbourhood matrix which moves over InMap.
NBCNDP Examples
OutMap = NBCNDP(InMap#)
In words: return the position of the neighbouring pixel for which the outcome is NOT undefined nor False.
Notes:
OutMap = NBCNDP(InMap#>20)
In words: return the position of the neighbouring pixel for which the outcome of a certain condition (i.e. pixel value > 20) is not undefined nor False.
3. Using predefined neighbourhood variables
This paragraph treats the neighbourhood variables NBDIS, NBPOS, and NBFLT(fltname) and their syntax. NBDIS, NBPOS and NBFLT can only be used in combination with NbFunction and NbExpression as described above.
|
returns the distance between the central pixel and its neighbouring ones. Notes:
Tip: NBDIS is generally multiplied by the pixel size of a raster map or a georeference, for instance like: NBDIS * PIXSIZE(RasterMap) or NBDIS * PIXSIZE(GeoReference.grf). |
|||||||||||||||||||||||
|
returns the position of a neighbour in the neighbourhood expression. Note: NBPOS and %P are aliases of each other.
|
|||||||||||||||||||||||
|
NBFLT (FltName) |
applies a linear 3x3 filter on the values found by a neighbourhood matrix where FltName is one of the system filters: AVG3x3, EDGESENH, etc. or a user-defined filter. |
Examples
NBDIS Example
See How to calculate distances using iterations.
NBPOS Example
Ridges = NBCNT8(10-Aspect#=NBPOS)
Calculate for each pixel the number of neighbour pixels for which the aspect is in the direction of the central pixel. A result of zero indicates a ridge or a flat area.
NBFLT Example
OUT = NBSUM(Map1# * NBFLT(Edgesenh))
Apply the edge enhancement filter on input map Map1 and sum the values of each neighbourhood matrix (same as using the edge enhancement filter in the Filter operation).
Iterations are a special type of calculations. They are a successive repetition of a mathematical operation, using the result of one calculation as input for the next one.
The calculation stops when the difference of the output compared to the input is negligible or if the number of iterations is reached as previously defined. Iterations are often used in combination with neighbourhood operations. Such an application might be for instance the selection of an item or area which fits a certain condition, starting from one pixel.
Iteration expressions can directly be typed on the command line of the Main window, or in the Iteration : dialog box.
Syntax
MAPITER(StartMap, IterExpr)
MAPITER(StartMap, Iterexpr, Nr of Iterations)
where:
MAPITERPROP(StartMap, IterExpr)
MAPITERPROP(StartMap, IterExpr, Nr of
Iterations)
where:
After each iteration ILWIS shows the number of changed pixels. This number is the total of changes after performing one iteration in all directions (up, down, right and left).
Examples
Examples on using iterations are presented in How to calculate distances using iterations and How to calculate flooded area and water volume after construction of a dam.
See also: