From: Artem Zhidkov Date: Wed, 20 May 2020 08:40:22 +0000 (+0300) Subject: Issue #19114: complete documentation of boolean operations X-Git-Tag: V9_5_0rc1~48 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=5e433555b13ebad9a62b6c92f64d5c5f5899935c;p=modules%2Fshaper.git 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 0f549fd30..bde9f7476 100644 --- 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 9b06e64e5..7f9ac37f7 100644 --- 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 index 000000000..ad2f3c307 --- /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 index 000000000..20a2268c7 --- /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 5216539fe..a63df77cd 100644 --- 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 08e87586c..9ce390dbe 100644 --- 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 3ff61a580..e9fb69620 100644 --- 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 6a3b5a67b..e4057a2d5 100644 --- 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 14ee70b44..e549310d2 100644 --- 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 08dfc9ebe..2e3b45828 100644 --- 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 ec962928e..61970dcd5 100644 --- 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 989e93684..984764286 100644 --- 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: