Update documentation for Release 4 (#202)

* Documentation and readme update

Author: mlavik1

Documentation/Documentation.md

@@ -0,0 +1,20 @@
+# UnityVolumeRendering documentation
+
+## General documentation
+
+- [Importing datasets](General/Importing/ImportingDatasets.md)
+- [Using the imported datasets](General/VolumeRendering/GameObjectManipulation.md)
+- [Changing the appearance](General/VolumeRendering/VolumeRenderingSettings.md)
+- [Transfer Functions](General/TransferFunctions/TransferFunctions.md)
+- [Cross section tools](General/CrossSectionTools/CrossSectionTools.md)
+- [Slice renderer](General/SliceRenderer/SliceRenderer.md)
+- [Editor import settings](General/Settings/Settings.md)
+
+## Scripting documentation
+
+- [Importing datasets from code](Scripting/Importing.md)
+- [Raycasting the geometry on CPU](Scripting/VolumeRaycasting.md)
+
+## Other
+
+- [SimpleITK integration (for JPEG2000-compressed DICOM and more)](SimpleITK/SimpleITK.md)

Documentation/General/CrossSectionTools/CrossSectionTools.md

@@ -0,0 +1,47 @@
+# Cross section tools
+
+**Table of contents:**
+<!-- TOC -->
+
+- [Cross section tools](#cross-section-tools)
+    - [Cross section plane](#cross-section-plane)
+    - [Box cutout](#box-cutout)
+    - [Sphere cutout](#sphere-cutout)
+
+<!-- /TOC -->
+
+You can spawn cross section tools from the Volume Rendering menu option.
+
+<img src="menu-cross-section.png" width="400px">
+
+There are three types of cross section tools:
+
+## Cross section plane
+
+The cross section plane is a simple plane that can be moved around and rotate, to clip the volume at an arbitrary position and angle.
+
+<img src="plane-tool.png" width="400px">
+
+If you need axis aligned clipping planes, I would recommend to implement your own clipping plane tool that implements the `CrossSectionObject` interface, and add it to the `CrossSectionManager`. 
+
+## Box cutout
+
+The box cutout tool spawns a box that you can move around and roate to do a box cutout on a dataset.
+
+<img src="box-cutout.png" width="400px">
+
+The tool has two modes:
+- Exclusive: Cuts out everything that overlaps the box.
+- Inclusive: Cuts out everything that is outside the box.
+
+You can change these modes by selecting the "CutoutBox" GameObject in the hierarchy and changing the settings in the inspector:
+
+<img src="box-cutout-inspector.png" width="400px">
+
+## Sphere cutout
+
+The sphere cutout tool spawns a sphere that you can move around and roate to do a sphere cutout on a dataset.
+
+<img src="sphere-tool.png" width="400px">
+
+The tool works the same as the box cutout, and also has two modes: inclusive and exclusive.

Documentation/General/CrossSectionTools/box-cutout-inspector.png

@@ -0,0 +1,116 @@
+# Importing datasets in the editor
+
+**Table of contents:**
+<!-- TOC -->
+
+- [Importing datasets in the editor](#importing-datasets-in-the-editor)
+    - [Importing datasets through the "Volume Rendering" menu bar option](#importing-datasets-through-the-volume-rendering-menu-bar-option)
+        - [Raw datasets](#raw-datasets)
+            - [ini files](#ini-files)
+        - [DICOM datasets](#dicom-datasets)
+        - [NRRD datasets](#nrrd-datasets)
+        - [NIfTI datasets](#nifti-datasets)
+        - [VASP/PARCHG datasets](#vaspparchg-datasets)
+        - [Image sequence datasets](#image-sequence-datasets)
+    - [Importing datasets by drag and drop into the assets folder](#importing-datasets-by-drag-and-drop-into-the-assets-folder)
+    - [Importing datasets by right clicking in the Assets folder](#importing-datasets-by-right-clicking-in-the-assets-folder)
+- [Coordinate system and real size](#coordinate-system-and-real-size)
+
+<!-- /TOC -->
+
+For documentation on how to import datasets from code, see [Importing datasets form code](../../Scripting/Importing.md).
+
+There are several ways to import datasets into the editor:
+1. [Through "Volume Rendering" -> "Load dataset" in the menu bar.](#importing-datasets-through-the-volume-rendering-menu-bar-option)
+2. [By drag-and-drop dataset into the "Assets" directory](#importing-datasets-by-drag-and-drop-into-the-assets-folder) (only RAW/NRRD/NIFTI, Unity 2020.2+)
+3. [Right click in "Assets" directory and choose "Volume Rendering" -> "Import dataset"](#importing-datasets-by-right-clicking-in-the-assets-folder)
+
+## Importing datasets through the "Volume Rendering" menu bar option
+
+Click "Volume Rendering" in the menu bar and then "Load dataset" and select which dataset you want to import
+
+<img src="menu-bar-import.png" width="500px">
+
+### Raw datasets
+
+For raw datasets you simply select a single file to import.
+
+An import settings menu will then pop up Here you can set the import setting for the raw dataset. For the included sample files you don't need to change anything.
+
+The available settings are:
+- X dimension: Number of voxels/pixels in the x dimension (this may be the row count)
+- Y dimension: Number of voxels/pixels in the y dimension (this may be the column count)
+- Z dimension: Number of voxels/pixels in the z dimension (this may be the slice count)
+- Bytes to skip: If the dataset contains a header, this should be the size of that header - else it should be 0.
+- Data format: The format of the voxel data. This will usually be specified somewhere, either in a header or in some documentation for the dataset. You can replace "char" with "int" here (and "uchar" with "uint").
+- Endianness: Usually "little endian"
+
+#### .ini files
+
+If the folder contains a ".ini" with the same name (dataset.raw => dataset.raw.ini) then this will be used to populate the import settings with some default values. so you don't have to do it every time you import the same dataset.
+
+For an example .ini file, see [VisMale.raw.init](../../../DataFiles/VisMale.raw.ini).
+
+<img src="raw-import-settings.png" width="400px">
+
+### DICOM datasets
+
+To import a DICOM dataset, click "Load DICOM" and select the folder where the DICOM dataset is loaded.
+
+If the folder contains multiple series, these will be loaded as separate objects.
+
+**Note:** If you are or Windows or Linux it is recommended to [enable the SimpleITK importer](../../SimpleITK/SimpleITK.md), which is a requirement for JPEG2000 compressed DICOM and NRRD.
+
+### NRRD datasets
+
+To import an NRRD dataset, click "Load NRRD dataset" and select the .nrrd file to import.
+
+**Note:** To import NRRD datasets you need to [enable the SimpleITK importer](../../SimpleITK/SimpleITK.md).
+
+### NIfTI datasets
+
+To import a NIfTI dataset, click "Load NIFTI dataset" and select the .nii/.nii.gz file to import.
+
+**Note:** If you are or Windows or Linux it is recommended to [enable the SimpleITK importer](../../SimpleITK/SimpleITK.md), which should work better overall.
+
+### VASP/PARCHG datasets
+
+To import a VASP dataset, click "Load PARCGH dataset" and select the file to import.
+
+### Image sequence datasets
+
+Some datasets will be stored as a series of image files (similar to DICOM, but in .jpg/.png/.tiff format), where each image represents a slice. These are referred to as "image sequence" datasets.
+
+To import an image sequence, click "Load image sequence" and select the folder containing the slices.
+
+## Importing datasets by drag and drop into the assets folder
+
+To import a RAW/NRRD/NIFTI/PARCHG dataset (not DICOM or other image sequences), you can simply drag and drop the dataset file into the "Assets" directory.
+
+<img src="drag-drop-import.png" width="500px">
+
+This will create a new Asset file for the dataset.
+
+For RAW datasets you can change the import settings by clicking on the asset, changing the import settings in the inspector and clicking "Apply".
+
+<img src="raw-asset-settings.png" width="500px">
+
+To use these datasets, you can either:
+- Drag and drop the dataset asset into the scene view or scene hierarchy view in the editor (Unity 2021.2 or newer)
+- Spawn from code: Referencing the `VolumeDataset` asset somewhere in code, or through the Resources folder, and spawn it using the [VolumeObjectFactory](../../Scripting/Importing.md).
+
+## Importing datasets by right clicking in the Assets folder
+
+You can also import datasets by right clicking in "Assets" directory and choosing "Volume Rendering" -> "Import dataset"
+
+All datasets (also DICOM) can be imported this way.
+
+<img src="import-context-menu.png" width="500px">
+
+Using the imported dataset assets works the same as for [datasets imported by drag and drop](#importing-datasets-by-drag-and-drop-into-the-assets-folder)
+
+# Coordinate system and real size
+
+Coordinate systems are handled for DICOM and NRRD, and we convert to Unity's coordinate system using metre units.
+
+By default import datasets will have their size normalised. If you wish to keep the original size (so multiple datasets will fit well together), you can select the outer GameObject (the ones that has a `VolumeRenderedObject` component), and set its scale to (1,1,1).

Documentation/General/CrossSectionTools/box-cutout.png

@@ -0,0 +1,34 @@
+# Settings window
+
+This window exposes some dataset and import-related settings, for using the plugin in the Editor.
+
+## How to open the settings window
+
+You can open the settings window from the "Volume Rendering" menu bar option:
+
+<img src="menubar-settings.png" width="200px">
+
+## Available settings
+
+<img src="settings-window.png" width="400px">
+
+### Show downscale prompt
+
+When this setting is enabled, you will see a promt asking you if you wish to downscale the dataset every time you import a dataset in the editor.
+
+Imported datasets are automatically downscaled if they are too large to fit into a 3D texture. However, in some cases you may wish to downscale it even if this is not a problem (to save memory, etc.).
+
+### Enable SimpleITK
+
+If you're on Windows/Linux/Mac, you can optionally enable the SimpleITK-based importer.
+
+This has a couple of advantages:
+- Better DICOM support (faster import, and fewer issues)
+- JPEG2000 compressed DICOM support
+- NRRD support
+- Better NIFTI support
+- Support for image sequence datasets in TIFF format
+
+It is recommeneded to enable this if you don't only use RAW datasets.
+
+This is a native plugin, so to support other platforms you would need to build it yourself.

Documentation/General/CrossSectionTools/menu-cross-section.png

@@ -0,0 +1,36 @@
+# Slice renderer
+
+<img src="slice-renderer.png" width="400px">
+
+The slice renderer can be used to create a axis aligned (or free transform) slice view of a dataset.
+
+## How to open the slice renderer window
+
+You can open the slice renderer window from the "Volume Rendering" menu bar option:
+
+<img src="menubar-slice-renderer.png" width="200px">
+
+## Creating slicing planes
+
+To create a new slice renderer, click one of the "Create plane" buttons.
+
+<img src="options.png" width="400px">
+
+The buttons to the left can be used to navigate between different slices.
+
+## Rotating the slice view
+
+At the top of the window there are some more buttons.
+
+<img src="top-options.png" width="400px">
+
+The two rightmost buttons can be used to rotate the slice view 90 degrees.
+
+## Moving and measuring the slices
+
+The three buttons to the top left will change the current interaction mode:
+- **Move slice**: Left click + drag mouse up/down => Slice moves forwards/backwards
+- **Inspect values**: Left click somewhere in the view, and the value will be printed in the bottom left corner.
+- **Measure distances**: Left click and drag mouse to measure a linear distance. The value will be printed at the bottom left corner.
+
+<img src="interaction-modes.gif" width="400px">

Documentation/General/CrossSectionTools/plane-tool.png

@@ -0,0 +1,44 @@
+# Transfer functions
+
+You can use transfer functions to apply different colours and opacities to different parts of the dataset, resulting in more interesting visualisations.
+
+Ttransfer functions will map density (and optionally gradient magnitude) to a selected colour/opacity, enabling you to highlight parts of the dataset (skin, bones, etc.).
+
+You can open the transfer function editors from the "Volume Rendering" menu bar option in the editor:
+
+<img src="menubar-tf1d.png" width="400px">
+
+##  1. <a name='Dimensionaltransferfunctions'></a>1-Dimensional transfer functions
+
+This is the simplest type of transfer function to work with. It maps density values to a selected colour and opacity (transparency).
+
+<img src="tf1d.png" width="400px">
+
+The axes:
+- X-axis: Represents density values.
+- Y-axis: Represents alpha values (opacity).
+
+How to use:
+- Move the grey alpha knots to create a curve for opacity by density.
+    - Right-click to add new alpha knots.
+- The bottom gradient-coloured panel maps colour to density. Here you can select which colour a part of the dataset should have, based on the density values of the voxels.
+    - Right-click to add new knots and click on an existing colour knot to modify its colour.
+
+##  2. <a name='Dimensionaltransferfunctions-1'></a>2-Dimensional transfer functions
+
+**Note: The 2D TF editor is still work-in-progress.** I plan to improve it further. Suggestions and feedback is very welcome! ([create an issue](https://github.com/mlavik1/UnityVolumeRendering/issues/new) or [start a discussion thread](https://github.com/mlavik1/UnityVolumeRendering/discussions)).
+
+<img src="tf2d.png" width="400px">
+
+The axes:
+- X-axis: Represents density
+- Y-axis: Represents gradient magnitude.
+
+How to use:
+- Click "add rectangle" to add a new rectangle-shape.
+    - Click on the rectangle and drag to move it. 
+    - Drag the edges of the rectangle to change its shape.
+- Click on the colour picker to change the colour of the selected rectangle shape.
+- Change the "min alpha" and "max alpha" sliders to change the minimum and maximum opacity of the selected shape.
+    - The "max alpha" defines the opacity value at the centre of the shape.
+    - The "min alpha" defines the opacity value at the edges of the shape.

Documentation/General/CrossSectionTools/sphere-tool.png

@@ -0,0 +1,18 @@
+# Manipulating spawned datasets
+
+Datasets will be spawned as GameObjects, with a `VolumeRenderedObject` component attached to them.
+
+You can move, rotate and scale these objects like any other GameObject in the Unity Editor.
+
+<img src="movement.gif" width="400px">
+
+# Saving spawned datasets
+
+Spawned datasets can be saved as a part of the scene (simply save the scene).
+
+However, if the datasets are large (or many) this will cause the scene asset to become very large, and saving/loading will be slow (or crash!).
+To prevent this, you may consider importing your datasets as an Asset (see [import documentation](ImportingDatasets.md)) and referencing the already imported dataset through some script and spawning it through the [VolumeObjectFactory](../../Scripting/Importing.md).
+
+# Changing the appearance settings
+
+To change the appearance settings and other volume rendering related settings, see [the appearance settings documentation](VolumeRenderingSettings.md).

Documentation/General/Importing/ImportingDatasets.md

@@ -0,0 +1,51 @@
+# Volume rendering appearance settings
+
+**Table of contents:**
+<!-- TOC -->
+
+- [Cross section tools](#cross-section-tools)
+    - [Cross section plane](#cross-section-plane)
+    - [Box cutout](#box-cutout)
+    - [Sphere cutout](#sphere-cutout)
+
+<!-- /TOC -->
+
+To modify the appearance settings of a volume rendered dataset, simply select the object in the scene / scene hierarchy - and you will find the appearance settings under "Volume Rendered Object" in the inspector.
+
+<img src="inspector.png" width="400px">
+
+## Render mode
+
+<img src="rendermode.png" width="300px">
+
+There are 3 render modes:
+- Direct Volume Rendering (raymarching, using transfer functions)
+- Maximum Intensity Projection (shows the maximum density)
+- Isosurface Rendering (raymarching, stops when it hits a surface)
+
+## Lighting
+
+You can enable lighting to get more realistic visualisation.
+
+<img src="lighting.png" width="300px">
+
+This comes at a cost, and performance may suffer (both memory and rendering speed).
+
+To apply lighting to the volume rendering, we calculate the gradient at each voxel and use this to calculate a normal, which we use to apply phong lighting.
+
+## Cubic interpolation
+
+<img src="cubic-interpolation.png" width="300px">
+
+To reduce so-called "staircase artifacts", you can enable cubic interpolation.
+
+<img src="cubic-sampling-results.png" width="400px">
+
+This can be quite expensive in terms of performance - especially when lighting is enabled!
+
+# Early ray termination
+
+To improve performance, the raymarching shader may optionally exit early when enough samples have been accumulated.
+This is a very simple optimisation that improves performance by avoiding enumeration of invisible voxels.
+
+You usually want to leave this setting enabled, since it improves performance considerably - usually without any noticable visual changes.