diffCheckOrg · 9and3 · Oct 4, 2024 · Sep 30, 2024 · Sep 30, 2024 · Sep 30, 2024
diff --git a/doc/_static/example_files/subtractive_gh_v1.gh b/doc/_static/example_files/subtractive_gh_v1.gh
diff --git a/doc/_static/example_files/subtractive_rh_v1.3dm b/doc/_static/example_files/subtractive_rh_v1.3dm
diff --git a/doc/_static/example_files/subtractive_rh_v1.3dmbak b/doc/_static/example_files/subtractive_rh_v1.3dmbak
diff --git a/doc/_static/gh_components/img_overview_dfareas.png b/doc/_static/gh_components/img_overview_dfareas.png
diff --git a/doc/_static/tutorials/fig_subtractive_detail_viz.png b/doc/_static/tutorials/fig_subtractive_detail_viz.png
diff --git a/doc/_static/tutorials/fig_subtractive_graph_viz.png b/doc/_static/tutorials/fig_subtractive_graph_viz.png
diff --git a/doc/_static/tutorials/fig_subtractive_high_res_overview.png b/doc/_static/tutorials/fig_subtractive_high_res_overview.png
diff --git a/doc/_static/tutorials/fig_subtractive_log.png b/doc/_static/tutorials/fig_subtractive_log.png
diff --git a/doc/_static/tutorials/fig_subtractive_square.png b/doc/_static/tutorials/fig_subtractive_square.png
diff --git a/doc/_static/tutorials/fig_subtractive_start.png b/doc/_static/tutorials/fig_subtractive_start.png
diff --git a/doc/_static/tutorials/fig_subtrative_high_res_2.png b/doc/_static/tutorials/fig_subtrative_high_res_2.png
diff --git a/doc/_static/tutorials/fig_subtrative_high_res_3.png b/doc/_static/tutorials/fig_subtrative_high_res_3.png
diff --git a/doc/_static/tutorials/fig_subtrative_high_res_4.png b/doc/_static/tutorials/fig_subtrative_high_res_4.png
diff --git a/doc/_static/tutorials/fig_subtrative_high_res_5.png b/doc/_static/tutorials/fig_subtrative_high_res_5.png
diff --git a/doc/_static/tutorials/fig_subtrative_high_res_6.png b/doc/_static/tutorials/fig_subtrative_high_res_6.png
diff --git a/doc/_static/tutorials/fig_subtrative_high_res_7.png b/doc/_static/tutorials/fig_subtrative_high_res_7.png
diff --git a/doc/segmentation_intro.md → doc/assembly-evaluation.md b/doc/segmentation_intro.md → doc/assembly-evaluation.md
@@ -1,4 +1,4 @@
-(segmentation_intro)=
-# Segmentation
+(assemblyeval)=
+# Assembly evaluation
 
 /// explain with simple example how to use the segmentation components of diffCheck and why we need them. It can be slit in two parts: single element - full structure
diff --git a/doc/assembly_intro.md b/doc/assembly_intro.md
diff --git a/doc/compute_error_intro.md b/doc/compute_error_intro.md
diff --git a/doc/image.png b/doc/image.png
diff --git a/doc/index.rst b/doc/index.rst
@@ -154,7 +154,6 @@ The software is developed by the `Laboratory of Timber Construction (IBOIS)`_ an
     :maxdepth: 2
     :caption: Getting Started
 
-    installation
     quickstart
     tutorials
 

