Work in progress starting to restructure docs in preparation for next release

src/bonsai/docs/guides/authoring/classification_and_types.rst

@@ -0,0 +1,4 @@
+Classification and Types
+========================
+
+IFC classification hierarchy and the concept of types and occurrences.

src/bonsai/docs/guides/authoring/creating_walls.rst

@@ -0,0 +1,79 @@
+Creating Walls
+--------------
+
+Walls are fundamental elements in any building design. Bonsai provides powerful tools for creating and manipulating wall elements.
+This section will guide you through the process of creating standalone walls, multiple connected walls, and joining walls using various techniques.
+
+By following these steps and utilizing the various tools provided by Bonsai,
+you can efficiently create, modify, and join walls to form complex building layouts.
+Remember to use snapping and alignment tools to ensure precision in your model.
+
+Creating a Standalone Wall
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Open an empty model (without predefined types).
+2. Click on the wall icon in the toolbar. The top bar will display "[No IfcWallType Found] | Name [TYPEX] | + Add IfcWallType".
+3. Edit [TYPEX] to use a wall type name of your choice (e.g., WALL100).
+4. Click "+ Add IfcWallType". The top bar will change, providing you with additional options.
+5. Click "Add" (or press SHIFT+A) to create a wall with its own type.
+6. You can adjust the wall's length and height using the parameters in the top bar.
+
+Creating Multiple Connected Walls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Activate the wall tool from the toolbar or use the shortcut (SHIFT + SPACEBAR, 6).
+2. Select the wall type from the dropdown menu, or create a new wall type if needed.
+3. Set the 3D cursor to the desired starting location for the wall by holding SHIFT and left-clicking in the 3D viewport.
+4. Add the first wall segment by pressing SHIFT + A.
+5. Adjust the length of the wall segment by dragging the "Length" parameter or entering a numeric value.
+6. Set the 3D cursor to the location for the next wall segment. Enable snapping to ensure precise connections between segments.
+7. Add the next wall segment by pressing SHIFT + A again.
+8. If needed, rotate the new wall segment by pressing SHIFT + R and adjusting the angle.
+9. Adjust the length of the new segment as required.
+10. Repeat steps 6-9 to create additional wall segments, setting the 3D cursor to the desired locations, until you've completed the wall layout.
+
+Modifying and Joining Walls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Bonsai offers various tools for modifying and joining wall segments:
+
+- **Extend (SHIFT + E)**: Extend an existing wall to intersect with another face.
+- **Butt (SHIFT + T)**: Join wall segments end-to-end.
+- **Mitre (SHIFT + Y)**: Create a mitre joint between two wall segments.
+- **Merge (SHIFT + M)**: Combine two wall segments into a single wall.
+- **Flip (SHIFT + F)**: Reverse the direction of a wall segment.
+- **Split (SHIFT + K)**: Divide a wall segment into two parts.
+- **Rotate 90° (SHIFT + R)**: Rotate the wall by 90 degrees.
+
+To use these tools:
+
+1. Select the wall segment(s) you want to modify.
+2. Use the appropriate shortcut or select the tool from the top bar.
+3. Follow the on-screen prompts or adjust parameters as needed.
+
+Aligning Walls
+^^^^^^^^^^^^^^
+
+You can align walls using the following options:
+
+- **Align Exterior (SHIFT + X)**: Align the wall to its exterior face.
+- **Align Centerline (SHIFT + C)**: Align the wall to its centerline.
+- **Align Interior (SHIFT + V)**: Align the wall to its interior face.
+
+Adding Openings
+^^^^^^^^^^^^^^^
+
+To add openings (e.g., for doors or windows) to your walls:
+
+1. Select the wall where you want to add an opening.
+2. Click "Add Void" in the top bar or press SHIFT + O.
+3. Adjust the opening's size and position as needed.
+
+Calculating Quantities
+^^^^^^^^^^^^^^^^^^^^^^
+
+After creating your walls, you can calculate quantities to ensure accurate measurements:
+
+1. Select the wall(s) you want to measure.
+2. Press Q or click "Calculate All Quantities" in the top bar.
+

src/bonsai/docs/guides/authoring/defining_rooms_spaces.rst

@@ -0,0 +1,7 @@
+Defining Rooms and Spaces
+=========================
+
+.. note::
+   This page is a stub. More detailed content will be added in future updates.
+
+[Content about defining rooms and spaces]

src/bonsai/docs/guides/authoring/door.rst

@@ -0,0 +1,154 @@
+Door
+====
+
+A door is a wall opening that allows passage between spaces, controlled access for people and goods.
+
+In IFC, it's represented by the IfcDoor entity, which is a subtype of IfcBuildingElement.
+Doors play a crucial role in building design, affecting circulation, accessibility, and space functionality.
+
+This section covers how to add and customize doors in your BIM model using Bonsai.
+
+Adding a Door
+-------------
+
+1. Select the wall where you want to place the door.
+2. Set the 3D cursor on the wall at the desired door location.
+3. Click on the "Create Door" tool in the Bonsai toolbar.
+4. In the top bar, you'll see "[No IfcDoorType Found] | Name [TYPEX] | + Add IfcDoorType".
+5. Edit [TYPEX] to use a door type name of your choice (e.g., DOOR001).
+6. Click "+ Add IfcDoorType". The top bar will update with additional options.
+7. Click "Add" (or press SHIFT+A) to create a door with its own type.
+8. Adjust the door's width and height using the parameters in the top bar.
+
+Placing a Door and Changing its Swing Direction
+-----------------------------------------------
+
+1. Select the wall:
+   - (Optional) Use the "Create Wall" tool to add a wall in your scene.
+   - Select the wall where you want to place the door.
+
+   Selecting the wall is crucial as it ensures that the void relation between the door and the wall is automatically created.
+
+2. Add a Door:
+   - Use the "Create Door" tool from the toolbar.
+   - Press SHIFT+A or click "Add" to place the door on the selected wall.
+
+**Applying Void**
+
+If you forgot to select the wall before placing the door, you'll need to manually create the void relation:
+
+   - Select both the wall and the door.
+   - Click "Apply Void" (Shift+O) button.
+
+.. important::
+   If you need to use "Apply Void", do this before making any modifications to the door,
+   as there are limitations with this function that may affect door orientation.
+
+   Usually, the Regen function will recalculate all the openings with existing void relationships.
+
+3. Adjust Door Position (if needed):
+   - With the door selected, use Blender's move tools to adjust its position along the wall.
+
+4. Regenerate the Wall Geometry:
+   - Select the wall.
+   - Press Shift+G to regenerate the wall geometry, incorporating the door opening.
+
+   .. note::
+      This step ensures the wall geometry is updated to include the door opening.
+
+      Moving the Door using Blender tools doesn't actually change the IFC model.
+      Future versions need to improve UX in that regard.
+      Synchronisation between the Blender scene and IFC model is an issue that has the highest priority.
+
+5. Change Door Swing Direction:
+   - Select only the door.
+   - Press Shift+F to flip the door. It rotates the door by 180 degrees and moves the pivot point.
+   - Locate the "Parametric Geometry" panel in the `Scene Properties > Geometry and Materials` subtab.
+   - Find the "Door" section within this panel.
+   - Change the "Operation Type" to "SINGLE_SWING_RIGHT".
+
+   .. note::
+      The Shift+F shortcut is currently a hidden feature and not available as a button in the Door tool interface.
+
+      You may need to experiment with the combination of changing the Operation Type and using Shift+F to achieve the desired orientation.
+
+6. Final Wall Geometry Regeneration:
+   - Select the wall again.
+   - Press Shift+G one more time to ensure all changes are properly applied.
+
+Additional Notes
+----------------
+
+- The Shift+F shortcut for flipping the door is not visible in the Door tool interface.
+  This functionality may be added as a visible button in future updates.
+- Always use Shift+G (Regenerate) after making changes
+  to ensure the wall and door geometries are correctly updated.
+- Avoid using Shift+O (Apply Void) as it may cause issues
+  with the door's orientation.
+
+
+Modifying Doors
+---------------
+
+.. note::
+   Some functionality is not implemented.
+
+You can modify doors using various tools:
+
+- Resize: Adjust the width and height parameters in the top bar.
+- Move: Use Blender's standard move tools to reposition the door.
+- Flip: Change the opening direction using the flip tool (Shift+F).
+
+.. note::
+   After moving a door, you need to recalculate the void in the wall. To do this:
+
+- Select the wall containing the moved door.
+- Click on the "Regen" (:kbd:`Shift` + :kbd:`G`) button in the top bar or use the appropriate shortcut.
+- This ensures that the opening in the wall is correctly positioned after moving the door.
+
+If Regen operation doesn't achive the required result, use Apply Void function:
+
+- Click on the "Apply Void" (:kbd:`Shift` + :kbd:`O`) button in the top bar or use the appropriate shortcut.
+- This ensures that the opening is linked to the wall.
+
+
+Door Properties
+^^^^^^^^^^^^^^^
+
+.. note::
+   This functionality is not implemented.
+
+After adding a door, you can customize its properties:
+
+1. Select the door in the 3D viewport.
+2. Go to the ... panel.
+3. Find the ... section.
+4. Here you can set various properties such as fire rating, u-value, or any custom properties required for your project.
+
+.. note::
+   This functionality is not implemented.
+
+You can customize various properties of the door:
+
+- Dimensions (width, height, thickness)
+- Opening direction 
+- Door type (e.g. single swing, double swing, sliding)
+- Material
+
+
+Creating Multiple Doors
+-----------------------
+
+To create multiple doors of the same type:
+
+1. Select the desired door type from the dropdown menu in the top bar.
+2. Set the 3D cursor on a wall where you want to place a new door.
+3. Select the wall
+4. Click "Add" (or press SHIFT+A) for each new door you want to create.
+5. Adjust the 3D cursor, position and parameters for each new door as needed.
+
+See Also
+--------
+
+- :doc:`../creating_walls`
+- :doc:`../../advanced_modeling/material_assignment`

src/bonsai/docs/guides/authoring/geometry_and_representations.rst

@@ -0,0 +1,81 @@
+Geometry and Representations
+============================
+
+Understanding IFC Elements and Geometry
+---------------------------------------
+
+In Bonsai, it's crucial to understand the relationship between IFC elements, their classification, types, and geometry.
+These concepts work together but serve different purposes.
+
+IFC Classification
+^^^^^^^^^^^^^^^^^^
+
+Every IFC element has a two-level classification:
+
+1. IFC Class: The top level (e.g., IfcWall)
+2. Predefined Type: The second level (e.g., PARTITIONING)
+
+This classification is purely for categorization and filtering. It doesn't determine the element's geometry or appearance.
+
+Types and Occurrences
+^^^^^^^^^^^^^^^^^^^^^
+
+IFC uses the concept of "Types" and "Occurrences":
+
+- Types: Define common properties or materials shared by multiple elements.
+- Occurrences: Individual instances of a type.
+
+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.
+
+Representations
+---------------
+
+In IFC, unlike traditional 3D modeling:
+
+- An object may have no geometry, one geometry, or multiple geometries.
+- Each geometry is called a "Representation".
+- Representations are differentiated by their "Context". A "Context" defines what the geometry is used for (e.g., 3D Body, 2D Plan, etc.).
+
+The most common context is the 3D Body context, which represents the physical shape of the object.
+
+Representation Types
+^^^^^^^^^^^^^^^^^^^^
+
+IFC supports various geometry types:
+
+- Mesh-like: Facetations, tessellations, triangulations, or planar breps.
+- Solid modeling: CSGs, swept solids, extrusions, lofts, etc.
+
+In Bonsai, you can create simple mesh geometries (like a cube) and assign them to IFC elements.
+However, for more complex elements like walls, slabs, or columns, other representation types are more appropriate.
+
+Parametric Materials
+^^^^^^^^^^^^^^^^^^^^
+
+IFC standardizes certain parametric modeling techniques:
+
+1. Material Layers: Uses an axis line and material layers to derive the body of an object by extruding layers of different thicknesses to a particular height.
+2. Material Profiles: Extrudes a profile (arbitrary or parametric) along a 3D axis.
+
+These are typically defined at the type level and inherited by occurrences.
+
+Working with Representations in Bonsai
+--------------------------------------
+
+- Creating swept solids: Currently, the best method is to use parametric material layers (e.g., for walls) or material profiles.
+- Mesh editing: For mesh-like representations, you can edit them directly in Blender's edit mode.
+- Non-mesh modeling: Bonsai currently has limited tools for direct modeling of non-mesh geometries.
+  Future updates will include more intuitive interfaces for this purpose.
+- Deleting representations: This should be avoided as it can create invalid IFC data.
+  If you delete a representation, the element should no longer be visible in the 3D view.
+
+.. note::
+  The current implementation allows low-level manipulation of IFC data, which requires a deep understanding of IFC rules.
+  Users should exercise caution when manually editing representations or other low-level IFC data.
+
+Future Developments
+-------------------
+
+The Bonsai team plans to develop more intuitive interfaces for non-mesh direct modeling tools in future versions.
+This will make it easier to create and manipulate complex geometric representations without needing to understand the intricacies of IFC data structures.

src/bonsai/docs/guides/authoring/georeferencing.rst

