Add API documentation for the material module

2026-08-11 02:02:22 +00:00 · 2022-12-07 17:30:08 +11:00
parent 7da3d9ee70
commit cf87852d9c
23 changed files with 1129 additions and 90 deletions
@@ -18,11 +18,61 @@


 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, name=None, category=None):
+        """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.
+
+        :param name: The name of the material, typically tagged in a finishes
+            drawing or schedule.
+        :type name: str
+        :param category: The category of the material.
+        :type category: str, optional
+        :return: The newly created IfcMaterial
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Let's create two materials with their respective categories
+            concrete = ifcopenshell.api.run("material.add_material", model, name="CON01", category="concrete")
+            steel = ifcopenshell.api.run("material.add_material", model, name="ST01", category="steel")
+
+            # Let's imagine an urban concrete bench which is purely made out of concrete
+            concrete_bench = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcFurnitureType")
+
+            # Assign the concrete material to that bench. Note that no colour
+            # "Style" has been specified.
+            ifcopenshell.api.run("material.assign_material", model, product=concrete_bench, material=concrete)
+        """
        self.file = file
-        self.settings = {"name": "Unnamed"}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"name": name or "Unnamed", "category": category}

    def execute(self):
-        return self.file.create_entity("IfcMaterial", **{"Name": self.settings["name"] or "Unnamed"})
+        material = self.file.create_entity("IfcMaterial", **{"Name": self.settings["name"] or "Unnamed"})
+        if self.settings["category"]:
+            material.Category = self.settings["category"]
+        return material