diff --git a/doc/installation.md b/doc/installation.md
diff --git a/doc/joints-evaluation.md b/doc/joints-evaluation.md
@@ -0,0 +1,168 @@
+(jointeval)=
+# Joints evaluation
+
+## Objective
+
+The following tutorial will guide you through the evaluation of joints in timber construction with DF. As a studycase we fabricated 3 beams presenting the same joints with:
+
+- a chainsaw, by hand
+- a circular saw, by hand
+- a CNC Maka machine
+
+the goal being to evaluate the quality of the joints and the accuracy of the fabrication processes. In DF the evaluation of the joint is dual:
+
+- i) the *evaluation of the joint itself*: by comparing the CAD model of the joint with the scan of the joint informs us about the quality of the positioning of the joints on the beam.
+- ii) the *evaluation of the joint's faces*: by comparing the CAD model of the joint's faces with the scan of the joint informs us about the quality of the fabrication of the joint itself.
+
+In the following we will see how to quantify and obtain data for these two metrics.
+
+<br>
+
+```{eval-rst}
+.. raw:: html
+
+    <a href="./_static/example_files/subtractive_gh_v1.gh" download style="display: inline-block; padding: 10px 20px; font-size: 16px; color: white; background-color: #28a745; text-align: center; text-decoration: none; border-radius: 5px;">
+        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" class="bi bi-arrow-down-circle" viewBox="0 0 16 16">
+        <path fill-rule="evenodd" d="M1 8a7 7 0 1 0 14 0A7 7 0 0 0 1 8m15 0A8 8 0 1 1 0 8a8 8 0 0 1 16 0M8.5 4.5a.5.5 0 0 0-1 0v5.793L5.354 8.146a.5.5 0 1 0-.708.708l3 3a.5.5 0 0 0 .708 0l3-3a.5.5 0 0 0-.708-.708L8.5 10.293z"/>
+        </svg>
+        Download .gh file
+    </a>
+```
+
+
+---
+
+## Steps
+
+### 1. Input the data
+First things first, let's import your cleaned scan and corresponding polysurface model in Rhino.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtractive_start.png" width="600">
+</p>
+
+### 2. Build the DFAssembly
+Here we convert the model of our structure into the internal datatype of diffcheck, DFAssembly. This component detects the joints and their faces.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtrative_high_res_2.png" width="500">
+</p>
+
+```{hint}
+If you are evaluating round sections e.g. logs, you can set the `i_is_roundwood` input to `True` in the `DFBuildAssembly` component. This will allow DF to detect automatically the joints on the roundwood.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtractive_log.png" width="600">
+</p>
+```
+
+> DF's components:
+> * [`DFAssebmly`](gh_DFBuildAssembly)
+
+### 3. Registration of CAD and scan
+The registration is the process of aligning the CAD model with the scan. This is done by selecting corresponding points on the CAD model and the scan and find a transformation that minimizes the distance between them.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtrative_high_res_3.png" width="1000">
+</p>
+
+> DF's components:
+> * [`DFBrepToCloud`](gh_DFBrepToCloud)
+> * [`DFCloudVoxelDownsample`](gh_DFCloudVoxelDownsample)
+> * [`DFCloudNormalEstimator`](gh_DFCloudNormalEstimator)
+> * [`DFRANSACGlobalRegistration`](gh_DFRANSACGlobalRegistration)
+> * [`DFICPRegistration`](gh_DFICPRegistration)
+
+### 4. Segmentation of the scan
+Once the scan and the CAD model are aligned, we can segment the scan to isolate the parts of the raw point cloud of the scan that corresponds tothe joints.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtrative_high_res_4.png" width="1000">
+</p>
+
+> DF's components:
+> * [`DFCloudNormalSegmentator`](gh_DFCloudNormalSegmentator)
+> * [`DFRemoveStatisticalOutliers`](gh_DFRemoveStatisticalOutliers)
+> * [`DFJointSegmentator`](gh_DFJointSegmentator)
+> * [`DFColorizeCloud`](gh_DFColorizeCloud)
+
+### 6. Error computation
+At this point we can compute the error between the CAD model and the scan. The error is computed as the distance between the closest point on the CAD model and the scan. The current DF's output metrics are:
+
+* *distance* : the distance between the closest point on the CAD model and the scan
+* *mean* : the mean distance between the closest point on the CAD model and the scan
+* *max_deviation* : the maximum distance between the closest point on the CAD model and the scan
+* *min_deviation* : the minimum distance between the closest point on the CAD model and the scan
+* *std_deviation* : the standard deviation of the distance between the closest point on the CAD model and the scan
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtrative_high_res_5.png" width="500">
+</p>
+
+> DF's components:
+> * [`DFCloudMeshDistance`](gh_DFCloudMeshDistance)
+
+### 7. Error Visulization
+DF allows you to quickly visualize the errors in the Rhino viewport. The color of the points represents the distance between the CAD model and the scan. The color scale can be adjusted to better visualize the error. We also provide a graph that shows the distribution of the errors.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtrative_high_res_6.png" width="600">
+</p>
+
+<div style="display: flex; justify-content: space-around; align-items: center;">
+    <figure style="margin: 10px;">
+        <img src="./_static/tutorials/fig_subtractive_detail_viz.png" alt="subtr detail" style="height: 400px; background-color: transparent;">
+        <figcaption>View on the visualization of the analysed clouds on the CAD model itself. To not that only the points considered as valid are considered for the analysis. </figcaption>
+    </figure>
+    <figure style="margin: 10px;">
+        <img src="./_static/tutorials/fig_subtractive_graph_viz.png" alt="subtr graph" style="height: 400px; background-color: transparent;">
+        <figcaption>View of the graph of the corresponding distribution of the total error directly in Rhino.</figcaption>
+    </figure>
+</div>
+
+> DF's components:
+> * [`DFVisualizationSettings`](gh_DFVisualizationSettings)
+> * [`DFVisualization`](gh_DFVisualization)
+
+### 8. Export the results
+The results can be also exported in a CSV file for further analysis or documentation.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/tutorials/fig_subtrative_high_res_7.png" width="500">
+</p>
+
+CSV can be exporting the value per joint..
+
+| Joint ID | Min Deviation | Max Deviation | Std Deviation | RMSE  |
+|----------|---------------|---------------|---------------|-------|
+| 0--0--0  | 0             | 0.006         | 0.0015        | 0.0023|
+| 0--1--0  | 0             | 0.0064        | 0.0011        | 0.0024|
+| 0--2--0  | 0.0001        | 0.0091        | 0.0019        | 0.0028|
+| 0--3--0  | 0             | 0.0061        | 0.0012        | 0.0018|
+| 0--4--0  | 0.0001        | 0.0062        | 0.0009        | 0.0021|
+
+.. or per face
+
+| Joint Face ID | Min Deviation | Max Deviation | Std Deviation | RMSE  | Mean  |
+|---------------|---------------|---------------|---------------|-------|-------|
+| 0--0--0       | 0             | 0.0032        | 0.0006        | 0.0009| 0.0007|
+| 0--0--1       | 0.2933        | 0.6587        | 0.1164        | 0.4882| 0.4741|
+| 0--0--2       | MISSING_PCD   | MISSING_PCD   | MISSING_PCD   | MISSING_PCD| MISSING_PCD|
+| 0--0--3       | MISSING_PCD   | MISSING_PCD   | MISSING_PCD   | MISSING_PCD| MISSING_PCD|
+| 0--0--4       | MISSING_PCD   | MISSING_PCD   | MISSING_PCD   | MISSING_PCD| MISSING_PCD|
+| 0--0--5       | MISSING_PCD   | MISSING_PCD   | MISSING_PCD   | MISSING_PCD| MISSING_PCD|
+| 0--0--6       | 0.2602        | 0.3317        | 0.0171        | 0.2991| 0.2986|
+| 0--0--7       | 0.1829        | 0.2453        | 0.0176        | 0.2076| 0.2069|
+| 0--0--8       | 0.0107        | 0.2884        | 0.0897        | 0.1512| 0.1217|
+| ...       | ...        | ...        | ...         | ...| ... |
+
+> DF's components:
+> * [`DFCsvExporter`](gh_DFCsvExporter)
diff --git a/doc/key-concepts.md b/doc/key-concepts.md
@@ -1,4 +1,45 @@
 (key-concepts)=
 # Key-concepts
 
