.. _mesh:


Mesh
=====

A Mesh is a data structure that represents a triangulated surface.

.. image:: mesh.png

A structure of a mesh includes:

* `vertices` (red) - triangle points, each defined by a 3D coordinate;
* `faces` (green) - triangles formed from available vertices, defined by vertex indices (for example `f1` is defined by vertices `v1`, `v2`, `v5`);
* `halfedges` (blue) - directed edges, each defined by a vertex it points to and a face to which it belongs (for example `he1` is defined by vertex `v1` and face `f1`). In other words, when some property is assigned to a halfedge, it's assigned to a corresponding vertex of a corresponding face.

Each triangle is expected to have a counterclockwise winding order. If a mesh that doesn't satisfy this condition is loaded, the program will either try to re-orient the triangles or - if that's not possible - it will duplicate them.

An optional list of properties includes:
 
* `face normals` - normal assigned to each face;
* `face labels` -  label assigned to each face;
* `vertex normals` - normal assigned to each vertex;
* `vertex colors` - color assigned to each vertex;
* `vertex texture coordinates` - coordinates assigned to each vertex for a look-up in a 2D texture map attached to the mesh;
* `vertex labels` - label assigned to each vertex;
* `halfedge normals` - normal assigned to each halfedge;
* `halfedge colors` - color assigned to each halfedge;
* `halfedge texture coordinates` - coordinates assigned to each halfedge for a look-up in a 2D texture map attached to the mesh.


See tutorial video on how to work with meshes `here <../Concepts/tutorial-videos.html#working-with-meshes>`_

Annotation
----------
Mesh annotation belongs to a special :ref:`data annotation<dataannotations>`. When a mesh is created/loaded, its annotation will show up in the 3D view. Besides the algorithms, there are several ways to manipulate the mesh data or change its annotation visualization:

* Context menu
* Mesh Display Options
* Mesh Data Controller

Context menu
--------------------
A right-click on the mesh annotation in the annotation widget opens a context menu containing different algorithms, visualization options and other actions applicable to meshes.

* **Algorithms**.	Refer to this :ref:`page<meshalgorithms>` for the documentation of some available algorithms.
* **Visualization options**. The list of options available specifically for the mesh annotations includes:
	
	* **Change Line Width**. When MPR views are open and their planes intersect a mesh, the intersection contours will be visualized in these views. The line width controls the thickness of these contours.
	* **Show Cross-Section**. Fills in the intersection contour in the MPR views. 
	* **Change Cross-Section Color**. Allows to change the fill color of the intersection contour in the MPR views.
	* **Draw Normals**. When checked, mesh normals will be visualized.
	* **Lighting Mode** (``Enable Front``, ``Enable Back``). Controls the lighting for front and back side of the faces.
	* **Render Mode**:
	
		* ``Surface``. Only the surface of the mesh is visualized.
		* ``Wireframe``. Only the triangle edges are visualized.
		* ``Surface + Wireframe``. Both, surface and triangle edges, are rendered.
			
	*	**Change Wireframe Color**.	Changes the color of the triangle edges in ``Wireframe`` and ``Surface + Wireframe`` modes.
	
	* **Material Mode**. Possible available options are:
	
		* ``Uniform``. Surface of the mesh is rendered with a uniform color
		* ``Color``. Surface of the mesh is rendered using vertex or halfedge colors
		* ``Texture```.	Surface of the mesh is rendered using an attached texture map
		* ``Shader``.	Surface of the mesh is rendered using an attached custom shader
		* ``Face Label``.	Surface of the mesh is rendered using colors of assigned face labels
		* ``Vertex Label``.	Surface of the mesh is rendered using colors of assigned vertex labels
	* **Change Color**.	This parameter changes color of the mesh in a ``Uniform`` material mode and color of the intersection contours in MPR views.
* **Other actions**:

	* **Move to Center**. Applies a transformation matrix to the mesh such that it is afterwards centered in the world coordinate system.
	* **Burn-in Transformation**. Transforms all the vertices and normals of the mesh.
	* **Reset Transformation**. Sets the transformation matrix to identity.
	* **Use Local Coordinates**. Specifies to use mesh local coordinates when initializing **Mesh Manipulator** (see below).
	
	Refer to :ref:`transformation dialog<Base.TransformationModifier>` dialog to view or modify mesh transformation matrix (note: convention of the mesh matrix is from local to world).
	
	
Mesh Display Options
---------------------
**Mesh Display Options** is a data component that allows configuring advanced rendering options. To open, right-click on mesh in the annotation widget, select **Inspect Properties** -> **MeshDisplayOptions**.

Mesh Data Controller
-------------------------------
Depending on the current setting this controller can be either detached, or located in a toolbar, a primary or a secondary dock.

Available options can be split into following categories:

* Visualization:

	* **Render Mode**: ``Surface``, ``Wireframe`` or ``Surface + Wireframe`` (described earlier).
	* **Material Mode**: ``Uniform``, ``Color``, ``Texture``, ``Shader``, ``Face Label``, ``Vertex Label`` (described earlier).
	* **Lighting**: ``on`` or ``off`` for both, front and back side of a mesh.
	* **Triangle Normals**: if ``on``, mesh surface will be rendered using face normals instead of vertex normals.
	
* Mesh Manipulator

	* **Translate**: adds a manipulator for translating the mesh (this changes transformation matrix of the mesh).
	* **Rotate**: adds a manipulator for rotating the mesh (this changes transformation matrix of the mesh).
	
* Mesh Info Overlay (**View Mesh Info**). Shows selected information as a text overlay in the left corner of the 3D View.	Available options are:
	
	* ``Triangle info``. Displays all available information that a particular triangle has: face index, face normal, face label, 3 vertex indices, 3 vertex positions, 3 vertex normals, 3 vertex colors, 3 vertex texture coordinates, 3 vertex labels, 3 halfedge normals, 3 halfedge colors, 3 halfedge texture coordinates.
	* ``Vertex info``. Displays all available information that a particular vertex has: index, position, normal, color, label.
	* ``Edge info``.  Displays all available information that a particular edge has: face index, 2 vertex indices, 2 vertex positions, 2 halfedge normals, 2 halfedge colors, 2 halfedge texture coordinates.
	* ``Show holes``. Displays a contour of the boundary faces.
	* ``Show non-manifold vertices``. Displays non-manifold vertices. These are vertices that are either known to have duplicates, or  if more than one gap exists, i.e. more than one outgoing boundary halfedge.