Issue #19114: complete documentation of boolean operations

* Improve the documentation of Boolean Operations.
* Clarify the arguments of each operation.

diff --git a/doc/gui/index.rst.in b/doc/gui/index.rst.in
index 0f549fd301307e7f404f3aab1fbe1dce027c84b7..bde9f74766aa7f155ad5d0cd82f06c48129bbe95 100644 (file)
--- a/doc/gui/index.rst.in
+++ b/doc/gui/index.rst.in
@@ -8,7 +8,7 @@ Welcome to SHAPER documentation!
 
 .. toctree::
    :titlesonly:
-   :maxdepth: 2
+   :maxdepth: 3
 
    General/Introduction.rst
    General/Tutorial.rst

diff --git a/src/FeaturesPlugin/doc/FeaturesPlugin.rst b/src/FeaturesPlugin/doc/FeaturesPlugin.rst
index 9b06e64e5b4d0156206e1e0b1560eed7e034ed57..7f9ac37f7fccb0ecc72a39860f770b3e8a9bd108 100644 (file)
--- a/src/FeaturesPlugin/doc/FeaturesPlugin.rst
+++ b/src/FeaturesPlugin/doc/FeaturesPlugin.rst
@@ -8,25 +8,21 @@ Features plug-in provides a set of common topological operations. It implements
 
 .. toctree::
    :titlesonly:
-   :maxdepth: 1
+   :maxdepth: 2
 
+   booleanOperations.rst
    angularCopyFeature.rst
    chamferFeature.rst
-   commonFeature.rst
    copyFeature.rst
-   cutFeature.rst
    defeaturingFeature.rst
    extrusionCutFeature.rst
    extrusionFeature.rst
    extrusionFuseFeature.rst
    filletFeature.rst
-   fuseFeature.rst
    fuseFeatureFaces.rst
    importResultFeature.rst
-   intersectionFeature.rst
    linearCopyFeature.rst
    measurementFeature.rst
-   partitionFeature.rst
    pipeFeature.rst
    placementFeature.rst
    recoverFeature.rst
@@ -35,9 +31,6 @@ Features plug-in provides a set of common topological operations. It implements
    revolutionFeature.rst
    revolutionFuseFeature.rst
    rotationFeature.rst
-   smashFeature.rst
-   splitFeature.rst
    symmetryFeature.rst
    transformationFeature.rst
    translationFeature.rst
-   unionFeature.rst