-/// add description here about the general structure of diffCheck with schemes and general functioning
+<img src="_static/logo_favicon.ico" alt="logo" style="width:30px; float:right; margin-left:10px;">
+
+## A modular structure
+
+To make DF broadly applicable and allow users to customize their evaluation pipelines, we designed the plugin with a modular structure. By assembling and combining different components, users can tailor their workflows to fit specific project needs.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/gh_components/img_overview_dfareas.png" width="800">
+</p>
+
+By combining different components, users can create a wide range of evaluation pipelines. The plugin includes components for:
+
+- **Data preparation**: Import and preprocess data from different sources.
+- **Data analysis**: Compute metrics and visualize results.
+- **Data manipulation**: Arrange and cluster scans or convert one datatype (e.g. brep) to another (e.g. cloud).
+- **Data export**: Export results to different formats.
+
+Have a look at [our documentation for all the components](gh_components).
+
+<img src="_static/logo_favicon.ico" alt="logo" style="width:30px; float:right; margin-left:10px;">
+
+## Evaluation pipelines
+
+In DF, evaluation pipelines to compare CAD and scans are *sequences of components that process data from input to output. They can be as simple as a single component or as complex as a chain of multiple components.* Normally it is composed of the following steps:
+
+```{mermaid}
+flowchart LR
+    A{Data input} --> 
+    B(Data cleaning) --> 
+    C(Registration) -->
+    D(Error Computation) -->
+    E{Data export}
+    D --> F[Visualization]
+```
+
+To show how this works in DF, we provide two examples of evaluation pipelines we have done for timber construction by combining different components:
+
+- [Evaluation of joins in timber construction](joints-evaluation)
+- [Evaluation of assembled structures in timber construction](assembly-evaluation)
+
+> You can create your own evaluation pipelines by combining different components and let us know if you want to share them with the community or you need a specific component that is not available yet, send an email to [diffcheckorg@gmail.com](mailto:diffcheckorg@gmail.com)!
diff --git a/doc/pre-processing.md b/doc/pre-processing.md
diff --git a/doc/quickstart.md b/doc/quickstart.md
@@ -1,4 +1,21 @@
 (qstart)=
 # Quickstart
 
