NEIGHBORS Function
Standard Library function that finds the neighbors of specified array elements.
enabled.
Usage
result = NEIGHBORS(a, i)
Input Parameters
a—An array of n dimensions.
i—An m-element vector of m one-dimensional indices into a.
Returned Value
result—An (m,*) array of one-dimensional indices into a: result(j,*) contains i(j) and its neighbors.
Keywords
K—A positive integer (less than or equal to n) defining connectivity. Two array cells are neighbors if they share a common boundary point, and if their centroids are within ÖK of each other. The default is K = 1, which implies neighbors share a common face.
Dims—If Dims is set to any scalar then the first argument, a, which is normally an array, should instead be a vector of dimensions for an array. Sometimes it useful to find connections within a virtual array, and since connections are functions only of index-coordinates and array dimensions, the Dims keyword allows them to be computed without actually creating an array. Dims is not set by default.
Discussion
In an ND array it is often useful to identify the set of array elements which are connected to another set of array elements. NEIGHBORS indentifies such connections. The connectivity definition represents the array as a collection of unit N-cubes, and by default connected array cells share a common face; that is, their centroids are within unit distance of each other. Higher values of keyword K relax the definition of connectivity. In a 3D array for example, K=2 admits both face-wise and edge-wise connectivity, and K=3 admits face-wise, edge-wise, and corner-wise connectivity. It is sometimes useful to establish connections within a virtual array, and since connectivity is a function only of index-coordinates and array dimensions, the Dims keyword provides a way to supply array dimensions without actually creating an array.
Examples
In this example create and print a 2D array in which each value is equal to its 1D index. This makes it easy to visually identify the neighbors of any given array element. The second printout shows neighbors of the elements denoted by 1D indices i=[0,4,26,47,71]. Row j contains i(j) and the 1D indices of its 4 nearest neighbors. This is easiest to see for i(2)=26 since it is the only 1D index in i which lies in the interior of the data matrix. The other indices in i lie on edges or corners in order to show how they are handled, and essentially they are handled in the same way as interior points, except that neighboring 1D indices which would be out-of-bounds are simply trunctated to their nearest in-bounds neighbors. The last printout again shows the same problem, but this time with the effect of increasing neighborhood radius to sqrt(2); now not only are the 4 nearest neighbors included but so too are the 4 diagonal-neighbors.
a = INDGEN(8, 9)
PM, a
; PV-WAVE prints:
; 0 8 16 24 32 40 48 56 64
; 1 9 17 25 33 41 49 57 65
; 2 10 18 26 34 42 50 58 66
; 3 11 19 27 35 43 51 59 67
; 4 12 20 28 36 44 52 60 68
; 5 13 21 29 37 45 53 61 69
; 6 14 22 30 38 46 54 62 70
; 7 15 23 31 39 47 55 63 71
PM, FIX(NEIGHBORS(a, [0, 4, 26, 47, 71]))
; PV-WAVE prints:
; 0 0 0 1 8
; 4 3 4 5 12
; 18 25 26 27 34
; 39 46 47 47 55
; 63 70 71 71 71
PM, FIX(NEIGHBORS(a, [0, 4, 26, 47, 71], K=2))
; PV-WAVE prints:
; 0 0 1 0 0 1 8 8 9
; 3 4 5 3 4 5 11 12 13
; 17 18 19 25 26 27 33 34 35
; 38 39 39 46 47 47 54 55 55
; 62 63 63 70 71 71 70 71 71
Output
0 8 16 24 32 40 48 56 64
1 9 17 25 33 41 49 57 65
2 10 18 26 34 42 50 58 66
3 11 19 27 35 43 51 59 67
4 12 20 28 36 44 52 60 68
5 13 21 29 37 45 53 61 69
6 14 22 30 38 46 54 62 70
7 15 23 31 39 47 55 63 71
0 0 0 1 8
4 3 4 5 12
18 25 26 27 34
39 46 47 47 55
63 70 71 71 71
0 0 1 0 0 1 8 8 9
3 4 5 3 4 5 11 12 13
17 18 19 25 26 27 33 34 35
38 39 39 46 47 47 54 55 55
62 63 63 70 71 71 70 71 71
