smesh/doc/salome/gui/SMESH/input/creating_groups.doc

/*!

\page creating_groups_page Creating groups

\n In MESH you can create a \ref grouping_elements_page "group" of
elements of a certain type. The main way to create a group, is to
select in the \b Mesh menu <b>Create Group</b> item (also available in
the context menu of the mesh).<br>
To create a group you should define the following: 
<ul>
<li><b>Mesh</b> - the mesh whose elements will form your
group. You can select your mesh in the Objet Browser or in the 3D
viewer.</li>
<li><b>Elements Type</b> - set of radio buttons allows to select the type of
elements which will form your group:</li>
<ul>
<li><b>Nodes</b></li>
<li><b>0D Element</b></li>
<li><b>Ball</b></li>
<li><b>Edges</b></li>
<li><b>Faces</b></li>
<li><b>Volumes</b></li>
</ul>
<li><b>Name</b> field allows to enter the name of your new group.</li>
<li><b>Color</b> - allows to assign to the group a certain color. The
  chosen color is used to display the elements of the group.<br>
  Activation of <em>Auto Color</em> item in mesh context menu
  switches on a random choice of a color for a new group.</li>
</ul>
Mesh module distinguishes between the three Group types:
<b>Standalone Group</b>, <b>Group on Geometry</b> and <b>Group on Filter</b>.

\anchor standalone_group <br><h2>"Standalone Group"</h2>

<b>Standalone Group</b> contains a list of mesh elements, which you can define in
the following ways:
<ul>
<li>By adding all entities of the chosen type existing in the
  mesh. For this, turn on the <b>Select All</b> check-box. In this mode
  all controls, which allow selecting the entities, are
  disabled.</li>
<li>By choosing entities manually with the mouse in the 3D Viewer. For
  this, turn on the <b>Enable manual edition</b> check box. You can
  click on an element in the 3D viewer and it will be highlighted. After
  that click the \b Add button and the ID of this element will be
  added to the list.<br>
  The <b>Set filter</b> button allows to define the filter for
  selection of the elements for your group. See more about filters on
  the \ref selection_filter_library_page "Selection filter library"
  page.</li> 
<li>By adding entities from either a sub-mesh or another
  group. For this, turn on the <b>Enable manual edition</b> check
  box. <b>Select from</b> fields group allows to select a sub-mesh or
  a group of the appropriate type and to \b Add their elements to the
  group.</li>
</ul>
In the <b>manual edition</b> mode you can
<ul>
<li>click the \b Remove button to remove the selected items from
  the list.</li>
<li>click the <b>Sort List</b> button to sort the list of IDs of 
  mesh elements.</li>
</ul>

\image html creategroup.png


For example, to create a new group containing all faces of an
existing group and some other faces selected in the viewer:
<ul>
<li> Select the \b Face type of entities and input the name of the new group.</li>
<li> Check the \b Group checkbox in <b>Select From</b> group.</li>
<li> Select the existing group of faces in the object browser or in the viewer.</li>
<li> Click \b Add in \b Content group. <b>Id Elements</b> list will be filled
with IDs of faces belonging to the selected group.</li>
<li> Select other faces in the viewer.</li>
<li> Click \b Add in \b Content group.</li>
<li> Click \b Apply button to create the new group.</li>
</ul>

Please note that the new group does not have references to the source
group. It contains only the list of face IDs. So if the source group
is changed, the new one is not updated accordingly.


\image html image130.gif
<center>In this picture the brown cells belong to a group defined
  manually.</center> 

<b>See Also</b> a sample TUI Script of a 
\ref tui_create_standalone_group "Create a Standalone Group"
operation.  


\anchor group_on_geom <br><h2>"Group on Geometry"</h2>

To create a group on geometry check <b>Group on geometry</b> in the \b
Group \b type field. The group on geometry contains the elements
of a certain type generated on the selected geometrical object. Group
contents are dynamically updated if the mesh is modified. The group on
geometry can be created only if the mesh is based on geometry.

To define a group, click the \a Selection button and choose
- <em>Direct geometry selection</em> to select a shape in the Object
  Browser or in the Viewer;
- <em>Find geometry by mesh element selection</em> to activate a
  dialog which retrieves a shape by the selected element generated on
  this shape.

Note that this choice is available only if the mesh elements are
already generated.

\image html a-creategroup.png

After confirmation of the operation a new group of mesh elements will
be created.

\image html image132.gif
<center>In this picture the cells which belong to a certain
  geometrical face are selected in green.</center>

<b>See Also</b> a sample TUI Script of a 
\ref tui_create_group_on_geometry "Create a Group on Geometry"
operation.


\anchor group_on_filter <br><h2>"Group on Filter"</h2>

To create a group on filter check <b>Group on filter</b> in the <b>
Group type</b> field. The group on filter contains the elements
of a certain type satisfying the defined filter. Group contents are
dynamically updated if the mesh is modified.

To define a group, click the <b>Set filter</b> button and define
criteria of the filter in the opened dialog. After the
operation is confirmed, a new group of mesh elements will be created. See more about
filters on the 
\ref selection_filter_library_page "Selection filter library" page. 

\image html creategroup_on_filter.png

<b>See Also</b> a sample TUI Script of a 
\ref tui_create_group_on_filter "Create a Group on Filter" operation.

*/