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.

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

@@ -0,0 +1,4 @@
+Coordination
+============
+
+TODO

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

@@ -0,0 +1,35 @@
+Costing and scheduling
+======================
+
+This section covers the cost estimation and project scheduling features in Bonsai.
+
+.. note::
+   This page is a stub. More detailed content will be added in future updates.
+
+Overview
+--------
+
+Bonsai offers integrated tools for cost estimation and project scheduling, allowing users to link BIM elements directly to cost data and timeline information.
+
+Key Features
+------------
+
+- Material and element cost association
+- Quantity takeoffs
+- Project timeline creation
+- Resource allocation
+- 4D BIM visualization
+
+Getting Started
+---------------
+
+To begin using the costing and scheduling features in Bonsai:
+
+1. Access the Costing and Scheduling panel in the Bonsai interface
+2. Associate costs with materials and elements
+3. Create a project timeline
+4. Link BIM elements to schedule activities
+
+.. seealso::
+   - :doc:`/users/modeling/ifc_modeling`
+   - :doc:`/users/advanced/index`

src/bonsai/docs/guides/development/hello_world.rst

@@ -0,0 +1,323 @@
+Hello, world!
+=============
+
+Bonsai takes a unique approach to authoring BIM data. Traditional BIM authoring
+apps create features that are tailored for a single discipline's paradigm, such
+as a 3D environment, or a spreadsheet view, and store their data structure in a
+schema that is unique to their application. In order to interoperate with
+others, there is an export or import process that translates between their
+bespoke schema to and from open data standards. The most famous ISO standard
+for BIM is IFC. After this translation, they then serialise it typically into a
+format, which may be saved to disk.
+
+Bonsai does things differently.
+
+Bonsai does not have its own bespoke data structure and does not import or
+export. Bonsai uses ISO open data standards directly in memory. Most commonly,
+this is IFC data. We will place a focus on IFC on this guide, but the reader
+should be aware that Bonsai also takes the same approach to dealing with other
+open data standards, like Brickschema or BCF. The same concepts will apply. We
+can call this Native OpenBIM authoring, which is a paradigm shift from
+traditional BIM which relies on translated IFC data.
+
+.. image:: images/native-openbim.png
+
+Every user operation reads or writes this data structure in memory, and the IFC
+data becomes the source of truth for all data. There is no such thing as an
+import or export. The data is always represented in IFC. When a BIM model is
+opened or saved, it is simply a serialisation or deserialisation operation. This
+also means that you are using Blender simply as an interface to interact with
+IFC, and the ``.blend`` container is largely unnecessary, as nothing of
+significance is stored in the Blender system, it is simply a snapshot of your
+working session.
+
+Due to this significant difference, hacking on Bonsai requires knowledge not
+just about how Blender works, but also how open data standards like IFC works.
+
+Just show me the code!
+----------------------
+
+Sometimes, the best way to learn how to hack on a project is to just start
+hacking away. First, download the code. To keep things simple, you can download
+the source as a zip file for now, but keep in mind that sooner or later you'll
+need to :ref:`use Git to collaborate <submitting-code-to-git>`.
+
+.. container:: blockbutton
+
+    `Download Source
+    <https://github.com/IfcOpenShell/IfcOpenShell/archive/refs/heads/v0.8.0.zip>`__
+
+BIM authoring is a really big topic. As a result, the Bonsai code is separated
+into modules. Each module focuses on a particular topic of BIM. Most modules
+are self-contained, but sometimes they connect to one another, just like how
+BIM works.
+
+.. image:: images/module-architecture.png
+
+Modules are not arbitrary divisions. They tend to reflect how portions of BIM
+data are segregated in the IFC international standard. This allows us to
+minimise the overlap between modules, so that developers can work on a single
+portion of the code with relative certainty that their actions will not affects
+other developers.
+
+- `Bonsai modules <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/bonsai/bonsai/bim/module>`__
+- `IFC modules <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/ifcopenshell-python/ifcopenshell/api>`__
+
+Bonsai comes with a secret **demo module** which is basically a hello world
+coding tutorial which teaches you about all the moving parts. It's far more
+interesting to read this code rather than 15 pages of abstract software
+architecture flow charts and diagrams. The code and its comments will guide you
+through the process.
+
+Before playing with the demo module, you may want to switch to using a source
+installation. See `bonsai/installation <./installation.html>`_ for details.
+
+To see the demo module in action, you'll need to enable it. In
+``src/bonsai/bonsai/bim/__init__.py``, uncomment the line for the demo
+module. When you restart Blender, you will see a new demo panel in your scene
+properties interface tab. Have fun!
+
+.. image:: images/demo-module.png
+
+Now you're ready to learn how to code! Here are all the files associated with
+the demo module. Feel free to read them in any order. Each file is heavily
+commented with explanations about what each line of code does. Change some of
+the code, reload Blender, and see what happens!
+
+::
+
+    src/bonsai/bonsai/bim/module/demo/__init__.py
+    src/bonsai/bonsai/bim/module/demo/operator.py
+    src/bonsai/bonsai/bim/module/demo/prop.py
+    src/bonsai/bonsai/bim/module/demo/ui.py
+    src/bonsai/bonsai/bim/module/demo/data.py
+    src/bonsai/bonsai/core/demo.py
+    src/bonsai/bonsai/tool/demo.py
+
+
+Wow! That's a lot of files needed for a hello world! Don't worry, it's mostly
+tutorial comments and it's there to teach you the basics from how Blender's
+add-on system works, how interfaces work, to how Bonsai works, and how to test
+and structure it so that you can build incredibly complex features in a
+maintainable way.
+
+Tests for quality checking also exist. The system is designed so that you can
+do "Test Driven Development". For reference on how to run these tests, see `bonsai/running_tests <./running_tests.html>`_
+for details. You can find the tests here:
+
+::
+
+    src/bonsai/test/bim/feature/demo.feature
+    src/bonsai/test/core/test_demo.py
+    src/bonsai/test/tool/test_demo.py
+
+Not all developers, especially those learning how to code, are familiar with
+testing and how to write tests. That's OK! Feel free to ignore the tests at
+first until you get a bit more comfortable with coding, and others can help
+guide you when you're ready to make the leap. Don't let this stop you from
+building things, others can also help write tests for you and clean your code.
+It's a great way to learn!
+
+Once you're through, you should be able to understand how most of Bonsai is
+built and where to find things.
+
+There are many Blender Python tutorials out there. A good place to start is the
+`Start coding for Blender
+<https://wiki.osarch.org/index.php?title=Start_coding_for_Blender>`__ from the
+OSArch Wiki. In addition, the Blender text editor comes with a menu called
+``Templates > Python`` which gives you a whole list of example code of how to
+create an add-on which creates objects, creates gizmos, new buttons, interfaces,
+and so on. This is a great way to try out how to build different extensions.
+
+Naturally, if you just want to tweak Bonsai or build a small feature just for
+yourself, you're free to ignore this advice, skip all the tests, and just write
+half the code in a single file and it'll get the job done.
+
+Software architecture
+---------------------
+
+If code isn't good enough for you and you want to learn more about why the code
+is structured the way it is, here is a list of design principles we follow:
+
+1.  Big systems are hard to maintain. Break big systems into small systems.
+2.  Separate abstract code from concrete code. Start with abstract code, and
+    deal with the details later.
+3.  Good code reads like poetry. Every usecase should have a poem.
+4.  Separate UI code from domain logic. UI code should be as dumb as possible.
+5.  Follow the Unix philosophy. We're dealing with a big industry problem here.
+    Building a shared ecosystem of tools is better than one behemoth.
+6.  Everything should be testable. You should be able to test first.
+7.  Have different types of tests. Inversely correlate test speed and scope.
+8.  Community first. Allow beginner programmers to join in the fun! Code should
+    feel easy, not like a course in design pattern jargon.
+9.  Incremental change, not waterfall. Don't trash and rebuild. Refactor and
+    redesign one commit at a time. With each commit, ask if you're making the
+    code nicer.
+10. Perfect is the enemy of the good. Half broken is better than completely
+    broken.
+
+The rest of this contains nasty software architecture jargon. If that's not your
+thing, stop reading now.
+
+Bonsai code may be understood in three separate layers: **Delivery**,
+**Domain**, and **Data**. The Bonsai architecture separates these three layers
+from one another. Because they are separate, they can be tested and built
+separately.
+
+.. image:: images/architecture.png
+
+The **Delivery** mechanism is how the application is delivered to
+the user and handles user interactions. It covers the interface and triggering
+events as inputs into the application, and rendering responses.
+
+As advertised in the name, the **Delivery** mechanism is based on **Blender**.
+**Blender** is a well established 3D platform. Out of the box, it provides an
+incredibly advanced interface to allow users to interact with geometry. The
+delivery mechanism code extends Blender extensively, including new *Operations*
+that users can perform, new *Properties* to store custom data, and new *UI*
+layouts to display information.
+
+When an event such as an *Operation* is triggered, the **Delivery** mechanism
+executes the **Domain** layer through dependency injection. The **Domain** layer
+will then decide how to process this input.
+
+The **Domain** layer is divided into two halves: an abstract *Core* and concrete
+*Tools*. The *Core* describes abstract, high-level application logic flow for
+every single possible usecase in application. The *Tools* actually implement
+this abstract logic, and figure out how things actually work, whether it is
+manipulating the Blender scene, writing and reading files, building new IFC
+graph relationships, and so on. The **Domain** layer also has interface classes
+to describe what it needs.
+
+Whenever the application needs to remember or store information, it does so
+using a **Data** repository. The data ensures that stored information confirms
+to a defined schema and is valid, and can be retrieved later. Some data is
+stored in Blender, such as information about your working session and active
+scene. Other data is stored in IFC, such as all the relationships in your BIM
+model. We mention **Data** specifically because OpenBIM data authoring is such
+a big aspect of Bonsai. In fact, it's so big that most of it is completely
+separated from the Bonsai code and lives elsewhere.
+
+For example, all the code that handles IFC data, which you can think of as a
+graph database, is in a completely separate codebase, even under a different
+software license. You can find it in the IfcOpenShell-python API module. Many of
+the various data processing functions are built as separate Unix-like utilities,
+even with their own CLI. This **Data** layer isn't a single folder of code we
+can point to, it's an ecosystem of libraries and utilities that we want to share
+with the entire industry.
+
+IfcOpenShell Architecture
+-------------------------
+
+A large part of Bonsai is understanding how IFC data is modified.  This code is
+not technically part of the Bonsai codebase, but it is vital to understand. You
+will need to be familiar with the IfcOpenShell Python module.
+
+Manipulating IFC data is not simple. IFC may be serialised into multiple
+formats, multiple schema versions must be supported, and geometry may be defined
+in a highly parametric or implicit manner, which geometry kernels do not
+natively support. All this heavy lifting is performed by the IfcOpenShell
+library.
+
+The IfcOpenShell library consists of a C++ based core. Its geometry processing
+is done using OpenCascade, and optionally CGAL as an experimental option. By the
+time Bonsai interacts with IFC, it uses the IfcOpenShell Python bindings, so
+all IFC data is already deserialised into Python objects. The inner workings of
+the C++ base is out of scope.
+
+.. image:: images/ifcopenshell-architecture.png
+
+IfcOpenShell offers a core set of low-level functionality to read and write this
+data. An example of the core functionality would be:
+
+.. code-block:: python
+
+    import ifcopenshell
+    model = ifcopenshell.open("foo.ifc")
+    wall = model.create_entity("IfcWall")
+    wall.Name = "Foobar"
+
+Core functions are simple read and write operations with no post processing.
+Core functions also include geometry processing, which converts IFC geometry
+into OpenCascade objects.
+
+Sometimes, there are repetitive actions that need to be performed. These
+functions are grouped into a ``util`` module. These include utility functions
+for coordinate calculations, date conversions, filtering elements, unit
+conversions, and more. Utility functions make no assumption about the context in
+which they are used, and so perform highly specific tasks and nothing else.
+Here's an example of utility functionality:
+
+.. code-block:: python
+
+    import ifcopenshell
+    import ifcopenshell.util.date
+    import ifcopenshell.util.geolocation
+    start = ifcopenshell.util.date.ifc2datetime(task_time.ScheduleStart)
+    coordinates = ifcopenshell.util.geolocation.local2global(matrix, eastings, ...)
+
+When authoring, core and utility functions are usually too low-level. To cater
+for this, a high level API is provided. The API is divided into mostly isolated
+modules, each module representing a distinct set of concepts in the IFC schema.
+Unlike the util module, these API modules are highly context-sensitive, and
+assume that you intend to be authoring native IFC.
+
+This context-sensitive assumption means that the functions within the modules
+are designed around typical usecases in an authoring environment. It performs
+all the necessary manipulations to achieve a domain-specific usecase. Authoring
+is complex and requires a deep knowledge of IFC to perform correctly and ensure
+that the IFC graph state is well maintained. Typically, any authoring operation
+that does not use the API is likely to contain mistakes.
+
+Here's an example of it in action:
+
+.. code-block:: python
+
+    import ifcopenshell.api
+    ifcopenshell.api.run("grid.create_grid_axis", model, ...)
+    ifcopenshell.api.run("structural.add_structural_load", model, ...)
+
+Because the API performs all the IFC manipulations to achieve a usecase, no
+further interaction is required in a typical native IFC authoring environment.
+For this reason, Bonsai only interacts with the API for its authoring
+capabilities.
+
+The code for IfcOpenShell's various systems can be found here:
+
+- `ifcopenshell (core) <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/ifcopenshell-python/ifcopenshell>`__
+- `ifcopenshell.util <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/ifcopenshell-python/ifcopenshell/util>`__
+- `ifcopenshell.api <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/ifcopenshell-python/ifcopenshell/api>`__
+
+.. _submitting-code-to-git:
+
+Submitting code to Git
+----------------------
+
+So, you've written some code, fixed a bug, made an improvement, and would like
+to get your code added to the Git repository? If your change is relatively
+small, you can submit your changes just using the Github website. Browse to the
+`IfcOpenShell repository <https://github.com/ifcopenshell/ifcopenshell>`__ and
+navigate to the file you want to edit the code of. Then just press the edit icon
+to begin editing. When you're done, you'll be prompted to submit your changes.
+
+.. image:: images/github-editing.png
+
+If you're making a large change, you'll need to create a **Pull Request**.
+Github has an excellent comprehensive guide on `how to contribute to projects
+<https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`__
+which you can follow.
+
+If you make regular contributions, you are also welcome to officially join the
+IfcOpenShell developer team, where you'll be able to make changes without
+waiting for code reviews and approvals.
+
+Asking for help
+---------------
+
+It's no fun to code alone! It's encouraged to reach out if there are any issues,
+if you'd like to code together with another developer, need a code review, or
+need further testing. Here are some places to reach out:
+
+- `Github issues <https://github.com/IfcOpenShell/IfcOpenShell/issues>`__
+- `OSArch live chat <https://osarch.org/chat>`__
+- `OSArch community forum <https://community.osarch.org>`__

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