@@ -0,0 +1,255 @@
+Georeferencing
+==============
+
+There are two types of construction: vertical construction (such as buildings
+and sites) which deal with small distances typically under 1km, and horizontal
+construction (such as transport, transmission, and subterranean networks) where
+distances frequently exceed 1km. Blender and Bonsai focuses on vertical
+construction, and will typically just work out of the box.
+
+Coordinate reference systems
+----------------------------
+
+The minimum requirement for a georeferenced model is to specify the coordinate
+reference system used. This is known as the **Projected CRS**, and is a feature
+available in IFC4 onwards.
+
+.. warning::
+
+    IFC2X3 models cannot be georeferenced. There is a proposed convention to
+    provide fallback support but this is not supported yet in any known vendor.
+    Please consider upgrading to IFC4.
+
+Most architects and engineers will know the name of the **Projected CRS**
+typically chosen by the surveyor. For example in Sydney, Australia, you might
+use GDA2020 / MGA Zone 56. In IFC a standardised code from the EPSG public
+registry is used to refer to the **Projected CRS**. For example, GDA 2020 / MGA
+Zone 56 will be named EPSG:7856.
+
+You can check whether or not your model is georeferenced in the **IFC
+Georeferencing** panel in the **Scene Properties** tab. You should see a section
+for the **Projected CRS** with an EPSG code.
+
+.. image:: images/projectedcrs.png
+
+If you do not see this, your project is not georeferenced.
+
+.. Note::
+
+    Even if a model has large "real world coordinates", this does not mean the
+    project is georeferenced. Without a **Projected CRS**, these coordinates are
+    meaningless.
+
+Map conversions
+---------------
+
+The coordinates for the nominated **Projected CRS** are known as **Map
+Coordinates**. These **Map Coordinates** are typically large numbers and read as
+Eastings and Northings.
+
+In vertical construction, some disciplines (such as a civil engineer or
+surveyor) will directly use **Map Coordinates** in their designs. Most others,
+such as the architect, structural, and service engineers will instead use
+**Local engineering coordinates**. A **Map Conversion** stores the parameters
+for transforming **Local engineering coordinates** to **Map Coordinates**.
+
+For example, a civil engineer will work directly in **Map Coordinates**. This
+means that the model's coordinates correlate directly to Eastings and
+Northings.  Similarly, the model's +Y axis will point to **Grid North**.  As
+there is no **Map Conversion** involved, you will see a 0 in the Eastings,
+Northings, and Orthogonal Height in the **IFC Georeferencing** panel.
+
+.. image:: images/mapcoordinates.png
+
+When **Local engineering coordinates** are used, typically the architect will
+nominate a local origin and model geometry will be drawn orthogonally (i.e.
+along the X and Y axis). This local origin often correlates with a site boundary,
+surveyed point, or grid intersection. This means that the model's coordinates
+are typically smaller numbers and correlate to surface distance measurements,
+not Eastings and Northings, and the model's +Y axis will point to **Project
+North**. The surveyor will then provide the necessary **Map Conversion**
+parameters to convert from **Local engineering coordinates** to Eastings,
+Northings, Orthogonal Height, and **Grid North**.
+
+.. image:: images/mapconversion.png
+
+.. warning::
+
+    Coordinate systems are a technical topic. A common error is that disciplines
+    may choose to use **Map Coordinates** without realising that map distances
+    do not correlate with surface distances measured on the ground.  Unless you
+    are trained to work in **Map Coordinates**, it is safer to work with local
+    engineering coordinates and consult your surveyor for professional guidance.
+
+**Map Conversions** contain six parameters.
+
+**Eastings**, **Northings** and **Orthogonal Height** parameters define the
+translation from the model's XYZ coordinates to map **Eastings**, **Northings**,
+and **Heights**.  Your model's local engineering origin at 0, 0, 0, will always
+convert exactly to the **Easting**, **Northing**, and **Orthogonal Height**
+displayed in this panel.
+
+The **X Axis Abcissa** and **X Axis Ordinate** define the rotation vector from
+**Project North** to **Grid North**. These two numbers combine into a coordinate
+vector pointing along the X axis (i.e. **Project East**). The default is an
+abscissa of 1 and ordinate of 0. This default (1, 0) vector implies **Project
+East** and **Grid East** coalign, which means there is no rotation between
+**Project North** and **Grid North**.
+
+.. image:: images/xaxisabscissaordinate.png
+
+.. tip::
+    
+   To save you the mental struggle of converting to degrees, a calculated
+   rotation is always just below these values. Phew!
+
+The distance measured on site, or the "surface distance" is actually not the
+same as the distance measured between Eastings and Northings. This difference is
+provided by the **Scale** parameter. The **Scale** defines the average combined
+scale factor across the small 1km site that converts from the model's surface
+distances to map grid distances. Note that the **Scale** is actually not a
+constant. However, for the small sites dealt with in vertical construction, it
+may be approximated to be a constant by your surveyor and will typically be a
+value close to, but not exactly 1.
+
+.. note::
+
+    Always check that the surveyor provides a scale factor such that surface
+    distance multiplied by **Scale** equals map grid distances (as opposed to
+    the other way around).
+
+Working with Map Coordinates
+----------------------------
+
+Bonsai is designed to work with small coordinates (under 1km), whereas map
+coordinates are typically large. When you load an IFC which uses map
+coordinates directly, or when you are working with IFC2X3 and you cannot use a
+map conversion, Bonsai will autodetect a point on your model to use as a false
+origin.
+
+The XYZ offset used for the false origin will be shown in the **IFC
+Georeferencing** panel under the **Blender Offset** header. It
+is very similar to a **Map Conversion**, but it will not have a scale and only
+temporarily affects your Blender session.
+
+.. image:: images/blenderoffset.png
+
+.. note::
+
+    A Blender offset is simply a shift in coordinates to reduce large model
+    coordinates to smaller coordinates. It should not be used as an indicator of
+    whether georeferencing is done correctly. Always check the **Projected
+    CRS**, **Map Conversion** and confirm the parameters with your surveyor.
+
+This distance limit of 1km and autodetected false origin may not be appropriate
+for your project. For example, your project may exceed the 1km limit, or you may
+want to federate multiple files together and manually specify a consistent and
+fixed false origin. You can customise these options by choosing
+:ref:`Enable Advanced Mode <Project Info Advanced Loading Mode>`  when loading a project.
+Then, set the **Distance Limit** (in meters) and the **False Origin** coordinate
+before pressing **Load Project Elements**.
+
+.. image:: images/manualorigin.png
+
+When a false origin is used, there are two possible methods to offset objects by
+the false origin.
+
+The first method is to offset the origin point of objects. We call this the
+**Object Placement** method.  The second method is to offset the local
+coordinates of geometry within the objects themselves. We call this the
+**Cartesian Point** method. Sometimes, BIM applications combine both of these
+methods in a single IFC project. To see which workaround was used on an object,
+check the "Blender Offset" property in the **Transform** panel in the **Object
+Properties**. This is an advanced property used by powerusers to debug
+coordinate issues and may be safely ignored by most users.
+
+.. image:: images/offsetmode.png
+
+Incorrect coordinate use
+------------------------
+
+Sometimes, a model may mix **Map Coordinates** and **Local engineering
+coordinates**. For example, a surveyed pipe may have its placement use **Map
+Coordinates** with large Eastings and Northings. However, the placement of the
+site object may be still set at 0, 0, 0. Since this range of coordinates exceed
+the default 1km distance limit, this creates a problem. Blender needs to choose
+between displaying the pipe accurately and sacrificing precision at the site
+placement, or vice versa, but it is impossible to satisfy both simultaneously in
+the same Blender session.
+
+.. warning::
+
+    Many IFC viewers only show geometry, and don't show object placements. This may
+    give users the false impression that their coordinates in their IFC project
+    do not have such a large range. However, as a native IFC authoring platform,
+    Bonsai will not accept this inconsistency.
+
+At this point, it is the users responsibility to reconcile this inconsistency in
+their coordinates. Either the user needs to fix their file to consistently
+offset all coordinates, or the user needs to manually tell Bonsai the
+coordinates of the desired false origin and accept the precision loss.
+
+Converting local and map coordinates
+------------------------------------
+
+You can convert **Local engineering coordinates** to **Map coordinates** and
+vice versa in the **Viewport** panel. First, enable ``View > Sidebar`` then type
+in your coordinate in the **Input** field. Press either the **Local to Global**
+or **Global to Local** button to convert the coordinate. You will see the result
+of the calculation in the **Output** field.
+
+.. image:: images/coordinateconversion.png
+
+True north
+----------
+
+When **Local engineering coordinates** are used, the model's +Y axis points to
+**Project North** for the convenience of drafting. When **Map Coordinates** are
+used, the model's +Y axis points to **Grid North** for the necessity of
+surveying.
+
+**Project North** and **Grid North** is different to **True North**. The angle
+to **True North** is not a fixed angle. It will actually vary depending on the
+Eastings and Northings you choose to calculate it from.
+
+However, this variable **True North** is a great source of confusion to
+architects, who typically just want to do a shadow study, solar study, or
+similar and go out for an early lunch. IFC can store a fixed **True North**
+value as a reference to be used for these types of usecases. If one is stored in
+your project, you may see it under the **True North** section of the **IFC
+Georeferencing** panel. Your surveyor will be able to provide the **True North**
+vector, but it should be only used as a reference, never used as a way to
+coordinate model rotations, and always with the understanding that it is not a
+fixed value.
+
+.. image:: images/truenorth.png
+
+.. warning::
+
+   Fun fact: **Magnetic North** is useless for the purposes of construction.
+
+Coordinate precision limits
+---------------------------
+
+Bonsai focuses on vertical construction. Vertical construction typically uses
+**Local engineering coordinates** on a small site. The buildingSMART
+georeferencing technical experts panel have determined that a small site under
+1km square can be assumed to have a constant **Map Conversion**.
+
+Therefore, if your model is less than 1km square, you are within the coordinate
+precision limits. This is where the 1km default distance limit is derived from.
+
+If you want to exceed the 1km square surveying limitation, you will need to be
+aware of software limitations that can result in precision loss when large
+coordinate ranges are used.
+
+Blender, and subsequently Bonsai, is not designed for **Map Coordinates**.
+Blender internally uses single precision floating point calculations. A full
+description of the precision implications are described in the `Blender working
+limits documentation
+<https://docs.blender.org/manual/en/latest/advanced/limits.html>`__.
+
+This means that lengths greater than 5,000 meters start to accumulate software
+precision errors that affect the nearest millimeter. Therefore, from a software
+perspective, it is unwise to embark on a project with coordinates ranging
+greater than +/- 5km.

