Commit aa7eaf6f authored by Harald Scheirich's avatar Harald Scheirich
Browse files

Merge branch 'fix/release-fixups' into 'main'

Prepare repository for unity packaging

See merge request !43
parents b3908be8 40ce0456
fileFormatVersion: 2
guid: 7b51c44e2d9da174ea92e0fc073710f5
folderAsset: yes
DefaultImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant:
fileFormatVersion: 2
guid: 8a66d2b9bd9c46345a517814e31cce23
folderAsset: yes
DefaultImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant:
========
Releases
========
2022-jul 1.0 Coincides with iMSTK 6.0, first release.
- General Infrastructure
- ``PbdModel``, ``RbdModel``
......@@ -12,15 +12,15 @@ Commonly a PhysicsGeometry is also needed on the Model ``GameObject``.
Component Structure
==============================
While the C# wrapper supports almost all iMSTK classes, there is a subset that is made available as unity components, this can be assembled in the editor to create simulations using iMSTK inside of Unity.
While the iMSTK C# wrapper supports almost all iMSTK classes. There is a subset that is made available as Unity components. These can be assembled in the editor to create simulations using iMSTK inside of Unity. The following section describes the roles and responsibilities of the available iMSTK-Unity classes
Infrastructure
------------------------------
``SimulationManager``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is a component responsible for controlling the simulation. There may only exist one. It also controls the construction, initialization, and destruction of ``iMSTKBehaviour`` to ensure execution ordering:
``SimulationManager`` is a component responsible for managing the simulation. There may only exist one. It also controls the construction, initialization, and destruction of ``iMSTKBehaviour`` to ensure execution ordering:
- Simulation Manager created
- iMSTK objects created and internally initialized
- iMSTK objects externally initialized
......@@ -53,7 +53,7 @@ Use this behavior to mark vertices on a deformable object as `fixed`. This means
Importers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
iMSTK-Unity provides a custom Unity importer to import geometry using iMSTK. This can import point, line, surface, tetrahedral, & hexahedral meshes (vtk, vtu, stl, ply, veg, ...). If the mesh imported is a point, line, or surface mesh then it will be imported as a Unity Mesh object. Anything else not supported by Unity, is loaded as an iMSTKUnity Geometry Object. When a volumetric mesh (such as a tetrahedral mesh) is imported the accompanying surface is extracted and provided as an additional asset.
iMSTK-Unity provides a custom Unity importer to import geometry using iMSTK. This can import point, line, surface, tetrahedral, & hexahedral meshes (vtk, vtu, stl, ply, veg, ...). If the mesh imported is a point, line, or surface mesh then it will be imported as a Unity Mesh object. Anything else not supported by Unity, is loaded as an iMSTK-Unity Geometry Object. When a volumetric mesh (such as a tetrahedral mesh) is imported the accompanying surface is extracted and provided as an additional asset.
Editor Scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -88,7 +88,7 @@ The physics geometry determines the type of constraint that can be used, an inva
``RbdModel``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use this to represent moveable rigid objects like forceps or scalpels. Visual and collision geometry can be assigned separately, this behavior will update the transform of the GameObject with each update. For more information set the `iMSTK Documentation <https://imstk.readthedocs.io/en/latest/Dynamical_Models.html#rigid-body-2>`__
Use this to represent moveable rigid objects like forceps or scalpels. Visual and collision geometry can be assigned separately, this behavior will update the transform of the GameObject with each update. For more information see the `iMSTK Documentation <https://imstk.readthedocs.io/en/latest/Dynamical_Models.html#rigid-body-2>`__
``StaticModel``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -114,7 +114,7 @@ Devices
``OpenHapticsDevice``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This device is only available with a custom build of iMSTK. It enable the use of the `3DSystems <https://www.3dsystems.com/haptics>`_ haptic device.
This device is only available with a custom build of iMSTK. It enables the use of the `3DSystems <https://www.3dsystems.com/haptics>`_ haptic device family.
``VrpnDevice``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -40,7 +40,9 @@ if not os.path.exists('./git-lfs'):
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.githubpages']
'sphinx.ext.githubpages',
# 'docxbuilder'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['ntemplates']
......
......@@ -22,30 +22,30 @@ The iMSTK-Unity classes utilizes a C# interface of iMSTK that is generated by us
Limitations
-----------------------
This is an early release, not all iMSTK classes are easily accessible through the unity layer. Additionally there may be some combinations that have not been tested. Some errors _may_ cause Unity to crash, save early and save often. Please report issues you encounter in the iMSTK-Unity `issue tracker <https://gitlab.kitware.com/iMSTK/imstk-unity/-/issues>`_
Not all iMSTK classes are currently accessible through the Unity layer. Additionally there may be some combinations that have not been tested. Some errors *may* cause Unity to crash, save early and save often. Please report issues you encounter in the iMSTK-Unity `issue tracker <https://gitlab.kitware.com/iMSTK/imstk-unity/-/issues>`_
While there is an OpenHaptics asset available at the store. Currently iMSTK-Unity does not support that, if you need support for the 3D-Touch series of devices you will have to build iMSTK with the appropriate settings.
While there is an OpenHaptics asset available on the `Unity Asset Store <https://assetstore.unity.com/packages/tools/integration/haptics-direct-for-unity-v1-197034>`_. This is currently unsupported by the iMSTK Unity Asset. If you need support for the 3D-Touch series of devices you will have to build iMSTK with the appropriate settings.
Project Structure
-----------------------
The files of the asset are split in the following directories:
- **iMSTK/Scripts**: This directory is for the runtime scripts of the plugin.
- **Scripts**: This directory is for the runtime scripts of the plugin.
- **iMSTK/Scripts/Editor**: This directory is for the editor scripts of the plugin. These scripts implement custom editor functionality. Editor scripts may use runtime scripts but won't be included in the player, which means you should not use functions from these in your own scripts
- **Scripts/Editor**: This directory is for the editor scripts of the plugin. These scripts implement custom editor functionality. Editor scripts may use runtime scripts but won't be included in the player, which means you should not use functions from these in your own scripts
- **iMSTK/Resources**: This directory contains resources required during runtime.
- **Resources**: This directory contains resources required during runtime.
- **iMSTK/Editor/Resources**: This directory contains resources required in the editor (such as style sheets or UI markup).
- **Editor/Resources**: This directory contains resources required in the editor (such as style sheets or UI markup).
- **iMSTK/Plugins**: This directory is for libraries (dlls/so) that Unity needs to load.
- **Plugins**: This directory is for libraries (dlls/so) that Unity needs to load.
Directories needed for the project but not relevant to the plugin:
- **iMSTK/Models, Materials, & Textures**: These directories are for various assets used by the Demo. They are not part of the plugin.
- **Models, Materials, & Textures**: These directories are for various assets used by the Demo. They are not part of the plugin.
The asset on the store may not contain the latest version of iMSTK-Unity, if you want to be up to date you can check out the sources `from gitlab <https://gitlab.kitware.com/iMSTK/iMSTK-unity>`_. As the binary files for iMSTK aren't included in the repository, you will also have to build iMSTK yourself when you go this route.
The asset on the store may not contain the latest version of iMSTK-Unity, if you want to be up to date you can check out the sources `from gitlab <https://gitlab.kitware.com/iMSTK/imstk-unity>`_. As the binary files for iMSTK aren't included in the repository, you will also have to build iMSTK yourself when you go this route.
.. _SetupForDevelopment:
......@@ -56,8 +56,8 @@ When checking out iMSTK-Unity from gitlab you will first need to build iMSTK. iM
You can install the binaries two different ways, for both methods you need to know the directory in which iMSTK was installed. If you didn't change anything that directory will be called `install` and resides inside the directory that you defined in cmake to build imstk, e.g. ``C:\Projects\imstk\build\install`` :
- Using ```InstallImstk.bat``` from the asset directory the format is
``InstallImstk.bat <path to imstk/install>``
- Using ```Tools~\InstallImstk.bat``` from the asset directory the format is
``Tools~\InstallImstk.bat <path to imstk/install>``
- Alternatively you can enable `Developer Mode` for iMSTK inside of Unity. This option ca be found in "Edit->Project Settings->iMSTK Settings". When turned on, you will be prompted to install iMSTK whenever you start Unity. After turning on this option, you may need to restart Unity. When it prompts you, select yes and provide your iMSTK install directory, located in ```<iMSTK build directory>/install```. All the necessary files will be copied. If you don't want to be asked to reinstall iMSTK toggle this option off again.
......@@ -70,7 +70,7 @@ Note: Make sure Unity is not running, even though closed it may be running in th
Devices
=======
The asset available from the asset store does not have `OpenHaptics <https://support.3dsystems.com/s/article/OpenHaptics-for-Windows-Developer-Edition-v35?language=en_US>`_ or `VRPN <https://github.com/vrpn/vrpn>`_ enabled. To use external devices you will have to build iMSTK for yourself. When building enable
The asset available from the asset store does not have `OpenHaptics <https://support.3dsystems.com/s/article/OpenHaptics-for-Windows-Developer-Edition-v35?language=en_US>`_ or `VRPN <https://github.com/vrpn/vrpn>`_ enabled. To use external devices you will have to build iMSTK. When building, enable
``iMSTK_USE_VRPN`` or ``iMSTK_USE_OpenHaptics`` respectively. This will create a version of iMSTK with device support enabled. When the build is done install iMSTK into the Unity Asset as described above.
Debugging
......
......@@ -17,51 +17,51 @@ For the purpose of this guides component names will be written in a mono-spaced
The ``SimulationManager`` 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 `Use Realtime` checkbox.
.. image:: media/guide/simulationmanager.png
:align: center
:alt: SimulationManager Component UI
.. image:: media/guide/simulationmanager.png
:align: center
:alt: SimulationManager Component UI
- Create an empty GameObject, add a ``PBDModel`` component and name it `HeartModel`.
``PBDModel`` is one of the classes that iMSTK-Unity offers, it implements the PBD [#]_ and XPBD [#]_ methods for simulating deformable objects.
We will add geometry separately but you can also use the items under the menu `Imstk\\GameObject` to add very simple objects with algorithmically generated meshes.
We will add geometry separately but you can also use the items under the menu `iMSTK\\GameObject` to add very simple objects with algorithmically generated meshes.
The ``PBDModel`` 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 `Imstk Documentation <https://imstk.readthedocs.io/en/latest/PbdModel.html>`_
The ``PBDModel`` 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 `iMSTK Documentation <https://imstk.readthedocs.io/en/latest/PbdModel.html>`_
We will come back to this later.
- From the *Models* folder add model named `heart` under the `HeartModel` GameObject
This will serve as the visual representation of what the simulation is doing, to make it look better get the `flesh` material from the *Materials* folder and assign it as well.
This will serve as the visual representation of what the simulation is doing, to make it look better, get the `flesh` material from the *Materials* folder and assign it as well.
With the `heart` GameObject selected add a ``GeometryFilter`` component to it and drag the `MeshFilter` component, the name will be `Heart_mesh_surface (Mesh Filter)` into the `Mesh` field of the ``GeometryFilter``. The dropdown should say `Unity Mesh`. This makes this mesh available to iMSTK-Unity.
With the `heart` GameObject selected add a ``GeometryFilter`` component to it and drag the `MeshFilter` component, the name will be `Heart_mesh_surface (Mesh Filter)` into the `Mesh` field of the ``GeometryFilter``. The drop down menu should say `Unity Mesh`. This makes this mesh available to iMSTK-Unity.
For every kind of geometry you want to use in the PBD model, iMSTK-Unity needs a ``GeometryFilter``. 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.
For every kind of geometry you want to use in the PBD model, iMSTK-Unity needs a ``GeometryFilter``. 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.
You can use the check box named `Show Handles` to verify that the mesh is in the correct location
.. image:: media/guide/geomfilter_heart_surface_drag.png
:align: center
:alt: Drag Meshfilter into Geometryfilter
.. image:: media/guide/geomfilter_heart_surface_drag.png
:align: center
:alt: Drag Meshfilter into Geometryfilter
- Set up the parameters for our ``PBDModel``
First check the `Distance Stiffness`, `Volume Stiffness` and `Use Realtime` 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
.. image:: media/guide/heartmodel.png
:align: center
:alt: PBModel overview
.. image:: media/guide/heartmodel.png
:align: center
:alt: PBModel overview
- Add a ``GeometryFilter`` to use in the simulation
We will need a mesh to use as the geometry for calculating the physical behavior of our object. Add a ``GeometryFilter`` to the `HeartModel` object. As we will use a tetrahedral mesh, the method to assign the mesh is slightly different than what we used before. First Select `Tetrahedral Mesh` in the dropdown box. Then click on the `o` icon to the right of the `Mesh` input field. This will bring up an input dialog. Select the "Assets" tab, and double click the item name `heart_mesh`.
We will need a mesh to use as the geometry for calculating the physical behavior of our object. Add a ``GeometryFilter`` to the `HeartModel` object. As we will use a tetrahedral mesh, the method to assign the mesh is slightly different than what we used before. First Select `Tetrahedral Mesh` in the drop down menu. Then click on the `o` icon to the right of the `Mesh` input field. This will bring up an input dialog. Select the "Assets" tab, and double click the item name `heart_mesh`.
As you can see the ``GeometryFilter`` component can be used for meshes in the scene or just assets of the project.
.. image:: media/guide/heart_mesh_tetrahedral.png
:align: center
:alt: Tetrahedral Mesh Geometry Filter
.. image:: media/guide/heart_mesh_tetrahedral.png
:align: center
:alt: Tetrahedral Mesh Geometry Filter
- Now we will set the shapes that are being used for simulation and visualization.
......@@ -71,7 +71,7 @@ For the purpose of this guides component names will be written in a mono-spaced
- `Physics Geometry` is the geometry that is being used in the simulation
- `Collision Geometry` is the geometry that is being used to determine collisions with other objects.
The tetrahedral mesh that was set up in the previous step will be used for the `Physics Geometry` the other mesh from earlier will be used for the two other geometries.
The tetrahedral mesh that was set up in the previous step will be used for the `Physics Geometry`; the other mesh from earlier will be used for the two other geometries.
First Drag the ``Geometry Filter`` that you just created into the `Physics Geometry` of the ``PBDModel`` component. Then drag the `heart` GameObject from the hierarchy view to both the `Visual Geometry` and the `Collision Geometry` fields.
......@@ -89,25 +89,29 @@ This concludes the setup for the ``PBDModel`` object.
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.
- Lets add a plane for collisions
- Let's add a plane for collisions
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 ``Geometry Filter`` to the plane object and select `Plane` 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.
To enable the plane to interact with other iMSTK objects we need to set up a model for it as well. Add a ``StaticModel`` component to the `Plane` object and drag the ``GeometryFilter`` component into the `Collision Geometry` field. A ``StaticModel`` represents an object that participates in collision but doesn't react.
.. image:: media/guide/plane-static-model.png
:align: center
:alt: Plane Object
.. image:: media/guide/plane-static-model.png
:align: center
:alt: Plane Object
- Add the interaction between the Heart and the Plane
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 ``CollisionInteraction`` to the plane object. Drag the `HeartModel` into the slot named `Model 1` and drag the plane itself into the slot named `Model 2`. The dropdown named `Collision Type` can be left in the setting `Auto`. At the moment there is most likely no need to select the `Collision Type` yourself, the automatic mechanism should be sufficient.
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 ``CollisionInteraction`` to the plane object. Drag the `HeartModel` into the slot named `Model 1` and drag the plane itself into the slot named `Model 2`. The drop down menu named `Collision Type` can be left in the setting `Auto`. At the moment there is most likely no need to select the `Collision Type` yourself, the automatic mechanism should be sufficient.
.. image:: media/guide/collision_interaction.png
:align: center
:alt: Adding a collision interaction
.. image:: media/guide/collision_interaction.png
:align: center
:alt: Adding a collision interaction
- This concludes the tutorial scene setup, press play you should see the deformable object hit the plane and bounce slightly on it.
.. image:: media/guide/heart_final.png
:align: center
:alt: The final result
.. compound::
......@@ -119,33 +123,33 @@ Example Scenes
PbdClothCollision
------------------------------
A scene with a freely moving deformable item (Cloth), shows how to set up a deformable (``PBDCloth``) with and various static obstacles.
A scene with a freely moving deformable item (Cloth) that demonstrates how to set up a deformable (``PBDCloth``) with and various static obstacles.
PbdClothScene
------------------------------
A cloth constrained on the top, look at for how to set up boundary conditions on a ``PbdObject``
A cloth constrained on the top that demonstrates how to set up boundary conditions on a ``PbdObject``
PbdThread
------------------------------
Sets up a line mesh that can be used as a thread
This demonstrates a line mesh that can be used as a thread
RbdScene
------------------------------
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
This is a 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
Tutorial
------------------------------
Scene that is used in the tutorial, uses a deformable model colliding with a plane
A scene that is used in the tutorial. It uses a deformable model colliding with a plane
Devices
------------------------------
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 :ref:`SetupForDevelopment`
The scenes in the devices folder can only be used with VRPN or OpenHaptics built. You will have to build iMSTK and install it into the asset as described in :ref:`SetupForDevelopment` to support these features
RbdController
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets up a ``OpenHapticsDevice`` with a ``RbdModel`` and a ``RigidController`` to show how these pieces interactive
This sets up a ``OpenHapticsDevice`` with a ``RbdModel`` and a ``RigidController`` to show how these pieces are interactive
RbdControllerVRPN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -5,7 +5,7 @@ Welcome to iMSTK-Unity
`iMSTK <https://www.imstk.org/>`_ is a free & open source C++ toolkit for the prototyping of interactive multi-modal surgical simulations. The iMSTK-Unity asset gives you access to its capabilities through the Unity authoring interface. While this asset is still under development you can already exercise a variety of parts of iMSTK inside of Unity. This guide will help you get acquainted with the architecture and workings of the plugin.
The latest version of this documentation can be found on `readthedocs <https://imstk-unity.readthedocs.io/en/latest/>`_
The latest version of this documentation can be found on `ReadTheDocs <https://imstk-unity.readthedocs.io/en/latest/>`_
.. toctree::
:maxdepth: 2
......
Supports Markdown
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