@@ -0,0 +1,16 @@
+Development
+===========
+
+This chapter covers how you can help contribute to Bonsai.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :maxdepth: 2
+
+      hello_world
+      running_tests
+      translations
+      undo_system
+      writing_docs

src/bonsai/docs/guides/development/installation.rst

@@ -0,0 +1,178 @@
+Installation
+============
+
+There are different methods of installation, depending on your situation.
+
+1. **Unstable installation** is recommended for power users helping with testing.
+2. **Bundling for Blender** is recommended for distributing the add-on.
+3. **Live development environment** is recommended for developers who are actively coding.
+4. **Packaged installation** is recommended for those who use a package manager.
+
+Unstable installation
+---------------------
+
+**Unstable installation** is almost the same as **Stable installation**, except
+that they are typically updated every day. Simply download a daily build from
+the `GitHub releases page
+<https://github.com/IfcOpenShell/IfcOpenShell/releases?q=bonsai&expanded=true>`__,
+then follow the usual :doc:`installation
+instructions</users/quickstart/installation>`.
+
+Bonsai officially supports all major 64-bit platforms, as well as the Python
+version shipped by the Blender Foundation for the most recent three major
+Blender versions:
+
+- 64-bit Linux (``linux-x64``)
+- 64-bit MacOS Intel (``macos-x64``)
+- 64-bit MacOS Silicon (``macos-arm64``)
+- 64-bit Windows (``windows-x64``)
+- Blender 4.2 with Python 3.11
+
+Due to significant changes in the Blender extensions system, Blender versions
+<4.2 are not supported.
+
+Developer builds may exist for different versions of Python but there will be
+no guarantee of the uptime or stability of these builds.
+
+Other system specifications match the `Blender Requirements
+<https://www.blender.org/download/requirements/>`_ and the `VFX Platform
+<https://vfxplatform.com/>`_ standard.
+
+Sometimes, a build may be delayed, or contain broken code. We try to avoid this,
+but it happens.
+
+Bundling for Blender
+--------------------
+
+Instead of waiting for an official release on the Bonsai website, it
+is possible to make your own Blender add-on from the bleeding edge source code
+of Bonsai. Bonsai is coded in Python and doesn't require any
+compilation, so this is a relatively easy process.
+
+Note that Bonsai depends on IfcOpenShell, and IfcOpenShell does require
+compilation. The following instructions will use a pre-built IfcOpenShell
+(using an IfcOpenBot build) for convenience. Instructions on how to compile
+IfcOpenShell is out of scope of this document.
+
+You can create your own package by using the Makefile as shown below. You can
+choose between a ``PLATFORM`` of ``linux``, ``macos``, ``macosm1``, and ``win``.
+You can choose between a ``PYVERSION`` of ``py312``, ``py311``, ``py310``, or
+``py39``.
+
+.. code-block:: bash
+
+    cd src/bonsai
+    make dist PLATFORM=linux PYVERSION=py311
+    ls dist/
+
+This will give you a fully packaged Blender add-on zip that you can distribute
+and install.
+
+Live development environment
+----------------------------
+
+One option for developers who want to actively develop from source is to follow
+the instructions from :ref:`devs/installation:Bundling for Blender`. However,
+creating a build, uninstalling the old add-on, and installing a new build is a
+slow process.  Although it works, it is very slow, so we do not recommend it.
+
+A more rapid approach is to follow the :ref:`devs/installation:Unstable
+installation` method, as this provides all dependencies for you out of the box.
+
+Once you've done this, you can replace certain Python files that tend to be
+updated frequently with those from the Git repository. We're going to use
+symbolic links, so we can code in our Git repository, and see the changes in
+our Blender installation (you will need to restart Blender to see changes).
+
+For Linux or Mac:
+
+.. literalinclude:: ../../scripts/installation/dev_environment.sh
+   :language: bash
+   :caption: dev_environment.sh
+
+Or, if you're on Windows, you can use the batch script below. You need to run
+it as an administrator. Before running it follow the instructions descibed
+in the `rem` tags.
+
+.. literalinclude:: ../../scripts/installation/dev_environment.bat
+   :language: bat
+   :caption: dev_environment.bat
+
+After you modify your code in the Git repository, you will need to restart
+Blender for the changes to take effect.
+
+The downside with this approach is that if a new dependency is added, or a
+compiled dependency version requirement has changed, or the build system
+changes, you'll need to fix your setup manually. But this is relatively rare.
+Reviewing the Makefile history, `here <https://github.com/IfcOpenShell/IfcOpenShell/commits/v0.8.0/src/bonsai/Makefile>`__, is one quick way to see if a dependency has changed.  
+
+.. seealso::
+
+    There is a `useful Blender Addon
+    <https://blenderartists.org/uploads/short-url/yto1sjw7pqDRVNQzpVLmn51PEDN.zip>`__
+    (see `forum thread
+    <https://blenderartists.org/t/reboot-blender-addon/640465/13>`__) that adds
+    a Reboot button in File menu.  In this way, it's possible to directly
+    restart Blender and test the modified source code.  There is also a VS Code
+    add-on called `Blender Development
+    <https://marketplace.visualstudio.com/items?itemName=JacquesLucke.blender-development>`__
+    that has a similar functionality.
+
+
+Packaged installation
+---------------------
+
+- **Arch Linux**: `Direct from Git <https://aur.archlinux.org/packages/ifcopenshell-git/>`__.
+- **Chocolatey on Windows**: `Unstable <https://community.chocolatey.org/packages/bonsai-nightly/>`__.
+
+Tips for package managers
+-------------------------
+
+Bonsai is fully contained in the ``bonsai/`` subfolder of the Blender add-ons
+directory. This is typically distributed as a zipfile as per Blender add-on
+conventions. Within this folder, you'll find the following file structure:
+
+::
+
+    core/ (Blender agnostic core logic)
+    tool/ (Blender specific shared functionality)
+    bim/ (Blender specific UI)
+    libs/ (other assets)
+    wheels/ (dependencies)
+    __init__.py
+
+This corresponds to the structure found in the source code `here
+<https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/bonsai/bonsai>`__.
+
+Bonsai is complex, and requires many dependencies, including Python modules,
+binaries, and static assets. When packaged for users, these dependencies are
+bundled with the add-on for convenience.
+
+If you choose to install Bonsai and use your own system dependencies, the
+source of truth for how dependencies are bundled are found in
+the `Makefile
+<https://github.com/IfcOpenShell/IfcOpenShell/blob/v0.8.0/src/bonsai/Makefile>`__
+in the ``dist`` target.
+
+Add-on compatibility
+--------------------
+
+Bonsai is a non-trivial add-on. By turning Blender into a graphical front-end
+to a native IFC authoring platform, some fundamental Blender features (such as
+hotkeys for basic functionality like object deletion or duplication) have been
+patched and many dependencies have been introduced.
+
+Other add-ons may no longer work as intended when Bonsai is enabled, or vice
+versa, Bonsai may no longer work as intended when other add-ons are enabled.
+
+Known scenarios which will lead to add-on incompatibility include:
+
+- The add-on also overrides the same hotkeys. For example, if an add-on
+  overrides the "X" key to delete an object, you will need to manually trigger
+  (either via menu or custom hotkey) the Bonsai equivalent operator
+  (e.g. IFC Delete).
+- The add-on uses object deletion or duplication macros with dictionary
+  override. Note that this is also deprecated in Blender, so the other add-on
+  should be updated to fix this.
+- The add-on requires a conflicting dependency, or a conflicting version of the
+  same dependency. Neither add-on may work simultaneously.

src/bonsai/docs/guides/development/running_tests.rst

@@ -0,0 +1,140 @@
+Running tests
+=============
+
+Bonsai has three layers of tests for each of its three technology layers:
+
+1. **Core tests**: abstract domain logic unit tests agnostic of Blender
+2. **Tool tests**: low-level concrete unit tests dependent on Blender
+3. **UI tests**: high-level integration UI and smoke tests dependent on Blender
+
+These tests use ``pytest`` as the test framework and runner, so install it:
+
+.. code-block:: bash
+
+    pip install pytest
+
+All development is expected to use test driven development, and so we expect
+test coverage to be 100% where it is technically possible to test.
+
+When running tests, Makefile targets are provided for convenience so you can
+type in a simple command without knowing the internals. This means you can run
+tests by using the ``make`` command.
+
+Because Bonsai depends on IfcOpenShell, it is advised to also run tests for
+IfcOpenShell and its Python bindings, which is not covered in this document.
+
+Core tests
+----------
+
+The core layer tests are pure Python unit tests with no dependencies on Blender
+or other modules. They are designed to be fast and easy to run as they test
+purely abstract domain logic.
+
+Although they are vanilla Python tests, they do not use the Python Mock module.
+Instead, a lightweight ``Prophecy`` mocker class is used, which allows tests to
+be written in a highly concise, expressive manner. For those coming from a
+BDD background in Ruby's RSpec, PHP's PHPSpec, and PHP's Prophecy, this is very
+similar.
+
+.. code-block:: bash
+
+    cd src/bonsai/
+    make test-core
+    # If you're on Windows, and don't want to use make, use:
+    pytest -p no:pytest-blender test/core
+
+Tool tests
+----------
+
+The tool layer tests actual concrete functions. You will need to install the
+following dependencies:
+
+* pytest-blender, accessible to your system's Python
+* Blender executable, accessible to pytest-blender on your system's Python
+  (e.g.  through the ``blender`` command in your path)
+
+.. code-block:: bash
+
+    pip install pytest-blender
+    # Check that "Blender" is in your system's path
+    blender
+
+On Windows, you can add Blender to the system path by doing:
+
+1. Open the start menu and launch **Control Panel** > **System** >  **Edit the
+   system environment variables**
+2. In the **System Properties** window, under the **Advanced** tab press
+   **Environment Variables**. This will open a dialog showing a list of all your
+   variables.
+3. In the **System Variables** section select the entry named **Path**, and
+   press **Edit...**. This will open a new dialog showing all the directories
+   stored in the **Path** variable.
+4. Press **New** and browse to the directory where your **blender.exe** is
+   located, such as in ``C:\Program Files\Blender Foundation\Blender 3.2``.
+
+In addition, you will need to install these dependencies for Blender:
+
+* pytest, accessible to your Blender Python
+* pytest-bdd, accessible to your Blender Python
+
+You can install the dependencies by running the ``setup_pytest.py`` script in
+Blender:
+
+1. Launch Blender
+2. Load ``src/bonsai/scripts/setup_pytest.py`` in the Blender text editor
+3. Run the script by pressing ``Text > Run Script``.
+4. Check the Blender console for any errors or success messages.
+
+.. warning::
+
+   The ``scripts/setup_pytest.py`` may not work for all operating systems and
+   installation environments. In this case, you may be required to install the
+   dependencies manually.
+
+   Please be aware that some Blender may come packaged with its own Python,
+   which may be separate to the Python installation on your system. Be sure to
+   install the dependencies to the correct Python environment.
+
+Then, run the tests. This will launch Blender headlessly and check the behaviour
+of all concrete functions.
+
+.. code-block:: bash
+
+    cd src/bonsai/
+    make test-tool # Test everything
+    make test-tool MODULE=foo # Only test a single module
+    # If you're on Windows, and don't want to use make, use:
+    pytest test/tool # Test everything
+    pytest test/tool/test_foo.py # Only test a single module
+
+UI tests
+--------
+
+The UI layer acts as a full integration test.
+
+Before running these tests, follow the instructions for running tool tests
+above.
+
+You will also need to enable the **Sun Position** add-on, as it is required to
+test georeferencing features: ``Edit > Preferences > Add-ons`` and install
+**Lighting: Sun Position**.
+
+.. code-block:: bash
+
+    cd src/bonsai/
+    make test-bim # Test everything
+    make test-bim MODULE=foo # Only test a single module
+    # If you're on Windows, and don't want to use make, use:
+    pytest test/bim # Test everything
+    pytest test/bim -m "foo" ./ --maxfail=1 # Only test a single module
+
+Code styling
+------------
+
+`Black <https://black.readthedocs.io/en/stable/index.html>`__ is used for code
+formatting. The settings for black are configured in the ``pyproject.toml`` at
+the project root. At the project root, just run:
+
+.. code-block:: bash
+
+    black .

