.. role:: blue
   :class: blue

Segmentation and Segmentation Iterators
=======================================
.. _Segmentation_and_Segmentation_Iterators_:

.. kernel version: 118027

Segmentation over a polygon mesh is also organized as a :blue:`Halfedge` structure. The following elements from the *halfedge_element.h* header file are used for segmentation representation. Each segmentation element can be either active or inactive.

A **subRegion** (:blue:`MbSegmentationSubRegion`) is a connected group of facets.

A **region** comprises one or more subregions, usually one. There is no separate class describing a region.

A **segmentation edge** is a sequence of mesh edges, where the subsequent edge starts from the vertex where the previous edge ends. It can be closed. Self-intersections are not allowed. Similar to a mesh edge, a segmentation edge contains links to its next and previous edges, its twin edge, and its associated vertex. These links are used to construct loops. If a segmentation edge belongs to an open boundary, there is no reference to the twin. Mesh edges that are part of a segmentation edge and its twin are also considered twins (see Fig. 1):

.. figure:: ../../pictures/P.2.3.1en.png
   :width: 15cm
   :align: center

   Fig. 1

A segmentation vertex corresponds to a mesh vertex where several segmentation edges are connected.

A **subRegion cycle** (:blue:`MbSegmentationLoop`) consists of a sequence of segmentation edges. A subregion can have any number of cycles, or none, if a subregion is a closed facet group. The subregion cycle has the same meaning as an edge cycle of a face in the boundary representation, with some differences. Usually, it is impossible to separate cycles into outer and inner ones on a mesh, so all cycles are treated equally. A cycle can also have “internal” edges.

An example of dividing the mesh into four regions, each consisting of a subregion, is shown in Fig. 2:

.. figure:: ../../pictures/P.2.3.2.png
   :width: 15cm
   :align: center

   Fig. 2

An example for the same mesh, but now there are two regions in the segmentation, the first of which has one subregion and the second has three, is shown in Fig. 3:

.. figure:: ../../pictures/P.2.3.3.png
   :width: 15cm
   :align: center

   Fig. 3

An example of a two-cycle subregion is shown in Fig. 4. The green cycle consists entirely of internal edges, while the red cycle contains internal edges 1, 2, 4–9.

.. figure:: ../../pictures/P.2.3.4.png
   :width: 15cm
   :align: center

   Fig. 4

The *halfedge_segm_iterators.h* header file provides segmentation iterators used to work with segmentation topology:

- :blue:`EdgeLoopIterator` is an iterator over edges of subregion cycle. The iterator returns a sequence of all cycle edges or only outer edges depending on the :blue:`bExcludeInnerEdges` flag.
- :blue:`EdgeEdgesIterator` is an iterator through mesh edges of a segmentation edge. The iterator returns a sequence of mesh edges in forward or reverse order depending on the :blue:`bReverse` flag.
- :blue:`SubregionRegionIterator` is an iterator through subregions of a region.
- :blue:`LoopSubregionIterator` is an iterator through subregion cycles.

To iterate through the segmentation vertex fan, use the :blue:`EdgeFanIterator` iterator, as shown in the example below:

.. code-block:: cpp

   MbPolymesh polymesh;

   const MbPolymeshTopo & topo = *polymesh->GetTopo();

   const MbHalfedge & halfedge = topo.GetMeshTopo();

   for( size_t r = 0; r < topo.RegionCount(); ++r ) {

       if( !topo.IsRegionActive( r ) )
           continue;

       for( SubregionRegionIterator itSub( topo, r ); !itSub.Done(); ++itSub ) {

           for( LoopSubregionIterator itLoop( topo, itSub.Subregion() ); !itLoop.Done(); ++itLoop ) {

               for( EdgeLoopIterator itEdge( topo, itLoop.Loop() ); !itEdge.Done(); ++itEdge ) {

                   for( EdgeEdgesIterator it( topo, itEdge.Edge() ); !it.Done(); ++it ) {

                       const MbHalfedgeEdge & ed = halfedge.Edge( it.Edge() );
                       ...
                   }
               }
           }
       }
   }

   for( EdgeFanIterator it( topo.GetSegmTopo(), iVxSegm, true ); !it.Done(); ++it ) {

       const MbHalfedgeEdge & edSegm = topo.GetSegmTopo().Edge( it.Edge() );
   }