diff --git a/src/FeaturesPlugin/doc/booleanArguments.rst b/src/FeaturesPlugin/doc/booleanArguments.rst
new file mode 100644 (file)
index 0000000..ad2f3c3
--- /dev/null
+++ b/src/FeaturesPlugin/doc/booleanArguments.rst
@@ -0,0 +1,70 @@
+.. |common.icon|    image:: images/bool_common.png
+   :height: 16px
+.. |cut.icon|    image:: images/bool_cut.png
+   :height: 16px
+.. |fuse.icon|    image:: images/bool_fuse.png
+   :height: 16px
+.. |smash.icon|    image:: images/bool_smash.png
+   :height: 16px
+.. |split.icon|    image:: images/bool_split.png
+   :height: 16px
+.. |partition.icon|    image:: images/partition_btn.png
+   :height: 16px
+.. |inter.icon|    image:: images/intersection_btn.png
+   :height: 16px
+.. |union.icon|    image:: images/union_btn.png
+   :height: 16px
+
+
+.. _bopArguments:
+
+Arguments of Boolean Operations
+===============================
+
+This section describes the shapes applicable as arguments of Boolean Operations.
+First of all, the result of Boolean Operations depends on the dimension of arguments. The following table shows the dimension and corresponding types of shapes.
+
++-----------+----------------------------+
+| Dimension | Shape types                |
++===========+============================+
+|     0     | VERTEX, COMPOUND           |
++-----------+----------------------------+
+|     1     | EDGE, WIRE, COMPOUND       |
++-----------+----------------------------+
+|     2     | FACE, SHELL, COMPOUND      |
++-----------+----------------------------+
+|     3     | SOLID, COMPSOLID, COMPOUND |
++-----------+----------------------------+
+
+*Note*: COMPOUND may consist of any shape combinations, therefore, it is present is each row.
+
+The next table aligns an operation and the dimensions of its arguments.
+Construction planes (mentioned PLANE) can be used in several operations, but not included in the table above due to their infinite nature. 
+
++-------------------------+---------------------------+-------------------------+
+|      Operation          | Dimension of objects (DO) | Dimension of tools (DT) |
++=========================+===========================+=========================+
+| |common.icon|           |            Any            |      Any (+ PLANE)      |
+| :ref:`featureCommon`    |                           |                         |
++-------------------------+---------------------------+-------------------------+
+| |cut.icon|              |            Any            |  Not less than **DO**   |
+| :ref:`featureCut`       |                           |                         |
++-------------------------+---------------------------+-------------------------+
+| |fuse.icon|             |            Any            |          Any            |
+| :ref:`featureFuse`      |                           |                         |
++-------------------------+---------------------------+-------------------------+
+| |inter.icon|            |          1 or 2           |          ---            |
+| :ref:`featureIntersect` |                           |                         |
++-------------------------+---------------------------+-------------------------+
+| |partition.icon|        |       Any (+ PLANE)       |          ---            |
+| :ref:`featurePartition` |                           |                         |
++-------------------------+---------------------------+-------------------------+
+| |smash.icon|            | 2 (planar FACE only) or 3 |    Equal to **DO**      |
+| :ref:`featureSmash`     |                           |                         |
++-------------------------+---------------------------+-------------------------+
+| |split.icon|            |            Any            |      Any (+ PLANE)      |
+| :ref:`featureSplit`     |                           |                         |
++-------------------------+---------------------------+-------------------------+
+| |union.icon|            | 3 (SOLIDs from COMPSOLID) |          ---            |
+| :ref:`featureUnion`     |                           |                         |
++-------------------------+---------------------------+-------------------------+

diff --git a/src/FeaturesPlugin/doc/booleanOperations.rst b/src/FeaturesPlugin/doc/booleanOperations.rst
new file mode 100644 (file)
index 0000000..20a2268
--- /dev/null
+++ b/src/FeaturesPlugin/doc/booleanOperations.rst
@@ -0,0 +1,19 @@
+
+.. _booleanOperations:
+
+Boolean Operations
+==================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   commonFeature.rst
+   cutFeature.rst
+   fuseFeature.rst
+   intersectionFeature.rst
+   partitionFeature.rst
+   smashFeature.rst
+   splitFeature.rst
+   unionFeature.rst
+   booleanArguments.rst

diff --git a/src/FeaturesPlugin/doc/commonFeature.rst b/src/FeaturesPlugin/doc/commonFeature.rst
index 5216539fe740a9d63ccdd28b5dbd70892a5af50b..a63df77cde3807f9e462a5357456a6521d85a149 100644 (file)
--- a/src/FeaturesPlugin/doc/commonFeature.rst
+++ b/src/FeaturesPlugin/doc/commonFeature.rst
@@ -72,10 +72,12 @@ Advanced
 - **Objects** contains a list of objects selected in the Object Browser or in the Viewer.
   If a subshape that belongs to a compsolid/compound was selected, other shapes of this compsolid/compound will be cut from
   other objects (to avoid self-intersection) and added to the result.
-- **Tools** contains a list of objects selected in the Object Browser or in the Viewer, which will be fused with tool objects.
-  If a subshape that belongs to a compsolid/compound was selected, other shapes of this compsolid/compound  will be ignored.
+- **Tools** contains a list of objects selected in the Object Browser or in the Viewer, which will be intersected with tool objects.
+  If a subshape that belongs to a compsolid/compound was selected, other shapes of this compsolid/compound will be ignored.
 - **See preview** button shows a result of the operation.
 
