3.5 Entity Selection And Filtering
Cubit Entity specification is a means of selecting objects or groups of objects. Entities can be selected from the command line using entity specification parameters, or directly in the graphics window using the mouse. This chapter describes these methods of entity selection.
3.5.1 Command Line Entity Specification
Cubit identifies objects in the geometry, mesh, and elsewhere using ID numbers and sometimes names. IDs and names are used in most commands to specify which objects on which the command is to operate.
These objects can be specified in Cubit commands in a variety of ways, which are best introduced with the following examples (the portion of each command which specifies a list of entities is shown in blue):
General ranges: Surface 1 2 4 to 6 by 2 3 4 5 Scheme Pave
Combined geometry, mesh, and genesis entities: Draw Sideset 1 Curve 3 Hex 2 4 6
Geometric topology traversal: Vertex in Volume 2 Size 0.3
Mesh topology traversal: Draw Edge in Hex 32}
All keyword: List Block all
Expand keyword: my_curve_group expand Scheme Bias Factor 1.5
Except keyword: List Curve 1 to 50 except 2 4 6
In addition to the examples above, there is an extended parsing capability that allows entities to be specified by a general set of criteria. See Extended Entity Specification for details. The following is a simple example of an extended entity specification:
By Criteria: Draw Curve With Length > 3
3.5.1.1 Types of Entity Range Input
The types of entity range input available in Cubit can be classified in 4 groups:
General range parsing
Entity IDs can be entered individually (volume 1), in lists (volume 1 2 3), in ranges (volume 3 to 7), and in stepped ranges (volume 3 to 7 step 2). The word all may also be used to specify all entities of a given type.An ID range has the form <start_id> to <end_id>. It represents each ID between start_id and end_id, inclusive.
A stepped ID range has the form <start_id> To <end_id> {Step|By} <step>. It represents the set of IDs between start_id and end_id, inclusive, which can be obtained by adding some integer multiple of step to start_id. For example, 3 to 8 step 2 is equivalent to 3 5 7.
The various methods of specifying IDs can be used together. For example:draw surface 1 2 4 to 6 vertex all
Topological traversal
Topological traversal is indicated using the "in" identifier, can span multiple levels in a hierarchy, and can go either up or down the topology tree. For example, the following entity lists are all valid:vertex in volume 3
volume in vertex 2 4 6
curve 1 to 3 in body 4 to 8 by 2
If ranges of entities are given on both sides of the "in" identifier, the intersection of the two sets results. For example, in the last command above, the curves that have ids of 1, 2 or 3 and are also in bodies 4, 6 and 8 are used in the command.
Topology traversal is also valid between entity types. Therefore, the following commands would also be valid:
draw node in surface 3
draw surface in edge 362
draw hex in face in surface 2
draw node in hex in face in surface 2
draw edge in node in surface 2
Exclusion
Entity lists can be entered then filtered using the "except" identifier. This identifier and the ids following it apply only to the immediately preceding entity list, and are taken to be the same entity type. For example, the following entity lists are valid:curve all except 2 4 6
curve 1 2 5 to 50 except 2 3 4
curve all except 2 3 4 in surface 2 to 10
curve in surface 3 except 2 (produces empty entity list!)
Group expansion
Groups in Cubit can consist of any number of geometry entities, and the entities can be of different type (vertex, curve, etc.). Operations on groups can be classified as operations on the group itself or operations on all entities in the group. If a group identifier in a command is followed immediately by the ‘expand’ qualifier, the contents of the group(s) are substituted in place of the group identifier(s); otherwise the command is interpreted as an operation on the group as a whole. If a group preceding the ‘expand’ qualifier includes other groups, all groups are expanded in a recursive fashion.For example, consider group 1, which consists of surfaces 1, 2 and curve 1. Surfaces 1 and 2 are bounded by curves 2, 3, 4 and 5. The commands in Table 1, illustrate the behavior of the ‘expand’ qualifier.
|
|
|
|
|
|
The ‘expand’ qualifier can be used anywhere a group command is used in an entity list; of course, commands which apply only to groups will be meaningless if the group id is followed by the ‘expand’ qualifier.
3.5.1.2 Precedence of "Except" and "In"
Several keywords take precedence over others, much the same as some operators have greater precedence in coding languages. In the current implementation, the keyword "Except" takes precedence over other keywords, and serves to separate the identifier list into two sections. Any identifiers following the "Except" keyword apply to the list of entities excluded from the entities preceding the "Except". Table 2 shows the entity lists resulting from selected commands.
|
|
|
|
|
|
In the first command, the entities to be excluded are the contents of the list "[Curve] 1 in Group 1", that is the intersection of the lists "Curve 1" and "Curve in Group 1"; since the only curve in Group 1 is Curve 1, the excluded list consists of only Curve 1. The remaining list, after removing the excluded list, is all curves except Curve 1.
In the second command, the excluded list consists of the intersection of the lists "Curve 2 3 4" and "Curve in Surf 2 to 10"; this intersection turns out to be just Curves 2, 3 and 4. The remaining list is all curves except those in the excluded list.
3.5.1.3 Placement in Cubit Commands
In general, anywhere a range of entities is allowed, the new parsing capability can be used. However, there can be exceptions to this general rule, because of ambiguities this syntax would produce. Currently, the only exception to this rule is the command used to define a sideset for a surface with respect to an owning volume.
3.5.2 Extended Command Line Entity Specification
In addition to basic entity specification, entities may be specified using an extended expression. An extended expression identifies one or more entities using a set of entity criteria. These criteria describe properties of the entities one wishes to operate upon.
3.5.2.1 Extended Parsing Syntax
The most common type of extended parsing expression is in the following format:
{Entity_Type With {Criteria}}
Entity_Type is the name of any type of entity that can be used in a command, such as Curve, Hex, or SideSet. Criteria is a combination of entity properties (such as Length), operators (such as >=), keywords (such as Not), and values (such as 5.3) that can be evaluated to true or false for a given entity. Here are some examples:
curve with length <1 surface with is_meshed = false node with x_coord > 10 And y_coord > 0
3.5.2.2 Keywords
These are the keyword defined by extended parsing
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.5.2.3 Functions
The following functions are defined. Not all functions apply to all entities. If a function does not apply to a given entity, the function returns 0 or false.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.5.2.4 Precedence
For complicated expressions, which entities are referred to is influenced by the order in which portions of the expression are evaluated. This order is determined by precedence. Operators with high precedence are evaluated before operators with low precedence. You may always include parentheses to determine which sub-expressions are evaluated first. Here all operators and keywords listed from high to low precedence. Items listed together have the same precedence and are evaluated from left to right.
(, ) Expand Not *, / +, - <, >, <=, >=, <>, = And, Or Except In Of With
curve with length + 2 * 2 > 10 and length <= 20 in my_group
expand(curve with (((length + (2*2)) > 10 )and( length <= 20 ))) in ( my_group expand )
3.5.3 Selecting Entities with the Mouse
The following discussion is applicable only to the command line version of Cubit. See GUI Entity Selection for a description of interactive entity selection with the Graphical User Interface. Also refer to Extended Selection Dialog to learn how to use Python scripts to create extensive selection capabilities.
Many of the commands in Cubit require the specification of an entity on which the command operates. These entities are usually specified using an object type and ID (see Entity Specification) or a name. The ID of a particular entity can be found by turning labels on in the graphics and redisplaying; however, this can be cumbersome for complicated models. Cubit provides the capability to select with the mouse individual geometry or mesh entities. After being selected, the ID of the entity is reported and the entity is highlighted in the scene. After selecting the entities, other actions can be performed on the selection. The various options for selecting entities in Cubit are described below, and are summarized in Table 1:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.5.3.1 Entity Selection
3.5.3.1.1 Specifying the type of entity to select
Clicking on the scene can be interpreted in more than one way. For example, clicking on a curve could be intended to select the curve or a mesh edge owned by that curve. The type of entity the user intends to select is called the picking type. In order for Cubit to correctly interpret mouse clicks, the picking type must be indicated. This can be done in one of two ways. The easiest way to change the picking type is to place the pointer in the graphics window and enter the dimension of the desired picking type and an optional modifier key. The dimension usually corresponds to the dimension of the objects being picked:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If a Shift modifier key is held while typing the dimension, the picking type is set to the mesh entity of corresponding dimension, otherwise the geometry entity of that dimension is set as the picking type. For example, typing 2 while the pointer is in the graphics window sets the picking type so that geometric surfaces are picked; typing Shift-1 sets the picking type so that mesh edges are picked. To differentiate between picking "tris" or "quads" use "pick face" or "pick tri"}
The picking type can also be set using the command
Pick <entity_type>
where entity_type is one of the following: Body , Volume , Surface , Curve , Vertex , Hex , Tet , Face , Tri , Edge , Node , or DicerSheet .
3.5.3.1.2 Selecting the entities
To select an object, hold down the control key and click on the entity (this command can be mapped to a different button and modifiers, as described in the section on Mouse-Based View Navigation). Clicking on an entity in this manner will first de-select any previously selected entities, and will then select the entity of the correct type closest to the point clicked. The new selection will be highlighted and its name will be printed in the command window.
3.5.3.2 Query Selection
If the highlighted entity is not the object you intended to selected, press the Tab key to move to the next closest entity. You can continue to press tab to loop through all possible selections that are reasonably close to the point where you clicked. Shift-Tab will loop backwards through the same entities.
3.5.3.3 Multiple Selected Entities
To select an additional entity, without first clearing the current selection, hold down the shift and control keys while clicking on an object. You can select as many objects as you would like. By changing the picking type between selections, more than one type of entity may be selected at a time. When picking multiple entities, each pick action acts as a toggle; if the entity is already picked, it is "unpicked", or taken out of the picked entities list.
3.5.3.4 Information About the Selection
When an entity is selected, its name, entity type, and ID are printed in the command window. There are several other actions which can then be performed on the picked entity list. These actions are initiated by pressing a key while the pointer is in the graphics window. Table 1 summarizes the actions which operate on the selected entities.
3.5.3.5 Picked Group
There is a special group whose contents can be altered using picking. This group is named picked , and is automatically created by Cubit. Other than its relationship to interactive picking, it is identical to other groups and can be operated on from the command line. Like other groups, both geometric and mesh entities can be held in the picked group. Table 1 lists the graphics window key presses used with the picked group.
It is important to distinguish between the current selection and the picked group contents. Clicking on a new entity will select that entity, but will not add it to the picked group. De-selecting an entity will not remove an entity from the picked group.
3.5.3.6 Substituting Selection into Other Commands
3.5.3.6.1 The Selection Keyword
You may refer to all currently selected entities by using the word selection in a command; the picked type and ID numbers of all selected entities will be substituted directly for selection . For example, if Volume 1 and Curve 5 are currently selected, typing
Color selection Blue
is identical to typing
Color Volume 1 Curve 5 Blue
Note that the selection keyword is case sensitive, and must be entered as all lowercase letters.
3.5.3.6.2 Echoing the ID of the Selection
Typing an e into a graphics window will cause the ID of each selected entity to be added to the command line at the current insertion point. This is a convenient way to use entities of which you don’t already know the name or ID.
As an added convenience, the picking type can be set based on the last word on the command line using the ‘ key. Note that this is not the apostrophe key, but rather the left tick mark, usually found at the upper-left corner of the keyboard on the same key as the tilde (~). For example, a convenient way to set the meshing scheme of a cylinder to sweep would be as follows:
Volume (hit ‘, select cylinder, hit e) Scheme Sweep Source Surface (hit ‘, select endcap, hit e) Target (select other endcap, hit e)
The result will be something similar to
Volume 1 Scheme Sweep Source Surface 1 Target 2
Notice that you must use the word Surface in the command, or ‘ will not select the correct picking type.
3.5.3.6.3 Using the Picked Group in Commands
Like other groups, the picked group may be used in commands by referring to it by name. The name of the picked group is picked. For example, if the contents of the picked group are Volume 1 and Volume 2, the command
Draw picked
is identical to
Draw Volume 1 Volume 2
Note that picked is case sensitive, and must be entered as all lowercase letters.
3.5.3.7 Select Commands
3.5.3.7.1 Creating and Modifying Selections
The following commands may be used to create a new selection or modify the current selection.
Select <entity_list> [add|remove]
Select None
Select Seed {face <ids>|tri <ids>} feature_angle <angle>
This command creates a new selection based on a seed face and feature angle. It finds all the neighboring faces with a feature angle that is less than the specified angle and adds them to the selection.
3.5.3.7.2 Rubberband Selection Control
Select Occluded {on|off}
Select Partial {on|off}
Select Rubberband Shape {box|polygon|circle}
Choose the rubberband shape to be box, polygon, or circle. If polygon is selected, the shape of the polygon is defined by the left mouse button clicks in the graphics windows. To end defining the polygon shape and make the selection, click the right mouse button.
3.5.4 Extended Selection Dialog
Selecting entities in the graphics window can sometimes be complicated. The Extended Selection Dialog (introduced in Cubit 16.0) leverages the combination of http://www.python.org and the CubitInterface class to give users a very powerful mechanism for creating and managing custom selection filters.
3.5.4.1 Accessing the Dialog
The dialog is accessible any time a geometry entity is selected in the graphics window. Consider this workflow:
3.5.4.1.1 Launch the Dialog
Select a geometric entity
Get the context menu and select "Pick Extended...". The Extended Selection dialog will be shown with the selected entity (or entities) listed in the Source Selection window.
When the dialog is first shown, no filters are available.
3.5.4.1.2 Load Existing Filters
Load existing filters by:
Press the "Load Filters" button
The Locate and Load Filters dialog will be shown
A list of custom filters, written in Python, will be shown. Select any given filter to examine its contents. Check all filters to be included in the menu for Extended Filters. Then press "OK".
3.5.4.1.3 Use a Filter
Use the pull down menu to select a filter. Click on an entity in the Source Selection list. Geometric entities that fit the filter criterion will be shown in the Target Entities list.
Make selections in the Target Entities list.
If a pickwidget is active selected IDs will be copied into the pickwidget
Access the context menu in the Target Entities list for other options, including copying entity names or IDs to the clipboard.
3.5.4.1.4 Dragging from Target Entities to Source Selection
Depending on the nature of the selection filter it may be useful to ’re-seed’ the Source Selection with an item from Target Entities. Simply drag an item or items from Target Entities into the Source Selection list.
3.5.4.2 Creating Parameterized Filters
Beginning with Cubit 16.1.2 users are able to create and use extended selection filters that contain input fields. In other words, selection filters may be parameterized.
Filters of this type will require a user interface which will be added into the extended selection filter dialog. The user interface can be made using Qt’s Designer, which is a free tool that ships with the Qt toolkit. The Qt Designer tool produces a XML file that will be read by Cubit and automatically included in the filter dialog.
For example, if we wanted to create a selection filter that would select all entities of a certain type within a certain radius of a source entity, we would require a user interface that captures the desired radius and the desired entity type to be selected. An image of that user interface is shown below. The image was copied directly from Qt Designer.
3.5.4.3 Writing Custom Python Filters
The class CubitInterface is used by the Cubit GUI to drive Cubit and access its database. You can read about the Python Interface used by Cubit for more details. Suffice to say, all of the functions and data included in CubitInterface are available to Python programmers.
Extended Selection custom filters are written in Python. Follow the instructions below, save the filters on the file system, then load the filters as explained above.
3.5.4.3.1 A Simple Example Filter
This first example shows a filter that will return a list of first generation children of the selected entities. No user input is required and no additional user interface is necessary.
The filter’s File Name and Class Name must match. In this example, the file name is ChildFilter.py and the class name is "ChildFilter".
LINE 2: import cubitgui – this is the Python module that owns the base class (SelectionFilter) from which this filter class is derived.
LINE 3: import cubit – this is the Python module that grants access to all of the CubitInterface functions.
LINE 6: When defining the class do the following:
Ensure the class name matches the file name
Derive the class from cubitgui.SelectionFilter
LINE 9: Implement the ’virtual’ function "display_name". Return a string that represents the name of the filter. It is this name that will be shown in the Extended Selection dialog’s filter menu.
LINE 13: Implement the ’virtual’ function "run_filter. This is the actual filter.
LINE 15: The function get_source_types() returns a list of the types selected in the "Source Selection" list of the Extended Selection dialog.
LINE 16: The function get_source_ids() returns a list of the ids selected in the "Source Selection" list of the Extended Selection dialog.
LINE 17: The function clear_target_selections() clears the Target Entities list of the Extended Selection dialog.
LINE 18: The example filter begins manipulating data to suit its needs
LINE 35: The function get_relatives(...) is a member of CubitInterface. It returns a list of ids of a specified type
LINE 37: The function add_target_selection(<type> <id>) adds one instance of an entity-type/id to the Target Entities list.
3.5.4.3.2 The Selection Filter Class
As mentioned above, the custom Python filters must implement a class and that class must be derived from the SelectionFilter class. The SelectionFilter class is available in the Cubit SDK. The SDK is available at no charge to any Cubit user.
3.5.4.3.3 A Sample Filter that Includes Additional User Interface
In order to include user input into an extended selection dialog, two additional things must happen:
1) The developer must create the user interface definition file (.ui file) using Qt Designer;
2) An additional function must be implemented in the class definition of the Python filter. The additional function is called get_ui_file().
Qt UI objects supported by the extended selection filter include:
1) QLineEdit - std::string get_line_edit_value ( object-name )
2) QComboBox - std::string get_combo_box_value( object-name )
3) QRadioButton - bool get_radio_button_value( object-name )
4) QCheckBox - bool get_check_box_value(object-name )
5) QSpinBox - int get_spin_box_value(object-name )
6) QSlider - int get_slider_value(object-name )
As the example Python code shows, the Qt objects are referenced by name. These code snippets below are not complete. Complete examples and a video tutorial are available from http://www.coreform.com. Detailed training is also available upon request.
"
"
