Merge pull request #4938 from Vanuan/documentation_geometry

[docs] Geometry related documentation

src/blenderbim/docs/users/modeling/advanced_modeling/index.rst

@@ -48,3 +48,4 @@ Complex Structures
       :maxdepth: 2
 
       material_assignment
+      parametric_geometry

src/blenderbim/docs/users/modeling/advanced_modeling/parametric_geometry.rst

@@ -0,0 +1,37 @@
+Parametric Geometry
+===================
+
+The BlenderBIM Add-on provides tools for creating and editing parametric geometry for IFC elements.
+Parametric geometry allows you to define building elements using parameters that can be easily adjusted, rather than modeling fixed geometry.
+
+Key features of the parametric geometry system include:
+
+- Predefined parametric types for common building elements like walls, windows, doors, slabs, etc.
+- Custom parametric types that can be created and saved
+- Parameters for dimensions, materials, profiles, and other properties
+- Automatic updating of geometry when parameters are changed
+- IFC-compliant parametric definitions that can be exchanged with other applications
+
+To work with parametric geometry:
+
+1. Select an IFC element in the 3D viewport
+2. Open the Geometric Relationships panel in the Scene Properties
+3. Expand the Parametric Geometry section
+4. Choose a parametric type from the dropdown or create a custom type
+5. Adjust the available parameters to define the element's geometry
+
+Parameters may include options like:
+
+- Overall dimensions (width, height, length)
+- Material layers and thicknesses  
+- Profiles for extrusions
+- Opening sizes and positions
+- Component offsets and angles
+
+The geometry will update in real-time as parameters are adjusted.
+The parametric definition is stored in the IFC data and can be exchanged with other applications that support parametric IFC.
+
+Some elements like windows and doors have additional specialized parametric options in their respective tools.
+
+Parametric geometry allows for efficient modeling and updating of BIM elements while maintaining IFC compatibility.
+Experiment with the available options to find parametric workflows that suit your modeling needs.

src/blenderbim/docs/users/modeling/ifc_concepts/geometry_and_representations.rst

@@ -28,8 +28,8 @@ IFC uses the concept of "Types" and "Occurrences":
 If a type has geometry associated with it, all its occurrences must have the same geometry (similar to instancing or cloning in other applications).
 However, if a type has no material or geometry, it doesn't impact the geometry of its occurrences.
 
-Geometry and Representations
+Representations
-----------------------------
+---------------
 
 In IFC, unlike traditional 3D modeling:
 

src/blenderbim/docs/users/modeling/ifc_concepts/working_with_representations.rst