+Any kind of shape is supported as an object or a tool of Common. Moreover, constructions planes can be selected as tools.
+
 **TUI Command**:
 
 .. py:function:: model.addCommon(Part_doc, objects, tools)

diff --git a/src/FeaturesPlugin/doc/cutFeature.rst b/src/FeaturesPlugin/doc/cutFeature.rst
index 08e87586c25df7ccdc1c98f917e262069a6c4115..9ce390dbedba97e2dc95eb56f0d5f133f23368d9 100644 (file)
--- a/src/FeaturesPlugin/doc/cutFeature.rst
+++ b/src/FeaturesPlugin/doc/cutFeature.rst
@@ -1,7 +1,8 @@
-.. _featureCut:
 .. |bool_cut.icon|    image:: images/bool_cut.png
    :height: 16px
 
+.. _featureCut:
+
 Cut
 ===
 
@@ -27,6 +28,8 @@ The following property panel will be opened:
   Non-selected subshapes from compsolids/compounds will be ignored.
 - **See preview** button shows a result of the operation.
 
+The minimal dimension of Tool Objects should be not less than the maximal dimension of Main Objects.
+
 **TUI Command**:
 
 .. py:function:: model.addCut(Part_doc, mainObjects, toolObjects)

diff --git a/src/FeaturesPlugin/doc/fuseFeature.rst b/src/FeaturesPlugin/doc/fuseFeature.rst
index 3ff61a580c4d39d7fd537d39df89ab052f44eb70..e9fb6962038e9fab32b94eec145cfda863177b08 100644 (file)
--- a/src/FeaturesPlugin/doc/fuseFeature.rst
+++ b/src/FeaturesPlugin/doc/fuseFeature.rst
@@ -1,6 +1,8 @@
 .. |bool_fuse.icon|    image:: images/bool_fuse.png
    :height: 16px
 
+.. _featureFuse:
+
 Fuse
 ====
 
@@ -35,8 +37,8 @@ Simple
 
    **Simple**
 
-- **Objects** - contains a list of objects selected in the Object Browser or in the Viewer, which will be fused with tool objects.
-  If a subshape that belongs to a compsolid/compound was selected, other shapes of this compsolid/compound will be ignored.
+- **Objects** - contains a list of objects selected in the Object Browser or in the Viewer, which will be fused to a single result.
+  If a subshape that belongs to a compsolid/compound was selected, other shapes of this compsolid/compound will cut the fuse shape then will be joined to the result.
 - **Remove intersection edges** -  if enabled, edges that lie on the same surface will be removed.
 - **See preview** - button shows a result of the operation.
 

diff --git a/src/FeaturesPlugin/doc/intersectionFeature.rst b/src/FeaturesPlugin/doc/intersectionFeature.rst
index 6a3b5a67b40d615f71903761e29da278f7bba8d5..e4057a2d56d59162bb03ba492c9b4319fdbde5ce 100644 (file)
--- a/src/FeaturesPlugin/doc/intersectionFeature.rst
+++ b/src/FeaturesPlugin/doc/intersectionFeature.rst
@@ -1,5 +1,7 @@
 .. |intersection_btn.icon|    image:: images/intersection_btn.png
 
+.. _featureIntersect:
+
 Intersection
 ============
 
@@ -19,6 +21,8 @@ The following property panel will be opened:
 
 **Objects** - contains a list of objects selected in the Object Browser or in the Viewer, which will be intersected.
 
+All intersected objects should be 1- or 2-dimensional (edges, faces, shells). However, it is allowed to select 3-dimensional objects, but only their shells will be taken into operation.
+
 **TUI Command**:
 
 .. py:function:: model.addIntersection(Part_doc, Objects)

