.. role:: blue
   :class: blue

Splitting Body Faces
====================
.. _Splitting_Body_Faces_:

.. kernel version: 118044

The function

.. code-block:: cpp

   MbResultType SplitSolid(       MbSolid &                    solid,
                                  MbeCopyMode                  sameShell,
                            const RPArray<MbSpaceItem> &       spItems,
                                  bool                         spSame,
                                  RPArray<MbFace> &            selFaces,
                            const MbMergingFlags &             flags,
                            const MbSNameMaker &               names,
                                  MbSolid *&                   result );

splits the specified body faces with spatial curves, surfaces and shells. The spatial splitting elements must not have full or partial overlaps and self-intersections.

The input parameters of the function are:

- **solid** - the source body;
- **sameShell** - a copy mode for the source body;
- **spItems** - spatial splitting elements of faces;
- **spSame** - the flag controlling use of spatial splitting elements;
- **selFaces** - the set of faces to be split;
- **flags** - flags controlling merging of shell elements;
- **names** - a name maker.

The output parameter of the function is the constructed body **result**.

The function returns a result code from the :ref:`MbResultType <MbResultType_>` enumeration.

The function is declared in the file *action_solid.h*.

The function splits the specified faces **selFaces** of the source body
**solid** with spatial objects **spItems**, if the specified faces intersect these objects.
The objects in **spItems** may be curves, surfaces, or a solid.

For successful operation, cutting objects must fully intersect the specified faces of the source body.

Parameter **sameShell** controls the transfer of faces, edges and vertices from the source body **solid** to the constructed body **result** and may take one of four values:

- *cm_Same = 0* (shell is not copied);
- *cm_KeepHistory* (the source shell and its copy share common base surfaces, vertices, and faces unchanged by the operation);
- *cm_KeepSurface* (the source shell and its copy share common base surfaces);
- *cm_Copy* (the source shell and its copy have no shared data).

Enumeration :blue:`MbeCopyMode` is described in section :ref:`Copying a Set of Faces MbFaceShell <Copying_a_Set_of_Faces_>`.

The parameter **spSame** controls copying of spatial splitting elements
(*true* -- use originals, *false* -- use copies).

Parameter **flags** controls merging of shell elements after splitting:

- **flags**.\ *mergeFaces* = *true* -- merge geometrically similar faces arising as a result of splitting;
- **flags**.\ *mergeEdges* = *true* -- merge geometrically similar edges.

The parameter **names** provides naming of the faces, edges, and vertices of the constructed body.

Fig. 1 shows the source body **solid**, the faces for splitting **selFaces**, and the cutting surface **spItems**\[0\].

.. figure:: /MODELER/OPERATIONS_ON_BODIES/pictures/M.2.21.1.png
   :width: 12cm
   :align: center

   Fig. 1

Fig. 2 shows the constructed body **result** with faces split
into parts. New edges return *true* when queried with :blue:`MbEdge`\:::blue:`IsSplit`\().

In Fig. 3, the split faces of the constructed body
are painted in different colors:

.. figure:: /MODELER/OPERATIONS_ON_BODIES/pictures/M.2.21.2.png
   :width: 12cm
   :align: center

   Fig. 2

.. figure:: /MODELER/OPERATIONS_ON_BODIES/pictures/M.2.21.3.png
   :width: 12cm
   :align: center

   Fig. 3

The function

.. code-block:: cpp

   MbResultType SplitSolid(       MbSolid &                    solid,
                                  MbeCopyMode                  sameShell,
                            const MbPlacement3D &              spPlace,
                                  MbeSenseValue                spType,
                            const RPArray<MbContour> &         spContours,
                                  bool                         spSame,
                                  RPArray<MbFace> &            selFaces,
                            const MbMergingFlags &             flags,
                            const MbSNameMaker &               names,
                                  MbSolid *&                   result );

performs the same operations as the function considered above with the difference
that instead of splitting objects **spItems**, the splitting of the body
**solid** faces is performed by surfaces constructed by extrusion
of two-dimensional contours **spContours** located in the XY plane
of the local coordinate system **spPlace**. Extrusion of contours
is performed in the direction of the **spPlace**.\ *axisZ* axis of the local coordinate
system for a length sufficient to fully intersect the source
body.

Functions :blue:`SplitSolid`\() add to the history log of the constructed body
the builder :blue:`MbSplitShell`, which contains all necessary data for
performing the operation. The builder :blue:`MbSplitShell` is declared in the file
*cr_split_shell.h*.

In the test application *test.exe*, splitting of the specified body faces is performed
by the menu command «Create → Solid → By faces processing → Face splitting».