@@ -0,0 +1,108 @@
+Working with Representations
+----------------------------
+
+BlenderBIM provides tools to view, edit, and manage representations of IFC elements directly within Blender's interface.
+This section covers how to work with these representations effectively.
+
+Viewing Representations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To view the representations of an IFC element:
+
+1. Select the element in the 3D viewport.
+2. Navigate to Scene > Geometry and Materials > Representations in the Properties panel.
+3. You'll see a list of all representations associated with the element, including their context and type.
+
+Editing Representations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To edit an existing representation:
+
+1. In the Representations panel, click on the representation you want to edit to make it active.
+2. Switch to Edit Mode in the 3D viewport.
+3. Make your desired changes to the geometry.
+4. Once finished, click "Manually Save Representation" in the Representation Utilities section.
+
+.. note::
+   Not all representation types can be directly edited. For example, SweptSolid representations cannot be modified in this way.
+
+Adding Representations
+^^^^^^^^^^^^^^^^^^^^^^
+
+To add a new representation to an element:
+
+1. Select the element in the 3D viewport.
+2. In the Representations panel, use the dropdown menu at the top to select the desired context (e.g., Model, Plan).
+3. Click the "+" button next to the dropdown.
+4. In the dialog that appears, choose the method for creating the representation (e.g., Trace Outline, Bounding Box).
+5. Follow any additional prompts to complete the creation of the new representation.
+
+Common Representation Types in BlenderBIM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BlenderBIM supports several representation types, each suitable for different purposes:
+
+1. SweptSolid
+   - RepresentationIdentifier: 'Body'
+   - RepresentationType: 'SweptSolid'
+   - Description: Used for 3D shapes created by extruded area solids or revolved area solids.
+   - Typical use: Walls, columns, beams with simple profiles.
+
+2. Tessellation
+   - RepresentationIdentifier: 'Body'
+   - RepresentationType: 'Tessellation'
+   - Description: Represents 3D shapes using tessellated surface models.
+   - Typical use: Complex geometries, imported meshes.
+
+3. Clipping
+   - RepresentationIdentifier: 'Body'
+   - RepresentationType: 'Clipping'
+   - Description: 3D shapes created using Boolean operations with half-spaces.
+   - Typical use: Complex shapes with cutouts or intersections.
+
+4. Curve2D
+   - RepresentationIdentifier: 'Axis'
+   - RepresentationType: 'Curve2D'
+   - Description: 2D curves, often used for wall axes or material layer alignments.
+   - Typical use: Defining the centerline of walls.
+
+5. Curve3D
+   - RepresentationIdentifier: 'Axis'
+   - RepresentationType: 'Curve3D'
+   - Description: 3D curves, used for axes of longitudinal elements.
+   - Typical use: Defining the profile of walls, openings.
+
+
+Converting Representations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BlenderBIM offers tools to convert between different representation types:
+
+1. Select the representation you want to convert.
+2. In the Representation Utilities section, you'll find options like:
+   - Convert To Tessellation
+   - Convert To Rectangle Extrusion
+   - Convert To Circle Extrusion
+   - Convert To Arbitrary Extrusion
+
+.. warning::
+   Converting representations may result in loss of parametric information. Use these tools with caution.
+
+Best Practices
+^^^^^^^^^^^^^^
+
+- Always use the appropriate representation type for the element you're modeling.
+- Be cautious when editing representations directly, as this may affect the element's relationship with its type or other elements.
+- When possible, use parametric definitions (like Material Layers for walls) instead of direct mesh editing.
+- Regularly check the IFC validity of your model after making significant changes to representations.
+
+Future Developments
+^^^^^^^^^^^^^^^^^^^
+
+The BlenderBIM team is continually working on improving the representation editing experience. Future updates may include:
+
+- More intuitive interfaces for non-mesh modeling.
+- Enhanced tools for working with parametric representations.
+- Improved validation and error checking when editing representations.
+
+For the latest updates and feature requests, refer to the BlenderBIM Add-on GitHub repository.

src/blenderbim/docs/users/modeling/understanding_ifc.rst

@@ -62,6 +62,11 @@ This section provides an overview of key IFC concepts and how they're implemente
          :doc:`ifc_concepts/geometry_and_representations`
             Understanding IFC geometry, representations, and parametric materials.
 
+      .. container:: card
+
+         :doc:`ifc_concepts/working_with_representations`
+            Representations in BlenderBIM.
+
 .. container:: global-index-toc
 
    .. toctree::
@@ -72,3 +77,4 @@ This section provides an overview of key IFC concepts and how they're implemente
       ifc_concepts/spatial_objects
       ifc_concepts/classification_and_types
       ifc_concepts/geometry_and_representations
+      ifc_concepts/working_with_representations

src/blenderbim/docs/users/user_interface/property_editor/scene_editor/geometry_and_materials/index.rst

@@ -6,23 +6,245 @@ Geometry and Materials
 
    Geometry and Materials sub-tab.
 
+The Geometry and Materials sub-tab in the Property Editor provides access to various aspects of an IFC element's
+geometric representation and material properties.
+
+
+This section is crucial for viewing and editing the physical and visual characteristics of IFC elements.
+
 Placement
