[[TOC]]
Keratin intermediate filaments are protein threads that are located inside cells of epithelial tissues such as skin and are responsible for the mechanical stability of these tissues.
This project allows you to view these filaments in a 3-Dimensional space, either in VR or on your Desktop and provides you with the tool to classify and color them to your specifications. It was created in cooperation with Prof. Dr. rer. nat. Reinhard Windoffer from the Institute of Molecular and Cellular Anatomy of the RWTH Aachen University Hospital for the corresponding paper Quantitative mapping of keratin networks in 3D.
- VR Headset (Recomended: HTC Vive)
- VR-ready PC
-
Unreal Engine 4.22.3
You can download the Unreal Engine here. You need a free epic games account before you can download the Unreal Engine. Choose a creator's license, when asked.
-
Microsoft Visual Studio 2017 Community or Professional, at least version 15.9.0
Older Visual Studio versions can be found here. A free microsoft account is needed to download and continuously use Visual Studio.
During installation of visual studio, make sure to install the following workloads: Desktop development with C++ and Game development with C++
Please note that versions of Unreal Engine greater than 4.22 and Visual Studio 2017 do not currently work.
First you have to clone this repository with the following command:
git clone --recurse-submodules https://devhub.vr.rwth-aachen.de/VR-Group/zytoskelett.gitIn order to start the Project, navigate to the root directory and double-click the zytoskelett2.uproject file. If you have multiple Unreal Engines installed, make sure to launch it with 4.22.3.
In order to load a cytoskeleton into the scene, you need an input file located in the subfolder Content/Data, relative to the project's root directory. If it doesn't exist, create it yourself. You will need one line for each vertex of your cell. Each line has to contain the following values:
- n_segment as an integer for every filament. Each vertex belonging to the same filament has the same line number.
- n_vert as an integer. Unique for every vertex within the same filament.
- (x, y, z)-position as a floating point number.
- density as a floating point number. Describes the thickness of the segment.
- class identifier, a number between 1 and 5.
id color 1 green 2 blue 3 red 4 orange 5 white - flag not used here but required by another program
All these values are seperated by tabulators. The values have to be in exactly this order. No values can be left out.
Example:
n_segment n_vert x y z density class flag
1 1 10.2 20.34 3.17 1422.89875 1 NaN
1 2 10.23 20.4 3.23 1422.89875 1 NaN
2 1 10.53 20.72 3.59 1964.99 1 NaN
2 2 10.62 20.81 3.56 1964.99 1 NaN
To change the name of the file to import, load your project in the Unreal Engine Editor and select the Zytoskelett Data Actor from the scene browser on the right. In the properties window below, choose Filename in the Menu Zytoskelett - Eingabe and change the name to your data files name including the file extension (e.g. .dat). Also, an actor is created in the subfolder Content/Data for easy reuse.
The changed cytoskeleton can be exported into a file of the same format as the input file. It will have an _exported added to its input file name. The only value that will be changed is the class, so when importing that file the next time your filaments will keep their assigned class.
The Zytoskelett project comes with an example file, found here: zytoskelett\Content\Data\ex_003_2_UNREAL.dat
Further Datasets can be found here.
You can select different viewport options by clicking the little arrow on the right side of the Play button. In order to run the project on desktop, use the option "Selected Viewport" or "New Editor Window".
When running in VR, make sure the HMD is connected and correctly set up. Then click "VR Preview" and use the project on the HMD.
| # | description |
|---|---|
| W, A, S, D | move through the scene |
| arrow keys | rotate the view |
| left mouse button | change the class of the selected segment |
| number key 1 | cycles the currently selected class from 1 through 5 |
| number key 2 | stops the VR-Pawn movement and enables the mouse cursor. The filament under the mouse cursor will change its class when left clicking |
| number key 3 | starts exporting an existing cytoskeleton into an output file |
| number key 4 | starts importing the chosen file an creating a cytoskeleton in the scene |
| # | description |
|---|---|
| 1 | move forward |
| 2 | move backward |
| 3 | move left |
| 4 | move right |
| 5 | Assign Class to Filament |
| 6 | Import Data |
| 7 | Cycle Filament Class |
| 8 | -- |
| 9 | Export Data |
| 10 | Assign Class to Filament |
| # | description |
|---|---|
| 1, 2 | up: move forward down: move backward left: move left right: move right |
| 3, 6 | Assign Class to Filament |
| 4, 5 | up: Cycle Filament Class down: Export Data left: Import Data right: Export Data |
currently not supported
-
After starting the project, you'll see the following screen
-
In the top right corner, a window that shows the numbers of the segment and vertex currently pointed at, and which class is assigned to it. In VR, the window is not shown.
-
A ray is coming out of the camera (or the right controller, when in VR). This points at the segment you are interacting with.
-
The data file (example is provided) can be loaded by pressing the import key (key map see below).
-
Flying close enough to a filament (indicated by square at the end of the ray) lets you assign a different class to it.
-
Export the annotated data by pressing the export key. The successful export is indicated by a message in the top left corner of the screen.
The input settings can be changed on a per-device basis under Edit > Project Settings > Engine > Input.
To change the input, the dropdown menus can be used. Furter input methods can be added by clicking the plus sign. For each action or axis mapping, the first input method represents mouse and keyboard input while the others are used for the HMDs.
The action mappings trigger the following events:
| action mapping name | event description |
|---|---|
| Fire | apply filament class |
| Action1 | cycle filament class |
| Action2 | stop movement and enable mouse controls |
| Action3 | export data |
| Action4 | import data |
The axis mappings control the following movements:
| axis mapping name | movement description |
|---|---|
| MoveForward | Keyboard: movement parallel to the line of sight HMD: movement parallel to the direction to which the right controller is pointing |
| MoveRight | movement perpendicular to the vector described above |
| TurnRate | turn the viewport left and right (keyboard only) |
| LookUpRate | turn the viewport up and down (keyboard only) |