.. _page-dockmesh:

Mesh tab of the dock
====================

- :ref:`mesh-section-mesh-list`
- :ref:`mesh-section-mesh-item`
- :ref:`mesh-section-icon-bar`
- :ref:`mesh-section-mesh-tools`
- :ref:`mesh-section-mesh-settings`

Meshes are displayed only in orthogonal view widget.

.. _mesh-section-mesh-list:
Mesh list
---------

Mesh list frame at the top. Left-click to select a mesh element in the list (blue outline in Windows platform, blue background in MasOS platform).

.. _mesh-section-mesh-item:
Mesh item
---------

Mesh item widgets:

**Check box**
	Some processes are performed on checked mesh(es) such as removing, export, duplicate, overlay, filtering, isotropic dilatation, isotropic shrinking, set operators, and features.

**Edit box**
	To display and edit mesh name.

|view|
	Left-click to toogle mesh visibility in the orthogonal view widget

|opacity|
	Left-click to select mesh opacity in the orthogonal view widget (0.0 transparent, 1.0 opaque).

|palette|
	Left-click to display a mesh color dialog and change the mesh color.

|meshsetting|
	Left-click to display a mesh dialog to edit mesh properties (ambient factor, diffuse factor, specular factor, specular power, metallic factor, roughness factor, algorithm of rendering i.e. Flat/Gouraud/Phong/PBR, vertex visibility, edge visibility, point size, line width, vertex color, edge color, render point as sphere, render line as tube).

|rotate|
	Left-click to display a menu for applying rigid geometric transformation to the mesh:

	- edit box **Tx**: apply an x-axis translation in mm to the mesh, its position is updated in the orthogonal view widget.
	- edit box **Ty**: apply an y-axis translation in mm to the mesh, its position is updated in the orthogonal view widget.
	- edit box **Tz**: apply an z-axis translation in mm to the mesh, its position is updated in the orthogonal view widget.
	- edit box **Rx**: apply a rotation in degrees around the x-axis to the mesh, its position is updated in the orthogonal view widget.
	- edit box **Ry**: apply a rotation in degrees around the y-axis to the mesh, its position is updated in the orthogonal view widget.
	- edit box **Rz**: apply a rotation in degrees around the z-axis to the mesh, its position is updated in the orthogonal view widget.
	- **Clear** button, clear translations and rotations (set to 0.0), mesh position is updated in the orthogonal view widget.
	- **Align mesh center to cursor**, move the mesh barycenter to the current cursor position in the orthogonal view widget.
	- **Resample mesh**, resample mesh vertices with current geometric transformation (edit boxes). Resampling is no longer reversible, it is therefore advisable to apply it to a copy of the original mesh.

|save|
	Left-click to save mesh (PySisyphe XMESH file, xml format), mesh name is used as file name.

|cross|
	Left-click to remove mesh from list and from orthogonal view widget.

.. _mesh-section-icon-bar:
Icon bar
--------

Icon bar below mesh list:

|open|
	Left-click to show mesh selection dialog (PySisyphe XMESH file, xml format), adds selected mesh(es) to the mesh list and displays them in the orthogonal view widget. **This mesh must be in the same space as the reference volume displayed in the view widget i.e. same space ID**.

|head|
	Left-click to add outer surface mesh to the list and displays it in the orthogonal view widget. The isosurface algorithm used to generate mesh is specified in :ref:`mesh-section-mesh-settings` (**Contour**, **Marching Cube** or **Flying Edge**).

|sphere|
	Left-click to show a menu to add a sphere mesh to the list. Edit the sphere radius in mm (default 10 mm). Select menu **Add sphere mesh** to display it at the cursor position in the orthogonal view widget.

|cube|
	Left-click to show a menu to add a cube mesh to the list. Edit sizes in each axis in mm (default 10 mm). Select menu **Add parallelepiped mesh** to display it at the cursor position in the orthogonal view widget.

|save|
	Left-click to save all mesh(es) of the list.

|delete|
	Left-click to remove all mesh(es) from the list and from the orthogonal view widget.

|cross|
	Left-click to remove checked mesh(es) from the list and from the orthogonal view widget.

|export|
	Left-click to export checked mesh(es) (supported formats OBJ, STL, VTK, XMLVTK).

|check|
	Left-click to check all mesh(es) of the list.

|uncheck|
	Left-click to uncheck all mesh(es) of the list.

|duplicate|
	Left-click to add a copy of the selected mesh in the list.

|overlay|
	Left-click to display a menu of available volume(s) in the :ref:`Thumbnail bar <page-thumbnailbar>` (reference and overlays) to paint mesh surface with scalars and LUT of this volume.

