See #7503. Add docs about geometry_library

src/ifcopenshell-python/docs/ifcopenshell-python/geometry_processing.rst

@@ -19,7 +19,6 @@ edges, and faces, or alternatively an OpenCASCADE BRep.
    applications. See the `Geometry iterator`_ section below after reading this
    to see how to process geometry with multiple threads.
 
-
 Here is a simple example of processing a single wall into a list of vertices and
 faces. In this example, a ``shape`` variable is returned, which holds geometry
 related information in ``shape.geometry``:
@@ -33,8 +32,12 @@ related information in ``shape.geometry``:
     ifc_file = ifcopenshell.open('model.ifc')
     element = ifc_file.by_type('IfcWall')[0]
 
+    # Create a shape using a hybrid of the cgal-simple geometry kernel and opencascade as a fallback
+    # Choosing a geometry kernel has a big impact on speed and capability.
+    # It is recommended to use the "hybrid-cgal-simple-opencascade" kernel.
     settings = ifcopenshell.geom.settings()
-    shape = ifcopenshell.geom.create_shape(settings, element)
+    shape = ifcopenshell.geom.create_shape(
+        settings, element, geometry_library="hybrid-cgal-simple-opencascade")
 
     # The GUID of the element we processed
     print(shape.guid)
@@ -224,7 +227,8 @@ Here is a simple example in Python:
     ifc_file = ifcopenshell.open('model.ifc')
 
     settings = ifcopenshell.geom.settings()
-    iterator = ifcopenshell.geom.iterator(settings, ifc_file, multiprocessing.cpu_count())
+    iterator = ifcopenshell.geom.iterator(
+        settings, ifc_file, multiprocessing.cpu_count(), geometry_library="hybrid-cgal-simple-opencascade")
     if iterator.initialize():
         while True:
             shape = iterator.get()
@@ -252,7 +256,9 @@ only process wall elements.
 .. code-block:: python
 
     walls = ifc.by_type('IfcWall')
-    iterator = ifcopenshell.geom.iterator(settings, ifc, multiprocessing.cpu_count(), include=walls)
+    iterator = ifcopenshell.geom.iterator(
+        settings, ifc, multiprocessing.cpu_count(),
+        include=walls, geometry_library="hybrid-cgal-simple-opencascade")
 
 .. note::
 

src/ifcopenshell-python/docs/ifcopenshell/geometry_settings.rst

@@ -111,6 +111,32 @@ In Python, this is set when the iterator is constructed:
     import multiprocessing
     iterator = ifcopenshell.geom.iterator(settings, ifc_file, num_threads=multiprocessing.cpu_count())
 
+geometry_library
+^^^^^^^^^^^^^^^^
+
++--------+-------------------+-------------+
+| Type   | IfcConvert Option | Default     |
++========+===================+=============+
+| STRING | ``--kernel``      | opencascade |
++--------+-------------------+-------------+
+
+IfcOpenShell supports multiple geometry kernels to process geometry. Choosing the geometry kernel has trade-offs on geometric support, speed, and maturity. It is possible and recommended to chose a hybrid geometry kernel by providing the name ``hybrid-kernelX-kernelY``, where ``kernelX`` is the name of the first kernel to try, and ``kernelY`` is the name of the fallback kernel, for example ``hybrid-cgal-simple-opencascade``.
+
+.. csv-table::
+   :header: "Comparison", "cgal-simple", "cgal", "opencascade"
+
+   "Speed", "Very fast", "Fast", "Slow"
+   "Curves in extrusion footprints", "Only circle and ellipse arcs are converted to polylines", "Only circle and ellipse arcs are converted to polylines", "Full support including beziers and nurbs"
+   "Advanced (curved) breps", "No", "No", "Full support"
+   "Boolean operations", "No", "Full support", "Full support"
+   "Boolean operations with tolerance / fuzziness handling", "No", "Only manifold inputs", "Full support, including non-manifold inputs"
+   "Sweeps along alignment curves", "Partial", "Partial", "Full support"
+
+.. code-block:: python
+
+    iterator = ifcopenshell.geom.iterator(settings, ifc_file, geometry_library="hybrid-cgal-simple-opencascade")
+    ifcopenshell.geom.create_shape(settings, element, geometry_library="opencascade")
+
 Iterator settings
 -----------------