
**************
Mesh Structure
**************

With meshes, everything is built from three basic elements:
*vertices*, *edges* and *faces*.

.. figure:: /images/modeling_meshes_structure_example.svg
   :width: 600px

   Example of mesh structure.

.. The geometry of the faces performing the model is called topology.


Vertices
========

The most elementary part of a mesh is the vertex (vertices plural) which is a single point or position in 3D space.
Vertices are represented in the 3D Viewport in Edit Mode as small dots.
The vertices of an object are stored as an array of coordinates.

.. tip::

   Do not mistake the :doc:`object origin </scene_layout/object/origin>` for a vertex.
   It may look similar, but it is bigger and cannot be selected.

   .. figure:: /images/modeling_meshes_structure_cube-example.png

      The vertex is labeled as "A"; the object's origin dot is labeled as "B".


Edges
=====

An edge always connects two vertices by a straight line.
The edges are the "wires" you see when you look at a mesh in wireframe view.
They are usually invisible on the rendered image. They are used to construct faces.


Faces
=====

Faces are used to build the actual surface of the object.
They are what you see when you render the mesh.
If this area does not contain a face,
it will simply be transparent or nonexistent in the rendered image.

A face is defined as the area between either three (triangles), four (quadrangles) or more (n-gons) vertices,
with an edge on every side. The faces are often abbreviated to *tris, quads & n-gons*.

Triangles are always flat and therefore easy to calculate. On the other hand,
quadrangles "deform well" and are therefore preferred for animation and subdivision modeling.

.. seealso::

   - `Why should triangles be avoided for character animation? <https://blender.stackexchange.com/questions/2931>`__
   - `When should N-gons be used, and when shouldn't they? <https://blender.stackexchange.com/questions/89>`__


.. _modeling-meshes-structure-normals:

Normals
=======

In geometry, a normal is a direction or line that is perpendicular to something,
typically a triangle or surface but can also be relative to a line,
a tangent line for a point on a curve, or a tangent plane for a point on a surface.

Normals help to determine the shading of the mesh among other things.

.. figure:: /images/modeling_meshes_structure_viewport.png
   :width: 350px

   A visualization of the face normals of a torus.

In the figure above, each blue line represents the normal for a face on the torus.
The lines are each perpendicular to the face on which they lie.
The visualization can be activated, in Edit Mode,
in the :ref:`Mesh Display Viewport Overlays panel <mesh-display-normals>`.


.. _modeling-meshes-structure-normals-shading:

Shading
-------

Surface normals play a fundamental role in determining how light interacts with 3D objects
and thus greatly influence the shading of those objects. Normals can be shaded smooth or flat.

When a mesh uses flat shading, the faces are rendered and displayed faces uniformly.
This is usually desirable for objects with flat surfaces such as a cube or pyramid.

When a mesh uses smooth shading, the normals are interpolated across the vertices of a polygonal mesh,
smooth transitions between adjacent polygons can be achieved, resulting in a more realistic appearance.

By default face normals have flat shading however, this can be adjusted either for the whole object or per face.

To adjust the shading of the whole object, use:

- :ref:`bpy.ops.object.shade_smooth` -- To mark the whole object as smooth.
- :ref:`bpy.ops.object.shade_auto_smooth` -- To mark portions of the object as smooth.

To revert to flat shading, use :ref:`bpy.ops.object.shade_flat`.

The shading of objects can also be adjusted per face, edge, or vertex.


.. _modeling_meshes_normals_custom:

Custom Split Normals
--------------------

Custom split normals are a way to tweak/fake shading by pointing normals towards
other directions than the default, auto-computed ones. It is mostly used in game development,
where it helps counterbalance some issues generated by low-poly objects
(the most common examples are low-poly trees, bushes, grass, etc. and the 'rounded' corners).

Blender supports custom normals on a 'smooth fan' base, defined as a set of neighbor face corners
sharing the same vertex and 'linked' by smooth edges. This means you can have normals per face corners,
per a set of neighbor face corners, or per vertex.

Custom split normal data is stored as the ``custom_normal``
:doc:`Attribute </modeling/geometry_nodes/attributes_reference>` on the face corner :ref:`Domain <attribute-domains>`.

.. tip::

   The computation of custom split normals can be disabled to improve performance.
   This option can be found in the :ref:`Simplify Rendering Settings <bpy.types.RenderSettings.use_simplify_normals>`.


Free Normals
^^^^^^^^^^^^

Free normals are a type of custom normal stored directly as direction vectors in object space.
Unlike traditional custom normals, which are defined relative to the surrounding geometry
(known as tangent or corner fan space),
free normals are independent of mesh topology and do not rely on smooth groups or edge connectivity.