|vol2mesh|
	Left-click to display a thresholding dialog box for selecting upper and lower thresholds used to generate an isosurface mesh (see :ref:`widgets <page-widgets>`). The isosurface calculation algorithm can be selected from :ref:`mesh-section-mesh-tools`.

|roi2mesh|
	Left-click to show a menu for selecting the ROI(s) to be converted to mesh(es). This menu displays available ROI(s) previously loaded in the ROI list dock, and "ROI from disk" to load ROI(s) from disk. New meshes are added to the mesh list dock.

|mesh2roi|
	Left-click for ROI conversion of the checked mesh(es).

.. _mesh-section-mesh-tools:
Mesh tools
----------

Mesh tools below icon bar:

|filter|
	Left-click to filter the checked mesh(es) of the list. New mesh(es) are added to the list and displayed in the orthogonal view widget. The filtering options are in :ref:`mesh-section-mesh-settings` (**decimate**, **fill holes**, **clean**, **smooth**, **smooth algorithm**, **smooth iterations**, **smooth relaxation factor** and **smooth pass band**).

|meshexpand|
	Left-click to show a menu to expand the checked mesh(es) of the list. Edit the isotropic margin expansion in mm (default 1.0 mm). Left-click **Dilate mesh** menu to add new mesh(es) to the list and display them in the orthogonal view widget.

|meshshrink|
	Left-click to show a menu to shrink the checked mesh(es) of the list. Edit the isotropic margin shrinking in mm (default 1.0 mm). Left-click **Erode mesh** menu to add new mesh(es) to the list and display them in the orthogonal view widget.

|union|
	Left-click to process union of the checked ROI(s), adds result to the ROI list and displays it in the view widget(s).

|intersection|
	Left-click to process intersection of the checked ROI(s), adds result to the ROI list and displays it in the view widget(s).

|difference|
	Left-click to process difference betwenn selected ROI and checked ROI(s), adds result to the ROI list and displays it in the view widget(s).

|differencesym|
	Left-click to process symmetric difference betwenn selected ROI and checked ROI(s), adds result to the ROI list and displays it in the view widget(s).

|cubefeature|
	Left-click to calculate checked mesh(es) geometric features (volume, surface, bounds, center of mass coordinates, major axis vector, mid-axis vector, minor axis vector, sizes in each vector directions) and displays them in a dialog box. Features can be stored in various formats (CSV, JSON, latex TEX, TEXT, Word XLSX, PySisyphe XSHEET).

.. _mesh-section-mesh-settings:
Mesh settings
-------------

Settings used by mesh tools.

- **Segmentation algorithm** combobox
	Algorithm used for automatic object/background segmentation:
	
	- **mean**, threshold is the mean value of the volume.
	- **otsu**, see `SimpleITK OtsuThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1OtsuThresholdImageFilter.html>`_.
	- **huang**, see `SimpleITK HuangThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1HuangThresholdImageFilter.html>`_.
	- **renyi**, see `SimpleITK RenyiEntropyThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1RenyiEntropyThresholdImageFilter.html>`_.
	- **yen**, see `SimpleITK YenThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1YenThresholdImageFilter.html>`_.
	- **li**, see `SimpleITK LiThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1LiThresholdImageFilter.html>`_.
	- **shanbhag**, see `SimpleITK ShanbhagThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1ShanbhagThresholdImageFilter.html>`_.
	- **triangle**, see `SimpleITK TriangleThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1TriangleThresholdImageFilter.html>`_.
	- **intermodes**, see `SimpleITK IntermodesThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1IntermodesThresholdImageFilter.html>`_.
	- **maximumentropy**, see `SimpleITK MaximumEntropyThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1MaximumEntropyThresholdImageFilter.html>`_.
	- **kittler**, see `SimpleITK KittlerIllingworthThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1KittlerIllingworthThresholdImageFilter.html>`_.
	- **isodata**, see `SimpleITK IsoDataThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1IsoDataThresholdImageFilter.html>`_.
	- **moments**, see `SimpleITK MomentsThresholdImageFilter class <https://simpleitk.org/doxygen/v2_5/html/classitk_1_1simple_1_1MomentsThresholdImageFilter.html>`_.

- **Isosurface algorithm** combobox
	Algorithm used to generate isosurface:

	- **contour**, see `vtkContourFilter class <https://vtk.org/doc/nightly/html/classvtkContourFilter.html>`_.
	- **marching**, see `vtkMarchingCubes class <https://vtk.org/doc/nightly/html/classvtkMarchingCubes.html>`_.
	- **flying**, see `vtkFlyingEdges3D class <https://vtk.org/doc/nightly/html/classvtkFlyingEdges3D.html>`_.