diff --git a/src/FeaturesPlugin/doc/partitionFeature.rst b/src/FeaturesPlugin/doc/partitionFeature.rst
index 14ee70b44e4bc4c21cc6ed318b4f8d0f7cdffb37..e549310d23a91213349f9609d1977891f1aad81c 100644 (file)
--- a/src/FeaturesPlugin/doc/partitionFeature.rst
+++ b/src/FeaturesPlugin/doc/partitionFeature.rst
@@ -1,5 +1,7 @@
 .. |partition_btn.icon|    image:: images/partition_btn.png
 
+.. _featurePartition:
+
 Partition
 =========
 
@@ -17,7 +19,7 @@ The following property panel will be opened:
 
    **Partition operation**
 
-**Base Objects** contains a list of objects selected in the Object Browser or in the Viewer, which will be partitioned.
+**Base Objects** contains a list of objects selected in the Object Browser or in the Viewer, which will be partitioned. Constuction planes are allowed too if at least one non-construction entity is selected.
 
 **TUI Command**:
 

diff --git a/src/FeaturesPlugin/doc/smashFeature.rst b/src/FeaturesPlugin/doc/smashFeature.rst
index 08dfc9ebeda5b1d52ccabb2813e9da92cec49f9a..2e3b45828ab3cf0674d2fce36972cb2afc3ffc1a 100644 (file)
--- a/src/FeaturesPlugin/doc/smashFeature.rst
+++ b/src/FeaturesPlugin/doc/smashFeature.rst
@@ -1,6 +1,8 @@
 .. |bool_smash.icon|    image:: images/bool_smash.png
    :height: 16px
 
+.. _featureSmash:
+
 Smash
 =====
 
@@ -25,6 +27,8 @@ The following property panel will be opened:
   If a subshape that belongs to a compsolid/compound was selected, other shapes of this compsolid/compound will be ignored.
 - **See preview** button shows a result of the operation.
 
+Main objects and Tools objects should have the same dimension. There are supported 2-dimensional (face) or 3-dimensional (solid, compsolid) arguments.
+
 **TUI Command**:
 
 .. py:function:: model.addSmash(Part_doc, mainObjects, toolObjects)

diff --git a/src/FeaturesPlugin/doc/splitFeature.rst b/src/FeaturesPlugin/doc/splitFeature.rst
index ec962928e973fbf711a10be03954b2c73553c313..61970dcd596df7e8c9e09443c7426ee6cdd67e27 100644 (file)
--- a/src/FeaturesPlugin/doc/splitFeature.rst
+++ b/src/FeaturesPlugin/doc/splitFeature.rst
@@ -1,6 +1,8 @@
 .. |bool_split.icon|    image:: images/bool_split.png
    :height: 16px
 
+.. _featureSplit:
+
 Split
 =====
 
@@ -19,7 +21,7 @@ The following property panel will be opened:
    **Split operation**
 
 - **Main Objects** contains a list of objects selected in the Object Browser or in the Viewer, which will be cut and splitted by tool objects.
-- **Tool Objects** contains a list of objects selected in the Object Browser or in the Viewer, which will cut and split the main objects.
+- **Tool Objects** contains a list of objects selected in the Object Browser or in the Viewer, which will cut and split the main objects. Construction planes may be selected too.
 - **See preview** button shows a result of the operation.
 
 **TUI Command**:

diff --git a/src/FeaturesPlugin/doc/unionFeature.rst b/src/FeaturesPlugin/doc/unionFeature.rst
index 989e9368477b16828be907694cf6a4171f46bf79..9847642861d1b33872d3dba9a5149dc500796708 100644 (file)
--- a/src/FeaturesPlugin/doc/unionFeature.rst
+++ b/src/FeaturesPlugin/doc/unionFeature.rst
@@ -1,8 +1,12 @@
 .. |union_btn.icon|    image:: images/union_btn.png
 
+.. _featureUnion:
+
 Union
 =====
 
+**Caution**. This operation is obsolete. Fuse operation should be used instead.
+
 Union feature implements a Boolean operation for creation of a union of selected objects.
 
 To create a Union in the active part: