First Commit

.venv/Lib/site-packages/ifcopenshell/api/material/add_material.py

@@ -0,0 +1,86 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2021 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+from typing import Optional
+
+import ifcopenshell
+
+
+def add_material(
+    file: ifcopenshell.file,
+    name: Optional[str] = None,
+    category: Optional[str] = None,
+    description: Optional[str] = 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.
+
+    :param name: The name of the material, typically tagged in a finishes
+        drawing or schedule.
+    :param category: The category of the material.
+    :param description: A description of the material.
+    :return: The newly created IfcMaterial
+
+    Example:
+
+    .. code:: python
+
+        # 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)
+    """
+    material = file.create_entity("IfcMaterial", **{"Name": name or "Unnamed"})
+    if category:
+        material.Category = category
+    if description:
+        material.Description = description
+    return material