ifcopenshell.api.project

Create an IFC project

All IFCs must have one, and only one IFC project before any data may be associated. If you are starting from scratch, see :func:create_file.

Once a project exists, you may optionally create project libraries and associate type assets with it. You may also append assets from other projects into your project.

Submodules

• ifcopenshell.api.project.append_asset
• ifcopenshell.api.project.assign_declaration
• ifcopenshell.api.project.create_file
• ifcopenshell.api.project.unassign_declaration

Package Contents

ifcopenshell.api.project.append_asset(file: ifcopenshell.file, library: ifcopenshell.file, element: ifcopenshell.entity_instance, reuse_identities: dict[int, ifcopenshell.entity_instance] | None = None) → ifcopenshell.entity_instance

Appends an asset from a library into the active project

A BIM library asset may be a type product (e.g. wall type), product (e.g. pump), material, profile, or cost schedule.

This copies the asset from the specified library file into the active project. It handles all details like ensuring that product materials, styles, properties, quantities, and so on are preserved.

If an asset contains geometry, the geometric contexts are also intelligentely transplanted such that existing equivalent contexts are reused.

Do not mix units.

Parameters:

• library (ifcopenshell.file) – The file object containing the asset.

• element (ifcopenshell.entity_instance) – An element in the library file of the asset. It may be an IfcTypeProduct, IfcProduct, IfcMaterial, IfcCostSchedule, or IfcProfileDef.

• reuse_identities (dict[int, ifcopenshell.entity_instance]) – Optional dictionary of mapped entities’ identities to the already created elements. It will be used to avoid creating duplicated inverse elements during multiple project.append_asset calls. If you want to add just 1 asset or if added assets won’t have any shared elements, then it can be left empty.

Returns:

The appended element

Return type:

ifcopenshell.entity_instance

Example:

# Programmatically generate a library. You could do this visually too.
library = ifcopenshell.api.project.create_file()
root = ifcopenshell.api.root.create_entity(library, ifc_class="IfcProject", name="Demo Library")
context = ifcopenshell.api.root.create_entity(library,
    ifc_class="IfcProjectLibrary", name="Demo Library")
ifcopenshell.api.project.assign_declaration(library, definitions=[context], relating_context=root)

# Assign units for our example library
unit = ifcopenshell.api.unit.add_si_unit(library,
    unit_type="LENGTHUNIT", name="METRE", prefix="MILLI")
ifcopenshell.api.unit.assign_unit(library, units=[unit])

# Let's create a single asset of a 200mm thick concrete wall
wall_type = ifcopenshell.api.root.create_entity(library, ifc_class="IfcWallType", name="WAL01")
concrete = ifcopenshell.api.material.add_material(usecase.file, name="CON", category="concrete")
rel = ifcopenshell.api.material.assign_material(library,
    products=[wall_type], type="IfcMaterialLayerSet")
layer = ifcopenshell.api.material.add_layer(library,
    layer_set=rel.RelatingMaterial, material=concrete)
layer.Name = "Structure"
layer.LayerThickness = 200

# Mark our wall type as a reusable asset in our library.
ifcopenshell.api.project.assign_declaration(library,
    definitions=[wall_type], relating_context=context)

# Let's imagine we're starting a new project
model = ifcopenshell.api.project.create_file()
project = ifcopenshell.api.root.create_entity(model, ifc_class="IfcProject", name="Test")

# Now we can easily append our wall type from our libary
wall_type = ifcopenshell.api.project.append_asset(model, library=library, element=wall_type)

Example of adding multiple assets and avoiding duplicated inverses:

# since occurrences of IfcWindow of the same type
# might have shared inverses (e.g. IfcStyledItem)
# we provide a dictionary that will be populated with newly created items
# and reused to avoid duplicated elements
reuse_identities = dict()

for element in ifcopenshell.util.selector.filter_elements(model, "IfcWindow"):
    ifcopenshell.api.project.append_asset(
        model, library=library,
        element=wall_type
        reuse_identities=reuse_identities
    )

