/*!

\page partition_page Partition

To produce a \b Partition in the <b>Main Menu</b> select <b>Operations - > Partition</b>

This operation builds a compound by intersection of several shapes
with a set of tool objects or with a plane.
The \b Result will be \b GEOM_Object.

<br><h2>Intersection of two shapes.</h2>

\image html partition1.png

<b>Arguments:</b> Name + 2 lists of shapes (the shapes from the
first list will be intersected with the shapes from the second list) +
Resulting Type of shape.

As far as the intersection of two objects can produce any type of
geometrical objects, <b>Resulting type</b> box allows choosing the
preferrable result, i.e. a solid, a shell, a list of faces, etc.

<b>Resulting type</b> has to be equal or lower than the type of the
\em Objects. In other words, if the \em Objects don't contain any
shape of this type, Partition fails.

<b>Keep shapes of lower type</b> checkbox manages standalone shapes of
type other than the \em Limit. If it is checked, lower dimension
objects will be preserved, else they will be lost.

For example, you do a partition of a box (Solid) and a face (Face)
without any tool. If you choose Resulting Type "Solid", you will
obtain a compound of two solids (let's the box will be splitted by the
face on two parts), but if you will also check <b>Keep shapes of lower
type</b> checkbox, you will obtain a compound of two solids and one
face (the face will have a hole where the original face lays inside
the box, see corresponding \ref partition_picture_3 "picture" below).

<b>No sub-shapes intersection (Compounds only)</b> check box affects only input shapes
of the Compound type. If this option is switched off (default
behavior) each input compound will be automatically exploded to the
sub-shapes and intersection between those shapes will be also
computed. If this option is switched on, the intersection between
sub-shapes will be not performed. In this case the Partition algorithm
will work faster, but result might differ from the default behavior.

 <b>Advanced option:</b>
   \ref restore_presentation_parameters_page "Set presentation parameters and subshapes from arguments".

\note Partition is a kind of complex operation, result of it depends
      on the initial shapes quality. Sometimes, if partition fails,
      some healing operations could help. Try <b>Shape Processing</b>
      and <b>Limit Tolerance</b> in such cases. See also \ref
      tui_limit_tolerance "TUI example" of shape healing.

<b>TUI Command (with sub-shapes intersection):</b>

<em>geompy.MakePartition(ListOfShapes, ListOfTools, ListOfKeepInside,
ListOfRemoveInside, Limit, RemoveWebs, ListOfMaterials,
KeepNonlimitShapes)</em>

<b>TUI Command (no sub-shapes intersection):</b>

<em>geompy.MakePartitionNonSelfIntersectedShape(ListOfShapes,
ListOfTools, ListOfKeepInside, ListOfRemoveInside, Limit, RemoveWebs,
ListOfMaterials, KeepNonlimitShapes)</em>

Here,
- \em ListOfShapes is a list of shapes to be intersected
- \em ListOfTools is a list of shapes to intersect the shapes from
ListOfShapes
- \em Limit is a Type of resulting shapes and \em KeepNonlimitShapes
is a flag that allows to preserve standalone shapes of low dimension
(than \em Limit) in the result.
- Other parameters are obsolete and kept only for compatibility with
previous versions of SALOME.

<br><h2>Intersection of a Shape and a Plane.</h2>

\image html partition2.png

<b>Arguments:</b> Name + 1 shape to be intersected + 1 cutting plane.

<b>Advanced option:</b>
\ref restore_presentation_parameters_page "Set presentation parameters and subshapes from arguments".

<b>TUI Command:</b>

<em>geompy.MakeHalfPartition(Shape, Plane)</em> where
- \em Shape is a source shape to be intersected by \em Plane
- \em Plane is a tool shape, to intersect the \em Shape.

<b>Example:</b>

\image html partitionsn1.png "Box intersected by a plane"

\image html partitionsn2.png "Result of intersection"

\anchor partition_picture_3
\image html partitionsn3.png "Result of intersection of a box and a plane (both as \em Objects, no tools) with Resulting type \em Solid and checked \em Keep \em shapes \em of \em lower \em type"

Our <b>TUI Scripts</b> provide you with useful examples of the use of
\ref tui_partition "Basic Operations".

*/