src/bonsai/docs/guides/authoring/git_support.rst

@@ -0,0 +1,221 @@
+Tracking revisions with Git
+===========================
+
+Bonsai supports tracking the development of your IFC files with a Git
+repository.
+
+Bonsai is an IFC file editor, you can create or load an IFC project,
+change, add or remove BIM objects and save to disk. A Git repository is a
+special folder on your computer where text files, such as IFC files, can be
+efficiently stored and past versions recalled.
+
+Git is also a tool to share files with other people, transmitting only file
+changes, and allowing multiple people to keep local copies of the same
+repository up-to-date.
+
+.. Note::
+
+    If you don't already have Git installed on your system, you will need to
+    `Download from the Git website <https://git-scm.com/downloads>`__.
+    You may have to restart Blender after installation.
+
+Adding your IFC file to a repository
+------------------------------------
+
+First, save your file to disk. If the folder is already a repository you can
+*Add* the file in the *IFC Git panel* to tell Git you want to track it,
+otherwise Bonsai will offer to convert the folder into a repository.
+
+.. Warning::
+
+    You probably don't want to turn your entire HOME or User folder into a Git
+    repository. Create one folder per project, this folder can contain multiple
+    IFC files, optionally in subfolders, plus any resources needed to support
+    them.
+
+After adding an IFC file, this action will appear as the most recent item at
+the top of the revision list.
+
+'Committing' changes
+--------------------
+
+As you work on your IFC project, save the file regularly as usual. When you
+get to a point where it would be useful to later retrieve this state, you need
+to *commit* this to the Git repository. Bonsai gives you three options:
+
+- Showing uncommitted changes will temporarily highlight the differences
+  between the saved file and the last committed revision. Green objects are new
+  and blue objects exist in the previous revision but have since been modified.
+
+- Discarding uncommitted changes will throw away all your saved changes and
+  revert the model to the previous revision.
+
+- Committing changes will save this state of the model in the repository, along
+  with a short commit message, the date, and your author details.
+
+.. Tip::
+
+    All revisions need to have some sort of commit message. Typically this
+    should be kept to 50 characters or less, but there is no practical limit,
+    consider that this message may appear in various places, including on
+    drawings, web pages, email subject lines etc.. It is also best to describe the
+    status of the revision rather than the changes, ie. "Kitchen now has a
+    door" is better than "Add a kitchen door" - but this is a matter of taste.
+
+Visualising differences
+-----------------------
+
+As you add commits, the revision list will build up. Usually you are working at
+the HEAD of a branch, ie. at the top of the list, but you can select items in
+the list to view commit metadata. You can also temporarily colourise the current
+model showing differences between this and any other saved revision - colours
+are the same as above: green objects are new to the current model, blue
+objects have changed in some way, and (if you have an older revision loaded)
+red objects have been deleted.
+
+Viewing object history
+----------------------
+
+The history of *everything* in the project is tracked in Git, the revision log
+for the currently selected object can be viewed with the Bonsai side-bar.
+
+Retrieving Revisions
+--------------------
+
+Colourising the model will show you *which* things are different, but it won't
+show you *how* they are different. As long as you have no uncommitted changes,
+you can switch to the selected revision, this will load in Bonsai as a
+full model that can be viewed and even edited.
+
+.. Warning::
+
+    Switching to a different revision actually changes the file on disk before
+    loading it in Bonsai. Don't worry, the original hasn't been lost,
+    simply select the revision at the top of the list, switch back to
+    that and you can continue as before.
+
+Branching
+---------
+
+Git supports a branched workflow. Say that you want to explore some design
+options, but don't want to mess-up the primary design, you can fork off any
+revision into a new branch and work on this without breaking anything in any
+other branches.
+
+.. Note::
+
+    The primary branch in a Git repository is usually called *main*, though
+    this is a convention, and older versions of Git call it *master*. Branch
+    names should be short, but can contain unicode characters, emojis etc...
+    Branch names can't contain spaces, and have some other minor limitations -
+    Bonsai will not allow you to create invalid branch names.
+
+To create a new branch from the current HEAD (ie. the top of the revision list)
+enter a branch name when committing. Leaving this field empty just adds a
+normal commit without creating a branch, however committing a change to an
+earlier revision necessarily implies a new branch, so Bonsai will insist
+that you give it a name.
+
+Each branch can now be navigated separately in the revision list, to switch
+between branches, and to any previous revision in any branch, select the
+revision you are interested-in and switch as before.
+
+.. Tip::
+
+    Conceptually a local branch is equivalent to a remote fork in somebody
+    else's copy of your repository, and indeed by adding a remote you
+    can fetch their work into a *remote branch* in your local repository.
+
+Merging
+-------
+
+.. Warning::
+
+    Merging is experimental functionality. There are various circumstances
+    where a merge will fail, don't worry, this won't break your model but you
+    may not want to rely on this functionality without having some experience
+    of what changes are likely to merge and what won't.
+
+You can merge changes that exist in a selected revision into the current
+model, even if changes have been made in both revisions - as long as these
+changes don't directly conflict.
+
+.. Note::
+
+    Merging requires the *ifcmerge* tool installed in your `PATH`, if it is
+    not installed the merge operator will not be enabled.
+
+When two branches have diverged, merging an IFC model requires *conflict
+resolution* (because added entities may inadvertently reuse the same Step-IDs),
+this means that data on one side or the other may be rewritten by Bonsai in
+order to accommodate both sets of changes. ie. the merge process is
+*asymmetrical*.  Bonsai privileges data in the remote `origin/main` branch
+over the local working branch, similarly it privileges data in the local `main`
+branch over any other local working branch. The practical result of this is
+that branches branched-off the `main` branch can generally be merged back into
+`main`, but any sub-branches of these will need to be merged back into their
+parent-branch *before* merging the parent-branch back into `main`.
+
+Tags
+----
+
+Git tags are useful to label important revisions (think of *TENDER*,
+*CONSTRUCTION*, *RevA* etc..). Tags appear as a prefix in the revision list,
+which can be filtered to only show revisions with tags. Tags for the selected
+revision are also listed in full below the revision list along with their
+optional message text.
+
+.. Note::
+
+    Tag names have the same limitations as branch names, names should be short
+    and without spaces, but can contain unicode characters, emojis etc...
+    Bonsai will not allow you to create invalid or duplicate tag names.
+    Similar to commit messages, tag messages should be 50 characters or less,
+    though there is no practical limit.
+
+.. Warning::
+
+    Tags can be deleted locally, but Git is distributed, so if the tag has
+    migrated to a remote repository it will reappear when you fetch changes
+    from that repository.
+
+Remote operations
+-----------------
+
+Git is a *distributed revision control system*, your local repository can be a
+version of a remote repository and vice-versa. This is conceptually similar to
+local branching except this remote repository could belong to someone else or
+could be hosted by an online Git-forge service.
+
+Your repository can have multiple remote repositories registered, each
+can have potentially multiple branches.
+
+Bonsai allows you to make a local *clone* of a remote repository.  You will
+need to provide a URL *origin* to fetch, and an empty local folder to become
+the local repository.
+
+The *Fetch* operator retrieves new data from the remote repository. This isn't
+automatically merged, each branch fetched from the remote repository appears as
+a branch that can be browsed, switched-to or merged just like a local branch.
+These remote branches have prefixed names, eg. `origin/main`.
+
+Once you have committed changes to your local repository, the *Push* operator
+tries to update the remote branch using changes from the selected local branch.
+
+.. Warning::
+
+    Remote repositories can be accessed in multiple ways; ssh, ftp or https
+    protocols, for example, can require authentication. This authentication may
+    expect you to generate and upload ssh keys, store API tokens, save
+    username/password pairs, or use some other form of credential.
+    Bonsai can't configure these credentials for you, follow the
+    configuration instructions provided by your online service before trying
+    actions that require authentication.
+
+Using other Git tools
+---------------------
+
+Bonsai is not a full Git user interface, but it provides most of the tools
+you will need for day-to-day usage. In general if you need other Git
+functionality you can use external Git tools with your repository and any
+changes will be reflected in the Bonsai UI.

src/bonsai/docs/guides/authoring/index.rst

@@ -0,0 +1,60 @@
+Authoring models
+================
+
+This chapter covers the essential aspects of working with Industry Foundation Classes (IFC) in Bonsai. It is divided into five main sections:
+
+.. only:: builder_html and (not singlehtml)
+
+   .. container:: toc-cards
+
+      .. container:: card
+
+         :doc:`understanding_ifc`
+            An introduction to IFC standards, schemas, and concepts.
+            This section explains the structure of IFC data, key spatial objects, and the role of organizations
+            like buildingSMART in maintaining IFC standards. It also covers IfcOpenShell and the broader ecosystem
+            of open standards in the AEC industry.
+
+
+      .. container:: card
+
+         :doc:`importing_viewing_models`
+            A guide on how to import existing IFC models into Bonsai and navigate them effectively.
+            This section includes techniques for inspecting and querying IFC data within the Bonsai environment.
+
+
+      .. container:: card
+
+         :doc:`starting_new_project`
+            Instructions on creating and setting up a new IFC project from scratch in Bonsai.
+            This covers initial project setup, including advanced options for more complex projects.
+
+      .. container:: card
+
+         :doc:`basic_modeling/index`
+          An exploration of fundamental IFC modeling techniques, including:
+              - Creating walls
+              - Adding doors and windows
+              - Modeling slabs and roofs
+              - Defining rooms and spaces
+
+      .. container:: card
+
+         :doc:`advanced_modeling/index`
+            A deep dive into more complex modeling techniques for experienced users, including:
+              - Creating custom parametric wall types
+              - Modeling furniture and fixtures
+              - Working with structural elements
+              - Designing multi-story buildings
+              - Modeling complex structures
+
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :maxdepth: 2
+
+      georeferencing
+      git_support
+      other_addons

src/bonsai/docs/guides/authoring/material_assignment.rst

