Updated Joints, Assembly and Utils

docs/tutorials/grasshopper/assembly.rst

@@ -2,18 +2,39 @@
 Assembly
 ********
 
-**Assembly** component creates a frame structure made of joined :code:`Beam` objects. 
-It connects the beams and adds features based on provided `Joints` (:doc:`joints`) and `Features` (:doc:`features`) definitions.
+**Assembly** component creates a structure composed of joined :code:`Beam` objects. It connects the beams with joints and adds
+features based on the :doc:`joints` and :doc:`features` inputs provided.
 
-Geometric operations like cutting, trimming and solid boolean subtractions, which are implied by joints and features, 
-may be computationally expensive, and are disabled by default. 
-To activate it, set `applyFeatures` to :code:`True`. 
-Output parameter `Errors` provides a log of unsuccessful feature-apply operations.
+Geometric operations like cutting, trimming and solid boolean subtractions, which are implied by joints and features,
+may be computationally expensive, and are disabled by default.
+To activate it, set `CreateGeometry` to :code:`True`.
 
+.. image:: ../images/gh_assembly.png
+    :width: 20%
 
-Assembly as such is an abstract object. To visualize it (to visualize the beams in the assembly), 
-use the :code:`ShowAssembly` component that returns the *Brep* geometry of the beams.
 
-.. image:: ../images/assembly_01.png
-    :width: 50%
+Inputs:
+
+*	`Beams` : collection of beams.
+*	`JointsRules` : collection of joint rules.
+*	`Features` : collection of features definitions.
+*	`MaxDist` : Max Distance Tolerance for topology detection.
+*	`CreateGeometry` : If True, Beam and joint geometry is created for visualisation. Default is False.
+
+Outputs
+
+*	`Assembly` : Assembly object.
+*	`Geometry` : Geometry of the beams and joints.
+*   `DebugInfo` : Debug information object in the case of feature or joining errors.
+
+|
+
+.. note::
+
+    **Visualisation**
+
+    Assembly as such is an abstract object. To visualise the beams in the assembly, the :code:`ShowAssembly` component returns a *Brep* geometry of the beams. See :doc:`show` for the visualisation  of other helpful
+    information such as *Joint Type* or *Beam Index*, spatially located.
+
+    For debugging, the :code:`ShowFeatureErrors` component or :code:`ShowJoiningErrors` component visualise the errors that occur during the assembly process. See :doc:`show`.
 

docs/tutorials/grasshopper/beam.rst

@@ -10,8 +10,8 @@ The *origin* is located at the start of the centerline.
 .. image:: ../images/beam_01png.png
     :width: 40%
 |
-Beams are created with the components **Beam** - to create a beam from a Grasshopper `Line` or `LineCurve`, or from a `Guid` of a `Line` object referenced from an active Rhino document.
-The latter is intended for a design workflow, where the input geometry (centerlines etc.) is drawn or stored in a Rhino document instead of Grasshopper.
+Beams are created with the component :code:`Beam` - to create a beam from a Grasshopper `Line` or `LineCurve`, or from a `Guid` of a `Line` object referenced from an active Rhino document.
+The latter is intended for a design workflow, where the input geometry (centerlines, etc.) is drawn or stored in a Rhino document instead of generated within the Grasshopper environment.
 
 Inputs:
 

docs/tutorials/grasshopper/joints.rst

@@ -2,7 +2,7 @@
 Joints
 ******
 
-In COMPAS Timber The joints between the beams are defined according to their topology and a joint type is then applied.
+In COMPAS Timber the joints between the beams are defined according to their topology and a joint type is then applied.
 
 Joint Topologies
 ----------------
@@ -20,52 +20,25 @@ There are three main topologies of how beams can connect to each other: **L**, *
 Joint Types
 ----------------
 
-Joints for *L* topologies
+Joints for *L* Topologies
 ^^^^^^
 
 For a *L* topology, several types of joint can be applied. Four of these are implemented in the current version of the COMPAS Timber: *French Ridge Lap*, *L-Butt*, *L-Half Lap* and *L-Miter*.
 
 |
 
-**French Ridge Lap** joint (*not fully implemented*)
-
-.. image:: ../images/Joints_FrenchRidgeExploded_Header.png
-    :width: 80%
-
-A French ridge lap joint extends two beams and removes the upper half of the overlap on one beam and the lower half on the other.
-Unlike the :doc:`L-Half Lap` joint, where the cut is made parallel in the centre of the beams, the cut of the French ridge lap joint is angled to keep the beams securely in place, preventing them from shifting.
-
-The tilted cut plane is generated as follow:
-
-* the inner vertical edges of the overlap is split in the middle, generating a point;
-* the vertical edge of the overlap along the lower beam is split at the bottom third, generating a point;
-* the outer vertical edges of the overlap is split in the middle, generating a point;
-* the vertical edge of the overlap on the lower beam is split at the top third, generating a point.
-
-By connecting sequentially these points, the tilted cut plane is generated.
-
-
-
-.. image:: ../images/Joints_FrenchRidge_Component.png
-    :width: 80%
-
-:code:`French Ridge Lap Options` component
-
-
-
-Inputs:
 
-* `Cutoff` : For very acute angles, limit the extension of the tip/beak of the joint.
-
-|
 
 
 **L-Butt** joint
 
-A L-Butt extends one beam and shortens the other beam with a planar cut, to create a clean corner joint.
+The L-Butt extends one beam and shortens the other beam with a planar cut, to create a clean corner joint.
+
+.. image:: ../images/gh_Joint_L-Butt.png
+    :width: 20%
 
-.. image:: ../images/Joints_L-Butt.png
-    :width: 80%
+.. image:: ../images/Joint_L-Butt.png
+    :width: 100%
 
 :code:`L-Butt Options` component
 
@@ -80,51 +53,85 @@ Inputs:
 
 **L-Half Lap** joint
 
-A *L-Half Lap* topology is when two beams meet at their ends at an angle.
+The *L-Half Lap* topology is when two beams meet at their ends at an angle.
 An L-Half Lap joint extends the two beams while removing the upper half of the overlap of one beam and the lower half of the overlaps the other to create a clean corner joint.
 
-.. image:: ../images/Joints_L-HalfLap.png
-    :width: 80%
+.. image:: ../images/gh_Joint_L-HalfLap.png
+    :width: 20%
+
+.. image:: ../images/Joint_L-HalfLap.png
+    :width: 100%
 
 :code:`L-Half Lap Options` component
 
 Inputs:
 
-* `FlipLapSide` : flip the side of the lap joint
-* `CutPlaneBias` : determines the depth of lap cuts on the beams
+* `FlipLapSide` : Flips the lap side.
+* `CutPlaneBias` : Determines the depth of lap cuts on the beams.
 
 |
 
 
 **L-Miter** joint
 
-A L-Miter joint extends and connects the two beams with a planar cut at a bisector of the angle between them.
+The L-Miter joint extends and connects the two beams with a planar cut at a bisector of the angle between them.
+
+.. image:: ../images/gh_Joint_L-Miter.png
+    :width: 20%
 
-.. image:: ../images/Joints_L-Miter.png
-    :width: 80%
+.. image:: ../images/Joint_L-Miter.png
+    :width: 100%
 
 :code:`L-Miter joint Options` component
 
+|
+
+**French Ridge Lap** joint (*not fully implemented*)
+
+The French ridge lap joint extends two beams and removes the upper half of the overlap on one beam and the lower half on the other.
+Unlike the L-Half Lap (presented above) joint, where the cut is made parallel in the centre of the beams, the cut of the French ridge lap joint is angled to keep the beams securely in place, preventing them from shifting.
+
+The tilted cut plane is generated by sequentially connecting the following points:
+
+* a point at the middle of the inner vertical edges of the overlap;
+* a point at the bottom third of the outer vertical edge of the overlap along the lower beam;
+* a point at the middle of the outer vertical edge of the overlap;
+* a point at the top third of the outer vertical edge of the overlap along the upper beam.
+
+
+.. image:: ../images/gh_Joint_L-FrenchRidge.png
+    :width: 20%
+
+.. image:: ../images/Joint_L-FrenchRidge.png
+    :width: 100%
+
+:code:`French Ridge Lap Options` component
+
+|
+
 Inputs:
 
 * `Cutoff` : For very acute angles, limit the extension of the tip/beak of the joint.
 
 
-Joints for *T* topologies
+Joints for *T* Topologies
 ^^^^^^
 
-A *T* topology is when one beam connects with one of its ends along the length of the other beam.
+The *T* topology is when one beam connects with one of its ends along the length of the other beam.
 For a *T* topology, several types of joint can be applied. Two of these are implemented in the current version of the COMPAS Timber: *T-Butt* and *T-Half Lap*.
 
 |
 
 **T-Butt** joint
 
 
-A T-Butt joint shortens the *cross beam* with a planar cut, to match the side of the *main beam*. The *main beam* remains unchanged.
+The T-Butt joint shortens the *cross beam* with a planar cut, to match the side of the *main beam*. The *main beam* remains unchanged.
+
+.. image:: ../images/gh_Joint_T-Butt.png
+    :width: 20%
 
-.. image:: ../images/TButt_diagramm.png
-    :width: 50%
+.. image:: ../images/Joint_T-Butt.png
+    :width: 100%
 
 :code:`T-Butt Options` component
 
@@ -136,90 +143,98 @@ Inputs:
 
 **T-Half Lap** joint
 
+A T-Half Lap joint crates an overlap between the *main beam* and the *cross beam*. The *cross beam* is extended to the opposite face of the *main beam* and cut flush with it to create a planar surface.
+It is similar to a L-Half Lap joint: the upper half of the overlap of the cross beam is removed from the main beam and the lower half of the overlap of the main beam is removed from the cross beam.
 
