[doc] Add a documentation file for this repository (#111)

* [doc] Created a documentation

* [doc] Remove assist documentation

* [doc] Small review

* [doc] Update README

* [doc] Review doc

* [doc] Some explanation on the layers

* [doc] Remove slop

* [doc] Add UML diagrams

* [doc] Suggestions from review

Author: th-skam

README.md

@@ -9,76 +9,81 @@
 This SOFA plugin (https://github.com/sofa-framework/sofa) provides a customized collision 
 pipeline, designed specifically for needle insertion simulations. 
 
-When used together with SOFA haptic device plugins, the system offers tactile feedback 
+Coupled with SOFA haptic device plugins, the system offers tactile feedback 
 for puncture resistance, release and friction during insertion and retraction.
 
-This plugin has also been integrated in Unity via the [`SOFAUnity`](https://github.com/InfinyTech3D/SofaUnity)
+Unity Engine integration is offered via the [`SOFAUnity`](https://github.com/InfinyTech3D/SofaUnity)
 plugin by InfinyTech3D for an enhanced simulation experience. Contact us for more information!
 
 ## Features
 
 - Proximity detection between the needle and tissue mesh primitives
-- Needle simulation phases: puncture, insertion, retraction
-- Constraint-based needle simulation during the 3 phases
+- Needle insertion is simulated in phases: puncture, insertion, retraction
+- Needle-tissue coupling is done using Lagrangian constraints
 - Support for haptic feedback such as resistance during puncture and friction during insertion
 - Compatible with SOFA-Unity integration for real-time interactive applications
 
 ## Installation and Setup
 
-First review the official SOFA documentation for building and registering SOFA plugins
+This plugin can be installed by following the official SOFA documentation for building and registering SOFA plugins
 https://sofa-framework.github.io/doc/plugins/build-a-plugin-from-sources/
 
+
 ### Build Steps
 
-- Set up your `external_directories` directory (described in the SOFA documentation link above)
-- Clone this repository into your `external_directories` directory:
-    - git clone https://github.com/InfinyTech3D/CollisionAlgorithm.git
-- Register the path to your local `CollisionAlgorithm` repository in the CMakeLists.txt file located inside your `external_directories` directory
-```sofa_add_subdirectory(plugin CollisionAlgorithm CollisionAlgorithm)```
-- Set `SOFA_EXTERNAL_DIRECTORIES` variable (preferably using CMake GUI) to point to your `external_directories` directory
+- Set up the `external_directories` directory
+- Clone into `external_directories`:
+```
+git clone https://github.com/InfinyTech3D/CollisionAlgorithm.git
+```
+- Register plugin path in the `external_directories` CMakeLists.txt.
+```
+sofa_add_subdirectory(plugin CollisionAlgorithm CollisionAlgorithm)
+```
+- Set the `SOFA_EXTERNAL_DIRECTORIES` variable pointing to `external_directories`
 - Configure and generate the SOFA solution using CMake
 - Compile SOFA solution (the plugin will be compiled as well)
 
 > [!IMPORTANT]
-> In order to use the plugin, make sure that you have also built the downstream 
+> In order to use it, this plugin must be build alongside the downstream 
 [`ConstraintGeometry`](https://github.com/InfinyTech3D/ConstraintGeometry) plugin.
 
 Supported SOFA version: v25.06 and above
 
 ## Architecture
 
 - doc:
-    - Documentation and screenshots of the examples
+    - Code documentation
 - scenes:
     - Various simple demo scenes
 - src/CollisionAlgorithm:
-    - source code of the insertion algorithm SOFA component and supporting collision pipeline classes
+    - SOFA components implementing the insertion algorithm and the supporting collision pipeline
 - regression:
-    - Files for automated regression testing in alignment with SOFA's testing framework
+    - Reference files for automated non-regression tests based on SOFA's testing framework
 
-## Usage
+## Get Started
 
-- To use the plugin, include the `CollisionAlgorithm` plugin in your SOFA .xml scene file.
+- Include the `CollisionAlgorithm` plugin in a scene file.
 
-``` <RequiredPlugin name=`CollisionAlgorithm`/> ```
-- Add the `CollisionLoop` component in the root node of your scene.
+``` <RequiredPlugin pluginName=`CollisionAlgorithm`/> ```
+- Add the `CollisionLoop` component at the root node of your scene.
 
 ``` 
 <FreeMotionAnimationLoop/>
 <ProjectedGaussSeidelConstraintSolver tolerance='<your tolerance>' maxIt='<maximum solver iterations>' />
-<CollisionLoop/>
+**<CollisionLoop/>**
 
 <CollisionPipeline/>
 <BruteForceBroadPhase/>
 <BVHNarrowPhase/>
 <CollisionResponse name='response' response='FrictionContactConstraint'/>
 <LocalMinDistance name='proximity' alarmDistance='0.2' contactDistance='0.08'/>
 ``` 
-This component substitutes the default `CollisionPipeline` and manages the needle insertion algorithm.
-However, the two components can co-exist, allowing users to mix the standard collision detection/constraint resolution pipelines of SOFA.
+This component manages the needle insertion algorithm. It can work simultaneously with the existing SOFA `CollisionPipeline` 
+and can thus be added incrementally in existing SOFA scenes where contacts and collisions are modelled. 
 
-- Create a node to represent the needle and additional nodes for the needle tip and shaft geometries
-Refer to the `scenes/NeedleInsertion.xml` example scene for guidance.
+- Create a node to represent the needle and additional nodes for the needle tip and shaft geometries.
+This step is more detailed, so refer to the examples in `scenes/NeedleInsertion.xml` for guidance.
 
 - Add an `InsertionAlgorithm` component inside the needle node as shown below.
 ```