`ifcopenshell.api.pset`¶

Submodules¶

Package Contents¶

ifcopenshell.api.pset.add_pset(file, product=None, name=None) → None¶

Adds a new property set to a product

Products, such as physical objects or types in IFC may have properties associated with them. These properties are typically simple key value metadata with data types. For example, a wall type may have a property called FireRating with a text value of “2HR”. Properties are grouped into property sets, so that related properties are grouped together.

If a property is assigned to a type, the property is inherited by all occurrences of that type. For example, a wall type with a FireRating property of “2HR” automatically implies that all walls of that wall type also have a FireRating of “2HR”. It is not necessary to explictly define the property again for each occurrence. This also means that properties are typically defined on types. If the same property is defined at an occurrence, this overrides the property defined on the type.

buildingSMART has come up with a long list of standardised properties for the most common properties required internationally. This solves the age-old question of “where do I store my FireRating data for walls”? The answer, in this case, is in the “FireRating” property with an “IfcLabel” data type grouped in the “Pset_WallCommon” property set. It is recommended to view the list of standardised buildingSMART properties and see if any suit your needs first. If none are appropriate, then you are free to create your own custom properties.

This function adds a blank named property set. One you have a property set you may add properties using ifcopenshell.api.pset.edit_pset.

See also ifcopenshell.api.pset.add_qto if you want to add quantification data, rather than arbitrary metadata.

Parameters:

product (ifcopenshell.entity_instance) – The IfcObject that you want to assign a property set to.
name (str) – The name of the property set. Property sets that are standardised by buildingSMART typically have a prefix of “Pset_”, like “Pset_WallCommon”. If you create your own, you must not use that prefix. It is recommended to use your own prefix tailored to your project, company, or local government requirement.

Returns:

The newly created IfcPropertySet

Return type:

ifcopenshell.entity_instance

Example:

# Let's imagine we have a new wall type.
wall_type = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWallType")

# Note that this only creates and assigns an empty property set. We
# still need to add properties into the property set. Having blank
# property sets are invalid.
pset = ifcopenshell.api.run("pset.add_pset", model, product=wall_type, name="Pset_WallCommon")

# Add a fire rating property standardised by buildingSMART.
ifcopenshell.api.run("pset.edit_pset", model, pset=pset, properties={"FireRating": "2HR"})

ifcopenshell.api.pset.add_qto(file, product=None, name=None) → None¶

Adds a new quantity set to a product

Products, such as physical objects or types in IFC may have quantities associated with them. These quantities are typically simple key value metadata with data types. For example, a wall type may have a quantity called NetSideArea with a area value of “4.2”. Quantities are grouped into quantity sets, so that related quantities are grouped together.

Quantities are similar to, but different from properties in that they may store a method of measurement or formula. Quantities may also have parametric relationships to other calculated values, such as cost schedules, resource utilisation, or construction task durations.

buildingSMART has come up with a long list of standardised quantities for the most common quantities required internationally. This solves the age-old question of “what’s the standard way of storing quantity take-off data”? It is recommended to view the list of standardised buildingSMART quantities and see if any suit your needs first. If none are appropriate, then you are free to create your own custom quantities.

This function adds a blank named quantity set. One you have a quantity set you may add quantities using ifcopenshell.api.pset.edit_qto.

See also ifcopenshell.api.pset.add_qto if you want to arbitrary metadata, rather than quantification data.

Parameters:

product (ifcopenshell.entity_instance) – The IfcObject that you want to assign a quantity set to.
name (str) – The name of the quantity set. Quantity sets that are standardised by buildingSMART typically have a prefix of “Qto_”, like “Qto_WallBaseQuantities”. If you create your own, you must not use that prefix. It is recommended to use your own prefix tailored to your project, company, or local government requirement.

Returns:

The newly created IfcElementQuantity

Return type:

ifcopenshell.entity_instance

Example:

# Let's imagine we have a new wall.
wall = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWall")

# Note that this only creates and assigns an empty quantity set. We
# still need to add quantities into the property set. Having blank
# quantity sets are invalid.
qto = ifcopenshell.api.run("pset.add_qto", model, product=wall_type, name="Qto_WallBaseQuantities")

# Add a side area property standardised by buildingSMART. This
# allows quantity take-off to occur, even though no geometry has
# even been modelled!
ifcopenshell.api.run("pset.edit_qto", model, qto=qto, properties={"NetSideArea": 4.2})

ifcopenshell.api.pset.edit_pset(file: ifcopenshell.entity_instance, pset: ifcopenshell.entity_instance, name: str | None = None, properties: dict[str, Any] | None = None, pset_template: ifcopenshell.entity_instance | None = None, should_purge: bool = False) → None¶

Edits a property set and its properties

At its simplest usage, this may be used to edit the name of a property set. It may also be used to add, edit, or remove properties, either arbitrarily or using a property set template.

