ifcopenshell.api.library

Manage references to external libraries

An external library is any system which uses a key to store information. This allows you to associate IFC entities with any arbitrary external database, API, system, and so on. This is typically useful in smart building systems.

Submodules

Package Contents

ifcopenshell.api.library.add_library(file: ifcopenshell.file, name: str) → ifcopenshell.entity_instance

Adds a new library to the project

A library is an external data source that is related to the project. It may be a database, a spreadsheet, an API, or even a stack of papers in a filing cabinet. This allows IFC data to store relationships to these external data sources.

For example, you may have a list of laser scans of a site stored in an online platform, which can be queried using an API. Or, you might have a database of live building sensor data. So long as there is a clear identifier you can use to link the two datasets together, you can create a relationship.

Note that IFC does not store any instructions on how to access the library. It does not specify whether a HTTP request or database connection needs to be made or what protocol the library operates with. Until this is fleshed out further, it is the users responsibility to name the libraries consistently and use appropriate identifiers. For example, if you are linking IFC data and Brickschema data, use a full URI for the identifier with no abbreviation (e.g. ‘http://example.org/digitaltwin#AHU01’, not ‘digitaltwin:AHU01’).

A library will then contain a list of references within that library. These references will then be related to IFC elements. For example, a library will represent an external database, and a reference will point to a particular table and row within that database.

Parameters:

name (str) – The name of the library

Returns:

The newly created IfcLibraryInformation

Return type:

ifcopenshell.entity_instance

Example:

ifcopenshell.api.library.add_library(model, name="Brickschema")
ifcopenshell.api.library.add_reference(file: ifcopenshell.file, library: ifcopenshell.entity_instance) → ifcopenshell.entity_instance

Adds a new reference to a library

A library represents an external data source, such as a database, spreadsheet, API, or something else that contains information related to the IFC project. Within a library, there will be one or more references, such as reference to a particular table or row in a database, or a sheet and row or column in a spreadsheet, a URI in a linked data Brickschema file, 32-bit decimal BACnetObjectIdentifier in a BACnet system, IP address in a network, and so on.

These references can then be related to IFC elements. You cannot relate an IFC element directly to a library, it must be related to one of the library’s references.

Parameters:

library (ifcopenshell.entity_instance) – The IfcLibraryInformation element to add a reference to

Returns:

The newly created IfcLibraryReference element

Return type:

ifcopenshell.entity_instance

Example:

library = ifcopenshell.api.library.add_library(model, name="Brickschema")

# Let's create a reference to a single AHU in our Brickschema dataset
reference = ifcopenshell.api.library.add_reference(model, library=library)
ifcopenshell.api.library.edit_reference(model,
    reference=reference, attributes={"Identification": "http://example.org/digitaltwin#AHU01"})
ifcopenshell.api.library.assign_reference(file: ifcopenshell.file, products: ifcopenshell.entity_instance, reference: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Associates a list products with a library reference

A product may be associated with zero, one, or many references across multiple libraries. See ifcopenshell.api.library.add_reference for more detail about how references work.

Parameters:

  • products (list[ifcopenshell.entity_instance]) – The list of IfcProducts you want to associate with the reference

  • reference (ifcopenshell.entity_instance) – The IfcLibraryReference you want the product to be associated with.

Returns:

The IfcRelAssociatesLibrary relationship entity or None if products was an empty list or all products were already assigned to the reference.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

library = ifcopenshell.api.library.add_library(model, name="Brickschema")

# Let's create a reference to a single AHU in our Brickschema dataset
reference = ifcopenshell.api.library.add_reference(model, library=library)
ifcopenshell.api.library.edit_reference(model,
    reference=reference, attributes={"Identification": "http://example.org/digitaltwin#AHU01"})

# Let's assume we have an AHU in our model.
ahu = ifcopenshell.api.root.create_entity(model,
    ifc_class="IfcUnitaryEquipment", predefined_type="AIRHANDLER")

# And now assign the IFC model's AHU with its Brickschema counterpart
ifcopenshell.api.library.assign_reference(model, reference=reference, products=[ahu])
ifcopenshell.api.library.edit_library(file: ifcopenshell.file, library: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcLibraryInformation

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

Parameters:

  • library (ifcopenshell.entity_instance) – The IfcLibraryInformation entity you want to edit

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

Returns:

None

Return type:

None

Example:

library = ifcopenshell.api.library.add_library(model, name="Brickschema")
ifcopenshell.api.library.edit_library(model, library=library,
    attributes={"Description": "A Brickschema TTL including only mechanical distribution systems."})
ifcopenshell.api.library.edit_reference(file: ifcopenshell.file, reference: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcLibraryReference

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

Parameters:

  • reference (ifcopenshell.entity_instance) – The IfcLibraryReference entity you want to edit

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

Returns:

None

Return type:

None

Example:

library = ifcopenshell.api.library.add_library(model, name="Brickschema")
# Let's create a reference to a single AHU in our Brickschema dataset
reference = ifcopenshell.api.library.add_reference(model, library=library)
ifcopenshell.api.library.edit_reference(model,
    reference=reference, attributes={"Identification": "http://example.org/digitaltwin#AHU01"})
ifcopenshell.api.library.remove_library(file: ifcopenshell.file, library: ifcopenshell.entity_instance) → None

Removes a library

All references along with their relationships will also be removed. Any products which have relationships to this library will not be removed.

Parameters:

library (ifcopenshell.entity_instance) – The IfcLibraryInformation entity you want to remove

Returns:

None

Return type:

None

Example:

library = ifcopenshell.api.library.add_library(model, name="Brickschema")
ifcopenshell.api.library.remove_library(model, library=library)
ifcopenshell.api.library.remove_reference(file: ifcopenshell.file, reference: ifcopenshell.entity_instance) → None

Removes a library reference

Any products which have relationships to this reference will not be removed.

Parameters:

reference (ifcopenshell.entity_instance) – The IfcLibraryReference entity you want to remove

Returns:

None

Return type:

None

Example:

library = ifcopenshell.api.library.add_library(model, name="Brickschema")
reference = ifcopenshell.api.library.add_reference(model, library=library)
# Let's change our mind and remove it.
ifcopenshell.api.library.remove_reference(model, reference=reference)
ifcopenshell.api.library.unassign_reference(file: ifcopenshell.file, reference: ifcopenshell.entity_instance, products: list[ifcopenshell.entity_instance]) → None

Unassigns a product of products from a reference

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

Parameters:

  • reference (ifcopenshell.entity_instance) – The IfcLibraryReference to unassign from

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

Returns:

None

Return type:

None

Example:

library = ifcopenshell.api.library.add_library(model, name="Brickschema")

# Let's create a reference to a single AHU in our Brickschema dataset
reference = ifcopenshell.api.library.add_reference(model, library=library)
ifcopenshell.api.library.edit_reference(model,
    reference=reference, attributes={"Identification": "http://example.org/digitaltwin#AHU01"})

# Let's assume we have an AHU in our model.
ahu = ifcopenshell.api.root.create_entity(model,
    ifc_class="IfcUnitaryEquipment", predefined_type="AIRHANDLER")

# And now assign the IFC model's AHU with its Brickschema counterpart
ifcopenshell.api.library.assign_reference(model, reference=reference, products=[ahu])

# Let's change our mind and unassign it.
ifcopenshell.api.library.unassign_reference(model, reference=reference, products=[ahu])