Commit 6eb4a04a authored by Andrew Wilson's avatar Andrew Wilson
Browse files

DOC: PbdModel documentation

parent fd1de943
......@@ -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
......
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:
- **IntegratePosition**: 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 dcdx. 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 Thin Tissue & Cloths
--------------------------------
For thin deformable tissues and cloths we use surface's 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 "bendy" the cloth 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 we use meshes made of tetrahedrons. There are two setups. Either use **PbdVolumeConstraint** & **PbdDistanceConstraint** constraints. Or use **PbdFemConstraint** constraints. The FEM constraints are more accurate than the volume+distance. However, they are much slower meaning you 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
--------------------------------
Threads are very common in surgical scenarios. For threads we 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**. You generally want this stiffness as high as possible as liquids are incompressible. If not, you may get "bouncey" behaviour. Liquids in iMSTK are most useful for blood spray effects. But may also be used to model larger flow problems. If one was modelling flow problems I would suggest other models though.
.. 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 define 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 masses set to 0 which indicates infinite mass.
**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. Samll timesteps are preferrable 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 system. For example, a really long thread with numerous segements may have a really high stiffness set 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
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment