diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/code_examples.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/code_examples.rst index 72102bdd58..4c52816c41 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python/code_examples.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/code_examples.rst @@ -1,4 +1,228 @@ Code examples ============= -TODO +Examples for common basic tasks are shown here. In all examples, it is assumed +that you have a IFC model loaded into model variable like so: + + +.. code-block:: python + + import ifcopenshell + + model = ifcopenshell.open('model.ifc') + +Get all wall types +------------------ + +.. code-block:: python + + for wall_type in model.by_type("IfcWallType"): + print("The wall type element is", wall_type) + print("The name of the wall type is", wall_type.Name) + +Get all door occurrences of a type +---------------------------------- + +.. code-block:: python + + import ifcopenshell.util.element + + for door_type in model.by_type("IfcDoorType"): + print("The door type is", door_type.Name) + doors = ifcopenshell.util.element.get_types(door_type) + print(f"There are {len(doors)} of this type") + for door in doors: + print("The door name is", door.Name) + + +Get the type of a wall +---------------------- + +.. code-block:: python + + import ifcopenshell.util.element + + wall = model.by_type("IfcWall")[0] + wall_type = ifcopenshell.util.element.get_type(wall) + print(f"The wall type of {wall.Name} is {wall_type.Name}") + +Get the properties of a wall type +--------------------------------- + +.. code-block:: python + + import ifcopenshell.util.element + + wall = model.by_type("IfcWall")[0] + wall_type = ifcopenshell.util.element.get_type(wall) + + # Get all properties and quantities as a dictionary + # returns {"Pset_WallCommon": {"id": 123, "FireRating": "2HR", ...}} + psets = ifcopenshell.util.element.get_psets(wall_type) + print(psets) + + # Get all properties and quantities of the wall, including inherited type properties + psets = ifcopenshell.util.element.get_psets(wall) + print(psets) + + # Get only properties and not quantities + print(ifcopenshell.util.element.get_psets(wall, psets_only=True)) + + # Get only quantities and not properties + print(ifcopenshell.util.element.get_psets(wall, qtos_only=True)) + + +Find the spatial container of an element +---------------------------------------- + +.. code-block:: python + + import ifcopenshell.util.element + + wall = model.by_type("IfcWall")[0] + # Walls are typically located on a storey, equipment might be located in spaces, etc + container = ifcopenshell.util.element.get_container(wall) + # The wall is located on Level 01 + print(f"The wall is located on {container.Name}") + +Get all elements in a container +------------------------------- + +.. code-block:: python + + import ifcopenshell.util.element + + for storey in model.by_type("IfcBuildingStorey"): + elements = ifcopenshell.util.element.get_decomposition(storey) + print(f"There are {len(elements)} located on storey {storey.Name}, they are:") + for element in elements: + print(element.Name) + +Get the XYZ coordinates of a element +------------------------------------ + +.. code-block:: python + + import ifcopenshell.util.placement + + wall = model.by_type("IfcWall")[0] + # This returns a 4x4 matrix, including the location and rotation. For example: + # array([[ 1.00000000e+00, 0.00000000e+00, 0.00000000e+00, 2.00000000e+00], + # [ 0.00000000e+00, 1.00000000e+00, 0.00000000e+00, 3.00000000e+00], + # [ 0.00000000e+00, 0.00000000e+00, 1.00000000e+00, 5.00000000e+00], + # [ 0.00000000e+00, 0.00000000e+00, 0.00000000e+00, 1.00000000e+00]]) + matrix = ifcopenshell.util.placement.get_local_placement(wall.ObjectPlacement) + # The last column holds the XYZ values, such as: + # array([ 2.00000000e+00, 3.00000000e+00, 5.00000000e+00]) + print(matrix[:,3][:3]) + +Get the geometry of an element +------------------------------ + +See :doc:`Geometry processing` for details. + +Get the classification of an element +------------------------------------ + +.. code-block:: python + + import ifcopenshell.util.classification + + wall = model.by_type("IfcWall")[0] + # Elements may have multiple classification references assigned + references = ifcopenshell.util.classification.get_references(wall) + for reference in references: + # A reference code might be Pr_30_59_99_02 + print("The wall has a classification reference of", reference[1]) + # A system might be Uniclass 2015 + system = ifcopenshell.util.classification.get_classification(reference) + print("This reference is part of the system", system.Name) + +Convert to and from SI units and project units +---------------------------------------------- + +.. code-block:: python + + import ifcopenshell.util.unit + + unit_scale = ifcopenshell.util.unit.calculate_unit_scale(model) + si_meters = ifc_project_length * unit_scale + ifc_project_length = si_meters / unit_scale + +Get the distribution system of an element +----------------------------------------- + +.. code-block:: python + + import ifcopenshell.util.classification + + pipe = model.by_type("IfcPipeSegment")[0] + # Elements may be assigned to multiple systems simultaneously, such as electrical, hydraulic, etc + systems = ifcopenshell.util.system.get_element_systems(pipe) + for system in systems: + # For example, it might be part of a Chilled Water system + print("This pipe is part of the system", system.Name) + +Create a simple model from scratch +---------------------------------- + +.. code-block:: python + + import ifcopenshell + from ifcopenshell.api import run + + # Create a blank model + model = ifcopenshell.file() + + # All projects must have one IFC Project element + project = run("root.create_entity", model, ifc_class="IfcProject") + project.Name = "My Project" + + # Geometry is optional in IFC, but because we want to use geometry in this example, let's define units + # Assigning without arguments defaults to metric units + run("unit.assign_unit", model) + + # Let's create a modeling geometry context, so we can store 3D geometry (note: IFC supports 2D too!) + context = run("context.add_context", model, context_type="Model") + # In particular, in this example we want to store the 3D "body" geometry of objects, i.e. the body shape + body = run( + "context.add_context", + model, + context_type="Model", + context_identifier="Body", + target_view="MODEL_VIEW", + parent=context, + ) + + # Create a site, building, and storey. Many hierarchies are possible. + site = run("root.create_entity", model, ifc_class="IfcSite") + building = run("root.create_entity", model, ifc_class="IfcBuilding") + storey = run("root.create_entity", model, ifc_class="IfcBuildingStorey") + + # Let's name them to be neat. + site.Name = "My Site" + building.Name = "Building A" + storey.Name = "Ground Floor" + + # Since the site is our top level location, assign it to the project + # Then place our building on the site, and our storey in the building + run("aggregate.assign_object", model, relating_object=project, product=site) + run("aggregate.assign_object", model, relating_object=site, product=building) + run("aggregate.assign_object", model, relating_object=building, product=storey) + + # Let's create a new wall + wall = run("root.create_entity", model, ifc_class="IfcWall") + # Add a new wall-like body geometry, 5 meters long, 3 meters high, and 200mm thick + representation = run("geometry.add_wall_representation", model, context=body, length=5, height=3, thickness=0.2) + # Assign our new body geometry back to our wall + run("geometry.assign_representation", model, product=wall, representation=representation) + + # Place our wall in the ground floor + run("spatial.assign_container", model, relating_structure=storey, product=wall) + + # Write out to a file + model.write("/home/dion/model.ifc") + +Here is the result: + +.. image:: images/simple-model.png diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/images/simple-model.png b/src/ifcopenshell-python/docs/ifcopenshell-python/images/simple-model.png new file mode 100644 index 0000000000..e6cd90649b Binary files /dev/null and b/src/ifcopenshell-python/docs/ifcopenshell-python/images/simple-model.png differ