0022869: Update documentation

doc/salome/gui/GEOM/input/creating_complex_obj.doc

@@ -3,23 +3,26 @@
 \page create_complex_obj_page Creating Complex Objects
 
 <b>New entity -> Generation</b> sub-menu allows creating new geometric
-objects by modification and multiplication of the existing objects: 
+objects by modification and multiplication of the existing objects:
 
 
 <ul>
 <li>\subpage create_extrusion_page "Extrude" a 2D object by vector,
-creating a 3D object. </li> 
+creating a 3D object. </li>
 <li>\subpage create_revolution_page "Revolve" an object around an
 axis, creating a body of revolution.</li>
 <li>\subpage create_filling_page  "Create a surface" from a set of edges.</li>
-<li>\subpage create_extrusion_alongpath_page "Extrude an object along a path", 
+<li>\subpage create_extrusion_alongpath_page "Extrude an object along a path",
 creating a more complex trajectory object.</li>
 <li>\subpage create_pipe_path_page "Restore Path" of a pipe-like shape.</li>
 <li>\subpage create_thickness_page "Thickness" operation that allows to add a thickness to objects.</li>
+
+<li>\subpage create_groups_page "Generate Groups".
+This cross-operation functionality allows creation of groups for certain generation operations.</li>
 </ul>
 
 <b> New entity -> Advanced </b> sub-menu allows creating new geometric
-objects using advanced algorithms: 
+objects using advanced algorithms:
 
 <ul>
 <li>\subpage create_smoothingsurface_page "Smoothing surface" from a

doc/salome/gui/GEOM/input/creating_extrusion_alongpath.doc

@@ -14,13 +14,17 @@ is created so that the <b>angle between the normal vector</b> to
 the base shape <b>and the tangent to the path</b> wire remains constant at any point of the
 given path.
 \n <b>Select unpublished edges</b> checkbox - if checked, allows to select an edge of any other shape as the path object. 
+\n <b>Generate groups</b> checkbox - if checked allows to create groups of
+sub-shapes. For more details on groups creation please refer to
+\ref create_groups_page "this description".
 \n The \b Result of the operation will be a GEOM_Object (edge, face, shell,
 solid or compsolid).
 
-\n <b>TUI Command:</b> <em>geompy.MakePipe(baseShape, pathShape)</em>
+\n <b>TUI Command:</b> <em>geompy.MakePipe(baseShape, pathShape,
+ IsGenerateGroups=False)</em>
 \n <b>Arguments:</b> Name + 1 shape (vertex, edge, planar wire, face or
 shell) serving as base object + 1 shape (edge or wire) for
-definition of the path.
+definition of the path + 1 boolean parameter (IsGenerateGroups).
 \n <b>Advanced options</b> \ref preview_anchor "Preview"
 
 \image html pipe.png
@@ -39,14 +43,19 @@ wire).
 to preserve the constant <b>angle between the normal vector</b> to the base
 shape <b>and the BiNormal vector</b> given as the third argument.
 \n <b>Select unpublished edges</b> checkbox - if checked, allows to select an edge of any other shape as the path object. 
+\n <b>Generate groups</b> checkbox - if checked allows to create groups of
+sub-shapes. For more details on groups creation please refer to
+\ref create_groups_page "this description".
 \n The \b Result of the operation will be a GEOM_Object (edge, face, shell,
 solid or compsolid).
 
-\n <b>TUI Command:</b> <em>geompy.MakePipeBiNormalAlongVector(baseShape, pathShape, binormalShape)</em>
+\n <b>TUI Command:</b> <em>geompy.MakePipeBiNormalAlongVector(baseShape, pathShape, binormalShape,
+ IsGenerateGroups=False)</em>
 \n <b>Arguments:</b> Name + 1 shape (edge, planar wire or face) 
 serving as base object + 1 shape (edge or wire) for
 definition of the path + 1 shape (edge or wire) to set a fixed 
-BiNormal direction to perform the extrusion.
+BiNormal direction to perform the extrusion + 1 boolean parameter
+(IsGenerateGroups).
 
 \image html pipe2.png
 
@@ -64,13 +73,17 @@ Additional controls:
 - If <b>With correction</b> is checked, the section is rotated to be orthogonal to the spine
 tangent in the corresponding point.
 
+<b>Generate groups</b> checkbox - if checked allows to create groups of
+sub-shapes. For more details on groups creation please refer to
+\ref create_groups_page "this description".
 \n The \b Result of the operation will be a shell or a solid.
 
-\n <b>TUI Command:</b> <em>geompy.MakePipeWithDifferentSections(baseShape, locations, pathShape, withContact, withCorrection)</em>
+\n <b>TUI Command:</b> <em>geompy.MakePipeWithDifferentSections(baseShape, locations, pathShape, withContact, withCorrection,
+ IsGenerateGroups=False)</em>
 \n <b>Arguments:</b> Name + list of shapes (edges, planar wires, faces or shells) serving as base object + 
 list of locations (vertices) on the path corresponding specified list of the shapes + 
 1 shape (edge or wire) for definition of the path + 
-2 Boolean parameters (withContact, withCorrection).
+3 Boolean parameters (withContact, withCorrection, IsGenerateGroups).
 \n <b>Advanced options</b> \ref preview_anchor "Preview"
 
 \image html pipe3.png

doc/salome/gui/GEOM/input/creating_groups.doc

@@ -0,0 +1,76 @@
+/*!
+
+\page create_groups_page Generation of Groups
+
+This option is available in some dialogs. To activate it please check
+<b>Generate Groups</b> check box. When it is checked, it is possible to define
+the prefix for generated groups names using <b>Group Names Prefix</b> input
+field.
+
+\image html gen_group_dlg.png "Generate groups option in a dialog"
+
+The groups are created along with the result of the operation when
+\b Apply or <b>Apply and Close</b> button is clicked. Each generated group
+represents a set of sub-shapes of the result that satisfies certain conditions.
+The groups of the following types can be generated:
+ - \b Down - sub-shapes starting the result, e.g. bottom lid
+for the pipe creation operation.
+ - \b Up - sub-shapes ending the result, e.g. top lid
+for the pipe creation operation.
+ - \b Side1, \b Side2 - sub-shapes corresponding to each side
+of the result.
+ - \b Other - faces generated from the bounding edges of
+\b Down group.
+
+The groups are named according to the following naming rule:
+If <b>Group Names Prefix</b> is set <b><Prefix>_<Type></b>, otherwise
+the name is \b <Type>. The following figure shows group names created with
+the prefix \b Group:
+
+\image html gen_group_tree.png "Group_Down, Group_Up, Group_Side1 and Group_Side2 are generated"
+
+
+The general behavior of this functionality is the following:
+<ul>
+<li>If <b>Generate Groups</b> option is not set, the groups are not generated.</li>
+<li>If starting and ending sub-shapes of the result are the same, e.g. if there is
+a closed path for pipe construction, <b>Generate Groups</b> option is disabled
+in the dialog box:</li>
+
+\image html gen_group_disabled.png "Disabled option in the Pipe Construction dialog if the path is closed"
+\n
+<li>Otherwise If the path is not closed edge/wire, the groups are created depending
+on the profile:</li>
+<ul>
+<li>Profile is unclosed edge or wire: \b Down, \b Up, \b Side1, \b Side2:</li>
+
+\image html gen_group_sides.png "Pipe with created groups Down(Red), Up(Green), Side1(Blue) and Side2(Yellow)"
+\n
+<li>Profile is closed edge or wire, face or shell: \b Down, \b Up, \b Other:</li>
+
+\image html gen_group_other.png "Created groups Down(Red), Up(Green) and Other(Yellow)"
+</ul>
+</ul>
+
+\b Down and \b Up groups contain:
+- Edges if the profile is edge or wire;
+- Faces if the profile is face or shell.
+
+\b Side1 and \b Side2 groups contain edges generated from the first and
+last vertices of the profile edge or wire correspondingly. The first and
+last vertices are determined taking into account edge/wire orientation.
+
+\b Other group represents faces generated from the bounding edges of profile.
+
+The behavior in TUI is the following:
+- Each Python function that supports groups generation has a flag
+\b IsGenerateGroups which is equal to \b False by default.
+- If \b IsGenerateGroups is not set the groups are not created; the returned
+value is GEOM_Object that represents a result of the operation.
+- If \b IsGenerateGroups is set the operation returns a list of GEOM_Object.
+Its first element is a result, the remaining ones are the groups in the order:
+\b Down, \b Up, \b Side1, \b Side2 for opened profile or \b Down, \b Up,
+\b Other for closed profile.
+- If \b IsGenerateGroups is set and the path is closed an error occurs.
+
+*/