function [idnn,idv] = get_nn_idx(idele,npx,ichk)

%GET_NN_IDX Given a linear index into a two-dimensional (2D) square

% matrix, returns a linear index matrix to the nine (9)

% nearest neighbors. The matrix has nine rows and the number

% of columns equal the number of input points.

%

% IDNN = GET_NN_IDX(IDELE,NPX) given the linear index into a

% two-dimensional (2D) square matrix, IDELE, with dimensions

% of NPX by NPX, returns a linear index matrix to the nine (9)

% nearest neighbors, IDNN. IDNN has dimensions of nine by

% the number of elements in the input index.

%

% Edge elements which do not have nine nearest neighbors has

% NaNs for indices to missing nearest neighbors.

%

% [IDNN,IDV] = GET_NN_IDX(IDELE,NPX) returns a logical matrix

% of the same size as IDNN and is true for valid nearest

% neighbors and false for missing nearest neighbors.

%

% IDNN = GET_NN_IDX(IDELE,NPX,ICHK) if ICHK is true, the

% nearest neighbors only includes elements in the input index.

% This is useful for finding nearest neighbors within a region

% of interest (ROI) within the 2D square matrix. By default,

% ICHK is false.

%

% NOTES: 1. Edge elements at the top of the 2D square matrix

% columns do not wrap around to reference elements at

% the bottom and bottom column elements do not wrap

% around and reference elements at the top of the

% column.

%

% 2. Similar to Matlab command conndef(2,'max'), but

% gets linear index to surrounding pixels instead of a

% matrix of ones.

%

% 3. Means and standard deviations of the nearest

% neighbors can be calculated using stat_nan.m. See

% stat_nan.m.

%

% 4. Future version may extend this function to 2D

% rectangular matrices.

%

% 10-Sep-2020 * Mack Gardner-Morse

%

%#######################################################################

%

% Check for Inputs

%

if nargin<2

error(' *** ERROR in GET_NN_IDX: Two inputs are required!');

end

%

if nargin<3

ichk = false; % Nearest neighbors are not confined to input index

end

%

if isempty(ichk)

ichk = false; % Nearest neighbors are not confined to input index

end

%

% Check Size of 2D Matrix and Get Number of Elements in 2D Matrix

%

ndim = size(npx(:),1);

if ndim>2||ndim<1

error([' *** ERROR in GET_NN_IDX: Incorrect number of 2D ', ...

'matrix dimensions!']);

end

%

if ndim==2

npx = npx(1); % Assumes 2D matrix is square

end

%

npx2 = npx*npx; % Maximum index into 2D square matrix

%

% Get Input Linear Index as a Row Vector

%

idele = idele(:)';

npts = size(idele,2);

%

% Get Offsets to All Nearest Neighbors

%

% There are nine (9) nearest neighbors. Similar to Matlab command

% conndef(2,'max'), but gets index offset to surrounding pixels in a

% two-dimensional (2D) image matrix with number of rows "npx".

%

inc = -1:1; % Nearest neighbors including input index

%

ids = [npx npx npx]'*inc;

ids = ids+repmat(inc',1,3);

ids = ids(:);

%

ids = repmat(ids,1,npts);

%

% Add Element Index to Get Index to Element and Neighbors

%

idnn = repmat(idele,9,1)+ids;

%

% Check for Invalid Indices

%

% Elements before first column (<1) or after last column (>npx2).

%

idb1 = idnn(:)<1;

idb2 = idnn(:)>npx2;

%

if any(idb1)

idnn(idb1) = NaN;

end

%

if any(idb2)

idnn(idb2) = NaN;

end

%

% Check Top and Bottom Rows to Prevent Wrap Around

%

toprow = 1:npx:npx2;

itop = ismember(idele,toprow);

if any(itop)

idnn(1:3:9,itop) = NaN;

end

%

botrow = npx:npx:npx2;

ibot = ismember(idele,botrow);

if any(ibot)

idnn(3:3:9,ibot) = NaN;

end

%

% Use Only Nearest Neighbors Within Input Point IDs?

%

if ichk

%

idnc = idnn(:);

idnc = ~ismember(idnc,idele);

idnn(idnc) = NaN;

%

end

%

% Output Logical Matrix to Valid Indices?

%

if nargout>1

idv = ~isnan(idnn);

end

%

return