%meshQuality - Evaluate shape quality of elements
%
%   Q = meshQuality(MSH) returns the shape quality of all elements in 
%   the mesh.
%
%   QE = meshQuality(MSH, E) returns the shape quality of the elements 
%   specified by E.
%
%   Q = meshQuality(___, METRIC) returns the shape quality computed using 
%   the specified METRIC.
%
% Input Arguments
% ---------------
%   MSH -- FEMesh object
%   E   -- Element IDs, specified as a scalar or matrix
%
%   METRIC - Alternate metric to evaluate specific shape quality and override 
%   the general-purpose default:
%      'aspect-ratio'    - ratio of min to max dimensions of an element
%                          
% Output Arguments
% ----------------
%
%   Q -- Shape quality metric for each element in the mesh, specified as a
%   row vector. 0 <= Q(i) <= 1, represents the shape quality of element i. 
%   A shape quality value of 1 represents an element with optimal shape, 
%   and a value of 0 represents a deflated element with zero area or volume.
% 
%   QE -- Shape quality metric for each of the specified elements, specified 
%   as a row vector. 0 <= Q(i) <= 1, represents the shape quality of element 
%   E(i). A shape quality value of 1 represents an element with optimal shape, 
%   and a value of 0 represents a deflated element with zero area or volume.
%
% Examples
% --------
%
%   Example 1: Evaluate the shape quality of a 2-D mesh.
%      pdem = createpde;
%      pdem.importGeometry('PlateSquareHolePlanar.stl');
%      pdegplot(pdem);
%      %Create a coarse mesh to produce elements of poor quality
%      msh = pdem.generateMesh('Hmax',35)
%      q = msh.meshQuality()
%
%      %Plot the mesh and then find the elements that have quality < 0.4
%      %and plot them in green.
%      figure
%      pdemesh(pdem)
%      elemIDs = find(q < 0.4);
%      nodes = msh.Nodes; 
%      elems = msh.Elements;
%      hold on
%      pdemesh(nodes,elems(:,elemIDs), 'EdgeColor','green')
%      hold off
%
%      %Plot the element quality in a histogram
%      figure
%      hist(q);
%      xlabel('Element Shape Quality', 'fontweight','b');
%      ylabel('Number of Elements', 'fontweight','b');
%
%      %Find the ID of the element with the worst quality.
%      qworst = min(q) 
%      elemID = find(q==qworst) 
%
%
%   Example 2: Evaluate the shape quality of a 3-D mesh.
%      pdem = createpde;
%      pdem.importGeometry('PlateSquareHoleSolid.stl');
%      %Create a coarse mesh to produce elements of poor quality
%      msh = pdem.generateMesh('Hmax',35)
%      q = msh.meshQuality();
%
%      %Plot the mesh and then find the elements that have quality < 0.2
%      %and plot them in green.
%      figure
%      pdemesh(pdem,'FaceAlpha',0.5)
%      elemIDs = find(q < 0.2);
%      nodes = msh.Nodes; 
%      elems = msh.Elements;
%      hold on
%      pdemesh(nodes,elems(:,elemIDs), 'FaceColor','blue', 'EdgeColor','blue')
%      hold off
%
%      %Plot the element quality in a histogram
%      figure
%      hist(q);
%      xlabel('Element Shape Quality', 'fontweight','b');
%      ylabel('Number of Elements', 'fontweight','b');
%
%      %Find the ID of the element with the worst quality.
%      qworst = min(q) 
%      elemID = find(q==qworst) 
%
% See also pde.FEMesh/findNodes, pde.FEMesh/findElements, pde.FEMesh/area

% Copyright 2017 The MathWorks, Inc.
