diff --git a/README.md b/README.md index 8e1383b6..8c34f545 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,115 @@ +# Collision Algorithm for Needle Insertion - SOFA Plugin + +[![Support](https://img.shields.io/badge/support-on_GitHub_Discussions-blue.svg)](https://github.com/sofa-framework/sofa/discussions/) +[![Discord](https://img.shields.io/badge/chat-on_Discord-darkred.svg)](https://discord.gg/G63t3a8Ra6) +[![Contact](https://img.shields.io/badge/contact-on_website-orange.svg)](https://infinytech3d.com/) +[![Support us](https://img.shields.io/badge/support_us-on_Github_Sponsor-purple.svg)](https://github.com/sponsors/InfinyTech3D) + ## Description -This is a SOFA plugin (https://github.com/sofa-framework/sofa) that provides a customized collision pipeline, specifically designed to support needle insertion simulations. -Works in conjunction with https://github.com/InfinyTech3D/ConstraintGeometry. +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 +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) +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 +- 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 +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 +- 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 +[`ConstraintGeometry`](https://github.com/InfinyTech3D/ConstraintGeometry) plugin. + +Supported SOFA version: v25.06 and above + +## Architecture + +- doc: + - Documentation and screenshots of the examples +- scenes: + - Various simple demo scenes +- src/CollisionAlgorithm: + - source code of the insertion algorithm SOFA component and supporting collision pipeline classes +- regression: + - Files for automated regression testing in alignment with SOFA's testing framework + +## Usage + +- To use the plugin, include the `CollisionAlgorithm` plugin in your SOFA .xml scene file. + +``` ``` +- Add the `CollisionLoop` component in the root node of your scene. + +``` + + + + + + + + + +``` +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. + +- 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. + +- Add an `InsertionAlgorithm` component inside the needle node as shown below. +``` + + + + + + + + +``` ## Acknowledgments -This project builds upon the original repository from [ICube Laboratory, University of Strasbourg](https://icube.unistra.fr/en/) and extends it with a needle insertion algorithm and additional functionality. +This project builds upon the original repository from +[ICube Laboratory, University of Strasbourg](https://icube.unistra.fr/en/) +and extends it with a needle insertion algorithm and additional functionality. diff --git a/scene/liver.scn b/scene/liver.scn deleted file mode 100644 index 56b1cf3e..00000000 --- a/scene/liver.scn +++ /dev/null @@ -1,63 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/scenes/NeedleBend.scn b/scenes/NeedleBend.scn deleted file mode 100644 index fbf07d57..00000000 --- a/scenes/NeedleBend.scn +++ /dev/null @@ -1,279 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -