Initial Commit
This commit is contained in:
@@ -0,0 +1,272 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Tutorial — imstk-unity 1.0.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
|
||||
<script src="_static/jquery.js"></script>
|
||||
<script src="_static/underscore.js"></script>
|
||||
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="_static/doctools.js"></script>
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Usage" href="classes.html" />
|
||||
<link rel="prev" title="Introduction" href="documentation.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
<a href="index.html" class="icon icon-home"> imstk-unity
|
||||
</a>
|
||||
<div class="version">
|
||||
1.0.0
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Introduction</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="documentation.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="documentation.html#setup-for-development">Setup for Development</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="documentation.html#devices">Devices</a></li>
|
||||
</ul>
|
||||
<p class="caption" role="heading"><span class="caption-text">User guide</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Tutorial</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="#example-scenes">Example Scenes</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#pbdclothcollision">PbdClothCollision</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#pbdclothscene">PbdClothScene</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#pbdthread">PbdThread</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#rbdscene">RbdScene</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#id3">Tutorial</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#devices">Devices</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#rbdcontroller">RbdController</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#rbdcontrollervrpn">RbdControllerVRPN</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#tissuecontact-and-pbdthintissuecontact">TissueContact and PbdThinTissueContact</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption" role="heading"><span class="caption-text">Class List</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="classes.html">Usage</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="classes.html#component-structure">Component Structure</a></li>
|
||||
</ul>
|
||||
<p class="caption" role="heading"><span class="caption-text">Release Notes</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="releases.html">Releases</a></li>
|
||||
</ul>
|
||||
<p class="caption" role="heading"><span class="caption-text">Licensing</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="license.html">Apache License</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="index.html">imstk-unity</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="index.html" class="icon icon-home"></a> »</li>
|
||||
<li>Tutorial</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="_sources/guide.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="tutorial">
|
||||
<h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this heading"></a></h1>
|
||||
<p>In this tutorial we are going to assemble a simple scene containing a deformable object colliding with static scenery. The completed tutorial is available as the <em>Tutorial</em> scene in the scene folder.</p>
|
||||
<p>For the purpose of this guides component names will be written in a mono-spaced font e.g. <code class="docutils literal notranslate"><span class="pre">SimulationManager</span></code>, whereas the names of GameObjects or EditorFields will be in italics e.g. <cite>HeartModel</cite></p>
|
||||
<ul>
|
||||
<li><p>Create a new scene in Unity</p></li>
|
||||
<li><p>Set the <cite>Main Camera</cite> transform to the values as seen in the image below</p>
|
||||
<img alt="Camera Parameters" class="align-center" src="_images/camera.png" />
|
||||
</li>
|
||||
<li><p>Create a new gameobject and add a <code class="docutils literal notranslate"><span class="pre">SimulationManager</span></code> component to it</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">SimulationManager</span></code> is a required component for all simulations using iMSTK-Unity, it controls initialization and updates and also lets you set a number of global variables. Set up the manager parameters as shown in the picture by checking the <cite>Use Realtime</cite> checkbox.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<img alt="SimulationManager Component UI" class="align-center" src="_images/simulationmanager.png" />
|
||||
<ul>
|
||||
<li><p>Create an empty GameObject, add a <code class="docutils literal notranslate"><span class="pre">PBDModel</span></code> component and name it <cite>HeartModel</cite>.</p>
|
||||
<blockquote>
|
||||
<div><p><code class="docutils literal notranslate"><span class="pre">PBDModel</span></code> is one of the classes that iMSTK-Unity offers, it implements the PBD <a class="footnote-reference brackets" href="#id4" id="id1">1</a> and XPBD <a class="footnote-reference brackets" href="#id5" id="id2">2</a> methods for simulating deformable objects.</p>
|
||||
<p>We will add geometry separately but you can also use the items under the menu <cite>Imstk\GameObject</cite> to add very simple objects with algorithmically generated meshes.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">PBDModel</span></code> has a large number of parameters but we will focus only on a few. This will eventually become a deformable object but there is still a lot of work to do. For more information look at the <a class="reference external" href="https://imstk.readthedocs.io/en/latest/PbdModel.html">Imstk Documentation</a></p>
|
||||
<p>We will come back to this later.</p>
|
||||
</div></blockquote>
|
||||
</li>
|
||||
<li><p>From the <em>Models</em> folder add model named <cite>heart</cite> under the <cite>HeartModel</cite> GameObject</p>
|
||||
<blockquote>
|
||||
<div><p>This will serve as the visual representation of what the simulation is doing, to make it look better get the <cite>flesh</cite> material from the <em>Materials</em> folder and assign it as well.</p>
|
||||
<p>With the <cite>heart</cite> GameObject selected add a <code class="docutils literal notranslate"><span class="pre">GeometryFilter</span></code> component to it and drag the <cite>MeshFilter</cite> component, the name will be <cite>Heart_mesh_surface (Mesh Filter)</cite> into the <cite>Mesh</cite> field of the <code class="docutils literal notranslate"><span class="pre">GeometryFilter</span></code>. The dropdown should say <cite>Unity Mesh</cite>. This makes this mesh available to iMSTK-Unity.</p>
|
||||
<p>For every kind of geometry you want to use in the PBD model, iMSTK-Unity needs a <code class="docutils literal notranslate"><span class="pre">GeometryFilter</span></code>. This maps the Unity type to something that iMSTK can understand. It can also be used to define fixed shapes like Plane or Capsule. For meshes the source of a Geometry filter can either be a Unity mesh in the scene, a mesh asset, or (especially for tetrahedral meshes) an asset imported by the geometry importer of imstk-Unity.</p>
|
||||
<p>You can use the check box named <cite>Show Handles</cite> to verify that the mesh is in the correct location</p>
|
||||
</div></blockquote>
|
||||
</li>
|
||||
</ul>
|
||||
<img alt="Drag Meshfilter into Geometryfilter" class="align-center" src="_images/geomfilter_heart_surface_drag.png" />
|
||||
<ul>
|
||||
<li><p>Set up the parameters for our <code class="docutils literal notranslate"><span class="pre">PBDModel</span></code></p>
|
||||
<p>First check the <cite>Distance Stiffness</cite>, <cite>Volume Stiffness</cite> and <cite>Use Realtime</cite> checkboxes and fill in the properties as you see in the image below. This sets the material properties of this object. Uncheck all other stiffness options</p>
|
||||
</li>
|
||||
</ul>
|
||||
<img alt="PBModel overview" class="align-center" src="_images/heartmodel.png" />
|
||||
<ul>
|
||||
<li><p>Add a <code class="docutils literal notranslate"><span class="pre">GeometryFilter</span></code> to use in the simulation</p>
|
||||
<p>We will need a mesh to use as the geometry for calculating the physical behavior of our object. Add a <code class="docutils literal notranslate"><span class="pre">GeometryFilter</span></code> to the <cite>HeartModel</cite> object. As we will use a tetrahedral mesh, the method to assign the mesh is slightly different than what we used before. First Select <cite>Tetrahedral Mesh</cite> in the dropdown box. Then click on the <cite>o</cite> icon to the right of the <cite>Mesh</cite> input field. This will bring up an input dialog. Select the “Assets” tab, and double click the item name <cite>heart_mesh</cite>.</p>
|
||||
<p>As you can see the <code class="docutils literal notranslate"><span class="pre">GeometryFilter</span></code> component can be used for meshes in the scene or just assets of the project.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<img alt="Tetrahedral Mesh Geometry Filter" class="align-center" src="_images/heart_mesh_tetrahedral.png" />
|
||||
<ul>
|
||||
<li><p>Now we will set the shapes that are being used for simulation and visualization.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">PBDModel</span></code> uses three different geometries</p>
|
||||
<ul class="simple">
|
||||
<li><p><cite>Visual Geometry</cite> is the geometry that is being shown on the screen, this is usually some textured mesh</p></li>
|
||||
<li><p><cite>Physics Geometry</cite> is the geometry that is being used in the simulation</p></li>
|
||||
<li><p><cite>Collision Geometry</cite> is the geometry that is being used to determine collisions with other objects.</p></li>
|
||||
</ul>
|
||||
<p>The tetrahedral mesh that was set up in the previous step will be used for the <cite>Physics Geometry</cite> the other mesh from earlier will be used for the two other geometries.</p>
|
||||
<p>First Drag the <code class="docutils literal notranslate"><span class="pre">Geometry</span> <span class="pre">Filter</span></code> that you just created into the <cite>Physics Geometry</cite> of the <code class="docutils literal notranslate"><span class="pre">PBDModel</span></code> component. Then drag the <cite>heart</cite> GameObject from the hierarchy view to both the <cite>Visual Geometry</cite> and the <cite>Collision Geometry</cite> fields.</p>
|
||||
<img alt="Assign Visual Geometry" class="align-center" src="_images/heart_gameobject_drag.png" />
|
||||
<p>As we used different geometries for visualization and simulation we need a way to keep those in the same state, this is the responsibility of the <code class="docutils literal notranslate"><span class="pre">GeometryMap</span></code> component. Add one and drag the <cite>HeartModel</cite> Gameobject into the <cite>Parent Geom</cite> slot. Then drag the <cite>heart</cite> GameObject into the <cite>Child Geom</cite> slot. Additionally make sure the <cite>Force One One</cite> is checked.</p>
|
||||
<img alt="Deformable Map" class="align-center" src="_images/deformable_map.png" />
|
||||
</li>
|
||||
</ul>
|
||||
<p>This concludes the setup for the <code class="docutils literal notranslate"><span class="pre">PBDModel</span></code> object.</p>
|
||||
<p>You should be able to run the scene now but as there are no other objects to interact with the heart will just succumb to gravity and drop on the ground.</p>
|
||||
<ul>
|
||||
<li><p>Lets add a plane for collisions</p>
|
||||
<p>Instead of meshes we will use a fixed shape for the other side of the collision. In the hierarchy view add a Plane and move it to a position of 0.0, -2.5, and 0.0. Add a <code class="docutils literal notranslate"><span class="pre">Geometry</span> <span class="pre">Filter</span></code> to the plane object and select <cite>Plane</cite> in the drop down menu. The default settings for the plane will work, its position and normal will be calculated from the transform. Even though the visual mesh of the plan is finite in the editor, with regards to iMSTK this plane is infinite.</p>
|
||||
<p>To enable the plane to interact with other iMSTK objects we need to set up a model for it as well. Add a <code class="docutils literal notranslate"><span class="pre">StaticModel</span></code> component to the <cite>Plane</cite> object and drag the <code class="docutils literal notranslate"><span class="pre">GeometryFilter</span></code> component into the <cite>Collision Geometry</cite> field. A <code class="docutils literal notranslate"><span class="pre">StaticModel</span></code> represents an object that participates in collision but doesn’t react.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<img alt="Plane Object" class="align-center" src="_images/plane-static-model.png" />
|
||||
<ul>
|
||||
<li><p>Add the interaction between the Heart and the Plane</p>
|
||||
<p>Imstk needs to know about which objects can interact with each other, in this case we want the heart and the plane to collide with each other. Add a <code class="docutils literal notranslate"><span class="pre">CollisionInteraction</span></code> to the plane object. Drag the <cite>HeartModel</cite> into the slot named <cite>Model 1</cite> and drag the plane itself into the slot named <cite>Model 2</cite>. The dropdown named <cite>Collision Type</cite> can be left in the setting <cite>Auto</cite>. At the moment there is most likely no need to select the <cite>Collision Type</cite> yourself, the automatic mechanism should be sufficient.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<img alt="Adding a collision interaction" class="align-center" src="_images/collision_interaction.png" />
|
||||
<ul class="simple">
|
||||
<li><p>This concludes the tutorial scene setup, press play you should see the deformable object hit the plane and bounce slightly on it.</p></li>
|
||||
</ul>
|
||||
<div class="compound">
|
||||
<p>Please note that at the moment iMSTK-Unity is very sensitive to misconfigurations and may cause Unity to crash, we are working to improve the error handling and stability both on the Unity asset side and inside the iMSTK sources.</p>
|
||||
</div>
|
||||
</section>
|
||||
<section id="example-scenes">
|
||||
<h1>Example Scenes<a class="headerlink" href="#example-scenes" title="Permalink to this heading"></a></h1>
|
||||
<section id="pbdclothcollision">
|
||||
<h2>PbdClothCollision<a class="headerlink" href="#pbdclothcollision" title="Permalink to this heading"></a></h2>
|
||||
<p>A scene with a freely moving deformable item (Cloth), shows how to set up a deformable (<code class="docutils literal notranslate"><span class="pre">PBDCloth</span></code>) with and various static obstacles.</p>
|
||||
</section>
|
||||
<section id="pbdclothscene">
|
||||
<h2>PbdClothScene<a class="headerlink" href="#pbdclothscene" title="Permalink to this heading"></a></h2>
|
||||
<p>A cloth constrained on the top, look at for how to set up boundary conditions on a <code class="docutils literal notranslate"><span class="pre">PbdObject</span></code></p>
|
||||
</section>
|
||||
<section id="pbdthread">
|
||||
<h2>PbdThread<a class="headerlink" href="#pbdthread" title="Permalink to this heading"></a></h2>
|
||||
<p>Sets up a line mesh that can be used as a thread</p>
|
||||
</section>
|
||||
<section id="rbdscene">
|
||||
<h2>RbdScene<a class="headerlink" href="#rbdscene" title="Permalink to this heading"></a></h2>
|
||||
<p>Simple example of two rigid spheres colliding with each other and the scenery. Uses geometric shapes rather than meshes, static colliders and collisions between dynamic objects</p>
|
||||
</section>
|
||||
<section id="id3">
|
||||
<h2>Tutorial<a class="headerlink" href="#id3" title="Permalink to this heading"></a></h2>
|
||||
<p>Scene that is used in the tutorial, uses a deformable model colliding with a plane</p>
|
||||
</section>
|
||||
<section id="devices">
|
||||
<h2>Devices<a class="headerlink" href="#devices" title="Permalink to this heading"></a></h2>
|
||||
<p>The scenes in the devices folder can only be used with VRPN or OpenHaptics built in. This means you have to build iMSTK and install it into the asset as described in <a class="reference internal" href="documentation.html#setupfordevelopment"><span class="std std-ref">Setup for Development</span></a></p>
|
||||
<section id="rbdcontroller">
|
||||
<h3>RbdController<a class="headerlink" href="#rbdcontroller" title="Permalink to this heading"></a></h3>
|
||||
<p>Sets up a <code class="docutils literal notranslate"><span class="pre">OpenHapticsDevice</span></code> with a <code class="docutils literal notranslate"><span class="pre">RbdModel</span></code> and a <code class="docutils literal notranslate"><span class="pre">RigidController</span></code> to show how these pieces interactive</p>
|
||||
</section>
|
||||
<section id="rbdcontrollervrpn">
|
||||
<h3>RbdControllerVRPN<a class="headerlink" href="#rbdcontrollervrpn" title="Permalink to this heading"></a></h3>
|
||||
<p>Uses the <code class="docutils literal notranslate"><span class="pre">VRPNDevice</span></code> in the same scene as the <cite>RBDController</cite></p>
|
||||
</section>
|
||||
<section id="tissuecontact-and-pbdthintissuecontact">
|
||||
<h3>TissueContact and PbdThinTissueContact<a class="headerlink" href="#tissuecontact-and-pbdthintissuecontact" title="Permalink to this heading"></a></h3>
|
||||
<p>Demonstrates the use of a rigid with haptics interacting with two kinds of simulated tissue</p>
|
||||
<dl class="footnote brackets">
|
||||
<dt class="label" id="id4"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
|
||||
<dd><ol class="upperalpha simple" start="13">
|
||||
<li><p>Müller, B. Heidelberger, M. Hennix, and J. Ratcliff, “Position based dynamics,” Journal of Visual Communication and Image Representation, vol. 18, no. 2, pp. 109–118, Apr. 2007, doi: 10.1016/j.jvcir.2007.01.005.</p></li>
|
||||
</ol>
|
||||
</dd>
|
||||
<dt class="label" id="id5"><span class="brackets"><a class="fn-backref" href="#id2">2</a></span></dt>
|
||||
<dd><ol class="upperalpha simple" start="13">
|
||||
<li><p>Macklin, M. Müller, and N. Chentanez, “XPBD: position-based simulation of compliant constrained dynamics,” in Proceedings of the 9th International Conference on Motion in Games, Burlingame California, Oct. 2016, pp. 49–54. doi: 10.1145/2994258.2994272.</p></li>
|
||||
</ol>
|
||||
</dd>
|
||||
</dl>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="documentation.html" class="btn btn-neutral float-left" title="Introduction" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="classes.html" class="btn btn-neutral float-right" title="Usage" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2022, Kitware.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user