A list of properties are provided as a dictionary, where the keys are property names, and values are property values. Keys that don’t already exist are interpreted as properties to be added. Keys that already exist are interpreted as properties to be edited. A “None” value may specify a property to be deleted.

Properties must have a data type. There are lots of data types in IFCs, not just simple unitless data types like integers, booleans, text, but also distinguishing between types of text, like labels versus descriptive text. There are also lots of unit-based data types like areas, volumes, lengths, power, density, flow rates, pressure, etc.

To ensure the appropriate data type is used for properties, a property set template may be used. These can be seen as “property specifications”. A default selection is provided by buildingSMART, so that all buildingSMART defined standard properties have exactly the same data types and exactly the right property names without fear of invalid data or typos. The built-in buildingSMART templates are always loaded. However, you may also specify your own templates. If you try to add a non-standard property that does not exist in either your own template or in the built-in buildingSMART template, then you have the responsibility to ensure that data types are always consistent and correct.

Parameters:

pset (ifcopenshell.entity_instance) – The IfcPropertySet to edit.
name (str, optional) – A new name for the property set. If no name is specified, the property set name is not changed.
properties (dict) – A dictionary of properties. The keys must be a string of the name of the property. The data type of the value will be determined by the property set template. If no property set template is found, the data types of the Python values will influence the IFC data type of the property. String values will become IfcLabel, float values will become IfcReal, booleans will become IfcBoolean, and integers will become IfcInteger. If more control is desired, you may explicitly specify IFC data objects directly. Note that provided properties might be mutated in the process.
pset_template (ifcopenshell.entity_instance, optional) – If a property set template is provided, this will be used to determine data types. If no user-defined template is provided, the built-in buildingSMART templates will be loaded.
should_purge (bool, optional) – If left as False, properties set to None will be left as None but not removed. If set to true, properties set to None will actually be removed.

Returns:

None

Return type:

None

Example:

# Let's imagine we have a new wall type.
wall_type = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWallType")

# This is a standard buildingSMART property set.
pset = ifcopenshell.api.run("pset.add_pset", model, product=wall_type, name="Pset_WallCommon")

# In this scenario, we don't specify any pset_template because it is
# part of the built-in buildingSMART templates, and so the
# FireRating will automatically be an IfcLabel, and the thermal
# transmittance value will automatically be an
# IfcThermalTransmittanceMeasure. Neither of these properties exist
# yet, so they will be created.
ifcopenshell.api.run("pset.edit_pset", model,
    pset=pset, properties={"FireRating": "2HR", "ThermalTransmittance": 42.3})

# We can edit existing properties. In this case, "FireRating" is
# edited from "2HR" to "1HR". Combustible is new, and will be added.
# The existing "ThermalTransmittance" property will be left
# unchanged.
ifcopenshell.api.run("pset.edit_pset", model,
    pset=pset, properties={"FireRating": "1HR", "Combustible": False})

# Setting to None will change the value but not delete the property.
ifcopenshell.api.run("pset.edit_pset", model, pset=pset, properties={"Combustible": None})

# If you actually want to delete the property, enable purging.
ifcopenshell.api.run("pset.edit_pset", model, pset=pset,
    properties={"Combustible": None}, should_purge=True)

# What if we wanted to manage our own properties? Let's create our
# own "Company Standard" property set templates. Notice how we
# prefix our property set with "Foo_", if our company name was "Foo"
# this would make sense.
template = ifcopenshell.api.run("pset_template.add_pset_template", model, name="Foo_bar")

# Let's imagine we want all model authors to specify two properties,
# one being a length measurement and another being a boolean.
prop1 = ifcopenshell.api.run("pset_template.add_prop_template", model,
    pset_template=template, name="DemoA", primary_measure_type="IfcLengthMeasure")
prop2 = ifcopenshell.api.run("pset_template.add_prop_template", model,
    pset_template=template, name="DemoB", primary_measure_type="IfcBoolean")

# Now we can use our property set template to add our properties,
# and the data types will always match our template.
pset = ifcopenshell.api.run("pset.add_pset", model, product=wall_type, name="Foo_Bar")
ifcopenshell.api.run("pset.edit_pset", model,
    pset=pset, properties={"DemoA": 42.3, "DemoB": True}, pset_template=template)

# Here's a third scenario where we want to add arbitrary properties
# that are not standardised by anything, not even our own custom
# templates.
pset = ifcopenshell.api.run("pset.add_pset", model, product=wall_type, name="Custom_Pset")
ifcopenshell.api.run("pset.edit_pset", model,
    pset=pset, properties={
        # Basic Python data types are mapped to a sensible default
        "SomeLabel": "Foo",
        "SomeNumber": 12.3,
        # But we can always specify exactly what we're after too
        "ExplicitLength": model.createIfcLengthMeasure(42.3)
    })