- **Decimate** checkbox 
	Reduce the number of triangles in the mesh. See `vtkDecimatePro class <https://vtk.org/doc/nightly/html/classvtkDecimatePro.html>`_.

- **Fill holes** checkbox
	Identify and fill mesh holes of the mesh. See `vtkFillHolesFilter class <https://vtk.org/doc/nightly/html/classvtkFillHolesFilter.html>`_.

- **Clean** checkbox
	Merge duplicate points, remove unused points and remove degenerate cells in the mesh. See `vtkCleanPolyData class <https://vtk.org/doc/nightly/html/classvtkCleanPolyData.html>`_.

- **Smooth** checkbox
	Adjust mesh point positions to "smooth" the mesh, making the cells better shaped and the vertices more evenly distributed.

- **Decimate percent** slidebar
	Reduction ratio (between 0.0 and 1.0), ex. 0.2, -20% of triangles.

- **Fill holes size** editbox
	Size threshold of the hole that can be filled, radius to the bounding circumsphere containing the hole (default 1000.0).

- **Smooth algorithm** combobox
	Choose mesh smoothing algorithm:
	
	- **Sinc** windowed sinc, see `vtkWindowedSincPolyDataFilter class <https://vtk.org/doc/nightly/html/classvtkWindowedSincPolyDataFilter.html>`_.
	- **Laplacian**, see `vtkSmoothPolyDataFilter class <https://vtk.org/doc/nightly/html/classvtkSmoothPolyDataFilter.html>`_.

- **Smooth iterations** editbox
	Determines the maximum number of smoothing iterations (between 10 and 20, default 10).

- **Smooth relaxation factor** editbox
	Relaxation factor of the laplacian smoothing, lower values produce more smoothing. Small relaxation factors and large numbers of iterations are more stable than larger relaxation factors and smaller numbers of iterations (between 0.0 and 1.0, default 0.1).

- **Smooth pass band** editbox
	Pass band factor of the Sinc smoothing, lower values produce more smoothing (between 0.0 and 2.0, default 0.1).

.. |open| image:: /GUI/dock/open.png
   :scale: 50 %
.. |head| image:: /GUI/dock/head.png
   :scale: 50 %
.. |sphere| image:: /GUI/dock/sphere.png
   :scale: 50 %
.. |cube| image:: /GUI/dock/cube.png
   :scale: 50 %
.. |save| image:: /GUI/dock/save.png
   :scale: 50 %
.. |delete| image:: /GUI/dock/delete2.png
   :scale: 50 %
.. |cross| image:: /GUI/dock/cross.png
   :scale: 50 %
.. |export| image:: /GUI/dock/export.png
   :scale: 50 %
.. |check| image:: /GUI/dock/check.png
   :scale: 50 %
.. |uncheck| image:: /GUI/dock/uncheck.png
   :scale: 50 %
.. |duplicate| image:: /GUI/dock/duplicate.png
   :scale: 50 %
.. |overlay| image:: /GUI/dock/overlay.png
   :scale: 50 %
.. |vol2mesh| image:: /GUI/dock/vol2mesh.png
   :scale: 50 %
.. |roi2mesh| image:: /GUI/dock/roi2mesh.png
   :scale: 50 %
.. |mesh2roi| image:: /GUI/dock/mesh2roi.png
   :scale: 50 %
.. |view| image:: /GUI/dock/view.png
   :scale: 50 %
.. |opacity| image:: /GUI/dock/opacity.png
   :scale: 50 %
.. |palette| image:: /GUI/dock/palette.png
   :scale: 50 %
.. |meshsetting| image:: /GUI/dock/meshsetting.png
   :scale: 50 %
.. |rotate| image:: /GUI/dock/rotate.png
   :scale: 50 %
.. |filter| image:: /GUI/dock/filter.png
   :scale: 50 %
.. |meshexpand| image:: /GUI/dock/meshexpand.png
   :scale: 50 %
.. |meshshrink| image:: /GUI/dock/meshshrink.png
   :scale: 50 %
.. |union| image:: /GUI/dock/union.png
   :scale: 50 %
.. |intersection| image:: /GUI/dock/intersection.png
   :scale: 50 %
.. |difference| image:: /GUI/dock/difference.png
   :scale: 50 %
.. |differencesym| image:: /GUI/dock/differencesym.png
   :scale: 50 %
.. |cubefeature| image:: /GUI/dock/cubefeature.png
   :scale: 50 %