src/bonsai/docs/guides/development/translations.rst

@@ -0,0 +1,76 @@
+Translations
+============
+
+Bonsai supports translations to all languages that Blender supports. We'll
+describe how you can help translate the add-on as a translator, or how you can
+ensure your strings are translatable as a developer.  Translations are managed
+using a separate add-on built for this purpose.
+
+1. Clone the `bonsai-translations
+   <https://github.com/IfcOpenShell/bonsai-translations>`_ repository. This
+   repository holds all the core translation strings in ``.po`` format.
+2. Download the `bonsai-translations add-on
+   <https://github.com/IfcOpenShell/IfcOpenShell/blob/v0.8.0/src/bonsai/scripts/bbim_translations.py>`_
+   and install it as a Blender add-on. This add-on lets you convert translation
+   data to and from the ``.po`` files for Bonsai.
+3. In the **Render Properties** tab, find the **Bonsai Translations**
+   panel, and browse to where you have closed the ``bonsai-translations``
+   repository, and click on **Setup Translation UI**.
+
+You should now see a new interface with two buttons.
+
+.. image:: images/translation-panel.png
+
+How to translate the add-on
+---------------------------
+
+Before beginning, look inside the ``bonsai-translations`` repository for a
+``.po`` file for the language you want to translate to (e.g. ``de_DE.po`` for
+German). If this file does not yet exist, congratulations! You are the first
+person to translate to this language! Create a folder in
+``bonsai-translations`` with your language code and copy the
+``bonsai.pot`` language template file to that folder and rename it
+according to your language (e.g. for German you would copy ``bonsai.pot`` to
+``de_DE/de_DE.po``).
+
+Supported language codes are:
+
+.. code-block::
+
+    'ca_AD', 'en_US', 'es', 'fr_FR', 'ja_JP', 'sk_SK', 'cs_CZ', 'de_DE',
+    'it_IT', 'ka', 'ko_KR', 'pt_BR', 'pt_PT', 'ru_RU', 'uk_UA', 'vi_VN',
+    'zh_HANS', 'zh_HANT', 'ab', 'ar_EG', 'bg_BG', 'el_GR', 'eo', 'eu_EU',
+    'fa_IR', 'fi_FI', 'ha', 'he_IL', 'hi_IN', 'hr_HR', 'hu_HU', 'id_ID',
+    'ky_KG', 'ne_NP', 'nl_NL', 'pl_PL', 'sr_RS', 'sr_RS@latin', 'sv_SE', 'sw',
+    'ta', 'th_TH', 'tr_TR'.
+
+As a translator, it is recommended to translate text in bulk by modifying the
+``.po`` files directly. We recommend installing software such as `Poedit
+<https://poedit.net/>`_. These translation software offer features such as auto
+translation, suggestions, and tracking. Alternatively, you may edit the ``.po``
+file as a text file.
+
+Once you have edited the relevant language's ``.po`` file, click on the
+**Update Translations From .po** button in the **Bonsai Translations**
+panel.
+
+How to add new translation strings
+----------------------------------
+
+When you have new strings to translate, press the **Parse Bonsai strings to
+.pot** button. This detects strings in the source code using regex patterns and
+writes out to the ``bonsai.pot`` language template file. You may then diff
+this file and propagate changes manually to all translated ``.po`` files.
+
+The ``.pot`` file is only used as a blank template for users to create or
+compare ``.po`` files. The ``.po`` files are the source of truth for
+translation strings. Blender does not read from the ``.pot`` or ``.po`` files.
+Instead, Blender reads from ``bonsai/translations.py`` which contains a
+dictionary of strings formatted specifically for Blender. The
+``translations.py`` file is generated from the ``.po`` files. This is generated
+when we distribute installable packages, or when translators manually press the
+**Update Translations From .po** button.
+
+.. warning::
+
+   Do not commit the ``translations.py`` file as it is auto-generated.

src/bonsai/docs/guides/development/undo_system.rst

@@ -0,0 +1,117 @@
+Undo system
+===========
+
+Supporting undo and redo is quite a complex problem because the Blender undo
+system only keeps track of changes occurring in the Blender system. However,
+changes actually occur in two other locations that Blender doesn't know about:
+the IFC dataset, and the Bonsai system that synchronises Blender and the IFC
+dataset.
+
+Let's see how undo works in a basic Blender add-on without IFC or Bonsai
+getting involved.
+
+.. code-block:: python
+    :emphasize-lines: 4
+
+    class Foobar(bpy.types.Operator):
+        bl_idname = "foobar"
+        bl_label = "Foobar"
+        bl_options = {"REGISTER", "UNDO"}
+
+        def execute(self, context):
+            context.scene.name = "Foobar"
+            return {"FINISHED"}
+
+This operation changes Blender data. The important line is ``bl_options =
+{"REGISTER", "UNDO"}``, which tells Blender to keep track of it as a single
+transaction in its undo history. When you press undo or redo, Blender figures
+out all the changes automatically and you don't need to do anything.
+
+If you have an operator that only manipulates (creates, removes, or edits)
+Blender data, this solution is sufficient.
+
+Now let's look at pure IfcOpenShell.
+
+.. code-block:: python
+    :emphasize-lines: 3,5
+
+    import ifcopenshell
+    model = ifcopenshell.open("foo.ifc")
+    model.begin_transaction()
+    model.create_entity("IfcWall")
+    model.end_transaction()
+    model.undo()
+    model.redo()
+
+Pure IfcOpenShell let's you start and stop recording transactions whenever you
+want. Since IfcOpenShell has no interface, you manually run code like
+``model.undo()`` and ``model.redo()`` to undo and redo.
+
+This scenario where there is pure IfcOpenShell never occurs with Bonsai.
+Instead, stuff happens in Blender operators.
+
+.. code-block:: python
+    :emphasize-lines: 6,7
+
+    class Foobar(bpy.types.Operator):
+        bl_idname = "foobar"
+        bl_label = "Foobar"
+        bl_options = {"REGISTER", "UNDO"}
+
+        def execute(self, context):
+            return IfcStore.execute_ifc_operator(self, context)
+
+        def _execute(self, context):
+            ifcopenshell.api.run("foo.bar", IfcStore.get_file())
+            return {"FINISHED"}
+
+When your operator manipulates (creates, removes, or edits) IFC data directly or
+indirectly (i.e. through calling another operator), your operator must be
+wrapped in an ``IfcStore.execute_ifc_operator`` call. This wrapper will:
+
+1. Begin a Bonsai transaction
+2. Begin an IfcOpenShell transaction
+3. Run your operator's ``_execute``.
+4. End the IfcOpenShell transaction
+5. End the Bonsai transaction
+
+The IfcOpenShell transaction keeps track of IFC data changes, and the Bonsai
+transaction keeps track of all other custom data changes, like changes in the
+``id_map`` and ``guid_map``. For the vast majority of operations, this wrapper
+provides everything that you need.
+
+If, however, your operator manipulates data that is not tracked by Blender, is
+not tracked in the IFC data, and is not tracked in the element map, then you
+will have to write your own rollback (undo) and commit (redo) code for your
+operator. Here is an example.
+
+.. code-block:: python
+
+    class Foobar(bpy.types.Operator):
+        bl_idname = "foobar"
+        bl_label = "Foobar"
+        bl_options = {"REGISTER", "UNDO"}
+
+        def execute(self, context):
+            IfcStore.begin_transaction(operator)
+            old_value = Foo.bar
+            result = self._execute(context)
+            new_value = Foo.bar
+            self.transaction_data = {"old_value": old_value, "new_value": new_value}
+            IfcStore.add_transaction_operation(self)
+            IfcStore.end_transaction(operator)
+            return result
+
+        def _execute(self, context):
+            Foo.bar = "baz"
+            return {"FINISHED"}
+
+        def rollback(self, data):
+            Foo.baz = data["old_value"]
+
+        def commit(self, data):
+            Foo.baz = data["new_value"]
+
+Note that there is still a distinction between ``execute`` and ``_execute``.
+This recommended convention allows you to quickly discern undo state tracking
+code from regular operation code.

src/bonsai/docs/guides/development/writing_docs.rst

@@ -0,0 +1,189 @@
+Writing documentation
+=====================
+
+A great way to contribute without writing code is to help writing
+documentation. Please reach out before contributing as the software is still in
+an alpha state and portions may not be worth documenting as it changes too
+frequently.
+
+Philosophy
+----------
+
+The documentation is split into three sections:
+
+1. **Quickstart**: a crash course where a user should be able to go from
+   nothing to doing the most basic, common tasks. It is not comprehensive, but
+   a highly focused tutorial style "taster" of what's available. It should be
+   kept very short, aiming to acquaint new users within an hour.
+2. **Guides**: a guidebook style, topic-driven series of articles discussing
+   things of interest, or tutorials that cover common workflows. This should
+   contain lots of images.
+3. **Reference**: a comprehensive index of the entire interface and all
+   available features.
+
+Documentation should not be a guide to IFC. Users should not have to know what
+IFC is.
+
+Official documentation should be polished and maintained. Less documentation of
+a higher quality that is kept updated with every release is preferred to more
+documentation with stubs, incomplete or inaccurate information.
+
+Syntax
+------
+
+All documentation is written in ReStructured Text and is available in the
+`Bonsai docs directory
+<https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/bonsai/docs>`_.
+You can press the edit button on the top right on any documentation page to
+quickly edit their content.
+
+Links
+^^^^^
+
+You can link to
+
+.. code-block:: restructuredtext
+
+  `external websites
+  <https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_
+
+(note the space between the url and the link text).  You can also link to
+sections on the same page, like
+
+.. code-block:: restructuredtext
+
+  :ref:`contribute/writing_docs:Writing technical documentation`
+  
+or with
+
+.. code-block:: restructuredtext
+
+  :ref:`custom text<contribute/writing_docs:writing technical documentation>`.
+  
+Traditional references like 
+  
+.. code-block:: restructuredtext
+ 
+  `Writing technical documentation`_
+
+work too but are discouraged. You can link to other pages, like this:
+
+.. code-block:: restructuredtext
+
+  :doc:`Hello World<hello_world>`
+
+or sections within other pages, like this:
+
+.. code-block:: restructuredtext
+
+  :ref:`devs/installation:unstable installation`
+
+We have ``autosectionlabel`` enabled so it is not necessary to manually create labels. The depth of sections
+with automatic labels is set to 2, so the third level of titles
+will not get automatic labels to avoid duplication.
+
+You can still create labels manually. This way you would ensure links still works when documentation is refactored.
+
+.. code-block:: restructuredtext
+
+    .. _My label:
+
+    My Section
+    ==========
+
+    :ref:`Link to My Section <My label>`
+
+This link will work across the documentation. Make sure the label is globally unique.
+
+Images
+^^^^^^
+
+The following colours and annotation styles should be used for annotating
+images. All stroke widths are 3px with a corner radius of 3px.  Horizontal
+underlines are 5px with a corner radius of 2px. The dark green is ``39b54a`` and
+the light green is ``d9e021``.
+
+.. image:: images/documentation-style.png
+
+Special keywords such as **Technical Terminology** that the user should be
+aware of should be bolded, titlecased, and used consistently. You *may*
+use italics to emphasize words or phrases. Inline code must be ``quoted`` and
+longer code snippets may use code blocks.
+
+.. code-block:: bash
+
+    cd /path/to/bonsai
+    ls
+
+Be sure to specify the language to enable syntax highlighting.
+
+.. code-block:: python
+
+   print("Hello, world!")
+
+A button may be used to point users to a critical sample file or
+download.
+
+.. container:: blockbutton
+
+    `Visit critical link <https://bonsaibim.org>`__
+
+You can use bulleted lists:
+
+- Like.
+- This.
+
+Or ordered lists:
+
+1. Like.
+2. This.
+
+.. note::
+
+   Instead of writing "Note that XYZ ..." you should use notes sparingly to
+   highlight "gotchas".
+
+.. tip::
+
+   Tips may be used to add a useful but optional suggestion.
+
+.. warning::
+
+   Warnings may be used to highlight common mistakes.
+
+.. seealso::
+
+    See also blocks should be used to reference `further reading
+    <https://bonsaibim.org>`__ links.
+
+Tables can be very annoying to format. You can use a CSV table instead.
+
+.. csv-table::
+   :header: "Foo", "Bar", "Baz"
+
+    "ABC", "01", "02"
+    "DEF", "03", "04"
+
+Building documentation
+----------------------
+
+If you want to build the documentation locally, the documentation system uses
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_. First, install the theme and
+theme dependencies:
+
+.. code-block:: bash
+
+    pip install furo
+    pip install sphinx-autoapi
+    pip install sphinx-copybutton
+
+Now you can generate the documentation:
+
+.. code-block:: bash
+
+    cd /path/to/ifcopenshell/src/bonsai/docs/
+    make html
+    cd _build/html
+    python -m http.server
+
+You will now have a local webserver running hosting the documentation.

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

@@ -0,0 +1,119 @@
+======================
+Drawings and documents
+======================
+
+Bonsai provides powerful tools for generating 2D drawings from your 3D BIM models and adding detailed annotations.
+This section covers the process of creating various types of drawings and enhancing them with annotations.
+
+Prerequisites
+=============
+
+Before starting with 2D drafting:
+
+1. Ensure you have completed the IFC modeling section or have a completed IFC model ready.
+2. Install and update to the latest compatible version of Bonsai as the Drafting module is still in early development.
+3. Install InkScape as the drafting is heavily based on SVG files.
+
+Generating 2D Drawings
+======================
+
+Creating a Floor Plan
+---------------------
+
+
+Creating Elevations and Sections
+--------------------------------
+
+The process for creating elevations and sections is similar:
+
+
+Annotations
+===========
+
+Using Annotation Tool
+---------------------
+
+
+Annotating Plan Layout
+------------------------
+
+1. Dimension key plan elements:
+   a. Wall lengths - both external and internal
+   b. Door/window openings
+   c. Room sizes
+2. Snap dimensions to wall edges/corners.
+3. Position dimensions.
+
+
+Line Work
+=========
+
+Annotations & Tags
+==================
+
+Text Labels
+-----------
+
+Leader Lines
+------------
+
+Room Labels
+-----------
+
+Door/Window Tags
+----------------
+
+Sanitary Symbols
+================
+
+Loading Symbol Types
+--------------------
+
+
+Placing Sanitaryware
+--------------------
+
+Doors and Windows 2D outline
+----------------------------
+
+
+IFC Grids
+=========
+
+Adding Grid Lines
+-----------------
+
+
+Positioning Grids
+-----------------
+
+Displaying Grids in Drawings
+----------------------------
+
+Materials/Hatching
+==================
+
+Naming Material Layers
+----------------------
+
+Automatic Hatch Patterns
+------------------------
+
+Custom Materials
+----------------
+
+Legend
+------
+
+Next Steps
+==========
+
+After mastering these basics, you may want to explore:
+
+- Generating elevations and sections
+- Creating detail drawings
+- Setting up custom hatch patterns and line styles
+- Advanced annotation techniques
+
+Remember, effective drawings are key to communicating your design intent.
+Take time to explore the various options and develop a consistent style for your project documentation.

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

@@ -0,0 +1,4 @@
+Facility management
+===================
+
+TODO

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

@@ -0,0 +1,4 @@
+Services and systems
+====================
+
+TODO

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