@@ -0,0 +1,102 @@
+Material Assignment
+===================
+
+This section covers how to assign and customize materials in your BIM model using the Bonsai.
+
+Types of Material Definitions
+-----------------------------
+
+In BIM, materials can be defined in several ways:
+
+1. Single Material: The simplest approach, where an object has one material.
+2. Material Constituent Set: For objects with multiple materials (e.g., a window with an aluminum frame and glass glazing).
+3. Material Layer Set: Used for objects like walls or slabs, defining layers of different materials and thicknesses.
+4. Material Profile Set: Typically used for structural elements, defining materials in relation to a specific profile shape.
+
+Basic Material Assignment
+-------------------------
+
+To assign a material to an object:
+
+1. Select the object in the 3D viewport.
+2. Go to the Material Properties panel.
+3. Click "New" to create a new material.
+4. Give the material a name.
+5. Set the material type (single, constituent set, layer set, or profile set).
+
+Material Categories
+-------------------
+
+Materials should be categorized for easy identification and scheduling:
+
+- In IFC4 models, materials are automatically grouped into categories (e.g., concrete, steel, wood).
+- For IFC2x3 models, materials may appear uncategorized.
+
+To view all materials in your project:
+
+1. Go to the Materials schedule in the Bonsai panels.
+2. You'll see a list of all materials used in the model.
+
+Best Practices for Material Naming
+----------------------------------
+
+- Use standardized naming conventions for materials.
+- Names should match how materials are tagged in drawings, schedules, and specifications.
+- Avoid using color codes as material names.
+
+Material Properties
+-------------------
+
+In IFC4 models, materials can have associated properties:
+
+1. Select a material in the Materials panel.
+2. Look for the "Common Properties" section.
+3. Set relevant properties for the material (e.g., density, thermal properties).
+
+Note: IFC2x3 models have limited support for material properties.
+
+Profiles for Structural Elements
+--------------------------------
+
+For structural models, especially steel structures:
+
+1. Use Material Profile Sets for elements like beams and columns.
+2. Name profiles according to standardized codes in your region.
+3. In IFC4 models, profiles can have associated structural properties.
+
+To view profiles:
+
+1. Look for the Profiles schedule in Bonsai panels.
+2. You should see a list of all profiles used in the project.
+
+Color vs. Material
+------------------
+
+It's important to distinguish between an object's color and its material:
+
+- Color is a visual property for rendering and display.
+- Material defines the physical properties and composition of the object.
+
+Avoid merging these concepts; an object can have a material without a specific color, and vice versa.
+
+Saving and Exporting
+--------------------
+
+Remember that Bonsai .ifc files cannot currently save textures from image files. To preserve both BIM data and detailed materials:
+
+1. Save your project as a .blend file to retain all material and texture information for rendering.
+2. Also save as an .ifc file to store BIM data.
+
+Always maintain both .blend and .ifc versions of your project to ensure all information is preserved.
+
+IFC Version Considerations
+--------------------------
+
+- IFC4 provides better support for material properties, categories, and profiles compared to IFC2x3.
+- Consider migrating to IFC4 for more comprehensive material information and structural analysis capabilities.
+
+See Also
+--------
+
+- :doc:`../../structural_analysis/index`
+- :doc:`../../costing_and_scheduling/index`

src/bonsai/docs/guides/authoring/modeling_slabs_roofs.rst

@@ -0,0 +1,7 @@
+Modeling Slabs and Roofs
+========================
+
+.. note::
+   This page is a stub. More detailed content will be added in future updates.
+
+[Content about modeling slabs and roofs]

src/bonsai/docs/guides/authoring/opening.rst

@@ -0,0 +1,61 @@
+Opening Without Filling
+=======================
+
+An opening without a filling is a void in a building element,
+typically a wall, that doesn't contain a door or window.
+
+These openings can serve various purposes such as ventilation, pass-throughs, service penetrations, or architectural features.
+
+In IFC, it's represented by the IfcOpeningElement entity, which is a subtype of IfcFeatureElementSubtraction.
+
+This section covers how to create openings without fillings in your BIM model using Bonsai.
+
+
+Creating an Opening Without Filling
+-----------------------------------
+
+Currently, there isn't a dedicated tool for creating openings without fillings.
+However, every door or window is a filling for an opening element, so it's created implicitly.
+
+It means, you can achieve an opening without a filling by creating a door or window and then removing it and its type.
+
+Here's the process:
+
+1. Select the wall where you want to create the opening.
+2. Set the 3D cursor on the wall at the desired opening location.
+3. Use either the "Create Door" or "Create Window" tool from the toolbar,
+   depending on the shape you need for your opening.
+4. Follow the steps to create a door or window as described in their respective sections.
+5. After creating the door or window, select it in the 3D viewport and press Delete.
+6. In the Outline panel, find the "Type" field and press Delete.
+
+This process will leave you with an opening element without a filling.
+
+Additionally, you can create an opening by using the "Add Void" button in Create Wall tool.
+This tool will add an Opening IFC element to the Outline and its 3D representation in the 3D Vieport.
+Blender move and scale tools will allow you to modify the opening.
+After you finished with modifications, you can press the check mark to complete the void.
+
+Modifying Openings
+------------------
+
+You can modify openings using various tools:
+
+- Resize: Adjust the width and height parameters in the top bar.
+- Move: Use Blender's standard move tools to reposition the opening.
+
+.. note::
+  The opening is hidden object. To show it, press the "eye" button hear the "Add Void" in the Create Wall tool.
+
+.. note::
+   After moving an opening, you need to recalculate the void in the wall. To do this:
+
+   - Click on checkmark near the "Add Void" in the Create Wall tool.
+
+
+See Also
+--------
+
+- :doc:`../creating_walls`
+- :doc:`door`
+- :doc:`window`

src/bonsai/docs/guides/authoring/other_addons.rst

@@ -0,0 +1,49 @@
+Other add-ons
+=============
+
+Blender has a large ecosystem of add-ons. Bonsai is one of many add-ons which
+provide utility to the architecture, engineering, and construction industry.
+
+Some of these add-ons come with Blender and merely need to be enabled in the
+``Edit > Preferences > Add-ons`` tab.
+
+- **Sun Position** - will allow you to set the correct location of the sun and
+  true north. Integrates with IFC4 georeferencing and solar analysis features
+  in Bonsai.
+- **AutoCAD DXF Format (.dxf)** - provides import and export support of the DXF
+  format in Blender.
+- **tinyCAD Mesh tools** - provides basic intersection and circle reconstruction
+  utilities similar to trim / extend / centroid tools in CAD tools.
+
+Some of these add-ons are not shipped with Blender:
+
+- `CAD Transform for Blender <https://gumroad.com/l/nqvcs>`__ - This will
+  provide CAD snapping, move, rotate, and scale functions in Blender. This is
+  highly recommended for precision modeling in Blender.
+- `Blender Archipack <https://blender-archipack.org/>`__ - Archipack lets you
+  create parametric architectural objects, like walls, floors, ceilings, doors,
+  roofs, and furniture with a single click from a preset templates.
+- `Sverchok <https://github.com/nortikin/sverchok/>`__ - Sverchok is a visual
+  programming add-on for Blender that allows you to generate parametric
+  geometry, create scripts for non-programmers, model solids from FreeCAD, and
+  much more. There is also
+  `IfcSverchok <https://github.com/IfcOpenShell/IfcOpenShell/blob/v0.8.0/src/ifcsverchok/README.md/>`__ 
+  that adds IFC features to Sverchok.
+- `BlenderGIS <https://github.com/domlysz/BlenderGIS>`__ - BlenderGIS lets you
+  import GIS data, grab elevation data from the web, and generate TINs from
+  survey points and contours.
+- `Ladybug Tools for Blender
+  <https://github.com/ladybug-tools/ladybug-blender/releases/download/ladybug-blender-240529/ladybug-blender-240529.zip>`__ - Ladybug Tools
+  is an extension of Sverchok for environmental analysis and building physics
+  simulation. It allows analysis of solar, daylight, energy, and CFD.
+- `Topologic <https://topologic.app/>`__ - Perform spatial and topological
+  analysis of simplified building geometry and space connectivity.
+- `Speckle Blender <https://speckle.systems/tag/blender/>`__ - Use Speckle to
+  get your designs in Blender from other CAD software.
+- `Point Cloud Visualizer <https://blendermarket.com/products/pcv>`__ - Display,
+  edit, filter, render, convert, generate and export colored point cloud PLY
+  files.
+- `MeasureIt_ARCH <https://github.com/kevancress/MeasureIt_ARCH>`__ - Simple
+  dimensioning and annotation tools in Blender.
+- `Sorcar <https://aachman98.itch.io/sorcar>`__ - Another visual node
+  programming alternative to Sverchok.

