ifcopenshell.api.nest.assign_object

Module Contents

ifcopenshell.api.nest.assign_object.assign_object(file: ifcopenshell.file, related_objects: list[ifcopenshell.entity_instance], relating_object: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Assigns objects as nested children to a parent host

All physical IFC model elements must be part of a hierarchical tree called the “spatial decomposition”, where large things are made up of smaller things. This tree always begins at an “IfcProject” and is then broken down using “decomposition” relationships, of which aggregation is the first relationship you will use.

Another type of “decomposition” relationship is known as “nesting”. Nesting is used when an child object is physically attached to a parent host object, through a physical predetermined connection point. The child object must be specifically designed to attach to a other objects at specific positions with a particular form factor. Examples include faucets which must always be attached through a predrilled hole in a basin. Alternatively, it could be a modular attachment with a correlating male and female joint that must join at a particular point. Because there is a strict connection point, when the parent moves, all nested children must move with the parent. Another example might be a predrilled hole in a door panel where hardware must fit through.

Nesting relationships are not very commonly used in most design and construction models. Its main usecase is in modular construction, kit of parts, or fabrication models.

As a product may only have a single location in the “spatial decomposition” tree, assigning an nesting relationship will remove any previous aggregation, containment, or nesting relationships it may have.

IFC placements follow a convention where the placement is relative to its parent in the spatial hierarchy. If your product has a placement, its placement will be recalculated to follow this convention.

For physical connections which are part of a distribution system, such as a plug connecting into a GPO, or a duct connecting to an AHU, or two pipe segments connecting with a bend, tee, or wye fitting, you should not nest the two objects directly. Instead, you should nest a connection port, which determines the type of compatible distribution flow that can be connected to it. To do this, do not use this function, but instead use the more specific functions in the ifcopenshell.api.system module.

Note that nesting relationships may also be used by non-physical elements, such as cost items or tasks. In this context, nesting means that there is an implied order to the child cost items or tasks (i.e. task 1 should be shown before task 2). It is not necessary to use this function for nesting non-physical elements. Instead, it is recommended to instead just use the relevant API functions, like ifcopenshell.api.cost.add_cost_item or ifcopenshell.api.sequence.add_task.

Parameters:
Returns:

The IfcRelNests relationship instance or None if related_objects was empty list.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

# Faucets are designed to attach onto a sink through a predrilled hole.
sink = ifcopenshell.api.run("root.create_entity", model,
    ifc_class="IfcSanitaryTerminal", predefined_type="SINK")
faucet = ifcopenshell.api.run("root.create_entity", model,
    ifc_class="IfcValve", predefined_type="FAUCET")
ifcopenshell.api.run("nest.assign_object", model, related_objects=[faucet], relating_object=sink)