Because they are simple vectors, free normals are:

- Efficient: Fast to evaluate, significantly improving viewport performance compared to tangent space normals.
- Lightweight: Require less memory, especially beneficial for dense or heavily instanced meshes.
- Static: They do not automatically update when the mesh is deformed (e.g. through modifiers or animations),
  so they are best suited for static geometry or cases where performance is critical.

Free normals can be assigned using the :doc:`/modeling/geometry_nodes/mesh/write/set_mesh_normal` in Free mode,
and stored on the vertex, face, or face corner domain depending on the desired granularity.


Editing Custom Split Normals
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. reference::

   :Mode:      Edit Mode
   :Menu:      :menuselection:`Mesh --> Normals`
   :Shortcut:  :kbd:`Alt-N`

There are a number of tools for editing custom split normals.
The custom normal mesh edit tools can affect all normals (the default), or only selected ones.
To select a custom normal associated with a particular vertex and face:

- Make the element selection mode both Vertex and Face (use :kbd:`Shift-LMB` to enable the second one).
- Select one or more vertices, then select a face.
  This can be repeated to select more vertices and a different face and so on.
  It is easiest to see the effect of these tools if you turn on
  the Edit Mode Overlays option *Display vertex-per-face normals as lines*.

.. seealso::

   :doc:`Editing Normals </modeling/meshes/editing/mesh/normals>`.


Importing Custom Split Normals
------------------------------

Some tools, particularly those used in :abbr:`CAD (Computer-Aided Design)`, tend to generate irregular geometry
when tessellating their objects into meshes (very thin and long triangles, etc.).
Auto-computed normals on such geometry often gives bad artifacts,
so it is important to be able to import and use the normals as generated by the CAD tool itself.

.. note::

   Currently, only the :doc:`FBX Importer </addons/import_export/scene_fbx>` and
   :doc:`Alembic Importer </files/import_export/alembic>` are capable of importing custom normals.

.. _modeling_meshes_structure_topology:

Topology
========

.. Note: this could be it's own page, for now keep this a fairly brief section.

Loops
-----

.. _fig-mesh-topo-loop:

.. figure:: /images/modeling_meshes_structure_edge-face-loops.png

   Edge and face loops.

*Edge* and *face* loops are sets of faces or edges that form continuous "loops" as shown in
Fig. :ref:`fig-mesh-topo-loop`.

In the image above, loops that do not end in poles are cyclic (1 and 3).
They start and end at the same vertex and divide the model into two partitions.
Loops can be a quick and powerful tool to work with specific,
continuous regions of a mesh and are a prerequisite for organic character animation.
For a detailed description of how to work with loops in Blender, see:
:ref:`bpy.ops.mesh.loop_multi_select`.

.. note::

   Note that loops (2 and 4) do not go around the whole model.
   Loops stop at so-called poles because there is no unique way to continue a loop from a pole.
   Poles are vertices that are connected to either three, five, or more edges. Accordingly,
   vertices connected to exactly one, two or four edges are not poles.


.. _modeling-mesh-structure-edge-loops:

.. rubric:: Edge Loops

Loops (1 and 2) in Fig. :ref:`fig-mesh-topo-loop` are edge loops.
They connect vertices so that each one on the loop has exactly two neighbors that are not on
the loop and placed on both sides of the loop (except the start and end vertex in case of poles).

Edge loops are an important concept especially in organic (subsurface)
modeling and character animation. When used correctly, they allow you to build models with
relatively few vertices that look very natural when used as subdivision surfaces and
deform very well in animation.

Take Fig. :ref:`fig-mesh-topo-loop` in organic modeling as an example: the edge loops follow
the natural contours and deformation lines of the skin and the underlying muscles.
The loops are denser in areas that deform more when the character moves, for example at the shoulders or knees.

Further details on working with edge loops can be found in :ref:`bpy.ops.mesh.loop_multi_select`.


.. rubric:: Face Loops

These are a logical extension of edge loops in that they consist of the faces between
two edge loops, as shown in loops (3 and 4) in Fig. :ref:`fig-mesh-topo-loop`.
Note that for non-circular loops (4)
the faces containing the poles are not included in a face loop.

Further details on working with face loops can be found in
:ref:`Face Loop Selection <modeling-meshes-selecting-face-loops>`.


Poles
-----

See `N-poles & E-poles <https://blender.stackexchange.com/a/133676/55>`__.


Non-Manifold
------------

See :term:`Non-manifold`.