@@ -0,0 +1,33 @@
+Structural analysis
+===================
+
+This section covers the structural analysis capabilities in Bonsai.
+
+.. note::
+   This page is a stub. More detailed content will be added in future updates.
+
+Overview
+--------
+
+Bonsai provides tools for structural analysis within the BIM environment.
+This integration allows for seamless workflow between architectural and structural engineering disciplines.
+
+Key Features
+------------
+
+- Structural element definition
+- Load case creation and management
+- Integration with external analysis software
+
+Getting Started
+---------------
+
+To begin using the structural analysis features in Bonsai:
+
+1. Ensure your model contains properly defined structural elements
+2. Access the Structural Analysis panel in the Bonsai interface
+3. Define load cases and boundary conditions
+
+.. seealso::
+   - :doc:`/users/modeling/ifc_modeling`
+   - :doc:`/users/advanced/index`

src/bonsai/docs/guides/troubleshooting.rst

@@ -0,0 +1,169 @@
+Troubleshooting
+===============
+
+Bonsai is alpha software. There are many bugs! When something goes wrong, you
+may see some computer code flash up on your screen. You may also see an error
+message:
+
+.. image:: images/error-message.png
+
+**Don't panic!** Click on the button that says **Copy Error Message To
+Clipboard**. You will need to paste this text in a bug report.
+
+If you do not have a GitHub account, you will need to sign up to report a bug.
+In addition to pasting the error message text, please also describe what you
+were doing, and attach your IFC file or screenshots if relevant.
+
+.. container:: blockbutton
+
+    `Report a bug <https://github.com/IfcOpenShell/IfcOpenShell/issues/new>`__
+
+If your issue is particularly complex, you can also chat live with developers
+or other powerusers.
+
+.. container:: blockbutton
+
+    `Chat live with a developer <https://osarch.org/chat>`_
+
+Updating
+--------
+
+We always recommend to use the latest version.
+
+Open up Blender, click on ``Edit > Preferences``, and select the **Get
+Extensions** tab. If an update is available, you will see a button next to the
+**Bonsai** add-on.
+
+Updates are typically available every 2 months. If you need something more
+frequent, check out :ref:`devs/installation:unstable installation` which is
+updated every day.
+
+.. image:: images/update.png
+
+Installation issues
+-------------------
+
+If you are unable to install Bonsai, make sure you are using **Blender 4.2**
+installed from https://blender.org/.
+
+Other common solutions are listed below. If none of these fix the problem, you
+can `report a bug <https://github.com/ifcopenshell/ifcopenshell/issues>`_ or
+`live chat with a developer <https://osarch.org/chat/>`_.
+
+1. **Some other error prevents me from installing or doing basic functions with
+   the add-on. Is it specific to my environment?**
+
+   Try installing and using Bonsai on a "clean environment". A clean
+   environment is a fresh Blender installation with no other add-ons enabled
+   with factory settings.
+
+   To quickly test in a clean environment, first :ref:`find your Blender
+   configuration folder<users/troubleshooting:Where is the add-on
+   installed?>`.  Rename the folder from ``X.XX`` to something else like
+   ``X.XX_backup``, then restart Blender and try follow the :doc:`installation
+   instructions</users/quickstart/installation>` again.
+
+   If this fixes your issue, consider disabling other add-ons one by one until
+   you find a conflict as a next step to isolating the issue.
+
+2. **I am on Ubuntu and get an error similar to "ImportError:
+   /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"**
+
+   Our latest package which uses IfcOpenShell v0.8.0 is built using Ubuntu 20 LTS.
+   If you have an older Ubuntu version, you can either upgrade to 19.10 or above,
+   or you'll need to compile IfcOpenShell yourself.
+
+3. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**"
+
+   If you have installed Blender from another source instead of from
+   `Blender.org <https://www.blender.org/download/>`__, such as from your
+   distro's package repositories, then you may be missing some modules like
+   ``numpy``. Try installing it manually like ``apt install python-numpy``.
+
+Saving and loading blend files
+------------------------------
+
+Bonsai transforms Blender into a native IFC authoring platform.  This means
+that you can open and save IFC files directly without using Blender's
+``.blend`` format.
+
+All data about your model is saved in your IFC. No data is stored in the
+``.blend`` format. This means that if you save or open a ``.blend`` file, you
+are **not** saving and loading your model. At best, you are saving and loading
+Blender geometry that represents what the model might've looked at at some
+point. At worst, you might be looking at a completely wrong model.
+
+If you continue to open and save ``.blend`` files, you will run the risk of
+editing something that doesn't actually exist in your IFC model. This will
+create unpredictable, and sometimes unrecoverable errors.
+
+To avoid this issue, only open and save IFCs.
+
+Where is the add-on installed?
+------------------------------
+
+Upon installation, Bonsai is stored in Blender configuration folder. However,
+the location of your Blender configuration folder depends on how you have
+installed Blender.
+
+If you downloaded Blender as a ``.zip`` file without running an installer,
+Bonsai will be installed in the following directory, where ``X.XX`` is the
+Blender version:
+
+::
+
+    /path/to/blender/X.XX/
+
+Otherwise, if you installed Blender using an installation package, the Blender
+configuration folder depends on which operating system you use.
+
+On Linux, if you are installing the add-on as a user:
+
+::
+
+    ~/.config/blender/X.XX/
+
+On Linux, if you are deploying the add-on system-wide (this may also depend on
+your Linux distribution):
+
+::
+
+    /usr/share/blender/X.XX/
+
+On Mac, if you are installing the add-on as a user:
+
+::
+
+    /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/
+
+On Mac, if you are deploying the add-on system-wide:
+
+::
+
+    /Library/Application Support/Blender/X.XX/
+
+On Windows:
+
+::
+
+    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\
+
+Inside the Blender configuration folder, Bonsai is stored in two different
+locations. The extension itself is stored in
+``extensions/blender_org/bonsai`` whereas the Python packages are installed
+into ``extensions/.local/lib/pythonX.XX/site-packages/``.
+
+Uninstalling
+------------
+
+Open up Blender, click on ``Edit > Preferences``, and select the **Get
+Extensions** tab. In the dropdown menu to the right of the **Bonsai** add-on,
+click on **Uninstall**.
+
+.. image:: images/uninstall.png
+
+Alternatively, you may start from a fresh setup by renaming or deleting the
+Blender version folder, found in the add-on path. In the screenshot above, this
+is ``/home/dion/.config/blender/4.2``.
+
+

src/bonsai/docs/guides/viewing/dealing_with_large_models.rst

@@ -0,0 +1,190 @@
+Dealing with large models
+=========================
+
+Bonsai can handle large models, or federated collections of models where the
+combined total IFCs may be many gigabytes or object counts may be in the
+hundreds of thousands.
+
+Models may be large in terms of different metrics, such as:
+
+- Filesizes over 750MB, which may cause memory issues
+- Individual object polygon counts over 100k, which may cause unreasonable
+  loading times
+- Objects having excessive or low quality booleans, which may cause
+  unreasonable loading times
+- Number of elements exceeding 50,000 loaded in the scene, which may cause
+  unreasonable loading times, selection glitches, and viewport lagging
+
+There are always solutions to all of these, but an understanding of the type of
+size limitation you are up against will always help.
+
+Large filesizes
+---------------
+
+The first priority is to ensure you do not have a prohibitively large filesize.
+
+- Use IFC4. It can handle geometry much more efficiently and expect your
+  filesize to drop significantly.
+- When coming from other software, ensure you are exporting solids, not faceted
+  BReps or tessellations where appropriate. Choosing the wrong export setting
+  can easily double or triple your filesize and export times. Choose **Design
+  Transfer View** instead of **Coordination View** or **Reference View**. Look
+  for export settings that use the keywords like "surface", "solid", "brep",
+  "tessellation", or "extrusion".
+- Improve your model breakdown strategy (see below)
+- Identify objects with large polygon counts and improve the modeling (see below)
+
+Model breakdown strategies
+--------------------------
+
+A good general strategy is to never have a large model to begin with. Breaking
+down models is critical for usability during design and coordination. Where full
+models are needed, such as during clash detection, review meetings, or client
+handover, many small models may be federated. Model breakdown strategies
+include:
+
+- **By discipline**, you probably already do this, so let's move on
+- **By location**, such as by building, floor, zone, mid-rise, high-rise, core
+  podium, underground, plant rooms, facade orientation, or similar.
+- **By object type**, such as by primary structural elements vs accessories
+  (plates, bolts, etc), furniture vs general arrangement, facade vs interiors,
+  distribution system elements (equipment, pipes, fittings) vs accessories (pipe
+  clamps, hangers, etc) or similar.
+- **By coordination task**, many people get into the habit of exchanging the
+  entire building when a task only requires a tiny portion of it. Think of the
+  workflow of exchanging traditional drawings. A large project would have
+  thousands of drawings with a few drawings exchanged for a single coordination
+  task. This strategy can be used with models: exchange hundreds of tiny models
+  (some maybe even only 1MB!), scoped to the task at hand. Keep exchanges small
+  and frequent (like code commits, for the geeks reading this).
+
+Filtered model loading
+----------------------
+
+You may filter elements and only load a portion of the model. Click on 
+:ref:`Enable Advanced Mode <Project Info Advanced Loading Mode>` checkbox when loading a model.
+
+
+.. image:: images/advanced-mode.png
+
+This will preload the model and present you with model loading options in the
+:doc:`Project Info </users/user_interface/property_editor/scene_editor/project_overview/project_info>`
+panel.
+
+.. image:: images/advanced-mode-settings.png
+
+**Filter Modes** include:
+
+- **Decomposition**, filter by location in the building, such as **Level 1** or
+  **Building A**.
+- **IFC Class**, filter by IFC class, such as **Wall**, **Column**, or **Pipe
+  Segments**
+- **IFC Type**, filter by IFC construction type, such as **Copper pipes** and
+  **200mm thick concrete slabs**
+- **Whitelist** or **Blacklist**, filter by a custom query
+
+When **Whitelist** or **Blacklist** is chosen, you may type a custom query to
+filter by attributes, properties, location, and so on.
+
+Large polygon counts
+--------------------
+
+If objects with large polygon counts are blocking you from importing, consider
+enabling **Native Meshes** in the :ref:`Advanced Loading Mode <Project Info Advanced Loading Mode>` when loading projects.
+
+The **Debug Panel** allows you to **Select High Polygon Meshes** or **Select
+Highest Polygon Meshes** to isolate geometrically complex objects by a polygon
+number threshold or a percentage.
+
+After selecting these elements, you can view them in edit mode to see a polygon
+count and where the offending polygons are. Often, fixing a single object may
+cut out 50MB.
+
+Excessive or low quality booleans
+---------------------------------
+
+In some cases, elements may be generated from external software with an
+excessive (over 50) number of boolean operations or with high polygon, complex
+booleans.
+
+The **IFC Debug** panel has a **Test All Shapes** feature which generates
+geometry for every element one by one and outputs the processing time to the
+console. When you see it stuck on an element, make a note of the element ID. You
+may then use the **IFC Debug** panel's **Inspector** to determine the nature of
+the boolean, or create a **Blacklist Filter Mode** to exclude the element from
+import.
+
+These types of errors are usually problems with external software (i.e. not
+intentionally by the end-user) and typically do not affect critical geometry
+and can be worked around.
+
+Fully resolving boolean issues is a complex case by case topic and not covered
+here.
+
+High number of elements
+-----------------------
+
+Click on :ref:`Enable Advanced Mode <Project Info Advanced Loading Mode>`  when loading a model and you will be presented
+with model loading options in the **Project Info** panel.
+
+You may specify an **Element Range** to process. The **Element Offset** says the
+first element to start processing at, and the **Element Limit** says how many
+elements should be processed. For example, in a model with 100,000 objects, an
+**Element Start** of 30,000 and an **Element Limit** of 20,000 will process the
+elements starting at item number 30,000 and ending at item number 50,000. This
+allows you to arbitrarily break down large models into submodels. This can be
+combined with other filters.
+
+Using Blender 3.3 and above will result in a faster load time (~50%) compared to
+older Blender versions.
+
+Coordination only models
+------------------------
+
+Bonsai defaults to authoring IFCs. This allows full editing and inspection of
+all element properties and relationships. However, sometimes only geometry and
+basic attributes such as names are sufficient. Example usecases include CG
+visualisation, overall federated model coordination, or pure geometric checks.
+
+Click on :ref:`Enable Advanced Mode <Project Info Advanced Loading Mode>` checkbox when loading a model and you will be presented
+with model loading options in the **Project Info** panel. Enable **For
+Coordination Only**, which will exclude non geometric elements, openings, and
+types from being imported. This leads to slightly faster imports, and a
+decreased object count.
+
+Enabling **For Coordination Only** also allows you to specify a **Merge Mode**.
+This combines objects to keep object counts low. Blender is very good at
+handling less objects with more complexity, rather than the other way around.
+When a **Merge Mode** is activated, import times will increase (~50%) but object
+counts will be drastically reduced, which is critical for the federation of
+large models. **Merge Modes** include:
+
+- **IFC Class**, where objects of the same IFC class are merged. This is useful
+  if you have models where only the class is meaningful for other disciplines,
+  such as structural models.
+- **IFC Type**, where objects of the same construction type are merged. This is
+  useful where the main identification of interest is the element type, not the
+  element instance.
+- **Material**, where objects of the same material are merged. This is useful if
+  the model is used for purely visual exploration such as CG visualisation.
+
+Once loaded, the model may be saved as a ``.blend`` file for subsequent loads.
+You can think of the ``.blend`` file as a geometry cache, which is very, very
+fast to load. If it no longer necessary to access IFC data, consider pressing
+the **Unload Project** icon so that future loads of the ``.blend`` file will be
+very fast.
+
+With these strategies, a federated 1GB IFC model can easily load in 10 seconds
+from the saved Blender files.
+
+Processing models headlessly
+----------------------------
+
+You can automate model processing using this command (~5% speedup):
+
+.. code-block:: bash
+
+    blender -b -P headless_import.py
+
+The ``headless_import.py`` script contains instructions on how to configure
+model loading settings.

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

@@ -0,0 +1,12 @@
+Viewing models
+==============
+
+This chapter covers how to navigate and explore models.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :maxdepth: 2
+
+      dealing_with_large_models