Merge pull request #43 from MicroscopeIT/michalisk/rename-and-final-i…

…mprovements

Rename to "Essential Vision", input specs improvements, button 2x speed, button to toggle transparency

Input documentation/VTK_Input_data_specification.md

@@ -1,18 +1,18 @@
 # VTK input file specification
 
-In order to upload your model into the application, your data needs to follow specific folder and file structure listed below. Additionally, apart from the unicorn_heart model, there is a quick test example within this folder, containing the simplest configuration for you to ensure everything is working correctly.
+This file describes how folders and data files should be arranged to upload then into our application. Anatomical data (meshes) and simulation data (i.e data to be visualised on the anatomy) should be provided as separate layers. As a reference, we provide two examples showing the basic working structure -- see the [Test Model](https://github.com/MicroscopeIT/holo/tree/master/Input%20documentation/Test%20Model) and [UnicornHeart](https://github.com/MicroscopeIT/holo/tree/master/UnicornHeart) subdirectories.
 
 ## Data folder structure specification
 
 All data describing a model should place in one root folder. The structure is as follows:
 
 - `XXX` - Root folder.
 
-	- `body`* - Folder with vtk meshes, which are animation frames for the model mesh. One such folder for each mesh layer can be present. Inside the folder, place each frame in a separate VTK file with a consecutive number.
+    - `body`* - Folder with VTK meshes, describing the anatomy. One such folder for each mesh layer can be present. Inside the folder, place each frame in a separate VTK file with a consecutive number.
 
-	- `simulation`* - Folder with dataflow simulation vtk files - animation frames for data simulation. One such folder for each simulation layer can be present. Inside the folder, place each frame in a separate VTK file with a consecutive number.
+    - `simulation`* - Folder with simulation VTK files. One such folder for each simulation layer can be present. Inside the folder, place each frame in a separate VTK file with a consecutive number.
 
-	- `ModelInfo.json` - info file with the name of a model (caption to be displayed to user) and additional information about each layer.
+    - `ModelInfo.json` - info file with the name of a model (caption to be displayed to user) and additional information about each layer.
 
 You can choose any names for the root and layer folders. Simply make sure to list the appropriate layer directory names inside `ModelInfo.json`.
 
@@ -43,12 +43,11 @@ You can choose any names for the root and layer folders. Simply make sure to lis
 
 ## Data files general specification
 
-VTK is a versatile format, allowing user to save its model in various combinations. As such, we would like to standardise the data that are going to be used in our application. Below are general rules that apply to every file, regardless whether it's a body or simulation frame:
+VTK is a versatile format, allowing user to save its model in various combinations. As such, we would like to standardise the data that are going to be used in our application. Below are general rules that apply to every layer (regardless whether it's anatomy or simulation):
 
-- All data should be made in accordance with VTK file format description. (https://www.vtk.org/VTK/img/file-formats.pdf).
+- All data should be made in accordance with [VTK file format description](https://www.vtk.org/VTK/img/file-formats.pdf).
 - All data should be stored in ASCII format and of UNSTRUCTURED_GRID dataset type.
 - One file is representing one frame in the animation.
-- File concerning one mesh/one simulation should be stored in one folder separately.
 - Each frame should have its number stated at the end, and the numbers should be zero-padded e.g.: XYZ_01.vtk, XYZ_02.vtk etc.
 - Number of frames should be the same in every root subfolder.
 - Every file starts with four lines listed below, followed by an empty line:
@@ -61,72 +60,79 @@ DATASET [POLYDATA/UNSTRUCTURED_GRID]
 ```
 Type of the dataset depends on the data inside.
 
-## Body data
+## Anatomical (mesh) data
 Dataset type **UNSTRUCTURED_GRID**
 
 Two fields are required; **POINTS** and **CELLS**.
 
--   **POINTS** are all the vertices that are defining the mesh in that particular frame. No additional vertices should be found there. A vertex is defined by 3 floats, corresponding to its x, y and z coordinates in that particular order. Additionally:
+- **POINTS** define vertices positions the mesh in one particular frame. No additional vertices should be found there. A vertex is defined by 3 floats, corresponding to its x, y and z coordinates in that particular order. Additionally:
 
-	-  The number after the POINTS flag indicates number of vertices in a mesh.
-	- There should be only one vertex per line.
-	- Number and order of vertices between frames is not supposed to change.
+    - The integer number after the POINTS flag indicates number of vertices in a mesh.
+    - There should be only one vertex per line.
+    - Number and order of vertices between frames is not supposed to change.
 
--   **CELLS** define mesh facets.  Currently we are supporting two types of topology - lines and triangles. A facet is defined first by a number of points which it consists of and then a list of indexes, indicating the vertices which belong to the facet. Furthermore:
+- **CELLS** defines mesh facets. Currently we support two types of topology -- lines and triangles. A facet is defined first by the number of connected vertices followed by the vertices' indexes. Vertex index is interpreted according to the entry order specified in POINTS. Furthermore:
 
-	- The number after the CELLS flag indicates number of facets in a mesh.
-	- There should be only one facet per line.
-	- Number and order of facets between frames is not supposed to change.
-	- In case of triangles, counter-clockwise winding order is required.
+    - The integer number after the CELLS flag indicates the number of facets in a mesh (first number) and the total number of integers in the CELL section (second number).
+    - There should be only one facet per line.
+    - Number and order of facets between frames is not supposed to change.
+    - In case of all polygons, consistent winding order is required. We advise using counter-clockwise winding order (as seen from the outside of the mesh), although the clockwise ordering will also work, as long as it is consistent.
+    - Only one **CELLS** section in the file is supported.
+
+- The VTK format also requires **CELL_TYPES**, so you should add it to the VTK file. Although it is ignored by our application: in our application, the first column within each CELLS row indicates whether it's a triangle, quad etc.
 
 ## Simulation data
 Dataset type: **POLYDATA**
 
-Currently, there are two types of data that we can simulate: fibre orientation data and flow simulation data. Both types differ from each other in structure, which is described below. Similarly to the body data, you can find them in the test files within this folder.
+With simulation data we refer to the vector field that we want to visualise on the anatomy described by the mesh in the _Anatomical (mesh) data_ section. Currently,we can only visualize vector fields: fibre orientation and flow data. Both types differ from each other in structure, which is described below. As in the case of the anatomy data, you can find the examples of files and directory structures in this folder.
 
 ### Fibre orientation data
 
-Four fields are mandatory: **POINTS**; **SCALARS alpha float**, **SCALARS beta float** and **Vectors fn float** all three under **POINT_DATA** section.
+Two sections are mandatory: **POINTS** and **POINT_DATA**. Moreover within the **POINT_DATA**, place subsections **SCALARS alpha float**, **SCALARS beta float** and **Vectors fn float**.
 
-- **POINTS** are vertices signifying initial vector point.
-	-  The number after the POINTS flag indicates number of vertices in a mesh.
-	- There should be only one vertex per line.
-	- Number and order of vertices between frames is not supposed to change.
+- **POINTS** are vertices specifying vector locations.
+    - The integer number after the POINTS flag indicates number of vertices in a mesh.
+    - There should be only one vertex per line.
+    - Number and order of vertices between frames is not supposed to change.
 
  - **POINT_DATA**
-	- Number by the **CELL_DATA** flag indicates number of colours/vectors and should be consistent with number beside **POINTS** flag.
-	-
-	- **SCALARS alpha float** and **SCALARS beta float** are angles in radians, describing position of the vector orientation in space.
-		- There should be only one angle per line and vertex.
-		- Number and order of angles shouldn't change between the frames.
-		- Each angle in both lists is corresponding to a vertex in **POINTS**, mapped by their order.
-	- Each angle should be a float.
-
-	- **Vectors fn float** is a list of vectors, signifying orientation of a particular fibre.
-		- Similar to **POINTS**, Vectors are described by 3 (x,y,z) floats.
-		- There should be only one vector per line and vertex.
-		- Each vector is corresponding to a vertex in **POINTS**, mapped by their order.
-		- Number and order of vectors between frames is not supposed to change.
+    - Number by the **POINT_DATA** flag indicates number of colours/vectors and should be consistent with number of points specified in the **POINTS** section.
+
+    - **SCALARS alpha float** and **SCALARS beta float** are angles in radians, describing position of the vector orientation in space.
+        - Each angle should be a float.
+        - These values are used for the colormap visualisation of the vector.
+        - There should be only one angle (scalar) per line and vertex.
+        - Number and order of angles shouldn't change between the frames.
+        - Each angle (scalar) corresponds to a vertex in **POINTS**, mapped by their order.
+
+    - **Vectors fn float** is a list of vectors, defining the orientation of a particular fibre.
+        - Similar to **POINTS**, Vectors are described by 3 (x,y,z) floats.
+        - There should be only one vector per line and vertex.
+        - Each vector is corresponding to a vertex in **POINTS**, mapped by their order.
+        - Number and order of vectors between frames is not supposed to change.
+
+- Note that we ignore the **CELLS** information for the simulation. We don't need this information, as we assume that the simulation data is composed only from points.
 
 ### Flow data
-Four fields are mandatory: **POINTS**; **COLOR_SCALARS** and **Vectors fn float** all two under **CELL_DATA** section.
 
-- **POINTS** are vertices signifying initial vector point.
-	-  The number after the POINTS flag indicates number of vertices in a mesh.
-	- There should be only one vertex per line.
-	- Number and order of vertices between frames is not supposed to change.
+Two sections are mandatory: **POINTS** and **CELL_DATA**. Moreover within the **CELL_DATA**, place subsections **COLOR_SCALARS** and **Vectors fn float**.
+
+- **POINTS** are vertices that define the initial vector point.
+    - The number after the POINTS flag indicates number of vertices in a mesh.
+    - There should be only one vertex per line.
+    - Number and order of vertices between frames is not supposed to change.
 
 - **CELL_DATA**
-	- Number by the **CELL_DATA** flag indicates number of colours/vectors and should be consistent with number beside **POINTS** flag
-
-	- **COLOR_SCALARS** is a list of 3 dimensional vectors, describing colour of each simulation point in RGB system.
-		- Similar to **POINTS**, Vectors are described by 3 (x,y,z) floats.
-		- There should be only one RGB vector per line and vertex.
-		- Each vector is corresponding to a vertex in **POINTS**, mapped by their order.
-		- Number and order of colors between frames is not supposed to change.
-
-	- **Vectors fn float** is a list of vectors, signifying orientation and speed of a particular point in the flow. We use this vector's length and color to visualise the speed of this point in the flow.
-		- Similar to **POINTS**, Vectors are described by 3 (x,y,z) floats.
-		- There should be only one vector per line and vertex.
-		- Each vector is corresponding to a vertex in **POINTS**, mapped by their order.
-		- Number and order of vectors between frames is not supposed to change.
+    - Number by the **CELL_DATA** flag indicates number of colours/vectors and should be consistent with number beside **POINTS** flag
+
+    - **COLOR_SCALARS** is a list of 3 dimensional vectors, describing colour of each simulation point in RGB system.
+        - Similar to **POINTS**, Vectors are described by 3 (x,y,z) floats.
+        - There should be only one RGB vector per line and vertex.
+        - Each vector is corresponding to a vertex in **POINTS**, mapped by their order.
+        - Number and order of colors between frames is not supposed to change.
+
+    - **Vectors fn float** is a list of vectors, signifying orientation and speed of a particular point in the flow. We use this vector's length and color to visualise the speed of this point in the flow.
+        - Similar to **POINTS**, Vectors are described by 3 (x,y,z) floats.
+        - There should be only one vector per line and vertex.
+        - Each vector is corresponding to a vertex in **POINTS**, mapped by their order.
+        - Number and order of vectors between frames is not supposed to change.

README.md

@@ -1,15 +1,12 @@
-# Holo Model Series
+# Essential Vision
 
-## Project location
-
-Unity project is located in unity/Holo directory
-To see initial model please load **AnimatedModels** scene located in *Assets/Scenes*
+Application to visualize animated 3D medical data using Hololens, with shared experience. See the [official webpage of Essential Vision](https://www.essential-vision.org/) for more detailed list of features and demo videos.
 
 ## Installation
 
 ### Prerequisites
   * Setup Hololens with Windows Device Portal enabled: https://docs.microsoft.com/en-us/windows/mixed-reality/using-the-windows-device-portal
-  * Install Holo Model Series application on Hololens (use relasese versions: https://github.com/MicroscopeIT/holo/releases)
+  * Install _Essential Vision_ application on Hololens (use relasese versions: https://github.com/MicroscopeIT/holo/releases)
     Application instalation: https://docs.microsoft.com/en-us/hololens/hololens-install-apps#use-the-windows-device-portal-to-install-apps-on-hololens
 
   **IMPORTANT**
@@ -36,7 +33,7 @@ Open Unity project from unity/Holo.
 
 1. Go to Windows Device Portal of Hololens headset
 2. Go to _**System -> File Explorer**_
-3. Navigate to: _**User Folders \ LocalAppData \ HoloModelSeries\_1.0.0.0_x86\_\_<hash/crc> \ LocalState**_
+3. Navigate to: _**User Folders \ LocalAppData \ EssentialVision\_1.0.0.0_x86\_\_<hash/crc> \ LocalState**_
 4. Upload Asset Bundle files (**\_bundle** along with **\_bundle.manifet**) in to **LocalState** directory one by one with the *Upload* button (first you need to select file from hard drive, you can drag and drop it as well)
 
 ## Usage
@@ -51,6 +48,12 @@ After starting the application, choose the "Shared Experience" mode in the UI:
 
 Teacher can then choose a model, choose layers to display inside, transform it and so on.
 
-Note that currently HoloModelSeries application loads only AssetBundles uploaded to Hololens headset. Models must be uploaded before application is run (rescanning of the collection's models is not yet implemented).
+Note that currently the application loads only AssetBundles uploaded to Hololens headset. Models must be uploaded before application is run (rescanning of the collection's models is not yet implemented).
+
+**IMPORTANT**: If you upload new models, the application must be closed. For the moment you need to run other application for the system to unload completly _Essential Vision_ application.
+
+## Developing in Unity
+
+Unity project is located in `unity/Holo` directory.
 
-**IMPORTANT**: If you upload new models HoloModelSeries must be closed. For the moment you need to run other application for the system to unload completly HoloModelSeries application.
+To see initial model please load **AnimatedModels** scene located in *Assets/Scenes*.

unity/Holo/Assets/Editor/ModelLoad/ModelImport/VTKImport/VTKImporter.cs

@@ -21,13 +21,17 @@ abstract class VTKImporter : IFileImporter
         };
         protected string datasetType;
 
+        private string filePath;
+
         public VTKImporter(string datasetType)
         {
             this.datasetType = datasetType;
         }
 
-        public void ImportFile(string filePath)
+        public void ImportFile(string aFilePath)
         {
+            filePath = aFilePath;
+
             using (StreamReader streamReader = new StreamReader(filePath, Encoding.ASCII))
             {
                 streamReader.ReadLine(); //DataFile version
@@ -51,7 +55,8 @@ protected void CheckType(StreamReader streamReader)
             if (!datasetType.Equals(currentDatasetType))
             {
                 EditorUtility.ClearProgressBar();
-                throw new Exception("Wrong dataset type!");
+                throw new Exception("Wrong dataset type. Expected " + datasetType + 
+                    ", got " + currentDatasetType + ". VTK file: " + filePath);
             }
         }