.. centered:: |image0|

.. centered:: **Imstk-Unity**

.. centered:: *User Documentation*

Introduction
============

This document describes the iMSTK-Unity interface as well as how to build and develop it.

Overview
-----------------------

Imstk is a free & open source C++ toolkit for prototyping of interactive multi-modal surgical simulations.

Unity is a game engine written in C/C++ with a nice GUI interface. Unity provides three coding interfaces C#, “UnityScript (flavor of javascript)”, and `Boo <https://en.wikipedia.org/wiki/Boo_(programming_language)>`_.

Imstk-Unity utilizes the SWIG wrapping functionality of Imstk which generates C# wrappings. These C# wrappings are effectively functions that forward and call C++ code. It allows you to use Imstk in C# much the same way as you would in C++ with a few subtle differences. This allows usage of Imstk in Unity.

   .. figure:: media/ImstkUnityArchitecture1.png
    :width: 600
    :alt: Alternative text
    :align: center

Project Structure
-----------------------

The code repository is on gitlab `here <https://gitlab.kitware.com/iMSTK/imstk-unity>`_. You can see its issues with various labels. The following directories are currently used:

   - **Imstk/Editor**: This directory is for the editor scripts of the plugin. Editor scripts may use runtime scripts.

   - **Imstk/Scripts**: This directory is for the runtime scripts of the plugin. Runtime scripts may not use editor scripts. Editor scripts are not shipped with the resulting Unity program.

   - **Imstk/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).

   - **Imstk/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.

   - **Imstk/Packages**: This directory contains the manifest for external packages (such as probuilder).

Setup for Development
=====================

A complete package of Imstk-Unity can be created but it is preferred to build from source when developing. This requires first building Imstk.

Imstk uses CMake for its build system. Imstk is a superbuild meaning it builds, includes, and links to all of its dependencies. There is no need to go find them. To build Imstk you need to clone `Imstk <https://gitlab.kitware.com/iMSTK/iMSTK>`_ and build using cmake. In cmake you must toggle on iMSTK_WRAP_CSHARP. This will generate ".cs" files as well as ".dlls"/".so" files in your install directory that are needed by the ".cs" code. These will be used in Unity.

After Imstk is built in Imstk-Unity you must open the project directory in Unity and navigate to "Edit->Project Settings->Imstk Settings". Here you will find a "Developer Mode" button. When turned on, upon starting Unity, you will prompted to install imstk. After turned on you may restart Unity, when it prompts you, select yes and provide it your imstk install directory, located in <imstk build directory>/install. It will thenc opy over these ".cs" files as well as ".dll" or ".so" files. If you make changes in Imstk you must reinstall it to Unity via this method. After install it will continue to prompt you, select no the latter time. I would then recommend turning off developer mode.

Note: There is a 'Force Install' button to install imstk into Unity at the instant it is clicked. This may no always work depending on if an imstk script (that dllimports) has run in the editor. The moment an imstk script dllimports, the dll's cannot be unloaded from Unity. Which is why we prompt on startup.

Note: Make sure Unity is not running. Sometimes it can close but still be running in the background prevenint installation.

Debugging
-------------------------

Debugging may be done in visual studios, even on the native side. You must attached the debugger as you would to an external process. With Imstk open in visual studios, click debug->attach to process. Select the unity executable and make sure you're set on native debugging.

Usage
============

For minimal usage of Imstk-Unity, two things must be added to a Unity Scene.

   - A GameObject with a SimulationManager attached to it
   - A GameObject with a Model attached to it.

Commonly a PhysicsGeometry is also needed on the Model GameObject.

Importers
-------------------------
Imstk-Unity provides a single custom Unity importer to import geometry using Imstk. This may import point, line, surface, tetrahedral, & hexahedral meshes (vtk, vtu, stl, ply, veg, ...). If the mesh importing is a point, line, or surface mesh then it will be imported as a Unity Mesh object. Anything else is not suported by Unity thus is loaded as an ImstkUnity Geometry. If a volumetric mesh (such as a tetrahedral mesh) is imported the accompanying surface is extracted and provided as an additional asset.

SimulationManager
-------------------------
SimulationManager is a GameObject Component responsible for managing the simulation. There may only exist one. It also controls the construction, initialization, and destruction of ImstkBehaviour's to ensure execution ordering: Simulation Manager created -> Imstk objects created and internally initialized -> Imstk objects externally initialized -> SimulationManager Start -> ... -> Imstk objects cleaned up -> SimulationManager cleaned up.

This Component is required to be on one GameObject for simulations to run. It is created before any other Imstk Components on any GameObjects. It implements the start, stop, pause, and other global scene related tasks.

ImstkBehaviour
-------------------------
An extension of MonoBehaviour to provide different callbacks for special construction, initialization, and destruction ordering.

GeometryFilter
-------------------------
Similar to a MeshFilter in Unity. It provides an input and output geometry. It may take in any imstk geometries, as well as a Unity Mesh (one can also drag/drop a MeshFilter to it). These are instances of geometries used in all of imstk unity scripts.

Editor
-------------------------
Imstk-Unity provides extensions to the Unity editor. These extensions include:

   - Custom inspectors for the models and geometry components.
   - A global settings menu.
   - Menu Items for quick creation of GameObjects with Imstk items already setup.
   - Editors/windows for various operations

Bibliography
------------

.. [sample-bib] Sample reference.

.. |image0| image:: media/logo.png
   :width: 3.5in
   :height: 1.28515625in