ifcopenshell.api.material.add_material

Module Contents

ifcopenshell.api.material.add_material.add_material(file: ifcopenshell.file, name: str | None = None, category: str | None = None, description: str | None = None) → ifcopenshell.entity_instance

Adds a new material

A material in IFC represents a physical material, such as timber, steel, concrete, aluminium, etc. It may also contain physical properties used for structural or lighting simulation. Note that unlike the computer graphics industry, a material by itself does not define any colour or lighting information. Colours in IFC are known as “styles”, and an IFC material may or may not have any style information associated with it. See ifcopenshell.api.style for more information.

A material is typically given a code name which is used by architects in elevations and details when tagging finishes. Materials are also useful to structural engineers in specifying the exact types of concrete and steel to be used in structural simulations.

In addition, materials can belong to a category. Specifying this category is critical to allow model recipients to make simple queries like “show me all concrete / steel” elements in the model. Without standardised category naming of all materials, this type of query becomes a bespoke and inefficient task. A list of categories are: ‘concrete’, ‘steel’, ‘aluminium’, ‘block’, ‘brick’, ‘stone’, ‘wood’, ‘glass’, ‘gypsum’, ‘plastic’, and ‘earth’. The user is allowed to specify their own category instead if none of these categories are appropriate.

Note that categories are not available in IFC2X3. This shortcoming is one of the big reasons projects should upgrade to IFC4.

Additionally, a material’s description provides more information beyond its name or category.

Parameters:

  • name (str, optional) – The name of the material, typically tagged in a finishes drawing or schedule.

  • category (str, optional) – The category of the material.

  • description (str, optional) – A description of the material.

Returns:

The newly created IfcMaterial

Return type:

ifcopenshell.entity_instance

Example:

# Let's create two materials with their respective categories
concrete = ifcopenshell.api.material.add_material(model, name="CON01", category="concrete", description="Garage Slab")
steel = ifcopenshell.api.material.add_material(model, name="ST01", category="steel", description="Corten Steel")

# Let's imagine an urban concrete bench which is purely made out of concrete
concrete_bench = ifcopenshell.api.root.create_entity(model, ifc_class="IfcFurnitureType")

# Assign the concrete material to that bench. Note that no colour
# "Style" has been specified.
ifcopenshell.api.material.assign_material(model, products=[concrete_bench], material=concrete)