| |
Groups |
| <<< Rollback | Chapters | Bulletin Board >>> |
Groups are collections of entities. They enable applications to assemble and track sets of entities within a part, in order to supplement the Parasolid data structure.
You create a group within a given part from a specified list of entities from that part using PK_GROUP_create_from_entities_2. You can then add further entities using either PK_GROUP_add_entities or PK_GROUP_merge_entities, and you can remove them using PK_GROUP_remove_entities.
Entities may be added to groups, and new groups may be created, as a result of modelling operations on the part. In addition, Parasolid provides a variety of options to let you control this behaviour, and to control the number of groups in a part.
Each group belongs to a particular part and has a particular class. A group can only contain entities that belong to the same part as the group belongs to. The group class, from the following list, determines the class of entities the groups can contain:
|
Note: Cyclic groups (i.e. groups containing themselves or groups higher up in the group hierarchy) are not allowed. |
Specifying a single class prevents inappropriate entities being added to the group.
Any number of groups can belong to the same part, and these can be of the same or different classes. Similarly, a particular entity can be in any number of groups that are able to contain that entity.
Groups are entities, and so all the general functions for managing entities can be used on groups.
To help you identify and structure the contents of a group, entities within a group can have an integer label assigned. This allows you to assign a meaning to different members of a group: for example to label the side faces of a body as “1”.
You can assign labels to entities in a group when you create a group, using the
labels
and
labelled_entities
options provided in PK_GROUP_create_from_entities_2. Alternatively, Parasolid provides functions PK_GROUP_set_entity_label and PK_GROUP_ask_entity_label, for assigning and enquiring entity labels after a group has been created, and finding entities within a group based on the label.
Entity labels do not have to be unique, so you could, for example, assign the same label to the topmost face in any group. Also, entity labels are independent for each group; if an entity is in multiple groups, setting its label in one group does not affect its label in any other groups. Several entities in the same group can be assigned the same label. For example, all the “side faces” in a body could be labelled as “1” for easy identification. Entity labels are persistent across transmit and receive. Unset entity labels are initialised to zero.
You can also use entity labels to determine when groups should be automatically deleted due to there not being sufficient members in the group. See Section 98.4, “Deleting groups automatically”, for information.
As a Parasolid session progresses, the members of a group are modified as modelling operations change entities by means of merge, split, or delete operations. Section 98.6 describes the behaviour of groups and group members in these situations.
If you use entity labels (Section 98.3) to structure and encapsulate particular types of information within groups, then these modelling operations are likely to change the members of your groups so that they eventually no longer represent the information you originally intended. For example, you might create a group in which all the side faces of a body are labelled. If, as a result of a boolean operation, those side faces are deleted from the body, then they are also removed from the group: the original purpose of the group is effectively made redundant.
To manage this, when you create a group, you can define rules to ensure Parasolid intelligently deletes that group when its purpose becomes redundant. You do this by setting criteria for the entity labels you use within the group using the following options in PK_GROUP_create_from_entities_2:
You do not have to use entity labels in your application in order to make use of this functionality. All entities without labels are assumed to have an entity label of 0, and this can be specified in
min_contents_labels
to control group deletion based on entities without labels. This can be a good way of ensuring, for instance, that the number of empty groups on a part does not proliferate during a Parasolid session.
The following table shows a number of examples to illustrate how you can use this mechanism:
|
Note: You can use PK_GROUP_remove_entities to remove entities from a group without triggering any rules defined using these options. This gives you the freedom to change the contents of a group, including removing all of its members, without having Parasolid automatically delete the group in the process. |
If you are deleting groups that contain other groups as members, you can specify whether you want to delete these member groups, using the
delete_dependants
option in PK_GROUP_create_from_entities_2. This can take the following values:
|
Note: This also applies when groups and group members are automatically deleted as described in Section 98.4. |
This section describes group behaviour when performing modelling operations on a part. For information on group behaviour in compound bodies, see Section 15.12.4, “Behaviour of groups in compound bodies”.
You can use the
membership
option in PK_GROUP_create_from_entities_2 to control the behaviour of entities in that group when those entities undergo a merge operation with another entity that may or may not be in the same group. This option takes the following values:
|
The resulting merged entity is always a member of the group. This is the default. |
|
|
The resulting merged entity is a member of the group only if both original entities were members of that group. Note: Using this value may lead to the removal of entities from a group. This in turn may trigger rules to automatically delete a group, as described in Section 98.4. |
Merging may be performed explicitly or as part of a local operation.
If an entity is split into a number of entities, the new entities are added to any group in which the original entity occurs. After splitting, the new entities have the same entity label as the original label in each group.
If an entity is deleted, it is removed from any group in which it occurs. If the last entity is removed from the group, the empty group continues to exist, unless you set controls for the group such that it is deleted automatically when it becomes empty (see Section 98.4).
If a new entity is created other than by splitting an existing entity, the new entity does not occur in any groups as a result of the creation operation.
If several bodies are merged (for example as a result of a boolean operation), then the resulting merged body inherits all the groups of the original bodies. Over time, this can lead to a proliferation of groups on a body,
When you create a group using PK_GROUP_create_from_entities_2, you can use the
merge_empty
and
merge_populated
options to let Parasolid control this proliferation of groups by merging groups it considers identical in the result body, as follows.
merge_empty |
Whether to merge identical empty groups in the resulting merged body. Empty groups are considered identical if they have no entities, and have the same attributes and group controls. |
merge_populated |
Whether to merge identical non-empty groups in the resulting merged body. Non-empty groups are considered identical if they have the same entities (and the same entity labels, if entity labels are used: see Section 98.3), and have the same attributes and group controls. |
Both
merge_empty
and
merge_populated
take the following values:
|
Do not merge groups considered identical. This is the default for both |
|
For non-empty groups, if a body splits one of the following occurs:
For empty groups, you can use the
split_empty
option when creating a group using PK_GROUP_create_from_entities_2 to control what happens if the owning body is split. This option takes the following values:
|
The empty group remains in the original part. This is the default. |
|
|
The empty group remains in the original part, and a copy of it is created in the split part. |
Once a group has been marked closed, you cannot manually add entities to or remove entities from the group. The contents of a closed group can only be modified by Parasolid operations which result in split, delete, or merge events.
For a group to be marked as a closed group, it must have an attribute attached whose definition is set to be group closing using PK_ATTDEF_set_group_closing. This attribute definition must be created from the PK_ATTDEF_class_01_c_class.
|
Note: Once a group is set to be a closed group, it will remain as one throughout the current session if it has at least one group closing attribute attached. |
You can use PK_ATTDEF_is_group_closing to find out whether or not the given attribute definition is a group closing definition.
You can use PK_GROUP_ask_closure to find out whether the given group is a closed group. In addition, you can choose to return the attributes that caused the group to be closed by setting the
want_attribs
option to PK_LOGICAL_true.
You can find closed groups of which a given entity is a member using the
group_closure
option of PK_ENTITY_ask_owning_groups_2.
You can find closed groups that are contained within a given part using the
group_closure
option of PK_PART_ask_groups_2.
The following table summarises the functions Parasolid provides for creating and working with groups.
|
Find the set of groups that the given entity is a member of. |
|
|
Return all the entities within a given group, optionally with a given label. |
|
In each of the following examples, the block has two groups:
Similarly, the rod has two groups:
Unless stated otherwise, the two bodies are positioned so that their centroids coincide.
| <<< Rollback | Chapters | Bulletin Board >>> |