src/bonsai/docs/guides/authoring/parametric_geometry.rst

@@ -0,0 +1,37 @@
+Parametric Geometry
+===================
+
+Bonsai 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/bonsai/docs/guides/authoring/spatial_objects.rst

@@ -0,0 +1,10 @@
+Basic Spatial Objects
+=====================
+
+IFC organizes building information in a hierarchical structure:
+
+- IfcProject
+- IfcSite
+- IfcBuilding
+- IfcBuildingStorey
+- IfcSpace

src/bonsai/docs/guides/authoring/starting_new_project.rst

@@ -0,0 +1,143 @@
+Starting a New IFC Project
+==========================
+
+To ensure the best start for your IFC project, follow these steps:
+
+Start a New Blender Session
+---------------------------
+
+- Close any open Blender windows.
+- Launch a fresh instance of Blender.
+
+This ensures there are no lingering connections or data from previous projects.
+
+Create a New IFC Project
+------------------------
+
+There are two main methods to create a new IFC project:
+
+Using File Menu (Recommended)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: images/file_new-ifc-project-submenu.png
+   :alt: New IFC Project submenu options
+   
+   New IFC Project submenu options
+
+1. Go to File > New IFC Project.
+2. Choose from the following options:
+
+   - New Metric (m) Project: Creates a project using meters as the base unit.
+   - New Metric (mm) Project: Creates a project using millimeters as the base unit.
+   - New Imperial (ft) Project: Creates a project using feet as the base unit.
+   - New Demo Project: Creates a project with pre-populated demo content.
+   - New Project Wizard: Opens the Project Info panel for customized setup.
+
+3. If you chose one of the first four options, your project will be created immediately.
+4. New Project Wizard is detailed below.
+
+Using New Project Wizard / Scene Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: images/project_wizard.png
+   :alt: Project Wizard in `Scene Properties > Project Overview` subtab
+   
+   Project Wizard in `Scene Properties > Project Overview` subtab
+
+
+1. You can access this method in two ways:
+
+   - Go to `File > New IFC Project > New Project Wizard`
+   - Navigate to Scene `Properties > Project Overview > Project Info`
+
+2. In the Project Info panel:
+
+   - Choose the IFC Schema (IFC2X3, IFC4, or IFC4X3).
+   - Select the Unit System (Metric or Imperial).
+   - Choose Length, Area, and Volume units.
+   - Select a Template (Blank or IFC4 Demo Template).
+
+3. Click the "Create Project" button.
+
+Cleaning the scene
+------------------
+
+- After creating a new project, Bonsai considers the presence of three default Blender objects:
+  a mesh (usually the default cube), a camera, and a light.
+- If have scene setup like this, Bonsai will clean it up
+- Any customizations you make to the Blender scene before finalizing the IFC project creation will be preserved.
+
+If you like, you can delete the default cube, camera and light manually. Or create your own objects.
+This is only recommended for users proficient in Blender. Otherwise, use the File menu or Create Project button in New Project Wizard.
+
+Project Initialization
+----------------------
+
+.. figure:: images/outliner.png
+   :alt: A basic spatial tree in the Outliner
+   
+   A basic spatial tree in the Outliner
+
+
+- A basic spatial tree will be created with `IfcProject > IfcSite > IfcBuilding > IfcStorey`.
+- You can view this structure in the Outliner.
+- The Project Info panel will update to show details about your new IFC project.
+
+Saving
+------
+
+.. figure:: images/project-info_unsaved.png
+   :alt: Project Info in Unsaved Mode
+   
+   Project Info in Unsaved Mode
+
+
+After creating a new project, Bonsai enters an Unsaved Mode. It's important to understand how saving works in Bonsai:
+
+**Saving IFC Project**:
+   - Using the keyboard shortcut `Ctrl+S` or `File > Save IFC Project` will save only the `.ifc` file.
+   - The `.blend` file remains unsaved and unnamed after this operation.
+
+**Initial Save**:
+   - On your first save, you'll be prompted to choose a location and name for your `.ifc` file.
+   - This does not automatically save a `.blend` file.
+
+**Blend File Saving**:
+   - To save the `.blend` file, you need to use Blender's standard `File > Save` or `File > Save As...` options.
+   - This operation is separate from saving the IFC project.
+
+**File Menu Options**:
+   - `File > Save IFC Project` saves only the `.ifc` file.
+   - `File > Save IFC Project As...` allows you to save the .ifc file to a new location or with a new name.
+   - Standard Blender save options (`File > Save`, `File > Save As...`) only affect the .blend file.
+
+**Opening Projects**:
+   - `File > Open IFC Project` loads only the `.ifc` file. It does not automatically load a corresponding `.blend` file.
+   - To open a `.blend` file associated with an IFC project, you need to open it separately using Blender's standard open options.
+
+**Best Practices**:
+   - Always use `File > Open IFC Project` to load your BIM data.
+   - If you want to preserve Blender-specific settings or custom scene setups, save the `.blend` file separately.
+   - Be aware that opening a `.blend` file directly will not load the associated IFC data.
+
+**For BIM Workflows**:
+   - Focus on the `.ifc` file as the primary source of truth for your BIM data.
+   - Use `.blend` files if you need to preserve specific Blender setups or visual configurations, but remember these are secondary to the IFC data.
+
+Remember, in Bonsai, the `.ifc` file contains the critical BIM information.
+The `.blend` file is primarily for Blender-specific settings and visual representations.
+Always ensure your IFC project is saved before closing Blender or starting a new session.
+If you need to preserve Blender-specific configurations, save the `.blend` file separately.
+
+Remember to save your work regularly using `File > Save IFC Project`.
+
+Next Steps
+----------
+
+- Begin modeling your building elements (walls, slabs, etc.).
+- Set up project properties and classifications.
+- Start defining spaces and zones within your building.
+
+.. seealso::
+  - :doc:`/users/user_interface/property_editor/scene_editor/project_overview/project_info`
+  - :doc:`/users/user_interface/topbar`

src/bonsai/docs/guides/authoring/understanding_ifc.rst

@@ -0,0 +1,80 @@
+=================
+Understanding IFC
+=================
+
+Industry Foundation Classes (IFC) is an open, international standard for Building Information Modeling (BIM) data.
+It provides a standardized way to describe, exchange, and share information about building and construction industry data.
+
+IFC Schema
+----------
+
+The IFC schema defines a comprehensive set of consistent data representations of building information for exchange between AEC software applications.
+It covers various aspects of buildings throughout their lifecycle, from conception to demolition.
+
+
+buildingSMART and Standards
+---------------------------
+
+buildingSMART International (bSI) is the organization responsible for developing and maintaining the IFC standard.
+They also develop other related standards like BCF (BIM Collaboration Format) and bSDD (buildingSMART Data Dictionary).
+
+IfcOpenShell
+------------
+
+IfcOpenShell is the open-source software library used by Bonsai to read, write, and manipulate IFC files.
+It provides the core functionality for working with IFC data.
+
+Interoperability and Other Standards
+------------------------------------
+
+IFC is part of a broader ecosystem of open standards in the AEC industry. Other relevant standards include:
+
+- COBie (Construction Operations Building Information Exchange)
+- CityGML (City Geography Markup Language)
+- gbXML (Green Building XML)
+
+The use of open standards like IFC ensures interoperability between different software tools
+and preserves data integrity throughout the building lifecycle.
+
+
+Key Concepts
+============
+
+This section provides an overview of key IFC concepts and how they're implemented in Bonsai.
+
+
+.. only:: builder_html and (not singlehtml)
+
+   .. container:: toc-cards
+
+      .. container:: card
+
+         :doc:`ifc_concepts/spatial_objects`
+            Basic spatial objects.
+
+      .. container:: card
+
+         :doc:`ifc_concepts/classification_and_types`
+            IFC classification hierarchy and the concept of types and occurrences.
+
+      .. container:: card
+
+         :doc:`ifc_concepts/geometry_and_representations`
+            Understanding IFC geometry, representations, and parametric materials.
+
+      .. container:: card
+
+         :doc:`ifc_concepts/working_with_representations`
+            Representations in Bonsai.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :caption: Understanding IFC
+      :maxdepth: 2
+
+      ifc_concepts/spatial_objects
+      ifc_concepts/classification_and_types
+      ifc_concepts/geometry_and_representations
+      ifc_concepts/working_with_representations

src/bonsai/docs/guides/authoring/window.rst

@@ -0,0 +1,145 @@
+Window
+======
+
+A window is an opening that allows light and air to enter a building, providing ventilation and views to the outside.
+
+In IFC, it's represented by the IfcWindow entity, which is a subtype of IfcBuildingElement.
+Windows play a crucial role in building design, affecting natural lighting, ventilation, energy efficiency, and aesthetics.
+
+This section covers how to add and customize windows in your BIM model using Bonsai.
+
+Adding a Window
+---------------
+
+1. Select the wall where you want to place the window.
+2. Set the 3D cursor on the wall at the desired window location.
+3. Click on the "Create Window" tool in the Bonsai toolbar.
+4. In the top bar, you'll see "[No IfcWindowType Found] | Name [TYPEX] | + Add IfcWindowType".
+5. Edit [TYPEX] to use a window type name of your choice (e.g., WINDOW001).
+6. Click "+ Add IfcWindowType". The top bar will update with additional options.
+7. Click "Add" (or press SHIFT+A) to create a window with its own type.
+8. Adjust the window's width and height using the parameters in the top bar.
+
+Placing a Window and Changing its Configuration
+-----------------------------------------------
+
+1. Select the wall:
+   - (Optional) Use the "Create Wall" tool to add a wall in your scene.
+   - Select the wall where you want to place the window.
+
+   Selecting the wall is crucial as it ensures that the void relation between the window and the wall is automatically created.
+
+2. Add a Window:
+   - Use the "Create Window" tool from the toolbar.
+   - Press SHIFT+A or click "Add" to place the window on the selected wall.
+
+**Applying Void**
+
+If you forgot to select the wall before placing the window, you'll need to manually create the void relation:
+
+   - Select both the wall and the window.
+   - Click "Apply Void" (Shift+O) button.
+
+.. important::
+   If you need to use "Apply Void", do this before making any modifications to the window,
+   as there are limitations with this function that may affect window orientation.
+
+   Usually, the Regen function will recalculate all the openings with existing void relationships.
+
+3. Adjust Window Position (if needed):
+   - With the window selected, use Blender's move tools to adjust its position along the wall.
+
+4. Regenerate the Wall Geometry:
+   - Select the wall.
+   - Press Shift+G to regenerate the wall geometry, incorporating the window opening.
+
+   .. note::
+      This step ensures the wall geometry is updated to include the window opening.
+
+      Moving the Window using Blender tools doesn't actually change the IFC model.
+      Future versions need to improve UX in that regard.
+      Synchronisation between the Blender scene and IFC model is an issue that has the highest priority.
+
+5. Change Window Configuration:
+   - Select only the window.
+   - Locate the "Parametric Geometry" panel in the `Scene Properties > Geometry and Materials` subtab.
+   - Find the "Window" section within this panel.
+   - Change the "Operation Type" to the desired configuration (e.g., "DOUBLE_PANEL").
+
+6. Final Wall Geometry Regeneration:
+   - Select the wall again.
+   - Press Shift+G one more time to ensure all changes are properly applied.
+
+Modifying Windows
+-----------------
+
+.. note::
+   Some functionality is not implemented.
+
+You can modify windows using various tools:
+
+- Resize: Adjust the width and height parameters in the top bar.
+- Move: Use Blender's standard move tools to reposition the window.
+- Flip: Change the opening direction using the flip tool (if available).
+
+.. note::
+   After moving a window, you need to recalculate the void in the wall. To do this:
+
+- Select the wall containing the moved window.
+- Click on the "Regen" (:kbd:`Shift` + :kbd:`G`) button in the top bar or use the appropriate shortcut.
+- This ensures that the opening in the wall is correctly positioned after moving the window.
+
+If Regen operation doesn't achieve the required result, use Apply Void function:
+
+- Click on the "Apply Void" (:kbd:`Shift` + :kbd:`O`) button in the top bar or use the appropriate shortcut.
+- This ensures that the opening is linked to the wall.
+
+Window Properties
+^^^^^^^^^^^^^^^^^
+
+.. note::
+   This functionality is not implemented.
+
+After adding a window, you can customize its properties:
+
+1. Select the window in the 3D viewport.
+2. Go to the ... panel.
+3. Find the ... section.
+4. Here you can set various properties such as thermal transmittance (U-value), solar heat gain coefficient, or any custom properties required for your project.
+
+.. note::
+   This functionality is not implemented.
+
+Customize window properties such as:
+
+- Dimensions
+- Window type (e.g. fixed, casement, sliding)
+- Glazing options
+- Frame material
+
+Creating Multiple Windows
+-------------------------
+
+To create multiple windows of the same type:
+
+1. Select the desired window type from the dropdown menu in the top bar.
+2. Set the 3D cursor on a wall where you want to place the new window.
+3. Select the wall
+4. Click "Add" (or press SHIFT+A) for each new window you want to create.
+5. Adjust the 3D cursor, position and parameters for each new window as needed.
+
+Calculating Quantities
+----------------------
+
+After creating windows, you can calculate quantities:
+
+1. Select the window(s) you want to measure.
+2. Press Q or click "Calculate All Quantities" in the top bar.
+
+This will update the quantity information for the selected elements.
+
+See Also
+--------
+
+- :doc:`../creating_walls`
+- :doc:`../../advanced_modeling/material_assignment`

src/bonsai/docs/guides/authoring/working_with_representations.rst

@@ -0,0 +1,108 @@
+Working with Representations
+----------------------------
+
+Bonsai 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 Bonsai
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Bonsai 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Bonsai 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 Bonsai 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 Bonsai GitHub repository.