-/// a brief rer-intro on how to install and a basic example of a working full and small pipeline of diffCheck
+Using `diffCheck` requires *Rhino* and *Grasshopper*. The plug-in can be installed simply by:
+
+*  Open *Rhino* and tpe on the command bar: 
+    ``` 
+    _PackageManager
+    ```
+* search for `diffCheck` and click on install.
+* launch *Grasshopper* you will find the a new tab in the toolbar.
+* drop on the canvas the [test component](gh_DFTester) and connect it to a point cloud and a CAD model.
+
+<p align="center">
+    <img style="background-color: transparent;"
+    src="./_static/correct_install_check.png" width="400">
+</p>
+
+
+```{important}
+For now, diffCheck is only supported on Windows ❖.
diff --git a/doc/tutorials.rst b/doc/tutorials.rst
@@ -8,7 +8,5 @@ diffCheck tutorials
 
    quickstart
    key-concepts
-   pre-processing
-   assembly_intro
-   segmentation_intro
-   compute_error_intro
+   joints-evaluation
+   assembly-evaluation
diff --git a/src/diffCheck/segmentation/DFSegmentation.cc b/src/diffCheck/segmentation/DFSegmentation.cc
@@ -179,13 +179,13 @@ namespace diffCheck::segmentation
                 }
                 if (correspondingSegment == nullptr)
                 {
-                    DIFFCHECK_WARN("No segment found for the face. Skipping the face.");
+                    DIFFCHECK_WARN("No segment found for the face. Returning an empty point cloud for this face.");
+                    faceSegments.push_back(facePoints);
                     continue;
                 }
                 bool hasColors = correspondingSegment->GetNumColors() > 0;
                 for (Eigen::Vector3d point : correspondingSegment->Points)
                 {
-                    bool pointInFace = false;
                     if (face->IsPointOnFace(point, associationThreshold))
                     {
                         facePoints->Points.push_back(point);
@@ -279,7 +279,8 @@ namespace diffCheck::segmentation
 
                 if (correspondingSegment == nullptr)
                 {
-                    DIFFCHECK_WARN("No segment found for the face. Skipping the face.");
+                    DIFFCHECK_WARN("No segment found for the face. Returning an empty point cloud for this face.");
+                    faceSegments.push_back(facePoints);
                     continue;
                 }
                 bool hasColors = correspondingSegment->GetNumColors() > 0;

diff --git a/src/gh/components/DF_build_assembly/code.py b/src/gh/components/DF_build_assembly/code.py
@@ -16,6 +16,10 @@ def RunScript(self,
             i_breps : System.Collections.Generic.IList[Rhino.Geometry.Brep],
             i_is_roundwood : bool):
         beams: typing.List[DFBeam] = []
+
+        if i_assembly_name is None or i_breps is None:
+            return None
+
         if i_is_roundwood is None:
             i_is_roundwood = False
 

diff --git a/src/gh/components/DF_cloud_cloud_distance/code.py b/src/gh/components/DF_cloud_cloud_distance/code.py
@@ -34,4 +34,4 @@ def RunScript(self,
         # calculate distances
         o_results = df_error_estimation.df_cloud_2_df_cloud_comparison(df_cloud_source_list, df_cloud_target_list)
 
-        return o_results.distances, o_results.distances_rmse, o_results.distances_max_deviation, o_results.distances_min_deviation, o_results.distances_sd_deviation, o_results
+        return o_results.distances, o_results.distances_mean, o_results.distances_rmse, o_results.distances_max_deviation, o_results.distances_min_deviation, o_results.distances_sd_deviation, o_results
diff --git a/src/gh/components/DF_cloud_cloud_distance/metadata.json b/src/gh/components/DF_cloud_cloud_distance/metadata.json
@@ -59,6 +59,14 @@
                 "sourceCount": 0,
                 "graft": false
             },
+            {
+                "name": "o_mean",
+                "nickname": "o_mean",
+                "description": "The mean of the distances.",
+                "optional": false,
+                "sourceCount": 0,
+                "graft": false
+            },
             {
                 "name": "o_rmse",
                 "nickname": "o_rmse",