Salome HOME
Fix Redesign of SMESH documentation
[modules/smesh.git] / doc / salome / gui / SMESH / input / tui_filters.rst
1 .. _tui_filters_page:
2
3 *************
4 Filters usage
5 *************
6
7 Filters allow picking only the mesh elements satisfying to a
8 specific condition or a set of conditions. Filters can be used to create
9 or edit mesh groups, remove elements from the mesh, control
10 mesh quality by different parameters, etc.
11
12 Several filtering criteria can be combined together by using logical
13 operators *AND* and *OR*. In addition, a filtering criterion can
14 be reverted using logical operator *NOT*.
15
16 Mesh filters can use the functionality of mesh quality controls to filter
17 mesh nodes / elements by a specific characteristic (Area, Length, etc).
18
19 This page provides a short description of the existing mesh filters,
20 describes required parameters and gives simple examples of usage in
21 Python scripts.
22
23 **See also:** :ref:`tui_quality_controls_page`
24
25 .. contents:: `Table of contents`
26
27
28 .. _filter_aspect_ratio:
29
30 Aspect ratio
31 ============
32
33 filters 2D mesh elements (faces) according to the aspect ratio value:
34
35 * element type should be *SMESH.FACE*
36 * functor type should be *SMESH.FT_AspectRatio*
37 * threshold is floating point value (aspect ratio)
38
39 .. literalinclude:: ../../../examples/filters_ex01.py
40     :linenos:
41     :language: python
42
43 :download:`Download this script <../../../examples/filters_ex01.py>`
44
45 **See also:** :ref:`tui_aspect_ratio`
46
47 .. _filter_aspect_ratio_3d:
48
49 Aspect ratio 3D
50 ===============
51
52 filters 3D mesh elements (volumes) according to the aspect ratio value:
53
54 * element type is *SMESH.VOLUME*
55 * functor type is *SMESH.FT_AspectRatio3D*
56 * threshold is floating point value (aspect ratio)
57
58 .. literalinclude:: ../../../examples/filters_ex02.py
59     :linenos:
60     :language: python
61
62 :download:`Download this script <../../../examples/filters_ex02.py>`
63
64 **See also:** :ref:`tui_aspect_ratio_3d`
65
66 .. _filter_warping_angle:
67
68 Warping angle
69 =============
70
71 filters 2D mesh elements (faces) according to the warping angle value:
72
73 * element type is *SMESH.FACE*
74 * functor type is *SMESH.FT_Warping*
75 * threshold is floating point value (warping angle)
76
77 .. literalinclude:: ../../../examples/filters_ex03.py
78     :linenos:
79     :language: python
80
81 :download:`Download this script <../../../examples/filters_ex03.py>`
82
83 **See also:** :ref:`tui_warping`
84
85 .. _filter_minimum_angle:
86
87 Minimum angle
88 =============
89
90 filters 2D mesh elements (faces) according to the minimum angle value:
91
92 * element type is *SMESH.FACE*
93 * functor type is *SMESH.FT_MinimumAngle*
94 * threshold is floating point value (minimum angle)
95
96 .. literalinclude:: ../../../examples/filters_ex04.py
97     :linenos:
98     :language: python
99
100 :download:`Download this script <../../../examples/filters_ex04.py>`
101
102 **See also:** :ref:`tui_minimum_angle`
103
104 .. _filter_taper: 
105
106 Taper
107 =====
108
109 filters 2D mesh elements (faces) according to the taper value:
110
111 * element type is *SMESH.FACE*
112 * functor type is *SMESH.FT_Taper*
113 * threshold is floating point value (taper)
114
115 .. literalinclude:: ../../../examples/filters_ex05.py
116     :linenos:
117     :language: python
118
119 :download:`Download this script <../../../examples/filters_ex05.py>`
120
121 **See also:** :ref:`tui_taper`
122
123 .. _filter_skew: 
124
125 Skew
126 ====
127
128 filters 2D mesh elements (faces) according to the skew value:
129
130 * element type is *SMESH.FACE*
131 * functor type is *SMESH.FT_Skew*
132 * threshold is floating point value (skew)
133
134 .. literalinclude:: ../../../examples/filters_ex06.py
135     :linenos:
136     :language: python
137
138 :download:`Download this script <../../../examples/filters_ex06.py>`
139
140 **See also:** :ref:`tui_skew`
141
142 .. _filter_area: 
143
144 Area
145 ====
146
147 filters 2D mesh elements (faces) according to the area value:
148
149 * element type is *SMESH.FACE*
150 * functor type is *SMESH.FT_Area*
151 * threshold is floating point value (area)
152
153 .. literalinclude:: ../../../examples/filters_ex07.py
154     :linenos:
155     :language: python
156
157 :download:`Download this script <../../../examples/filters_ex07.py>`
158
159 **See also:** :ref:`tui_area`
160
161 .. _filter_volume: 
162
163 Volume
164 ======
165
166 filters 3D mesh elements (volumes) according to the volume value:
167
168 * element type is *SMESH.VOLUME*
169 * functor type is *SMESH.FT_Volume3D*
170 * threshold is floating point value (volume)
171
172 .. literalinclude:: ../../../examples/filters_ex08.py
173     :linenos:
174     :language: python
175
176 :download:`Download this script <../../../examples/filters_ex08.py>`
177
178 **See also:** :ref:`tui_volume`
179
180 .. _filter_free_borders:
181
182 Free borders
183 ============
184
185 filters 1D mesh elements (edges) which represent free borders of a mesh:
186
187 * element type is *SMESH.EDGE*
188 * functor type is *SMESH.FT_FreeBorders*
189 * threshold value is not required
190
191 .. literalinclude:: ../../../examples/filters_ex09.py
192     :linenos:
193     :language: python
194
195 :download:`Download this script <../../../examples/filters_ex09.py>`
196
197 **See also:** :ref:`tui_free_borders`
198
199 .. _filter_free_edges:
200
201 Free edges
202 ==========
203
204 filters 2D mesh elements (faces) having edges (i.e. links between
205 nodes, not mesh segments) belonging to one face of mesh only:
206
207 * element type is *SMESH.FACE*
208 * functor type is *SMESH.FT_FreeEdges*
209 * threshold value is not required
210
211 .. literalinclude:: ../../../examples/filters_ex10.py
212     :linenos:
213     :language: python
214
215 :download:`Download this script <../../../examples/filters_ex10.py>`
216
217 **See also:** :ref:`tui_free_edges`
218
219 .. _filter_free_nodes:
220
221 Free nodes
222 ==========
223
224 filters free nodes:
225
226 * element type is *SMESH.NODE*
227 * functor type is *SMESH.FT_FreeNodes*
228 * threshold value is not required
229
230 .. literalinclude:: ../../../examples/filters_ex11.py
231     :linenos:
232     :language: python
233
234 :download:`Download this script <../../../examples/filters_ex11.py>`
235
236 **See also:** :ref:`tui_free_nodes`
237
238 .. _filter_free_faces: 
239
240 Free faces
241 ==========
242
243 filters free faces:
244
245 * element type is *SMESH.FACE*
246 * functor type is *SMESH.FT_FreeFaces*
247 * threshold value is not required
248
249 .. literalinclude:: ../../../examples/filters_ex12.py
250     :linenos:
251     :language: python
252
253 :download:`Download this script <../../../examples/filters_ex12.py>`
254
255 **See also:** :ref:`tui_free_faces`
256
257 .. _filter_bare_border_faces: 
258
259 Bare border faces
260 =================
261
262 filters faces with bare borders:
263
264 * element type is *SMESH.FACE*
265 * functor type is *SMESH.FT_BareBorderFace*
266 * threshold value is not required
267
268 .. literalinclude:: ../../../examples/filters_ex13.py
269     :linenos:
270     :language: python
271
272 :download:`Download this script <../../../examples/filters_ex13.py>`
273
274 **See also:** :ref:`tui_bare_border_faces`
275
276 .. _filter_coplanar_faces:
277
278 Coplanar faces
279 ==============
280
281 filters coplanar faces:
282
283 * element type is *SMESH.FACE*
284 * functor type is *SMESH.FT_CoplanarFaces*
285 * threshold value is the face ID
286 * tolerance is in degrees
287
288 .. literalinclude:: ../../../examples/filters_ex14.py
289     :linenos:
290     :language: python
291
292 :download:`Download this script <../../../examples/filters_ex14.py>`
293
294 .. _filter_over_constrained_faces: 
295
296 Over-constrained faces
297 ======================
298
299 filters over-constrained faces:
300
301 * element type is *SMESH.FACE*
302 * functor type is *SMESH.FT_OverConstrainedFace*
303 * threshold value is not required
304
305 .. literalinclude:: ../../../examples/filters_ex15.py
306     :linenos:
307     :language: python
308
309 :download:`Download this script <../../../examples/filters_ex15.py>`
310
311 **See also:** :ref:`tui_over_constrained_faces`
312
313 .. _filter_double_elements: 
314
315 Double edges, Double faces, Double volumes
316 ##########################################
317
318 filters mesh elements basing on the same set of nodes:
319
320 * element type is either *SMESH.EGDE*, *SMESH.FACE* or *SMESH.VOLUME*
321 * functor type is either *SMESH.FT_EqualEdges*, *SMESH.FT_EqualFaces* or *SMESH.FT_EqualVolumes*,
322 * threshold value is not required
323
324 .. literalinclude:: ../../../examples/filters_ex16.py
325     :linenos:
326     :language: python
327
328 :download:`Download this script <../../../examples/filters_ex16.py>`
329
330 .. _tui_double_nodes_control: 
331
332 Double nodes
333 ============
334
335 filters mesh nodes which are coincident with other nodes (within a given tolerance):
336
337 * element type is *SMESH.NODE*
338 * functor type is *SMESH.FT_EqualNodes*
339 * threshold value is not required
340 * default tolerance is 1.0e-7
341
342 .. literalinclude:: ../../../examples/filters_ex17.py
343     :linenos:
344     :language: python
345
346 :download:`Download this script <../../../examples/filters_ex17.py>`
347
348 .. _filter_node_nb_conn:
349
350 Node connectivity number
351 ========================
352
353 filters nodes according to a number of elements of highest dimension connected to a node:
354
355 * element type should be *SMESH.NODE*
356 * functor type should be *SMESH.FT_NodeConnectivityNumber*
357 * threshold is an integer value (number of elements)
358
359 .. literalinclude:: ../../../examples/filters_node_nb_conn.py
360     :linenos:
361     :language: python
362
363 :download:`Download this script <../../../examples/filters_node_nb_conn.py>`
364
365 .. _filter_borders_multiconnection: 
366
367 Borders at multi-connection
368 ===========================
369
370 filters 1D mesh elements (segments) according to the specified number of
371 connections (faces and volumes on whose border the segment lies):
372
373 * element type is *SMESH.EDGE*
374 * functor type is *SMESH.FT_MultiConnection*
375 * threshold is integer value (number of connections)
376
377 .. literalinclude:: ../../../examples/filters_ex18.py
378     :linenos:
379     :language: python
380
381 :download:`Download this script <../../../examples/filters_ex18.py>`
382
383 **See also:** :ref:`tui_borders_at_multiconnection`
384
385 .. _filter_borders_multiconnection_2d: 
386
387 Borders at multi-connection 2D
388 ==============================
389
390 filters 2D mesh elements (faces) with the specified maximal number of
391 faces connected to a border (link between nodes, not mesh segment):
392
393 * element type is *SMESH.FACE*
394 * functor type is *SMESH.FT_MultiConnection2D*
395 * threshold is integer value (number of connections)
396
397 .. literalinclude:: ../../../examples/filters_ex19.py
398     :linenos:
399     :language: python
400
401 :download:`Download this script <../../../examples/filters_ex19.py>`
402
403 **See also:** :ref:`tui_borders_at_multiconnection_2d`
404
405 .. _filter_length: 
406
407 Length
408 ======
409
410 filters 1D mesh elements (edges) according to the edge length value:
411
412 * element type should be *SMESH.EDGE*
413 * functor type should be *SMESH.FT_Length*
414 * threshold is floating point value (length)
415
416 .. literalinclude:: ../../../examples/filters_ex20.py
417     :linenos:
418     :language: python
419
420 :download:`Download this script <../../../examples/filters_ex20.py>`
421
422 **See also:** :ref:`tui_length_1d`
423
424 .. _filter_length_2d: 
425
426 Length 2D
427 =========
428
429 filters 2D mesh elements (faces) according to the maximum length of its
430 edges (links between nodes):
431
432 * element type should be *SMESH.FACE*
433 * functor type should be *SMESH.FT_Length2D*
434 * threshold is floating point value (edge length)
435
436 .. literalinclude:: ../../../examples/filters_ex21.py
437     :linenos:
438     :language: python
439
440 :download:`Download this script <../../../examples/filters_ex21.py>`
441
442 **See also:** :ref:`tui_length_2d`
443
444 .. _filter_max_element_length_2d: 
445
446 Element Diameter 2D
447 ===================
448
449 filters 2D mesh elements (faces) according to the maximum length
450 of its edges and diagonals:
451
452 * element type should be *SMESH.FACE*
453 * functor type should be *SMESH.FT_MaxElementLength2D*
454 * threshold is floating point value (length)
455
456 .. literalinclude:: ../../../examples/filters_ex22.py
457     :linenos:
458     :language: python
459
460 :download:`Download this script <../../../examples/filters_ex22.py>`
461
462 **See also:** :ref:`tui_max_element_length_2d`
463
464 .. _filter_max_element_length_3d: 
465
466 Element Diameter 3D
467 ===================
468
469 filters 3D mesh elements (volumes) according to the maximum length
470 of its edges and diagonals:
471
472 * element type should be *SMESH.VOLUME*
473 * functor type should be *SMESH.FT_MaxElementLength3D*
474 * threshold is floating point value (edge/diagonal length)
475
476 .. literalinclude:: ../../../examples/filters_ex23.py
477     :linenos:
478     :language: python
479
480 :download:`Download this script <../../../examples/filters_ex23.py>`
481
482 **See also:** :ref:`tui_max_element_length_3d`
483
484 .. _filter_bare_border_volumes: 
485
486 Bare border volumes
487 ===================
488
489 filters 3D mesh elements with bare borders, i.e. having a facet not
490 shared with other volumes and without a face on it:
491
492 * element type is *SMESH.VOLUME*
493 * functor type is *SMESH.FT_BareBorderVolume*
494 * threshold value is not required
495
496 .. literalinclude:: ../../../examples/filters_ex24.py
497     :linenos:
498     :language: python
499
500 :download:`Download this script <../../../examples/filters_ex24.py>`
501
502 **See also:** :ref:`tui_bare_border_volumes`
503
504 .. _filter_over_constrained_volumes: 
505
506 Over-constrained volumes
507 ========================
508
509 filters over-constrained volumes, whose all nodes are on the mesh boundary:
510
511 * element type is *SMESH.VOLUME*
512 * functor type is *SMESH.FT_OverConstrainedVolume*
513 * threshold value is not required
514
515 .. literalinclude:: ../../../examples/filters_ex25.py
516     :linenos:
517     :language: python
518
519 :download:`Download this script <../../../examples/filters_ex25.py>`
520
521 **See also:** :ref:`tui_over_constrained_faces`
522
523 .. _filter_belong_to_group: 
524
525 Belong to Mesh Group
526 ====================
527
528 filters mesh entities (nodes or elements) included in a mesh group
529 defined by threshold value:
530
531 * element type can be any, from *SMESH.NODE* to *SMESH.BALL*
532 * functor type should be *SMESH.FT_BelongToMeshGroup*
533 * threshold is mesh group object
534
535 .. literalinclude:: ../../../examples/filters_belong2group.py
536     :linenos:
537     :language: python
538
539 :download:`Download this script <../../../examples/filters_belong2group.py>`
540
541 .. _filter_belong_to_geom: 
542
543 Belong to Geom
544 ==============
545
546 filters mesh entities (nodes or elements) which all nodes lie on the
547 shape defined by threshold value:
548
549 * element type can be any, from *SMESH.NODE* to *SMESH.BALL*
550 * functor type should be *SMESH.FT_BelongToGeom*
551 * threshold is geometrical object
552 * tolerance is a distance between a node and the geometrical object; it is used if an node is not associated to any geometry.
553
554 .. literalinclude:: ../../../examples/filters_ex26.py
555     :linenos:
556     :language: python
557
558 :download:`Download this script <../../../examples/filters_ex26.py>`
559
560 .. _filter_lying_on_geom:
561
562 Lying on Geom
563 =============
564
565 filters mesh entities (nodes or elements) at least one node of which lies on the
566 shape defined by threshold value:
567
568 * element type can be any, from *SMESH.NODE* to *SMESH.BALL*
569 * functor type should be *SMESH.FT_LyingOnGeom*
570 * threshold is geometrical object
571 * tolerance is a distance between a node and the geometrical object;
572
573 it is used if an node is not associated to any geometry.
574
575 .. literalinclude:: ../../../examples/filters_ex27.py
576     :linenos:
577     :language: python
578
579 :download:`Download this script <../../../examples/filters_ex27.py>`
580
581 .. _filter_belong_to_plane: 
582
583 Belong to Plane
584 ===============
585
586 filters mesh entities (nodes or elements) which all nodes belong to the
587 plane defined by threshold value with the given tolerance:
588
589 * element type can be any except *SMESH.VOLUME*
590 * functor type should be *SMESH.FT_BelongToPlane*
591 * threshold is geometrical object (plane)
592 * default tolerance is 1.0e-7
593
594 .. literalinclude:: ../../../examples/filters_ex28.py
595     :linenos:
596     :language: python
597
598 :download:`Download this script <../../../examples/filters_ex28.py>`
599
600 .. _filter_belong_to_cylinder: 
601
602 Belong to Cylinder
603 ==================
604
605 filters mesh entities (nodes or elements) which all nodes belong to the
606 cylindrical face defined by threshold value with the given tolerance:
607
608 * element type can be any except *SMESH.VOLUME*
609 * functor type should be *SMESH.FT_BelongToCylinder*
610 * threshold is geometrical object (cylindrical face)
611 * default tolerance is 1.0e-7
612
613 .. literalinclude:: ../../../examples/filters_ex29.py
614     :linenos:
615     :language: python
616
617 :download:`Download this script <../../../examples/filters_ex29.py>`
618
619 .. _filter_belong_to_surface: 
620
621 Belong to Surface
622 =================
623
624 filters mesh entities (nodes or elements) which all nodes belong to the
625 arbitrary surface defined by threshold value with the given tolerance:
626
627 * element type can be any except *SMESH.VOLUME*
628 * functor type should be *SMESH.FT_BelongToGenSurface*
629 * threshold is geometrical object (arbitrary surface)
630 * default tolerance is 1.0e-7
631
632 .. literalinclude:: ../../../examples/filters_ex30.py
633     :linenos:
634     :language: python
635
636 :download:`Download this script <../../../examples/filters_ex30.py>`
637
638 .. _filter_range_of_ids: 
639
640 Range of IDs
641 ============
642
643 filters mesh entities elements (nodes or elements) according to the
644 specified identifiers range:
645
646 * element type can be any, from *SMESH.NODE* to *SMESH.BALL*
647 * functor type is *SMESH.FT_RangeOfIds*
648 * threshold is string listing required IDs and/or ranges of IDs, e.g."1,2,3,50-60,63,67,70-78"
649
650 .. literalinclude:: ../../../examples/filters_ex31.py
651     :linenos:
652     :language: python
653
654 :download:`Download this script <../../../examples/filters_ex31.py>`
655
656 .. _filter_bad_oriented_volume:
657
658 Badly oriented volume
659 =====================
660
661 filters 3D mesh elements (volumes), which are incorrectly oriented from
662 the point of view of MED convention. 
663
664 * element type should be *SMESH.VOLUME*
665 * functor type is *SMESH.FT_BadOrientedVolume*
666 * threshold is not required
667
668 .. literalinclude:: ../../../examples/filters_ex32.py
669     :linenos:
670     :language: python
671
672 :download:`Download this script <../../../examples/filters_ex32.py>`
673
674 .. _filter_linear_or_quadratic: 
675
676 Linear / quadratic
677 ==================
678
679 filters linear / quadratic mesh elements:
680
681 * element type should be either *SMESH.EDGE*, *SMESH.FACE* or *SMESH.VOLUME*
682 * functor type is *SMESH.FT_LinearOrQuadratic*
683 * threshold is not required
684 * if unary operator is set to SMESH.FT_LogicalNOT, the quadratic elements are selected, otherwise (by default) linear elements are selected
685
686 .. literalinclude:: ../../../examples/filters_ex33.py
687     :linenos:
688     :language: python
689
690 :download:`Download this script <../../../examples/filters_ex33.py>`
691
692 .. _filter_group_color: 
693
694 Group color
695 ===========
696
697 filters mesh entities, belonging to the group with the color defined by the threshold value.
698
699 * element type can be any, from *SMESH.NODE* to *SMESH.BALL*
700 * functor type is *SMESH.FT_GroupColor*
701 * threshold should be of SALOMEDS.Color type
702
703 .. literalinclude:: ../../../examples/filters_ex34.py
704     :linenos:
705     :language: python
706
707 :download:`Download this script <../../../examples/filters_ex34.py>`
708
709 .. _filter_geom_type: 
710
711 Geometry type
712 =============
713
714 filters mesh elements by the geometric type defined with the threshold
715 value. The list of available geometric types depends on the element
716 entity type.
717
718 * element type can be any, e.g.: *SMESH.EDGE*, *SMESH.FACE*, *SMESH.VOLUME*, etc.
719 * functor type should be *SMESH.FT_ElemGeomType*
720 * threshold is either of smesh.GeometryType values. Type *SMESH.GeometryType._items* in the Python Console to see all geometric types.
721
722 .. literalinclude:: ../../../examples/filters_ex35.py
723     :linenos:
724     :language: python
725
726 :download:`Download this script <../../../examples/filters_ex35.py>`
727
728 .. _filter_entity_type: 
729
730 Entity type
731 ===========
732
733 filters mesh elements by the geometric type and number of nodes. 
734
735 * element type can be any, e.g.: *SMESH.EDGE*, *SMESH.FACE*, *SMESH.VOLUME*, etc.
736 * functor type should be *SMESH.FT_EntityType*
737 * threshold is either of SMESH.EntityType values. Type *SMESH.EntityType._items* in the Python Console to see all entity types.
738
739 .. literalinclude:: ../../../examples/filters_ex37.py
740     :linenos:
741     :language: python
742
743 :download:`Download this script <../../../examples/filters_ex37.py>`
744
745 .. _filter_ball_diam: 
746
747 Ball diameter
748 =============
749
750 filters ball elements by diameter. 
751
752 * element type should be *SMESH.BALL*
753 * functor type should be *SMESH.FT_BallDiameter*
754 * threshold is floating point value (ball diameter)
755
756 .. literalinclude:: ../../../examples/filters_ex38.py
757     :linenos:
758     :language: python
759
760 :download:`Download this script <../../../examples/filters_ex38.py>`
761
762 .. _filter_domain: 
763
764 Elements of a domain
765 ====================
766
767 filters elements of a specified domain. 
768
769 * element type can be any, e.g.: *SMESH.EDGE*, *SMESH.FACE*, *SMESH.VOLUME*, etc.
770 * functor type should be *SMESH.FT_ConnectedElements*
771 * threshold is either (1) node ID or (2)  geometrical vertex or (3) 3 coordinates of a point.
772
773 .. literalinclude:: ../../../examples/filters_ex39.py
774     :linenos:
775     :language: python
776
777 :download:`Download this script <../../../examples/filters_ex39.py>`
778
779 .. _combining_filters: 
780
781 How to combine several criteria into a filter?
782 ==============================================
783
784 Several criteria can be combined into a filter.
785
786 .. literalinclude:: ../../../examples/filters_ex36.py
787     :linenos:
788     :language: python
789
790 :download:`Download this script <../../../examples/filters_ex36.py>`