-   tbd
+---------
+
+.. figure:: images/placement.png
+   :alt: Placement panel in the Geometry and Materials sub-tab
+
+   Placement panel in the Geometry and Materials sub-tab
+
+The Placement panel allows you to view and edit the spatial position and orientation of the IFC element within the project.
+
+Location
+^^^^^^^^
+The Location fields display and allow editing of the element's position in 3D space:
+
+- X: The position along the X-axis (left/right)
+- Y: The position along the Y-axis (front/back)
+- Z: The position along the Z-axis (up/down)
+
+These values are typically measured in the project's chosen unit of measurement.
+
+Rotation
+^^^^^^^^
+The Rotation fields show and allow modification of the element's orientation:
+
+- X: Rotation around the X-axis (pitch)
+- Y: Rotation around the Y-axis (roll)
+- Z: Rotation around the Z-axis (yaw)
+
+Rotation values are measured in degrees.
+
+Derived Coordinates
+^^^^^^^^^^^^^^^^^^^
+This section provides additional information about the element's placement:
+
+**Edit Object Placement**
+   A button that allows you to manually edit the object's placement.
+
+**XYZ Dimensions**
+   Displays the absolute bounding box dimensions of the object.
+
+**Min Global Z and Max Global Z**
+   Shows the lowest and highest points of the object in the global Z coordinate system.
+
+**Min Decomposed Z and Max Decomposed Z**
+   Indicates the lowest and highest points of the object when considering its decomposed parts or components.
+
+Note: The specific units used may depend on your project settings. Always ensure you're working in the correct units when adjusting placement values.
+
+For more detailed information about Object Placements in IFC,
+including how they are represented mathematically and how to create them programmatically,
+please refer to the `IfcOpenShell documentation on Object Placements <https://docs.ifcopenshell.org/ifcopenshell-python/geometry_creation.html#object-placements>`_.
+
 
 Representations
-   tbd
+---------------
+
+.. figure:: images/representations.png
+   :alt: Representations panel in the Geometry and Materials sub-tab
+
+   Representations panel in the Geometry and Materials sub-tab
+
+The Representations panel allows you to view and manage the geometric representations of an IFC element.
+In IFC, an element can have multiple representations for different purposes or contexts.
+
+Adding Representations
+^^^^^^^^^^^^^^^^^^^^^^
+At the top of the panel, you can add new representations to the element:
+
+1. Select the desired representation context from the dropdown menu (e.g., Model, Plan).
+2. Click the "+" button next to the dropdown.
+3. A dialog box will appear, allowing you to choose the type of representation to add (e.g., Trace Outline, Bounding Box).
+4. Depending on the chosen type, you may be prompted to select an object as the basis for the new representation.
+
+This feature allows you to create multiple representations for different purposes, such as simplified views, detailed 3D models, or 2D symbols.
+
+.. figure:: images/add-representation-dialog.png
+   :alt: Add Representation dialog
+
+   Add Representation dialog
+
+Representation List
+^^^^^^^^^^^^^^^^^^^
+Below the add representation controls, you can see a list of representations.
+Each row shows the context (e.g., Model, Plan) and type (e.g., Axis, Body) of a representation.
+
+Two buttons are available for each representation in the list:
+
+1. View/Edit button: This button allows you to switch to the selected representation and view or edit it in the 3D view.
+   It's useful for inspecting or modifying specific representations of the element.
+
+   - When a representation is not active, this button appears as a standard "switch/geometry" icon.
+   - When a representation is active (i.e., currently being viewed/edited), the button changes to a "reload" icon.
+     This visual cue helps you identify which representation is currently active in the 3D view.
+
+2. Delete button: This button allows you to remove the selected representation from the element.
+   Use this with caution, as deleting a representation can affect how the element is displayed or used in different contexts.
+
+The ability to switch between representations and visually identify the active one allows for efficient management of multiple geometric
+representations for a single IFC element.
+
+Representation Items
+^^^^^^^^^^^^^^^^^^^^
+This section lists the items that make up the current representation. In the example, there is one item of type "IfcExtrudedAreaSolid".
+
+- You can select items to view or edit their properties.
+- The "x" button allows you to remove items from the representation.
+
+Surface Style
+~~~~~~~~~~~~~
+
+Indicates whether a surface style is applied to the representation. You can assign a style using the pencil icon.
+
+Presentation Layer
+~~~~~~~~~~~~~~~~~~
+
+Shows if the representation is assigned to a presentation layer. This can be useful for organizing and displaying elements in CAD or BIM software.
+
+Shape Aspect
+~~~~~~~~~~~~
+
+Displays any shape aspects associated with the representation. Shape aspects can define specific parts or features of the geometry.
+
+Representation Utilities
+^^^^^^^^^^^^^^^^^^^^^^^^
+This section provides advanced tools for manipulating representations:
+
+- Manually Save Representation: Allows direct saving of representation data.
+- Copy Mesh From Active To Selected: Copies mesh data between representations.
+- Convert To Tessellation: Transforms the representation into a tessellated form.
+- Convert To Rectangle Extrusion: Changes the representation to a simple rectangular extrusion.
+- Convert To Circle Extrusion: Changes the representation to a circular extrusion.
+- Convert To Arbitrary Extrusion: Allows for custom extrusion shapes.
+- Convert To Arbitrary Extrusion With Voids: Similar to above, but includes the ability to add voids.
+- Get Representation IFC Parameters: Retrieves the IFC-specific parameters of the representation.
+
+Note: These utilities are marked as "Advanced Users Only" and should be used with caution,
+as they can significantly alter the element's geometry and IFC data.
+
+For more detailed information about IFC Representations and how they are handled in IfcOpenShell,
+refer to the `IfcOpenShell documentation on Representations <https://docs.ifcopenshell.org/ifcopenshell-python/geometry_creation.html#representations>`_.
+
 
 Geometric Relationships
