diff --git a/Docs/Maintainance.md b/Docs/Maintainance.md
index 1c44f52e49204956d72bcb92b3d218380a5de37c..1173e387b4de4df678c4e1943819a76e796cf687 100644
--- a/Docs/Maintainance.md
+++ b/Docs/Maintainance.md
@@ -101,7 +101,7 @@ Any `find_package` commands issued in the main file have to be replicated here a
# Updating a Dependency in iMSTK
-To update a dependency in imstk one needs to:
+## Updating a dependency in imstk
- Swap the url in ` /CMake/External/<DependencyLibraryName>.cmake` to a different url.
- Ex: `https://gitlab.kitware.com/iMSTK/assimp/-/archive/fixCompilationError/assimp-fixCompilationError.zip`. Pulling zips prevents git history with it which can be sizeable.
@@ -112,10 +112,10 @@ To update a dependency in imstk one needs to:
## Updating a Remote Fork
-Most dependencies in iMSTK are forked. This way we don't depend on the remote repository as it could change (rebased/amended/etc). A few forks also contain our own diffs in the rare case something like a cmake fix is introduced. To update a fork:
+Most dependencies in iMSTK are forked. This way we don't depend on the remote repository as it could change (rebased/amended/moved/deleted). A few forks also contain our own diffs in the rare case something like a CMake fix is introduced. To update a fork:
- Clone the fork locally: `git clone <git url of fork>` (all forks found in iMSTK group here: https://gitlab.kitware.com/iMSTK)
- Add upstream `git remote add upstream <url of actual repo/repo forked off>` (the description of the fork normally provides what it was forked from)
- - Tip: `git remote -v` to list all remotes
+ - Tip: Issue `git remote -v` to list all remotes
- Merge upstream (or rebase): `git merge upstream/<branch to update from>`
- Push your changes
@@ -129,6 +129,6 @@ iMSTKs data sits in a separate repository https://gitlab.kitware.com/iMSTK/imstk
The repository is already checked out as an external dependency in your build directory (if using superbuild) as `<build_dir>\External\iMSTKData\src\Data`, data can be added to the folder here and directly commited and pushed.
-**2. Update SHA in ExternalData.cmake**
+**2. Update SHA in `ExternalData.cmake`**
-The file that controls the downloading of the data is `CMake/External/External_iMSTKData.cmake` after commiting and pushing a change in the iMSTKData repository, the SHA to checkout needs to be updated to the SHA matching your latest commit.
\ No newline at end of file
+The file that controls the downloading of the data is `CMake/External/External_iMSTKData.cmake`. After commiting and pushing a change in the `iMSTKData` repository, the SHA to checkout needs to be updated to the SHA matching the latest commit.
diff --git a/Docs/source/Dynamical_Models.rst b/Docs/source/Dynamical_Models.rst
index b260d434067c0bb32ee4ddc76986d353bf9e34d2..a0c1ebd58d5d94fba969de46f4d33671df1bc957 100644
--- a/Docs/source/Dynamical_Models.rst
+++ b/Docs/source/Dynamical_Models.rst
@@ -6,85 +6,10 @@ Overview
========
Dynamical Models, model dynamical systems which describe a function in time. Generally, this is given via some dynamical equation (usually a PDE) that can be discretized for various geometries. Commonly used geometries include tetrahedral, hexahedral, triangle meshes, pointsets, and implicit geometries.
-Position Based Dynamics (PBD)
+:doc:`Position Based Dynamics (PBD) <../PbdModel>`.
=============================
-The first is position based dynamics which is fast and stable constraint based simulation method [pbd]_. It's fast and stable because it directly solves for positions. That is, each constraint is formulated with the positions. For example, a distance constraint may try to maintain a scalar distance L between two positions. While some models may compute a velocity that would converge the position to L. PBD directly computes the position to converge to L. For a single constraint this has a very simple solution. But when multiple constraints are involved, they may begin to conflict with each other, so we reproject the constraints to quantify how satisfied a constraint is. In PBD velocities are then computed aftewards given the resulting positions. The full list of PBD constraints may be found here.
-
-xPBD
-=====
-With original PBD, constraints become very stiff as the timestep decreases. Extended PBD (xPBD) alleviates this by removing that dependency. xPBD is the default in iMSTKs PbdModel.
-
-Usage
-=====
-Position based dynamics is very flexible. If you can come up with a constraint for it, you can simulate it. This includes things such as fluids, deformables, solids. This allows:
-
-- Blood (pointsets)
-
-.. image:: media/blood.png
- :width: 400
- :alt: Alternative text
- :align: center
-
-
-- 2d/thin tissues and cloth (triangle meshes)
-
-.. image:: media/cloth1.png
- :width: 400
- :alt: Cloth simulation
- :align: center
-
-.. image:: media/cloth2.png
- :width: 400
- :alt: Cloth cutting
- :align: center
-
-- Soft tissues and organs (tetrahedral meshes)
-
-.. image:: media/heart2.png
- :width: 400
- :alt: Tetrahedral mesh heart
- :align: center
-
-.. image:: media/vess.gif
- :width: 400
- :alt: VESS
- :align: center
-
-- String (linemeshes, useful for suturing)
-
-.. image:: media/strings.png
- :width: 400
- :alt: Strings
- :align: center
-
-
-Code
-====
-To setup a PbdModel we do:
-
-::
-
- // Setup the config
- imstkNew<PBDModelConfig> pbdConfig;
-
- // Constraints
- pbdConfig->enableConstraint(PbdConstraint::Type::Distance, 1e2);
- pbdConfig->enableConstraint(PbdConstraint::Type::Dihedral, 1e1);
- pbdConfig->m_fixedNodeIds = { 0, 1 };
-
- // Other parameters
- pbdConfig->m_uniformMassValue = 1.0;
- pbdConfig->m_gravity = Vec3d(0, -9.8, 0);
- pbdConfig->m_defaultDt = 0.005;
- pbdConfig->m_iterations = 10;
-
- // Setup the model
- imstkNew<PbdModel> pbdModel;
- pbdModel->setModelGeometry(surfMesh);
- pbdModel->configure(pbdConfig);
-
-This can be given to a PbdObject for usage in the scene.
+PBD is probably the most common model used in iMSTK, it may be used for cloths, thin tissues, volumetric/tetrahedral tissues, fluids (both liquids and gasses), and threads/strings. Read more about it at the link above.
Smoothed Particle Hydrodynamics (SPH)
=====================================
@@ -337,14 +262,6 @@ Bibliography
conjugate gradient method in cloth simulation. Vis. Comput. 19, 7-8
(December 2003), 526-531.
-.. [pbd] Matthias Müller, Bruno Heidelberger, Marcus Hennix, and John
- Ratcliff. 2007. Position based dynamics. J. Vis. Comun. Image
- Represent. 18, 2 (April 2007), 109-118.
-
-.. [xpbd] Miles Macklin, Matthias Müller, and Nuttapong Chentanez
- 2016. XPBD: position-based simulation of compliant constrained dynamics.
- In Proc. of Motion in Games. 49–54
-
.. [vrpn] Russell M. Taylor, II, Thomas C. Hudson, Adam Seeger, Hans Weber,
Jeffrey Juliano, and Aron T. Helser. 2001. VRPN: a device-independent,
network-transparent VR peripheral system. In Proceedings of the ACM
diff --git a/Docs/source/PbdModel.rst b/Docs/source/PbdModel.rst
new file mode 100644
index 0000000000000000000000000000000000000000..91f94ea60dd9474f2409e46b64822065202930bf
--- /dev/null
+++ b/Docs/source/PbdModel.rst
@@ -0,0 +1,146 @@
+Position Based Dynamics
+===================
+
+Position based dynamics [pbd]_, as used in iMSTK, is a first order, particle & constraint based dynamical model. It simulates the dynamics of objects through direct manipulation of particle positions with velocities computed afterwards. This has various pro's and cons, but a major pro is the stability of such method. Pbd in iMSTK is primarily used for deformable bodies but can also be used for fluids (both gas and liquid). Discussed here are its medical applications. The particular implementation of PBD used in iMSTK is Extended PBD [xpbd]_.
+
+The general pbd pipeline is as follows:
+
+- **Integrate Position**: Given the current velocity of every particle, compute the new/tentative position.
+- **Solve Internal Constraints**: Solve all internal constraints (directly changing positions). Resolving any violations.
+- **Update Velocities**: Compute new velocities from the displacements produced.
+
+Constraints
+--------------------------------
+
+Pbd is a constraint based model. Constraints are made for particles in pbd. This constrains the movement of a particle. Constraints are given via a constraint function q, and the gradient of the function q. To solve a constraint is to reduce the scalar, q, to 0. The gradient gives the direction to move the particle to do this. The following constraints are available in iMSTK and referred to in later sections on how to use them:
+
+There are two types of constraints in iMSTK. PbdConstraints and PbdCollisionConstraints. PbdConstraints are generally inernal constraints and work by particle index. They often exist for the entire duration of a simulation. PbdCollisionConstraints are often external, they are added at runtime upon contact, they work by particle pointer value (position and velocity). Among the PbdConstraints are:
+
+- **PbdDistanceConstraint**: Constraints two points by the initial distance between them.
+- **PbdDihedralConstraint**: Constrains two triangles by the initial angle between their planes.
+- **PbdVolumeConstraint**: Constrains all points of a tetrahedron by the initial volume.
+- **PbdFETetConstraint**:
+- **PbdBendConstraint**: Constrains 3 points by the angle between the two lines. (like a 1d Dihedral)
+- **PbdConstantDensityConstraint**: Constrains all points of a system to achieve constant density using SPH kernels (ie: repels particles in a spherical manner).
+- **PbdAreaConstraint**: Constrains 3 points of a triangle by the initial area of that triangle.
+
+To implement your own custom constraint one needs to subclass either ``PbdConstraint`` or ``PbdCollisionConstraint``, construct or initialize it appropriately, then implement/override ``computeValueAndGradient`` which should fill out the constraint value C and constraint gradient dC/dx. This constraint would then need to be added to an existing system or solved in it's own computational block somewhere (depending on when it should be solved).
+
+Deformable Membranes
+--------------------------------
+
+For thin deformable membraneous tissues (cloth like) we use surfaces made of triangles. For this simulation one may use **PbdDistanceConstraint**, **PbdDihedralConstraint**, and/or **PbdAreaConstraint**. The most common setup is just distance and dihedral constraints though. The distance constraints keep the cloth together, whilst the dihedral constraint controls how resistent to bending the membrane is.
+
+.. image:: media/PbdModel/tissue1.png
+ :width: 400
+ :alt: Cloth simulation
+ :align: center
+
+.. image:: media/PbdModel/cloth2.png
+ :width: 400
+ :alt: Cloth cutting
+ :align: center
+
+Deformable Volumetric Tissue
+--------------------------------
+
+For volumetric deformable tissues discretized with tetrahedrons may be used. With the tetrahedrons one may either use (a) **PbdVolumeConstraint** & **PbdDistanceConstraint** constraints Or (b) use **PbdFemConstraint** constraints. The FEM constraints are more accurate than the volume+distance. However, they are much slower in that one may not be able to achieve the target element count or timestep, iteration count, & stiffness. The volume constraints behave well with sign inversion, recovering well from inverted tetrahedrons.
+
+.. image:: media/PbdModel/tissue2.png
+ :width: 400
+ :alt: Cloth simulation
+ :align: center
+
+.. image:: media/PbdModel/heart2.png
+ :width: 400
+ :alt: Cloth simulation
+ :align: center
+
+.. image:: media/PbdModel/tissue3.gif
+ :width: 400
+ :alt: Cloth simulation
+ :align: center
+
+Deformable Threads
+--------------------------------
+
+Surture threads are very common in surgical scenarios. For threads one may use **PbdDistanceConstraint** & **PbdBendConstraint** constraints. The distance constraints keep the particles of the thread together, whilst the bend controls the rigidity of the the thread. The bend constraints may also be generated between multiple sets of particles to reduce iteration count.
+
+.. image:: media/PbdModel/thread1.png
+ :width: 400
+ :alt: Cloth simulation
+ :align: center
+
+Liquids
+--------------------------------
+
+Liquids can be modeled with pbd using **PbdConstantDensityConstraint**. Generally, the stiffness is kept as high as possible as liquids are incompressible. If not, you may observe "bouncey" behaviour. Liquids in iMSTK are most useful for bleeding simulation.
+
+.. image:: media/PbdModel/blood.png
+ :width: 400
+ :alt: Cloth simulation
+ :align: center
+..
+ Gasses
+ --------------------------------
+
+ The primary usage for gas is particles during electrocautery. Often these would be billboarded smoke images on particles that fade fairly quickly. There are currently no examples for gas in iMSTK. It is a fluid though, so its approach is not much different than liquids. The **PbdConstantDensityConstraint** may be used. I would suggest using a lower stiffness as liquids tend to be incompressible (constant density) whereas gasses are compressible. The other issue is the lack of proper boundary conditions. Often we are modeling a gas suspended in air. This air must be modeled too if you want accuracy. There do exist some solutions with "ghost particles" to approximate air without adding air particles, but iMSTK does not have such solutions yet. If this is for visual purposes I might suggest lowering gravity, fiddling with mass, etc to get believable behaviour without being suspended in anything.```
+
+Code
+====
+To setup a PbdModel we do:
+
+::
+
+ // Setup the config
+ imstkNew<PBDModelConfig> pbdConfig;
+
+ // Constraints
+ pbdConfig->enableConstraint(PbdConstraint::Type::Distance, 1e2);
+ pbdConfig->enableConstraint(PbdConstraint::Type::Dihedral, 1e1);
+ pbdConfig->m_fixedNodeIds = { 0, 1 };
+
+ // Other parameters
+ pbdConfig->m_uniformMassValue = 1.0;
+ pbdConfig->m_gravity = Vec3d(0, -9.8, 0);
+ pbdConfig->m_dt = 0.005;
+ pbdConfig->m_iterations = 10;
+
+ // Setup the model
+ imstkNew<PbdModel> pbdModel;
+ pbdModel->setModelGeometry(surfMesh);
+ pbdModel->configure(pbdConfig);
+
+**Constraints**: Constraints of varying types may be used via ``PBDModelConfig::enableConstraint``, internally this uses PbdConstraintFunctor's which defines how to generate constraints. If one needs more hands on with constraints you may write your own ``PbdConstraintFunctor``. Implemented by subclassing PbdConstraintFunctor and overriding the operator() function. See existing functors in ``imstkPbdConstraintFunctor.h``.
+
+::
+
+ auto myCustomFunctor = std::make_shared<MySuperCustomFunctor>();
+ myCustomFunctor->setStiffness(0.95);
+ pbdModel->addPbdConstraintFunctor(myCustomFunctor);
+
+**Fixed Node Ids**: This indicates the indices of the particles/nodes that are immovable. Immovable nodes have their inverse masses set to 0 which indicates infinite mass (hence immovable).
+
+**Uniform Mass Value**: This mass value is assigned to all particles/nodes on initialization if masses are not provided as a vertex attribute in the input mesh.
+
+**dt**: The timestep is used during integration to move the particles. Small timesteps are preferable for stability. Real time steps may be used by varying dt every update of the simulation.
+
+::
+
+ connect<Event>(sceneManager, &SceneManager::postUpdate, [&](Event*)
+ {
+ pbdConfig->m_dt = sceneManager->getDt();
+ });
+
+**Iterations**: The iterations of the solver used in the internal constraints. More iterations give changes more time to percolate through the body. For example, a really long thread with numerous segments may have a really high stiffness but if it doesn't have enough iterations it will never be able to reach maximum stiffness. In the original PBD paper stiffness varied with the number of iterations. In xPBD (default) it does not.
+
+Bibliography
+------------
+
+.. [pbd] Matthias Müller, Bruno Heidelberger, Marcus Hennix, and John
+ Ratcliff. 2007. Position based dynamics. J. Vis. Comun. Image
+ Represent. 18, 2 (April 2007), 109-118.
+
+.. [xpbd] Miles Macklin, Matthias Müller, and Nuttapong Chentanez
+ 1. XPBD: position-based simulation of compliant constrained dynamics.
+ In Proc. of Motion in Games. 49–54
\ No newline at end of file
diff --git a/Docs/source/documentation.rst b/Docs/source/documentation.rst
index bca17516657ce7ad3b899acaec8e02d32af8d9ec..cbd44a8483c8282930d78165649d5d21768faeeb 100644
--- a/Docs/source/documentation.rst
+++ b/Docs/source/documentation.rst
@@ -140,31 +140,23 @@ The following diagram gives a high level view of iMSTK architecture. Most of the
:width: 700
:alt: iMSTK architecture
-Geometry
---------
-
+:doc:`Geometry <../Geometry>`
+-------------------
Geometries are used throughout iMSTK. The geometries themselves can be used standalone though. We have analytical, implicit, surface, volumetric, and image geometries.
-Read more about iMSTK geometry :doc:`here <../Geometry>`.
-
-
-Dynamical Models
-----------------
+:doc:`Dynamical Models <../Dynamical_Models>`
+-------------------
Geometries are great. But you're likely going to want to do something with it. The primary use case is to advance it in time via some dynamical model. In iMSTK we provide models for dynamic and static deformable/soft bodies, fluids, & rigid bodies. We include PBD, SPH, FEM, and Rigid Bodies.
-Read more about dynamical models :doc:`here <../Dynamical_Models>`.
-
-Geometric Filtering
+:doc:`Geometric Filtering <../Filtering>`
-------------------
What else can you do with geometries? Filtering! Our filtering library provides a set of geometry algorithms we have found useful for surgical simulations.
-Read more about filtering :doc:`here <../Filtering>`.
-
-Devices
---------
+:doc:`Devices <../Devices>`
+-------------------
Devices are an important part to iMSTK. This is an the interactive surgical simulation toolkit after all.
@@ -173,82 +165,54 @@ Devices are an important part to iMSTK. This is an the interactive surgical simu
- OpenHaptics: Allows one to use haptic tracking devices such as the Phantom Omni, these provide force feedback, under the right models we can stop your hand from moving when touching something, or give slight resistance.
- Coming Soon: VRPN, Bluetooth, Arduino ...
-
-Read more about iMSTK's device support :doc:`here <../Devices>`.
-
-
-Controllers
------------
+:doc:`Controllers <../Controllers>`.
+-------------------
Controllers implement the controls of a device. We provide a couple of abstract base classes such as MouseControl, KeyboardControl, TrackingDeviceControl. As well as a few subclasses such as KeyboardSceneControl and MouseSceneControl which have some default behaviors such as stopping, starting, pausing a scene. But it's heavily encouraged you to subclass your own. You may also use lambdas on the devices for fast prototyping.
-Read more about controllers :doc:`here <../Controllers>`.
-
-
-Collision Detection
+:doc:`Collision Detection <../Collision_Detection>`
-------------------
Collision detection can be standalone in iMSTK but often finds it use through Interactions, later described in Scene. Put simply, its the act of computing "CollisionData" from two geometries. Most of the time these are "contacts" such as point normal contacts which give a point, a normal, and penetration depth. Often these are then later given to constraints to be added to a dynamical model.
-Read more about iMSTK's collision detection support :doc:`here <../Collision_Detection>`.
-
-
-Collision Handling
+:doc:`Collision Handling <../Collision_Handling>`
------------------
Collision handling implements how to consume collision data. For this reason it takes input CollisionData which is generally shared with CollisionDetection. iMSTK provides a number of handling methods, generally these call upon the functions of a DynamicalModel to immediately respond (explicit solve) or add something (such as a constraint) to later implicitly solve.
-Read more about iMSTK's collision handling support :doc:`here <../Collision_Handling>`.
-
-
-Scene
---------
+:doc:`Scene <../Scene>`
+-------------------
A scene contains a flat collection of SceneObjects and can fully represent the virtual environment. These SceneObjects may be something like an OR table, a tissue, a leg, a light, or even non-visual objects. Additionally a scene contains a set of interactions via it's InteractionGraph. A number of predefined InteractionPairs are available for iMSTK physics.
-Read more about iMSTK scene :doc:`here <../Scene>`.
-
-
-Mesh IO
---------
-Geometries are great. But to fully leverage them you need to be able to import from other tools which are much better at creating them.
-
-Read more about the geometry file types supported in iMSTK. Additionally about Scene and SceneObject importing :doc:`here <../Mesh_IO>`.
-
+:doc:`Mesh IO <../Mesh_IO>`
+-------------------
+Geometries are great. But to fully leverage them you need to be able to import from other tools which are much better at creating them. Read more about the files types supported by iMSTK. Additionally about Scene and SceneObject at the link above.
-SimulationManager & Modules
----------------------------
+:doc:`SimulationManager & Modules <../SimManager_Modules>`
+-------------------
Whilst scene's define the virtual environment and how to update it. They don't define how to drive it. You can certainly just call advance on the scene in a loop. That will get you decently far, but there's a bit more too it than that.
Modules in iMSTK define something that can be init'd, update'd, and uninit'd and added to a ModuleDriver. In every iMSTK example you can simply add modules to our concrete ModuleDriver called the SimulationManager to run them. It defines a special way of updating them.
-Read more about the SimulationManager in iMSTK with code samples :doc:`here <../SimManager_Modules>`.
-
-Rendering
----------
+:doc:`Rendering <../Rendering>`
+-------------------
Rendering in iMSTK is done through delegation to support multiple backends. This means we setup delegate classes for each thing we want to render. And map what we want to render to what the backend allows us to render. Primarily we use VTK.
-Read more about Rendering in iMSTK with code samples :doc:`here <../Rendering>`.
-
Miscellaneous Topics
====================
-Parallelism
------------
-Visit :doc:`Parallelism page <../Parallelism>` which goes over loop, task, and module parallelism in iMSTK.
-
-
-Events
-------
-Visit :doc:`iMSTK events Page <../Event_System>` which goes over events. Direct and message queues.
-
-
-Computational Flow
-------------------
-Visit :doc:`Computational Flow Page <../Computational_Flow>` which goes over the flow of the advancement of a scene.
+:doc:`Parallelism <../Parallelism>`
+-------------------
+Goes over loop, task, and module parallelism in iMSTK.
+:doc:`Events <../Event_System>`
+-------------------
+Goes over events. Direct and message queues.
-
+:doc:`Computational Flow <../Computational_Flow>`
+-------------------
+Goes over the flow/advancement of a scene.
.. |image0| image:: media/logo.png
:width: 3.5in
diff --git a/Docs/source/media/blood.png b/Docs/source/media/PbdModel/blood.png
similarity index 100%
rename from Docs/source/media/blood.png
rename to Docs/source/media/PbdModel/blood.png
diff --git a/Docs/source/media/cloth.png b/Docs/source/media/PbdModel/cloth.png
similarity index 100%
rename from Docs/source/media/cloth.png
rename to Docs/source/media/PbdModel/cloth.png
diff --git a/Docs/source/media/cloth1.png b/Docs/source/media/PbdModel/cloth1.png
similarity index 100%
rename from Docs/source/media/cloth1.png
rename to Docs/source/media/PbdModel/cloth1.png
diff --git a/Docs/source/media/cloth2.png b/Docs/source/media/PbdModel/cloth2.png
similarity index 100%
rename from Docs/source/media/cloth2.png
rename to Docs/source/media/PbdModel/cloth2.png
diff --git a/Docs/source/media/heart2.png b/Docs/source/media/PbdModel/heart2.png
similarity index 100%
rename from Docs/source/media/heart2.png
rename to Docs/source/media/PbdModel/heart2.png
diff --git a/Docs/source/media/PbdModel/thread1.png b/Docs/source/media/PbdModel/thread1.png
new file mode 100644
index 0000000000000000000000000000000000000000..7008a4789d39bf55e353f6cfb39b915784dcfcb5
Binary files /dev/null and b/Docs/source/media/PbdModel/thread1.png differ
diff --git a/Docs/source/media/PbdModel/tissue1.png b/Docs/source/media/PbdModel/tissue1.png
new file mode 100644
index 0000000000000000000000000000000000000000..ee6ee00cb82aca487415199d1cfcacdfd8b0b79d
Binary files /dev/null and b/Docs/source/media/PbdModel/tissue1.png differ
diff --git a/Docs/source/media/PbdModel/tissue2.png b/Docs/source/media/PbdModel/tissue2.png
new file mode 100644
index 0000000000000000000000000000000000000000..4abd341468e0c8c5e39f9d287dd8e4f820fdf481
Binary files /dev/null and b/Docs/source/media/PbdModel/tissue2.png differ
diff --git a/Docs/source/media/vess.gif b/Docs/source/media/PbdModel/tissue3.gif
similarity index 100%
rename from Docs/source/media/vess.gif
rename to Docs/source/media/PbdModel/tissue3.gif