restructuring documentation

compas-dev · Oct 25, 2024 · a507b6a · a507b6a
1 parent 62b8f2b
commit a507b6a
Show file tree

Hide file tree

Showing 18 changed files with 251 additions and 143 deletions.
diff --git a/docs/_images/architecture.jpg b/docs/_images/architecture.jpg
diff --git a/docs/architecture.rst b/docs/architecture.rst
@@ -1,5 +1,59 @@
 ********************************************************************************
-Archtiecture
+Software Architecture
 ********************************************************************************
 
-This section is still under construction. Please check back later.
+In a nutshell, COMPAS IFC is built around a three-layer structure, purposefully designed for different group of users concerned with different level of granularity of the IFC data.
+
+- **Top-layer**: This layer provides simple usage interfaces for interacting with a BIM model. It abstracts the complexities of the IFC format, allowing non-experts to manipulate IFC data with ease.
+
+- **Middle-layer**: This layer grants access to individual IFC entities and their properties. It is designed for advanced users who need to work with the geometry and metadata of IFC entities at a more granular level.
+
+- **Bottom-layer**: This layer deals with the raw IFC data and schema processing. It concerns the most technical users such as contributors to the software itself regarding issues such as performance, memory usage, etc.
+
+The architecture is designed to separate concerns, allowing users to choose the level of complexity they need, from simple model manipulations to detailed data handling.
+
+.. figure:: _images/architecture.jpg
+   :alt: COMPAS IFC architecture
+   :align: center
+
+   COMPAS IFC architecture
+
+
+
+
+Top-layer
+---------
+
+The Top-layer of COMPAS IFC centers on the `Model` class, providing a user-friendly interface for IFC data interaction. This class offers intuitive APIs for simplified BIM model manipulation.
+
+**Key features of the `Model` class:**
+
+1. **Simple file operations**: Load, save, and create IFC files effortlessly.
+2. **Built-in visualization methods**: For easy model inspection.
+3. **High-level querying**: For straightforward element retrieval and manipulation.
+4. **Abstraction of IFC complexities**: Enabling effective BIM model work without deep IFC knowledge.
+
+This approach lowers the entry barrier for IFC file handling, allowing users to focus on their tasks rather than underlying data structures. For more details on the `Model` class, see the `Tutorials <tutorials.html>`_ section.
+
+Middle-layer
+------------
+
+The Middle-layer of COMPAS IFC provides a comprehensive suite of native Python classes for interacting with individual IFC entities and their properties. These classes are automatically generated from the official IFC schemas, ensuring a complete and up-to-date mapping of IFC classes and types.
+
+**Key features of the Middle-layer include:**
+
+1. **Strongly typed classes**: Each class is strongly typed, enabling modern IDEs (such as those using Pylance) to provide extensive type hints and analysis. This enhances the development experience by improving code completion, reducing development time, and minimizing the need for constant documentation lookups.
+
+2. **Robust extension mechanism**: COMPAS IFC includes a powerful extension mechanism that allows for the enhancement of key classes to simplify their usage and empowers users to create custom extensions for tailored functionality. For instance:
+
+   - The ``IfcProduct`` class is extended with a ``geometry`` property that parses complex IFC geometric representations into COMPAS-based geometry.
+   - The ``IfcElement`` class is augmented with ``parent`` and ``children`` properties, simplifying navigation of the IFC spatial hierarchy.
+
+These features provide a powerful and flexible interface for working with IFC data at a granular level, suitable for advanced users who require detailed control over IFC entities and their properties.
+
+For more information on the extension mechanism, please refer to the `API: extensions <architecture.html>`_ section. For a comprehensive overview of the class mapping, see the `API Reference: Full class mapping <api.html>`_.
+
+Bottom-layer
+------------
+
+Lastly, in the Bottom-layer, COMPAS IFC interacts with the IfcOpenShell library to parse and manage IFC data. This layer is primarily of interest to contributors and advanced users who needs to modify the lower-level functionalities for tasks such as performance optimization, memory usage reduction, etc.
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,22 @@
+********************************************************************************
+Examples
+********************************************************************************
+
+In this section you will find full examples scripts on how to use the COMPAS IFC package.
+
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :glob:
+
+   examples/Basics.1_overview.rst
+   examples/Basics.2_query_entities.rst
+   examples/Basics.3_spatial_hierarchy.rst
+   examples/Basics.4_element_info.rst
+   examples/Basics.5_visualization.rst
+   examples/Basics.6_edit_export.rst
+   examples/Basics.7_create_new.rst
+   examples/Advanced.1_units.rst
+   examples/Advanced.2_sessions.rst
+   examples/Advanced.3_custom_extensions.rst
diff --git a/docs/tutorials/Advanced.1_units.rst → docs/examples/Advanced.1_units.rst b/docs/tutorials/Advanced.1_units.rst → docs/examples/Advanced.1_units.rst
diff --git a/docs/tutorials/Advanced.2_sessions.rst → docs/examples/Advanced.2_sessions.rst b/docs/tutorials/Advanced.2_sessions.rst → docs/examples/Advanced.2_sessions.rst
diff --git a/...utorials/Advanced.3_custom_extensions.rst → ...examples/Advanced.3_custom_extensions.rst b/...utorials/Advanced.3_custom_extensions.rst → ...examples/Advanced.3_custom_extensions.rst
diff --git a/docs/tutorials/Basics.1_overview.rst → docs/examples/Basics.1_overview.rst b/docs/tutorials/Basics.1_overview.rst → docs/examples/Basics.1_overview.rst
diff --git a/docs/tutorials/Basics.2_query_entities.rst → docs/examples/Basics.2_query_entities.rst b/docs/tutorials/Basics.2_query_entities.rst → docs/examples/Basics.2_query_entities.rst
diff --git a/.../tutorials/Basics.3_spatial_hierarchy.rst → docs/examples/Basics.3_spatial_hierarchy.rst b/.../tutorials/Basics.3_spatial_hierarchy.rst → docs/examples/Basics.3_spatial_hierarchy.rst
diff --git a/docs/tutorials/Basics.4_element_info.rst → docs/examples/Basics.4_element_info.rst b/docs/tutorials/Basics.4_element_info.rst → docs/examples/Basics.4_element_info.rst
diff --git a/docs/tutorials/Basics.5_visualization.rst → docs/examples/Basics.5_visualization.rst b/docs/tutorials/Basics.5_visualization.rst → docs/examples/Basics.5_visualization.rst
diff --git a/docs/tutorials/Basics.6_edit_export.rst → docs/examples/Basics.6_edit_export.rst b/docs/tutorials/Basics.6_edit_export.rst → docs/examples/Basics.6_edit_export.rst
diff --git a/docs/tutorials/Basics.7_create_new.rst → docs/examples/Basics.7_create_new.rst b/docs/tutorials/Basics.7_create_new.rst → docs/examples/Basics.7_create_new.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -71,5 +71,6 @@ Table of Contents
    Introduction <self>
    Architecture <architecture>
    Tutorials <tutorials>
-   api
+   Examples <examples>
+   API <api>
    license
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -3,150 +3,14 @@ Tutorials
 ********************************************************************************
 
 .. rst-class:: lead
-This is a hello-world tutorial for the COMPAS IFC package. It shows how to load an IFC file and and inspect its contents.
-
-Installation
-================================
-
-
-A minimal version of COMPAS IFC can be installed directly with pip.
-
-.. code-block:: bash
-
-    pip install compas_ifc
-
-If you want to visualize the IFC model, install COMPAS Viewer as well.
-
-.. code-block:: bash
-
-    pip install compas_viewer
-
-If you need to interact with IFC geometry using OCC Brep or CGAL for boolean operations, install COMPAS OCC and COMPAS CGAL througn conda-forge.
-
-.. code-block:: bash
-
-    conda install compas_occ compas_occ -c conda-forge
-
-
-Load IFC model
-================================
-
-::
-
-    >>> from compas_ifc.model import Model
-    >>> model = Model("data/wall-with-opening-and-window.ifc")
-    Opened file: d:\Github\compas_ifc\scripts\..\data\wall-with-opening-and-window.ifc
-    >>> print(model.schema)
-    <schema IFC4>
-
-Query entities
-================================
-
-With ``model.get_all_entities()`` function, you can get a list of all entities in the model.
-
-::
-
-    >>> all_entities = model.get_all_entities()
-    >>> print("Total number of entities: ", len(all_entities))
-    Total number of entities:  133
-    >>> for entity in all_entities[:5]:
-    >>>     print(entity)
-    <Entity:IfcAxis2Placement3D>
-    <Entity:IfcCartesianPoint>
-    <Entity:IfcCartesianPoint>
-    <Entity:IfcCartesianPoint>
-    <Entity:IfcCartesianPoint>
-
-Use ``model.get_entities_by_type()`` function to get a list of entities of a specific type (including their inherent ones).
-
-::
-
-    >>> building_elements = model.get_entities_by_type("IfcBuildingElement")
-    >>> print("Total number of building elements: ", len(building_elements))
-    Total number of building elements:  2
-    >>> for entity in building_elements:
-    >>>     print(entity)
-    <Window:IfcWindow Name: Window for Test Example, GlobalId: 0tA4DSHd50le6Ov9Yu0I9X>
-    <Wall:IfcWallStandardCase Name: Wall for Test Example, GlobalId: 3ZYW59sxj8lei475l7EhLU>
-
-You can also use ``model.get_entities_by_name()`` function search elements with a specific name.
-
-::
-
-    >>> name = "Wall for Test Example"
-    >>> walls = model.get_entities_by_name(name)
-    >>> print("Found {} entities with the name: {}".format(len(walls), name))
-    Found 1 entities with the name: Wall for Test Example
-    >>> print(walls)
-    [<Wall:IfcWall Name: Wall for Test Example, GlobalId: 3ZYW59sxj8lei475l7EhLU>]
-
-Entity attributes
-================================
-
-You can access the attributes of an entity using the ``attributes`` property.
-
-::
-
-    >>> wall = walls[0]
-    >>> print(wall.attributes)
-    {'GlobalId': '3ZYW59sxj8lei475l7EhLU', 'OwnerHistory': <Entity:IfcOwnerHistory>, 'Name': 'Wall for Test Example', 'Description': 'Description of Wall', 'ObjectType': None, 'ObjectPlacement': <Entity:IfcLocalPlacement>, 'Representation': <Entity:IfcProductDefinitionShape>, 'Tag': None, 'PredefinedType': None}
-
-You can also inspect the spatial hierarchy of the model. For example, you can get the parent of an entity using the ``parent`` property, or get the children of an entity using the ``children`` property.
-
-::
-    
-    >>> print("parent:", wall.parent)
-    parent: <BuildingStorey:IfcBuildingStorey Name: Default Building Storey, GlobalId: 2GNgSHJ5j9BRUjqT$7tE8w>
-    >>> print("children", wall.children)
-    children: []
-
-For geomtric information, you can use the ``geometry`` property of an entity, if you have ``compas_occ`` installed, the geometry will be in form of ``Brep``.
-
-::
-    
-    >>> geometry = wall.geometry
-    >>> print(geometry)
-    <compas_occ.brep.brep.BRep object at 0x000001F7480C97F0>
-    >>> print(geometry.is_solid)
-    True
-    >>> print(geometry.volume)
-    1.8
-
-
-
-
-Visualisation
-================================
-
-If you have ``compas_viewer`` installed, you can visualize the model using the ``model.show()`` function.
-
-::
-
-    >>> model.show()
-
-.. image:: _images/visualisation.jpg
-    :width: 100%
-
-
-More Examples
-=============
-
-Below are more examples of how to use the COMPAS IFC package.
-(Please note these are still under construction)
+In this section you will find tutorials on how to use the COMPAS IFC package.
 
 
 .. toctree::
    :maxdepth: 1
    :titlesonly:
    :glob:
 
-   tutorials/Basics.1_overview.rst
-   tutorials/Basics.2_query_entities.rst
-   tutorials/Basics.3_spatial_hierarchy.rst
-   tutorials/Basics.4_element_info.rst
-   tutorials/Basics.5_visualization.rst
-   tutorials/Basics.6_edit_export.rst
-   tutorials/Basics.7_create_new.rst
-   tutorials/Advanced.1_units.rst
-   tutorials/Advanced.2_sessions.rst
-   tutorials/Advanced.3_custom_extensions.rst
+   tutorials/basics.hello_world
+   tutorials/intermediate.multi_story_building
+   tutorials/advanced.custom_extensions
diff --git a/docs/tutorials/advanced.custom_extensions.rst b/docs/tutorials/advanced.custom_extensions.rst
@@ -0,0 +1,8 @@
+********************************************************************************
+Advanced - Custom extensions
+********************************************************************************
+
+.. rst-class:: lead
+
+This tutorial is for advanced users whom are familiar with IFC classes and attributes.
+It shows how to create an custom extension to an existing IFC class which is also inherited by its subclasses.