% addFace - Adds an internal face to geometry
%
%   NewGM = addFace(GM,EDGES) adds new geometric faces bounded by the
%   specified edges to geometry GM.
%   EDGES is a vector of IDs of edges or a cell array of such vectors.
%   Edges specified in each vector must form a unique closed contour.
%   Each contour in the cell array must be unique.
%   NewGM is a handle to the geometry object GM.
%
%   [NewGM,FaceID] = addFace(GM, EDGES) also returns a row vector FaceID
%   containing IDs of added faces.
%
%   A new face in a 2-D geometry must fill an internal void region in the
%   geometry. A new face in a 3-D geometry splits a geometric cell and
%   becomes a boundary between new cells. For both 2-D and 3-D geometries,
%   you cannot add a new face on an exterior geometric boundary.
%   
%   New faces modify a geometry, but they do not modify the mesh. After
%   adding faces, always call generateMesh. Creating a new mesh ensures
%   a proper mesh association with the new geometry.
%
%   Example: Add a face to a 2-D geometry to fill an internal void region.
%
%       model = createpde;
%       gm = importGeometry(model,'PlateHolePlanar.stl')
%       newgm = addFace(gm,5)
%       pdegplot(gm,'FaceLabels','on')
%
%   See also pde.DiscreteGeometry, pde.EquationModel/importGeometry,
%            pde.DiscreteGeometry/addVertex,
%            pde.EquationModel/generateMesh

% Copyright 2019-2020 The MathWorks, Inc.
% Built-in function.
