MeshFaceList
============

.. py:module:: rhino3dm

.. py:class:: MeshFaceList

   .. py:attribute:: Count

      int: Gets or sets the number of mesh faces. When getting this can includes invalid faces.

   .. py:attribute:: QuadCount

      int: Gets the number of faces that are valid quads (4 corners).

   .. py:attribute:: TriangleCount

      int: Gets the number of faces that are valid triangles (3 corners).

   .. py:attribute:: Capacity

      int: Gets or sets the total number of mesh triangles and quads the internal data structure can hold without resizing.

   .. py:method:: __len__()

      [todo] add documentation

   .. py:method:: __getitem__()

      [todo] add documentation

   .. py:method:: GetFaceVertices(faceIndex)

      Gets the 3D location of the vertices forming a face.

      :param int faceIndex: A face index.

      :return: tuple (bool, Point3f, Point3f, Point3f, Point3f)

         - True if the operation succeeded, otherwise false.
         - A first point. This out argument is assigned during the call. \
         - A second point. This out argument is assigned during the call. \
         - A third point. This out argument is assigned during the call. \
         - A fourth point. This out argument is assigned during the call. \

      :rtype: (bool, Point3f, Point3f, Point3f, Point3f)

   .. py:method:: GetFaceCenter(faceIndex)

      Gets the center point of a face.
      For a triangular face, this is the centroid or barycenter.For a quad, this is the average of four comer points.

      :param int faceIndex: A face index.

      :return: The center point.

      :rtype: rhino3dm.Point3d

   .. py:method:: Clear()

      Clears the Face list on the mesh.


      :rtype: void

   .. py:method:: Destroy()

      Releases all memory allocated to store faces. The list capacity will be 0 after this call.
      Subsequent calls can add new items.


      :rtype: void

   .. py:method:: AddFace(vertex1, vertex2, vertex3)

      Appends a new mesh face to the end of the mesh face list.

      :return: The index of the newly added face.

      :rtype: int

   .. py:method:: AddFace(vertex1, vertex2, vertex3, vertex4)

      Appends a new mesh face to the end of the mesh face list.

      :return: The index of the newly added face.

      :rtype: int

   .. py:method:: SetFace(index, vertex1, vertex2, vertex3)

      Sets a face at a specific index of the mesh.

      :return: True if the operation succeeded, otherwise false.

      :rtype: bool

   .. py:method:: SetFace(index, vertex1, vertex2, vertex3, vertex4)

      Sets a face at a specific index of the mesh.

      :return: True if the operation succeeded, otherwise false.

      :rtype: bool

   .. py:method:: ConvertQuadsToTriangles()

      Splits all quads along the short diagonal.

      :return: True on success, False on failure.

      :rtype: bool

   .. py:method:: ConvertNonPlanarQuadsToTriangles()

      Splits non-planar quads into two triangles based on given parameters.

      :param float planarTolerance: If planarTolerance >= 0, then a quad is split if its vertices \
         are not coplanar. \
         If both planarTolerance = Rhino.RhinoMath.UnsetValue and \
         angleToleranceRadians >= 0.0, then the planarity test is skipped.
      :param float angleToleranceRadians: If angleToleranceRadians >= 0.0, then a quad is split if the \
         angle between opposite corner normals is > angleToleranceRadians. \
         The corner normal is the normal to the triangle formed by two \
         adjacent edges and the diagonal connecting their endpoints. \
         A quad has four corner normals. \
         If both angleToleranceRadians = Rhino.RhinoMath.UnsetValue and planarTolerance >= 0.0, \
         then the corner normal angle test is skipped.
      :param int splitMethod: 0 default \
         Currently divides along the short diagonal. This may be \
         changed as better methods are found or preferences change. \
         By passing zero, you let the developers of this code \
         decide what's best for you over time. \
         1 divide along the short diagonal \
         2 divide along the long diagonal \
         3 minimize resulting area \
         4 maximize resulting area \
         5 minimize angle between triangle normals \
         6 maximize angle between triangle normals

      :return: Number of quads that were converted to triangles.

      :rtype: int

   .. py:method:: ConvertTrianglesToQuads()

      Joins adjacent triangles into quads if the resulting quad is 'nice'.

      :param float angleToleranceRadians: Used to compare adjacent triangles' face normals. For two triangles \
         to be considered, the angle between their face normals has to \
         be <= angleToleranceRadians. When in doubt use RhinoMath.PI/90.0 (2 degrees).
      :param float minimumDiagonalLengthRatio: ( <= 1.0) For two triangles to be considered the ratio of the \
         resulting quad's diagonals \
         (length of the shortest diagonal)/(length of longest diagonal). \
         has to be >= minimumDiagonalLengthRatio. When in doubt us .875.

      :return: True on success, False on failure.

      :rtype: bool

   .. py:method:: CullDegenerateFaces()

      Attempts to removes degenerate faces from the mesh.
      Degenerate faces are faces that contains such a combination of indices,
      that their final shape collapsed in a line or point.Before returning, this method also attempts to repair faces by juggling
      vertex indices.

      :return: The number of degenerate faces that were removed.

      :rtype: int

   .. py:method:: IsHidden()

      Gets a value indicating whether a face is hidden.
      A face is hidden if, and only if, at least one of its vertices is hidden.

      :param int faceIndex: A face index.

      :return: True if hidden, False if fully visible.

      :rtype: bool

   .. py:method:: HasNakedEdges()

      Returns True if at least one of the face edges are not topologically
      connected to any other faces.

      :param int faceIndex: A face index.

      :return: True if that face makes the mesh open, otherwise false.

      :rtype: bool