-A T-Half Lap joint crates an overlap between the *main beam* and the *cross beam*. The *cross beam* is extended to the opposite face of the *main beam* and cut flush with it and similar to a :doc:``L-Half Lap`` joint, the upper half
-of the overlap of the cross beam is removed from the main beam and the lower half of the overlap of the main beam is removed from the cross beam.
+.. image:: ../images/gh_Joint_T-HalfLap.png
+    :width: 20%
 
-.. image:: ../images/TButt_diagramm.png
-    :width: 50%
+.. image:: ../images/Joint_T-HalfLap.png
+    :width: 100%
 
 :code:`T-Half Lap` component
 
 Inputs:
 
-* `FlipLapSide` : flip the side of the lap joint.
-* `CutPlaneBias` : determines the depth of lap cuts on the beams.
+* `FlipLapSide` : Flips the lap side.
+* `CutPlaneBias` : Determines the depth of lap cuts on the beams.
 
 |
 
 
-Joints for *X* topologies
+Joints for *X* Topologies
 ^^^^^^^
 
-A *X* topology is when two beams cross each other along their length.
+The *X* topology is when two beams cross each other along their length.
 For a *X* topology, several types of joint can be applied. One of these are implemented in the current version of the COMPAS Timber: *T-Butt* and *T-Half Lap*.
 
 |
 
 **X-Half Lap** joint
 
 
-A X-Half Lap joint shortens the *cross beam* with a planar cut, to match the side of the *main beam*. The *main beam* remains unchanged.
+The X-Half Lap joint removes the upper half of the overlap from one beam and the lower half from the other.
 
-.. image:: ../images/TButt_diagramm.png
-    :width: 50%
+.. image:: ../images/gh_Joint_X-HalfLap.png
+    :width: 20%
 
-:code:`T-Butt Options` component
+.. image:: ../images/Joint_X-HalfLap.png
+    :width: 100%
+
+:code:`X-HalfLap Options` component
 
 Inputs:
 
-* `Gap` : Gap for tolerance between the beams, i.e., if the distance between the beams is less than the gap, the joint will be applied.
+* `FlipLapSide` : Flips the lap side.
+* `CutPlaneBias` : Determines the depth of lap cuts on the beams.
 
 |
 
 
-.. image:: ../images/LMiter_diagramm.png
-    :width: 50%
+**Null Joint** joint
+
+
+The Null joint is used to define the joint between two beams when....
+
+.. image:: ../images/gh_Joint_NullJoints.png
+    :width: 20%
+
+:code:`Null Joint` component
 
 |
 
-.. list-table:: matching joint topologies and joint types
-   :widths: 5 10 10 10
+Summary Table
+----------------
+
+The following table summarises the joint types that can be applied to the different joint topologies.
+
+
+.. list-table:: Joint Topologies and Joint Types
+   :widths: 20 10 10 10
    :header-rows: 1
    :stub-columns: 1
 
    * -
      - L Topology
      - T Topology
      - X Topology
-   * - L Butt
+   * - Butt Joints
      - x
-     -
-     -
-   * - L-Miter
      - x
      -
-     -
-   * - L-HalfLap
+   * - Miter Joints
      - x
      -
      -
-   * - French Ridge Lap
+   * - Half Lap Joints
      - x
-     -
-     -
-   * - T-Butt
-     -
      - x
-     -
-   * - T-Half Lap
-     -
      - x
-     -
-   * - X-HalfLap
+   * - French Ridge Lap joints
+     - x
      -
      -
-     - x
+
 
 |
 

docs/tutorials/grasshopper/rules.rst

@@ -7,15 +7,15 @@ Joint Rules
 |
 The joints between beams are defined by rules. There are three different levels of rules, where each of them overrides any lower-priority rule. The rules are listed hereafter from lowest to highest level of priority:
 
-1. **Topological Joint Rules** - the lowest-priority-level rule, applied on the entire assembly. It automatically recognises the joint topology (L, T or X) between each beam and applies joint type the corresponding the joint topology. See also :doc:`joints`
+1. **Topological Joint Rules** - the lowest-priority-level rule, applied on the entire assembly. It automatically recognises the joint topology (L, T or X) between each beam and applies joint type corresponding to the joint topology. See also :doc:`joints`
 
    Inputs:
 
    * `L` - joint type to be applied to L topology. Default type is L-Miter.
    * `T` - joint type to be applied to T topology. Default type is T-Butt.
    * `X` - joint type to be applied to X topology. Default type is X-HalfLap.
 |
-2. **Category Joint Rules** - the second level, defines a single joint type for a specific topology between two categories of beams. The categories are assigned through the string-input `Category` in the component :code:`Beam` and added to the rhino lines.
+1. **Category Joint Rules** - the second level, defines a single joint type for a specific topology between two categories of beams. The categories are assigned through the string-input `Category` in the component :code:`Beam` and added to the rhino lines.
 
    Inputs: