ifcopenshell.api.document

Reference external project documents and associate them to model elements

Some project information (drawings, specifications, certificates, reports, etc) may be stored in external documents (locally or in a CDE). IFC lets you store a register of documents with metadata and associate them with elements (both physical and non-physical).

Submodules

• ifcopenshell.api.document.add_information
• ifcopenshell.api.document.add_reference
• ifcopenshell.api.document.assign_document
• ifcopenshell.api.document.edit_information
• ifcopenshell.api.document.edit_reference
• ifcopenshell.api.document.remove_information
• ifcopenshell.api.document.remove_reference
• ifcopenshell.api.document.unassign_document

Package Contents

ifcopenshell.api.document.add_information(file: ifcopenshell.file, parent: ifcopenshell.entity_instance | None = None) → ifcopenshell.entity_instance

Adds a new document information to the project

An IFC document information is a document associated with the project. It may be a drawing, specification, schedule, certificate, warranty guarantee, manual, contract, and so on. They are often used for drawings and facility management purposes.

A document may also be a subdocument of a larger document, this is useful for superseding documents or tracking older versions. The parent is considered the latest version and the children are older revisions.

Parameters:

parent (ifcopenshell.entity_instance, optional) – The parent document, if necessary.

Returns:

The newly created IfcDocumentInformation entity

Return type:

ifcopenshell.entity_instance

Example:

document = ifcopenshell.api.document.add_information(model)
# A document typically has a unique drawing or document name (which
# follows a coding system depending on the project), as well as a
# title.  This should match what is shown on the titleblock or title
# page of the document. At a minimum you'd also want to specify a
# URI location. The location may be on local, or on a CDE, or any
# other platform.
ifcopenshell.api.document.edit_information(model,
    information=document,
    attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
    "Location": "A-GA-6100 - Overall Plan.pdf"})

ifcopenshell.api.document.add_reference(file: ifcopenshell.file, information: ifcopenshell.entity_instance) → ifcopenshell.entity_instance

Creates a new reference to a document to assign to products

A document may be associated with physical products, tasks, cost items, and so on. For example, spaces, storeys, and buildings may have a list of associated drawings so you can see which drawings (e.g. plans, sections, details) are documenting that location. Alternatively, equipment may have associated training manuals, operation and maintenance manuals or detailed assembly drawings. Resources may be training certification required, schedules may have gantt charts or bid documents, and so on.

In order to associate a document with an object, a reference to that document needs to be created. It could be a reference to the entire document, or a reference to a particular page or chapter. See ifcopenshell.api.document.assign_document for more information.

Parameters:

information (ifcopenshell.entity_instance) – The IfcDocumentInformation that the reference will be created for

Returns:

The newly created IfcDocumentReference entity

Return type:

ifcopenshell.entity_instance

Example:

document = ifcopenshell.api.document.add_information(model)
ifcopenshell.api.document.edit_information(model,
    information=document,
    attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
    "Location": "A-GA-6100 - Overall Plan.pdf"})

# In this case, we don't specify any more information, and so the
# reference is for the entire document, as opposed to a single page or
# chapter or section.
reference = ifcopenshell.api.document.add_reference(model, information=document)

# Alternatively, we can specify a single section, such as by a
# subheading code.
reference2 = ifcopenshell.api.document.add_reference(model, information=document)
ifcopenshell.api.document.edit_reference(model,
    reference=reference2, attributes={"Identification": "2.1.15"})

ifcopenshell.api.document.assign_document(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], document: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Assigns a document to a list of products

An object may be assigned to zero, one, or multiple documents. Almost any object or property may be assigned to a document, though typically we’d only use it for spaces, types, physical products and schedules. Adding a new assignment is typically done using a document reference and an object. IFC technically allows association with a document information and an object, but this is not encouraged because it is not consistent with other external relationships (such as classification systems or libraries).

Parameters:

• product (list[ifcopenshell.entity_instance]) – The list of objects to associate the document to. This could be almost any sensible object in IFC.

• document (ifcopenshell.entity_instance) – The IfcDocumentReference to associate to, or alternatively an IfcDocumentInformation, though this is not recommended.

Returns:

The IfcRelAssociatesDocument relationship or None if products was an empty list or all products were already assigned to the document.

Return type:

ifcopenshell.entity_instance

Example:

document = ifcopenshell.api.document.add_information(model)
ifcopenshell.api.document.edit_information(model,
    information=document,
    attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
    "Location": "A-GA-6100 - Overall Plan.pdf"})
reference = ifcopenshell.api.document.add_reference(model, information=document)

# Let's imagine storey represents an IfcBuildingStorey for the ground floor
ifcopenshell.api.document.assign_document(model, products=[storey], document=reference)

ifcopenshell.api.document.edit_information(file: ifcopenshell.file, information: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcDocumentInformation

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

Parameters:

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

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

Returns:

None

Return type:

None

Example:

document = ifcopenshell.api.document.add_information(model)
ifcopenshell.api.document.edit_information(model,
    information=document,
    attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
    "Location": "A-GA-6100 - Overall Plan.pdf"})

ifcopenshell.api.document.edit_reference(file: ifcopenshell.file, reference: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcDocumentReference

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

Parameters:

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

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

Returns:

None

Return type:

None

Example:

document = ifcopenshell.api.document.add_information(model)
ifcopenshell.api.document.edit_information(model,
    information=document,
    attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
    "Location": "A-GA-6100 - Overall Plan.pdf"})
reference = ifcopenshell.api.document.add_reference(model, information=document)
ifcopenshell.api.document.edit_reference(model,
    reference=reference, attributes={"Identification": "2.1.15"})

ifcopenshell.api.document.remove_information(file: ifcopenshell.file, information: ifcopenshell.entity_instance) → None

Removes a document information

All references and associations are also removed.

Parameters:

information (ifcopenshell.entity_instance) – The IfcDocumentInformation to remove

Returns:

None

Return type:

None

Example:

# Add a document
document = ifcopenshell.api.document.add_information(model)
# ... and remove it!
ifcopenshell.api.document.remove_information(model, information=document)

ifcopenshell.api.document.remove_reference(file: ifcopenshell.file, reference: ifcopenshell.entity_instance) → None

Remove a document reference

All associations with objects are removed.

Parameters:

reference (ifcopenshell.entity_instance) – The IfcDocumentReference to remove

Returns:

None

Return type:

None

Example:

document = ifcopenshell.api.document.add_information(model)
reference = ifcopenshell.api.document.add_reference(model, information=document)
ifcopenshell.api.document.remove_reference(model, reference=reference)

ifcopenshell.api.document.unassign_document(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], document: ifcopenshell.entity_instance) → None

Unassigns a document and an association to the list of products

Parameters:

• product (list[ifcopenshell.entity_instance]) – The list of objects that the document reference or information is related to.

• document (ifcopenshell.entity_instance) – The IfcDocumentReference (typically) or in rare cases the IfcDocumentInformation that is associated with the product

Returns:

None

Return type:

None

Example:

document = ifcopenshell.api.document.add_information(model)
ifcopenshell.api.document.edit_information(model,
    information=document,
    attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
    "Location": "A-GA-6100 - Overall Plan.pdf"})
reference = ifcopenshell.api.document.add_reference(model, information=document)

# Let's imagine storey represents an IfcBuildingStorey for the ground floor
ifcopenshell.api.document.assign_document(model, products=[storey], document=reference)

# Now let's change our mind and remove the association
ifcopenshell.api.document.unassign_document(model, products=[storey], document=reference)