-   tbd
+-----------------------
+
+.. figure:: images/geometric_relationships.png
+   :alt: Geometric Relationships panel in the Geometry and Materials sub-tab
+
+   Geometric Relationships panel in the Geometry and Materials sub-tab
+
+The Geometric Relationships panel provides tools and information about how the current IFC element relates geometrically to other elements in the model.
+
+Vendor Workarounds
+^^^^^^^^^^^^^^^^^^
+This section contains options to force certain geometric behaviors:
+
+- Force Faceted Breps: Converts curved surfaces to faceted representations.
+- Force Triangulation: Ensures all polygonal faces are triangulated.
+- Force Presentation Style Assignment: Applies presentation styles to all geometric items.
+
+These options can be useful when working with software that has specific geometric requirements or limitations.
+
+Presentation Layers
+^^^^^^^^^^^^^^^^^^^
+Displays and manages the presentation layers associated with the element. The pencil icon allows you to add or manage presentation layers.
+
+Note: There are known bugs an limitations with using presentation layers.
+
+.. tip::
+   While layers are supported for compatibility with CAD environments,
+   consider using IFC properties, groups, or model views for more advanced data organization in BIM workflows.
+
+Voids
+^^^^^
+Lists the voids (openings) associated with the element. Each void has an associated element.
+
+The "x" button allows you to remove a void from the element.
+
+Booleans
+^^^^^^^^
+Shows boolean operations applied to the element's geometry. The panel displays the number of booleans found and how many are manual (user-defined) versus automatic.
+
+- The "+" button allows you to add a new boolean operation.
+- The dropdown menu lets you choose the type of boolean operation.
+- The "x" button removes the selected boolean operation.
+
+Connections
+^^^^^^^^^^^
+Lists other elements that are geometrically connected to the current element. In this example, "Wall.006" is connected "AT_START" to the current element.
+
+- The connection type (e.g., AT_START) indicates how the elements are related.
+- The arrow button likely allows you to navigate to the connected element.
+
+This panel is crucial for understanding and managing the geometric relationships between different elements in your IFC model,
+including openings, boolean operations, and connections to other building components.
 
 Parametric Geometry
-   tbd
+-------------------
+
+.. figure:: images/geometric_relationships.png
+   :alt: Parametric Geometry panel in the Geometry and Materials sub-tab
+
+   Parametric Geometry panel in the Geometry and Materials sub-tab
+
+For elements with parametric definitions,
+this panel allows you to view and edit the parameters that control the element's geometry.
+This is particularly useful for elements like doors, windows, stairs, etc.
+
+Parametric geometry allows for efficient modeling and updating of BIM elements while maintaining IFC compatibility.
+Experiment with the available options to find parametric workflows that suit your modeling needs.
 
-Profiles
-   tbd
 
 Materials
-   tbd
+---------
+
+.. figure:: images/materials.png
+  :alt: Materials panel in the Geometry and Materials sub-tab
+
+  Materials panel in the Geometry and Materials sub-tab
+
+
+The Materials panel allows you to manage material assignments for IFC elements.
+You can assign materials to elements, create and edit material definitions, and manage material layers for layered elements (e.g., walls).
 
 Styles
-   tbd
+------
+
+The Styles panel is used to manage presentation styles for elements, including surface styles (color, texture, etc.),
+curve styles (line color, thickness, etc.), and fill area styles. These styles control how elements are visually represented in various contexts,
+such as in 2D drawings or 3D views.
+
+Profiles
+--------
+
+The Profiles panel is used to manage cross-sectional profiles for elements such as beams, columns, or railings.
+You can create new profiles, edit existing ones, or assign profiles to elements.