%findNodes - Find nodes in a specified region
%   N = findNodes(MSH, SEARCHMETHOD, SEARCHPARAMETERS,...) finds nodes in a 
%   region specified by SEARCHMETHOD and SEARCHPARAMETERS.
%
%   The findNodes function supports the following search methods:
%   'region'  - Finds nodes in a geometric region specified by REGIONPARAMETERS
%   'box'     - Finds nodes in a box specified by BOXPARAMETERS
%   'radius'  - Finds nodes in a circle/sphere specified by RADIUSPARAMETERS
%   'nearest' - Finds nodes nearest to query points specified by NEARESTPARAMETERS
%
% Input Arguments
% ---------------
%   SEARCHMETHOD:
%     'region', 'box', 'radius', 'nearest'
%   
%   The SEARCHPARAMETERS corresponding to the SEARCHMETHOD are as follows:
% 
%   REGIONPARAMETERS:
%     REGIONTYPE -- Geometric region type: 'Cell', 'Face', 'Edge', or 'Vertex'
%     REGIONID   -- ID of geometric region
%
%   BOXPARAMETERS:
%     XLIMITS -- Lower and upper bounds on X value of bounding box, specified
%                as a 1-by-2 vector.
%     YLIMITS -- Lower and upper bounds on Y value of bounding box, specified
%                as a 1-by-2 vector.
%     ZLIMITS -- Lower and upper bounds on Z value of bounding box, specified
%                as a 1-by-2 vector.(Supported by 3-D meshes only)
%
%   RADIUSPARAMETERS:
%     CENTER --  Center of disk (2-D) or sphere(3-D), specified as a vector
%                of 2 or 3 elements containing the X,Y or X,Y,Z coordinates.
%     RADIUS --  Radius of enclosing disk or sphere, specified as a scalar.
%  
%   NEARESTPARAMETERS:
%     POINT --   Cartesian coordinates of query POINT, a 2-by-N or 3-by-N 
%                matrix defining the X,Y or X,Y,Z coordinates of N query
%                points.
%
% Output Arguments
% ----------------
%   N -- ID of the nodes found by the search, returned as a scalar or row vector.
%
% Example 1: Find nodes associated with a geometric region.
%
%    pdem = createpde;
%    geometryFromEdges(pdem,@lshapeg);
%    msh = generateMesh(pdem,'Hmax',0.5);
%    nodes = msh.Nodes;
%    pdegplot(pdem,'FaceLabels','on','EdgeLabels','on');
%    figure
%    pdemesh(pdem, 'NodeLabels','on')
%
%    %Find the nodes associated with Face 2
%    Nf2 = findNodes(msh,'region','Face',2);
%    %Plot the nodes
%    hold on
%    plot(nodes(1, Nf2), nodes(2, Nf2),'ok');
%
%    %Find the nodes associated with Edges 5 and 7
%    Ne79 = findNodes(msh,'region','edge',[5,7]);
%    % Plot the nodes
%    plot(nodes(1, Ne79), nodes(2, Ne79),'or');
%    hold off
%
% Example 2: Find nodes using a bounding box.
%
%   pdem = createpde()
%   importGeometry(pdem,'PlateHolePlanar.stl')
%   msh = generateMesh(pdem,'Hmax',2,'Hmin',0.4,'GeometricOrder','linear')
%   pdemesh(pdem, 'NodeLabels','on')
%   % Find the nodes within a bounding box X=[5, 10], Y=[10,20]
%   % and highlight nodes in the plot
%   figure('Color','white')
%   pdemesh(pdem)
%   ni = findNodes(msh,'box',[5,10],[10,20])
%   % Highlight the nodes found on the plot
%   nodes = msh.Nodes;
%   hold on
%   plot(nodes(1,ni), nodes(2,ni),'or');
%   hold off
%   
% Example 3: Find nodes within a disk.
%
%   pdem = createpde()
%   importGeometry(pdem,'PlateHolePlanar.stl')
%   msh = generateMesh(pdem,'Hmax',2,'Hmin',0.4, 'GeometricOrder','linear')
%   pdemesh(pdem, 'NodeLabels','on')
%   % Find the nodes within a disk of radius 2 centered at [5, 10] and
%   % highlight the nodes in the plot
%   figure('Color','white')
%   pdemesh(pdem)
%   ni = findNodes(msh,'radius',[5,10],2)
%   % Highlight the nodes found on the plot
%   nodes = msh.Nodes;
%   hold on
%   plot(nodes(1,ni), nodes(2,ni),'or');
%   hold off
%
% Example 4: Find nodes closest to a specified point.
%
%   pdem = createpde()
%   importGeometry(pdem,'PlateHolePlanar.stl')
%   msh = generateMesh(pdem,'Hmax',2,'Hmin',0.4)
%   pdemesh(pdem)
%   % Find the boundary node closest to the point (15,10)
%   % and highlight nodes in the plot
%   hold on
%   plot(15,10,'xr');
%   ni = findNodes(msh,'nearest',[15, 10]')
%   % Highlight the node found
%   nodes = msh.Nodes;
%   hold on
%   plot(nodes(1,ni), nodes(2,ni),'or');
%   hold off
%
% See also pde.FEMesh, pde.FEMesh/findElements

% Copyright 2017 The MathWorks, Inc.