src/FiltersPlugin/doc/FiltersPlugin.rst

   1 .. |plus.icon|    image:: images/add.png
   2 .. |minus.icon|   image:: images/reverce.png
   3 .. |delete.icon|  image:: images/delete.png
   4
   5
   6 .. _filtersPlugin:
   7
   8 Filters plug-in
   9 ===============
  10
  11 Filters plug-in provides a collection of filters used Filters property panel (for example see :ref:`groupPage` feature).
  12
  13
  14 **Selection filters**
  15
  16 Selection by filters panel looks like following:
  17
  18 .. figure:: images/selection_by_filters.png
  19   :align: center
  20
  21   Selection by filters property panel
  22
  23 In this panel:
  24
  25 - **Filters** a panel for added filters.
  26
  27 - **Add new filter** combo box. It contains accessible filters according to the selection mode. When user selects an item from this combo box a filter item appears in **Filters** panel like in the following example:
  28
  29 .. figure:: images/selection_by_filters_added.png
  30   :align: center
  31
  32   Filters **Horizontal faces** and **On plane** added to the property panel.
  33
  34 If filter is implemented as "Multiple", several instances of this filter may be added in one selection. Otherwise the added filter is removed from the "Add new filter..." list.
  35
  36 Each filter item can be deleted with help of |delete.icon| button. A filter can be reverced with help of toggle button |plus.icon|/|minus.icon|. Also a filter could have input fields in case
  37 if the filter has arguments.
  38
  39 - **Select** button traverces all objects of a current document and selects entities acceptable by currently defined set of filters. All selected entities will be shown in viewer 3d with
  40   blue semi-transparent color. Any modification in filters clears current selection.
  41
  42 - **Number of selected objects** shows number currently selected entities.
  43
  44 - **Show only** check box hides all non-selected objects.
  45
  46 **Accept** button in the **Selection filters** property panel reopens a property panel where the **selection filters** was called and transfers all selected entities to the corresponded list.
  47
  48
  49 Filters
  50 -------
  51
  52 **Belongs to**
  53
  54 By default, the result of Selection feature all selectable entities from all Shapes registered in the “Results” folder. This filter provides a way to explicit (restrict) the results in which looking for selectable entities.
  55
  56 - **Result type:** Any
  57 - **Argument:** Any result object, multiple OR selection accepted
  58 - **Algorithm:** Returns only shapes that belong to selected results.
  59
  60 **Edge size**
  61
  62 - **Result type:** Edge
  63 - **Argument:**
  64     - **Comparator:** <, <=, >, >=, is between, is strictly between
  65     - **Size** or  **Min size** and **Max size**
  66 - **Algorithm:** Returns all edges whose length respect comparator rules.
  67
  68 **Face size**
  69
  70 - **Result type:** Face
  71 - **Argument:**
  72     - **Comparator:** <, <=, >, >=, is between, is strictly between
  73     - **Size** or  **Min size** and **Max size**
  74 - **Algorithm:** Returns all faces whose area respect comparator rules.
  75
  76 **Volume size**
  77
  78 - **Result type:** Solid
  79 - **Argument:**
  80     - **Comparator:** <, <=, >, >=, is between, is strictly between
  81     - **Size** or  **Min size** and **Max size**
  82 - **Algorithm:** Returns all solids whose volume respect comparator rules.
  83
  84 **Feature edges**
  85
  86 This algorithm identifies edges between two faces discontinuous with an angular tolerance.
  87
  88 - **Result type:** Edge
  89 - **Argument:**
  90     - **Angle** an angular tolerance used by G1 continuity criterion for comparing the angle between the normals
  91 - **Algorithm:** Returns all edges between two discontinuous faces.
  92
  93 **On a plane**
  94
  95 - **Result type:** Vertex, Edge, Face
  96 - **Argument:** Planar face or Construction plane, multiple OR selection accepted
  97 - **Algorithm:** Returns all vertices, edges or planar faces geometrically located on (co-planar) the given plane.
  98
  99 **On a Line**
 100
 101 - **Result type:** Vertex, Edge
 102 - **Argument:** Straight Edge or Construction axis, multiple OR selection accepted
 103 - **Algorithm:** Returns all vertices coincident or all edges collinear to the given line.
 104
 105 **On geometry**
 106
 107 - **Result type:** Any
 108 - **Argument:** Any Shape, multiple OR selection accepted
 109 - **Algorithm:** Returns the shapes which have the similar underlying geometry of the given Shape. Like all faces laying of the same geometrical surface or edges laying on the line.
 110
 111 **On plane side**
 112
 113 - **Result type:** Any
 114 - **Argument:** Planar face or Construction plane
 115 - **Algorithm:** By default, the side is in direction of normal of the given plane. For getting the other side, simply invert the filter by clicking on the Check button.
 116
 117 **Opposite to an edge**
 118
 119 This algorithm is based on the Propagate geompy function. It works on a model partitioned into quadrangular faces blocks for the purpose of hexahedral meshing.
 120
 121 - **Result type:** Edge
 122 - **Argument:** An edge belonging to a quadrangular face
 123 - **Algorithm:** Returns all Edges opposite to the given Edge on all quadrangular faces connected to this Edge. The algorithm is recursive: after an edge is found on one face, it adds edges opposite to this new one.
 124
 125 **Continuous Faces**
 126
 127 This algorithm identifies continuous faces with an angular tolerance given by topological propagation.
 128
 129 - **Result type:** Face
 130 - **Argument:**
 131     - **Angle:** an angular tolerance used by G1 continuity criterion for comparing the angle between the normals.
 132     - **Faces:** Faces to start the propagation.
 133 - **Algorithm:** Returns continuous faces.
 134
 135 **On/In/Out a Solid**
 136
 137 This algorithm reproduces the GetShapesOnShape function of geompy.
 138
 139 - **Result type:** Vertex, Edge or Face
 140 - **Arguments:** Solid. Location according to the given Solid, as described below
 141 - **Algorithm:**
 142     - **In:** strictly inside the solid.
 143     - **Not In:** strictly outside the solid.
 144     - **On:** confused with the boundary of the solid
 145     - **Not On:** strictly inside or outside the solid
 146     - **In & On:** i.e. inside or confused with the boundary of the solid
 147     - **Not In & On:** outside or confused with the boundary of the solid.
 148
 149 **External Faces**
 150
 151 This algorithm finds all not-shared faces.
 152
 153 - **Result type:** Face
 154 - **Arguments:** None
 155 - **Algorithm:** Returns all faces which are not shared between higher level shapes of the connected compound of the connected compound of compsolid. For an example, if there is a compsolid of two boxes with one shared face between them, the filter returns all faces except the shared.
 156
 157 **Horizontal Faces**
 158
 159 This algorithm finds all the horizontal faces of the model.
 160
 161 - **Result type:** Face
 162 - **Arguments:** None
 163 - **Algorithm:** Returns only planar faces with normal of the plane perpendicular to OZ.
 164
 165 **Vertical Faces**
 166
 167 This algorithm finds all the vertical faces of the model.
 168
 169 - **Result type:** Face
 170 - **Arguments:** None
 171 - **Algorithm:** Returns only planar faces with normal of the plane parallel to OZ or cylindrical faces with axis parallel to OZ.
 172
 173 **Topologically connected Faces**
 174
 175 This algorithm finds all the faces topologically connected the argument selected by the user.
 176
 177 - **Result type:** Face
 178 - **Arguments:** A point, an edge or a face. A “propagation” flag (check-box).
 179 - **Algorithm:**
 180     - If a point of an edge is selected as an argument, the result is all faces that contain this argument.If a face is selected, the result is all faces that have shared edges or vertices with this selection.
 181     - If “propagation” flag is enabled (it is disabled by default), the algorithm becomes recursive: all connected faces are added to the results. So, for the solid shape there will be all faces except internal-volumes faces, not connected to any external faces.
 182
 183 **Shape name**
 184
 185 - **Result type:** Any
 186 - **Arguments:** A regular expression value, representing a pattern for searching by result name. The search pattern must comply with the rules of regular expressions.
 187 - **Algorithm:**
 188     - Returns objects or subobjects of results where their name matches the given search pattern (regular expression).
 189     - For example, if we have in the result a shape with the name “cube” and we want to select all the edges according to the pattern "cube", then we will get all the edges of the objects containing "cube" in their name.
 190     - The filter searches not only for complete matches but for any pattern inclusions.
 191
 192 - **Examples:**
 193     - Selecting all edges belonging to objects from the result with a name starting with "Cyl".
 194     .. figure:: images/selection_byShapeName1.png
 195       :align: center
 196
 197     - Selecting all vertices belonging to objects from the result with a name containing pattern "Cube".
 198     .. figure:: images/selection_byShapeName2.png
 199       :align: center
 200
 201     - Selecting all results with names containing "Poutre", followed by a space and a digit.
 202     .. figure:: images/selection_byShapeName3.png
 203       :align: center
 204