ifcopenshell.api.group

Elements may be arbitrarily assigned to groups for organisation

Groups are useful for filtering elements or non-hierarchical organisation of a model. Note that this only targets arbitrary groups. If you want to group elements into a distribution system, see ifcopenshell.api.system.

Submodules

Package Contents

ifcopenshell.api.group.add_group(file: ifcopenshell.file, name: str = 'Unnamed', description: str | None = None) → ifcopenshell.entity_instance

Adds a new group

An IFC group is an arbitrary collection of products, which are typically physical. It may be used when there is no other more specific group which may be used. Other types of groups include distribution systems, which group together products that are connected and circulate a medium (such as fluid or electricity), or zones, which group together spaces, or structural load groups, which group together loads for structural analysis, or inventories, which are groups of assets.

Parameters:

  • Name (str, optional) – The name of the group. Defaults to “Unnamed”

  • description (str, optional) – The description of the purpose of the group.

Returns:

The newly created IfcGroup

Return type:

ifcopenshell.entity_instance

Example:

ifcopenshell.api.group.add_group(model, name="Unit 1A")
ifcopenshell.api.group.assign_group(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], group: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Assigns products to a group

If a product is already assigned to the group, it will not be assigned twice.

Parameters:

  • products (list[ifcopenshell.entity_instance]) – A list of IfcProduct elements to assign to the group

  • group (ifcopenshell.entity_instance) – The IfcGroup to assign the products to

Returns:

The IfcRelAssignsToGroup relationship or None if products was empty list.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

group = ifcopenshell.api.group.add_group(model, name="Furniture")
ifcopenshell.api.group.assign_group(model,
    products=model.by_type("IfcFurniture"), group=group)
ifcopenshell.api.group.edit_group(file: ifcopenshell.file, group: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcGroup

For more information about the attributes and data types of an IfcGroup, consult the IFC documentation.

Parameters:

  • group (ifcopenshell.entity_instance) – The IfcGroup entity you want to edit

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

group = ifcopenshell.api.group.add_group(model, name="Unit 1A")
ifcopenshell.api.group.edit_group(model,
    group=group, attributes={"Description": "All furniture and joinery included in the unit"})
ifcopenshell.api.group.remove_group(file: ifcopenshell.file, group: ifcopenshell.entity_instance) → None

Removes a group

All products assigned to the group will remain, but the relationship to the group will be removed.

Parameters:

group (ifcopenshell.entity_instance) – The IfcGroup entity you want to remove

Returns:

None

Return type:

None

Example:

group = ifcopenshell.api.group.add_group(model, name="Unit 1A")
ifcopenshell.api.group.remove_group(model, group=group)
ifcopenshell.api.group.unassign_group(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], group: ifcopenshell.entity_instance) → None

Unassigns products from a group

If the product isn’t assigned to the group, nothing will happen.

Parameters:

  • products (list[ifcopenshell.entity_instance]) – A list of IfcProduct elements to unassign from the group

  • group (ifcopenshell.entity_instance) – The IfcGroup to unassign from

Returns:

None

Return type:

None

Example:

group = ifcopenshell.api.group.add_group(model, name="Furniture")
furniture = model.by_type("IfcFurniture")
ifcopenshell.api.group.assign_group(model, products=furniture, group=group)

bad_furniture = furniture[0]
ifcopenshell.api.group.unassign_group(model, products=[bad_furniture], group=group)
ifcopenshell.api.group.update_group_products(file: ifcopenshell.file, group: ifcopenshell.entity_instance, products: list[ifcopenshell.entity_instance]) → ifcopenshell.entity_instance

Sets a group products to be an explicit list of products

Any previous products assigned to that group will have their assignment removed.

Parameters:

  • products (list[ifcopenshell.entity_instance]) – A list of IfcProduct elements to assign to the group

  • group (ifcopenshell.entity_instance) – The IfcGroup to assign the products to

Returns:

The IfcRelAssignsToGroup relationship

Return type:

ifcopenshell.entity_instance

Example:

group = ifcopenshell.api.group.add_group(model, name="Furniture")
ifcopenshell.api.group.update_group_products(model,
    products=model.by_type("IfcFurniture"), group=group)