ifcopenshell.api.project.assign_declaration(file: ifcopenshell.file, definitions: list[ifcopenshell.entity_instance], relating_context: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Declares the list of elements to the project

All data in a model must be directly or indirectly related to the project. Most data is indirectly related, existing instead within the spatial decomposition tree. Other data, such as types, may be declared at the top level.

Most of the time, the API handles declaration automatically for you. There is one scenario where you might want to explicitly declare objects to the project, and that’s when you want to organise objects into project libraries for future use (such as an assets library). Assigning a declaration lets you say that an object belongs to a library.

Parameters:

• definitions (list[ifcopenshell.entity_instance]) – The list of objects you want to declare. Typically a list of assets.

• relating_context (ifcopenshell.entity_instance) – The IfcProject, or more commonly the IfcProjectLibrary that you want the object to be part of.

Returns:

The new IfcRelDeclares relationship or None if all definitions were already declared / do not support declaration.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

# Programmatically generate a library. You could do this visually too.
library = ifcopenshell.api.project.create_file()
root = ifcopenshell.api.root.create_entity(library, ifc_class="IfcProject", name="Demo Library")
context = ifcopenshell.api.root.create_entity(library,
    ifc_class="IfcProjectLibrary", name="Demo Library")

# It's necessary to say our library is part of our project.
ifcopenshell.api.project.assign_declaration(library, definitions=[context], relating_context=root)

# Assign units for our example library
unit = ifcopenshell.api.unit.add_si_unit(library,
    unit_type="LENGTHUNIT", name="METRE", prefix="MILLI")
ifcopenshell.api.unit.assign_unit(library, units=[unit])

# Let's create a single asset of a 200mm thick concrete wall
wall_type = ifcopenshell.api.root.create_entity(library, ifc_class="IfcWallType", name="WAL01")
concrete = ifcopenshell.api.material.add_material(file, name="CON", category="concrete")
rel = ifcopenshell.api.material.assign_material(library,
    products=[wall_type], type="IfcMaterialLayerSet")
layer = ifcopenshell.api.material.add_layer(library,
    layer_set=rel.RelatingMaterial, material=concrete)
layer.Name = "Structure"
layer.LayerThickness = 200

# Mark our wall type as a reusable asset in our library.
ifcopenshell.api.project.assign_declaration(library,
    definitions=[wall_type], relating_context=context)

# All done, just for fun let's save our asset library to disk for later use.
library.write("/path/to/my-library.ifc")

ifcopenshell.api.project.create_file(version: str = 'IFC4') → ifcopenshell.file

Create a blank IFC model file object

Create a new IFC file object based on the nominated schema version. The schema version you choose determines what type of IFC data you can store in this model. The file is blank and contains no entities.

It also sets up header data for STEP file serialisation, such as the current timestamp, IfcOpenShell as the preprocessor, and defaults to a DesignTransferView MVD.

Parameters:

version (str, optional) – The schema version of the IFC file. Choose from “IFC2X3”, “IFC4”, or “IFC4X3”. If you have loaded in a custom schema, you may specify that schema identifier here too.

Returns:

The created IFC file object.

Return type:

ifcopenshell.file

Example:

# Start a new model.
model = ifcopenshell.api.project.create_file()

# It's currently a blank model, so typically the first thing we do
# is create a project in it.
project = ifcopenshell.api.root.create_entity(model, ifc_class="IfcProject", name="Test")

# ... and off we go!

ifcopenshell.api.project.unassign_declaration(file: ifcopenshell.file, definitions: list[ifcopenshell.entity_instance], relating_context: ifcopenshell.entity_instance) → None

Unassigns a list of objects from a project or project library

Typically used to remove an asset from a project library.

Parameters:

• definitions (list[ifcopenshell.entity_instance]) – The list of objects you want to undeclare. Typically a list of assets.

• relating_context (ifcopenshell.entity_instance) – The IfcProject, or more commonly the IfcProjectLibrary that you want the object to no longer be part of.

Returns:

None

Return type:

None

Example:

# Programmatically generate a library. You could do this visually too.
library = ifcopenshell.api.project.create_file()
root = ifcopenshell.api.root.create_entity(library, ifc_class="IfcProject", name="Demo Library")
context = ifcopenshell.api.root.create_entity(library,
    ifc_class="IfcProjectLibrary", name="Demo Library")

# It's necessary to say our library is part of our project.
ifcopenshell.api.project.assign_declaration(library, definitions=[context], relating_context=root)

# Remove the library from our project
ifcopenshell.api.project.unassign_declaration(library, definitions=[context], relating_context=root)