# Editing existing properties will retain their current data types
# if possible. So this will still be a length measure.
ifcopenshell.api.run("pset.edit_pset", model, pset=pset, properties={"ExplicitLength": 12.3})

ifcopenshell.api.pset.edit_qto(file, qto=None, name=None, properties=None, pset_template=None) → None¶

Edits a quantity set and its quantities

At its simplest usage, this may be used to edit the name of a quantity set. It may also be used to add, edit, or remove quantities.

See ifcopenshell.api.pset.edit_pset for documentation on how this is intended to be used.

One major difference is that quantities set to None are always purged. It is not allowed to have None quantities in IFC.

Parameters:

qto (ifcopenshell.entity_instance) – The IfcElementQuantity to edit.
name (str, optional) – A new name for the quantity set. If no name is specified, the quantity set name is not changed.
properties (dict) – A dictionary of properties. The keys must be a string of the name of the quantity. The data type of the value will be determined by the quantity set template. If no quantity set template is found, the data types of the Python values will influence the IFC data type of the quantity. String values will become IfcLabel, float values will become IfcReal, booleans will become IfcBoolean, and integers will become IfcInteger. If more control is desired, you may explicitly specify IFC data objects directly.
pset_template (ifcopenshell.entity_instance) – If a quantity set template is provided, this will be used to determine data types. If no user-defined template is provided, the built-in buildingSMART templates will be loaded.

Returns:

None

Return type:

None

Example:

# Let's imagine we have a new wall type.
wall = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWall")

# This is a standard buildingSMART property set.
qto = ifcopenshell.api.run("pset.add_qto", model, product=wall, name="Qto_WallBaseQuantities")

# In this scenario, we don't specify any pset_template because it is
# part of the built-in buildingSMART templates, and so the Length
# will automatically be an IfcLengthMeasure, and the NetVolume will
# automatically be an IfcVolumeMeasure. Neither of these properties
# exist yet, so they will be created.
ifcopenshell.api.run("pset.edit_qto", model, qto=qto, properties={"Length": 12, "NetVolume": 7.2})

# Setting to None will delete the quantity.
ifcopenshell.api.run("pset.edit_qto", model, qto=qto, properties={"Length": None})

# What if we wanted to manage our own properties? Let's create our
# own "Company Standard" property set templates. Notice how we
# prefix our property set with "Foo_", if our company name was "Foo"
# this would make sense. In this example, we say that our template
# only applies to walls and is for quantities.
template = ifcopenshell.api.run("pset_template.add_pset_template", model,
    name="Foo_Wall", template_type="QTO_OCCURRENCEDRIVEN", applicable_entity="IfcWall")

# Let's imagine we want all model authors to specify a length
# measurement for the portion of a wall that is overhanging.
prop = ifcopenshell.api.run("pset_template.add_prop_template", model, pset_template=template,
    name="OverhangLength", template_type="Q_LENGTH", primary_measure_type="IfcLengthMeasure")

# Now we can use our property set template to add our properties,
# and the data types will always match our template.
qto = ifcopenshell.api.run("pset.add_qto", model, product=wall, name="Foo_Wall")
ifcopenshell.api.run("pset.edit_qto", model,
    qto=qto, properties={"OverhangLength": 42.3}, pset_template=template)

# Here's a third scenario where we want to add arbitrary quantities
# that are not standardised by anything, not even our own custom
# templates.
qto = ifcopenshell.api.run("pset.add_qto", model, product=wall, name="Custom_Qto")
ifcopenshell.api.run("pset.edit_qto", model,
    qto=qto, properties={
        "SomeLength": model.createIfcLengthMeasure(42.3),
        "SomeArea": model.createIfcAreaMeasure(21.0)
    })

# Editing existing quantities will retain their current data types
# if possible. So this will still be a length measure.
ifcopenshell.api.run("pset.edit_qto", model, qto=qto, properties={"SomeLength": 12.3})

ifcopenshell.api.pset.remove_pset(file, product=None, pset=None) → None¶

Removes a property set from a product

All properties that are part of this property set are also removed.

Parameters:

product (ifcopenshell.entity_instance) – The IfcObject to remove the property set from.
pset (ifcopenshell.entity_instance) – The IfcPropertySet or IfcElementQuantity to remove.

Returns:

None

Return type:

None

Example:

# Let's imagine we have a new wall type with a property set.
wall_type = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWallType")
pset = ifcopenshell.api.run("pset.add_pset", model, product=wall_type, name="Pset_WallCommon")

# Remove it!
ifcopenshell.api.run("pset.remove_pset", model, product=wall_type, pset=pset)

ifcopenshell.api.pset¶

Submodules¶

Package Contents¶

`ifcopenshell.api.pset`¶