Merge pull request #3 from KTHVisualization/main

New Isosurface Raycaster

Author: lquatrin

.gitignore

@@ -1,2 +1,3 @@
 .vs/
-bin/
+bin/
+data/eval*

AddingNewVolumeRenderer.md

@@ -0,0 +1,24 @@
+## Adding a new volume renderer
+
+All volume rendering algorithms are found in `cppvolrend/structured`. Assume we want to create a new renderer, which visualizes isosurfaces. We call it a *ray-casting 1-pass isosurface renderer*, or short `rc1piso`. These steps need to be taken to add it:
+
+* Create a new subfolder `cppvolrend/rc1piso` and add some files:
+* * Add the C++ files named `rc1pisorenderer.cpp` and `rc1pisorenderer.h`. Their content could come from one of the other algorithms, or be based on `volrendernull.cpp/h`.
+* * Add a compute shader called `ray_marching_1p_iso.comp`.
+* Edit `structured/CMakeLists.txt` to add the new C++ files in the call to `add_executable()`. Follow the structure of the existing text there.
+* Run CMake. The files should now be part of your buildsystem and appear in your IDE.
+* Include the new renderer in the list of renderers available to the program by adding a few lines in `structured/main.cpp`:
+
+```c++
+// near the beginning of main.cpp ...
+#include "structured/rc1piso/rc1pisorenderer.h"
+
+// ... and in the main function
+int main (int argc, char **argv)
+{
+    RenderingManager::Instance()->AddVolumeRenderer(new RayCasting1PassIso());
+}
+```
+
+You can now compile and test your new renderer.
+

Evaluation.md

@@ -0,0 +1,78 @@
+## Evaluation Possibilities
+
+Any class derived from `BaseVolumeRenderer` can make use of the built-in support for evaluating the parameters of an algorithm. To do so, one has to override the virtual function `FillParameterSpace` like this in the header file:
+
+```c++
+virtual void FillParameterSpace(ParameterSpace& pspace) override;
+```
+
+The implementation then needs to add the parameters that shall be evaluated. In the following example, two parameters are added:
+
+* the number of ambient occlusion shells `ambient_occlusion_shells`, to be evaluated in the range \[1, 20\] with a stepping of 1. This is an integer parameter.
+
+* the radius for ambient occlusion `ambient_occlusion_radius`, to be evaluated in the range \[0.1, 1.5\] with a stepping of 0.1. This is a float parameter.
+
+The code will interpret this as a 2-dimensional parameter space and evaluate all parameter combinations. In this example, that is $20 \times 15 = 300$ parameter combinations.
+
+```c++
+void RC1PExtinctionBasedShading::FillParameterSpace(ParameterSpace& pspace)
+{
+  pspace.ClearParameterDimensions();
+  pspace.AddParameterDimension(new ParameterRangeInt("AmbientOccShells", &ambient_occlusion_shells, 1, 20, 1));
+  pspace.AddParameterDimension(new ParameterRangeFloat("AmbientOccRadius", &ambient_occlusion_radius, 0.1f, 1.5f, 0.1f));
+}
+```
+
+The user is able to start the evaluation from the GUI by pressing the "Start Evaluation" button in the "Rendering Manager". The code in `BaseVolumeRenderer` will then measure the frames per second and take a snapshot for every parameter combination. The results are stored in a newly created subfolder of the current folder (probably under 'data'). It is named according to the scheme 'eval_DATE_TIME'. This folder contains a file 'eval.csv' with the measurements and a subfolder 'img' with the images.
+
+#### Plotting Performance
+
+Assume that 'eval.csv' looks like this:
+
+|StepSize|TimePerFrame (ms)|FramesPerSecond|ImageFile|
+|--------|-----------------|---------------|---------|
+|0.200000|18.950000        |52.770449      |0000.png |
+|0.300000|13.610000        |73.475386      |0001.png |
+|0.400000|10.870000        |91.996320      |0002.png |
+|0.500000|9.220000         |108.459870     |0003.png |
+|0.600000|8.030000         |124.533001     |0004.png |
+|0.700000|7.310000         |136.798906     |0005.png |
+|0.800000|6.640000         |150.602410     |0006.png |
+|0.900000|6.170000         |162.074554     |0007.png |
+|1.000000|5.760000         |173.611111     |0008.png |
+|1.100000|5.470000         |182.815356     |0009.png |
+|1.200000|5.200000         |192.307692     |0010.png |
+|1.300000|5.010000         |199.600798     |0011.png |
+|1.400000|4.720000         |211.864407     |0012.png |
+|1.500000|4.600000         |217.391304     |0013.png |
+|1.600000|4.460000         |224.215247     |0014.png |
+|1.700000|4.270000         |234.192037     |0015.png |
+|1.800000|4.250000         |235.294118     |0016.png |
+|1.900000|4.120000         |242.718447     |0017.png |
+
+It can be plotted like this:
+
+```py
+from matplotlib import pyplot as plt
+import pandas as pd
+import numpy as np
+
+d = pd.read_csv('eval.csv', quotechar='"')
+
+plt.plot(d['StepSize'], d['FramesPerSecond'], linestyle='dotted', marker='o')
+plt.title('Performance')
+plt.ylabel('Frames per Second')
+plt.xlabel('Step Size')
+
+plt.show()
+```
+
+#### Computing Image Differences
+
+The difference between the images can be assessed using different metrics. One example is the Structural Similarity Index Measure (SSIM). A simple call to [ImageMagick Compare](https://imagemagick.org/script/compare.php) suffices to measure this:
+
+```console
+magick compare -metric SSIM 0000.png 0001.png cmp_0000_0001.png
+```
+
+This also creates a comparison image where the differences are highlighted. Note that a number of [different metrics](https://imagemagick.org/script/command-line-options.php#metric) are supported and choosing the right one depends on the application. Some of the metrics also have parameters that may need attention.

cppvolrend/CMakeLists.txt

@@ -33,6 +33,9 @@ add_executable(cppvolrend
                # GPU Image Order Ray Casting
                structured/rc1pass/rc1prenderer.cpp                             structured/rc1pass/rc1prenderer.h
 
+               # GPU Image Order Iso Ray Casting with adaptive step size
+               structured/rc1pisoadapt/rc1pisoadaptrenderer.cpp                structured/rc1pisoadapt/rc1pisoadaptrenderer.h
+
                # Directional Ambient Occlusion and Cone Shadows Ground Truth
                structured/rc1pcrtgt/crtgtrenderer.cpp                          structured/rc1pcrtgt/crtgtrenderer.h
 

cppvolrend/main.cpp

@@ -21,6 +21,7 @@
 #include "volrendernull.h"
 // 1-pass - Ray Casting - GLSL
 #include "structured/rc1pass/rc1prenderer.h"
+#include "structured/rc1pisoadapt/rc1pisoadaptrenderer.h"
 #include "structured/rc1pcrtgt/crtgtrenderer.h"
 #include "structured/rc1pdosct/dosrcrenderer.h"
 #include "structured/rc1pextbsd/ebsrenderer.h"
@@ -57,6 +58,7 @@ int main (int argc, char **argv)
   //-----------------------------------------------------------------------------------------------------------------------------------------------------------------
   // 1-pass - Ray Casting - GLSL
   RenderingManager::Instance()->AddVolumeRenderer(new RayCasting1Pass());
+  RenderingManager::Instance()->AddVolumeRenderer(new RayCasting1PassIsoAdapt());
   RenderingManager::Instance()->AddVolumeRenderer(new RC1PConeLightGroundTruthSteps());
   RenderingManager::Instance()->AddVolumeRenderer(new RC1PConeTracingDirOcclusionShading());
   RenderingManager::Instance()->AddVolumeRenderer(new RC1PExtinctionBasedShading());

cppvolrend/renderingmanager.cpp

@@ -282,7 +282,7 @@ void RenderingManager::Display ()
       }
       m_eval_csvfile << std::to_string(time_per_frame) << ","
                      << std::to_string(frames_per_second) << ","
-                     << imagefilename << "\n";
+                     << "\"" << imagefilename << "\"\n";
 
 
       //We go to the next sample point in the parameter space.

cppvolrend/structured/rc1pextbsd/ebsrenderer.cpp

@@ -431,7 +431,7 @@ void RC1PExtinctionBasedShading::FillParameterSpace(ParameterSpace& pspace)
 {
   pspace.ClearParameterDimensions();
   pspace.AddParameterDimension(new ParameterRangeInt("AmbientOccShells", &ambient_occlusion_shells, 1, 20, 1));
-  pspace.AddParameterDimension(new ParameterRangeFloat("AmbientOccShells", &ambient_occlusion_radius, 0.1f, 1.5f, 0.1f));
+  pspace.AddParameterDimension(new ParameterRangeFloat("AmbientOccRadius", &ambient_occlusion_radius, 0.1f, 1.5f, 0.1f));
 }
 
 

cppvolrend/structured/rc1pisoadapt/evaluation/EvalSSIM_aneurism.csv

@@ -0,0 +1,201 @@
+StepSizeSmall,StepSizeLarge,StepSizeRange,TimePerFrame (ms),FramesPerSecond,ImageFile,SSIM
+0.01,0.25,0.05,54.63,18.304961,0000.png,0.999676
+0.01,0.25,0.1,56.51,17.695983,0001.png,0.999826
+0.01,0.25,0.15,59.45,16.820858,0002.png,0.999846
+0.01,0.25,0.2,65.22,15.33272,0003.png,0.999886
+0.01,0.25,0.25,80.58,12.410027,0004.png,1
+0.01,0.5,0.05,28.33,35.29827,0005.png,0.996657
+0.01,0.5,0.1,30.2,33.112583,0006.png,0.999303
+0.01,0.5,0.15,32.52,30.750308,0007.png,0.999794
+0.01,0.5,0.2,36.74,27.218291,0008.png,0.999874
+0.01,0.5,0.25,47.78,20.929259,0009.png,0.999973
+0.01,0.75,0.05,19.53,51.203277,0010.png,0.990922
+0.01,0.75,0.1,21.03,47.551117,0011.png,0.996815
+0.01,0.75,0.15,22.82,43.821209,0012.png,0.999151
+0.01,0.75,0.2,26.23,38.124285,0013.png,0.999768
+0.01,0.75,0.25,35.54,28.13731,0014.png,0.999919
+0.01,1.0,0.05,15.22,65.703022,0015.png,0.981849
+0.01,1.0,0.1,16.44,60.827251,0016.png,0.990622
+0.01,1.0,0.15,18.08,55.309735,0017.png,0.996066
+0.01,1.0,0.2,20.78,48.123195,0018.png,0.998663
+0.01,1.0,0.25,28.46,35.137034,0019.png,0.999784
+0.01,1.25,0.05,12.74,78.492936,0020.png,0.972032
+0.01,1.25,0.1,13.71,72.93946,0021.png,0.982644
+0.01,1.25,0.15,15.07,66.357001,0022.png,0.990107
+0.01,1.25,0.2,17.29,57.8369,0023.png,0.995363
+0.01,1.25,0.25,24.0,41.666667,0024.png,0.998623
+0.01,1.5,0.05,10.83,92.336103,0025.png,0.962472
+0.01,1.5,0.1,11.8,84.745763,0026.png,0.973366
+0.01,1.5,0.15,13.02,76.804916,0027.png,0.98197
+0.01,1.5,0.2,15.05,66.445183,0028.png,0.989707
+0.01,1.5,0.25,20.46,48.875855,0029.png,0.99579
+0.01,1.75,0.05,9.41,106.269926,0030.png,0.951985
+0.01,1.75,0.1,10.5,95.238095,0031.png,0.963262
+0.01,1.75,0.15,11.65,85.83691,0032.png,0.972954
+0.01,1.75,0.2,13.49,74.128984,0033.png,0.982014
+0.01,1.75,0.25,18.33,54.555374,0034.png,0.990505
+0.01,2.0,0.05,8.34,119.904077,0035.png,0.94338
+0.01,2.0,0.1,9.53,104.931794,0036.png,0.954123
+0.01,2.0,0.15,10.25,97.560976,0037.png,0.964068
+0.01,2.0,0.2,12.26,81.566069,0038.png,0.973842
+0.01,2.0,0.25,16.66,60.02401,0039.png,0.984166
+0.06,0.25,0.05,53.44,18.712575,0040.png,0.998113
+0.06,0.25,0.1,53.8,18.587361,0041.png,0.998232
+0.06,0.25,0.15,54.1,18.484288,0042.png,0.998248
+0.06,0.25,0.2,54.89,18.218255,0043.png,0.99824
+0.06,0.25,0.25,56.67,17.646021,0044.png,0.998114
+0.06,0.5,0.05,27.76,36.023055,0045.png,0.995304
+0.06,0.5,0.1,27.95,35.778175,0046.png,0.997759
+0.06,0.5,0.15,28.56,35.014006,0047.png,0.998217
+0.06,0.5,0.2,29.51,33.886818,0048.png,0.998293
+0.06,0.5,0.25,32.44,30.826141,0049.png,0.998175
+0.06,0.75,0.05,19.06,52.465897,0050.png,0.989928
+0.06,0.75,0.1,19.2,52.083333,0051.png,0.99552
+0.06,0.75,0.15,19.88,50.301811,0052.png,0.997673
+0.06,0.75,0.2,20.79,48.100048,0053.png,0.998129
+0.06,0.75,0.25,23.75,42.105263,0054.png,0.998108
+0.06,1.0,0.05,14.89,67.159167,0055.png,0.980959
+0.06,1.0,0.1,15.24,65.616798,0056.png,0.989417
+0.06,1.0,0.15,15.69,63.734863,0057.png,0.994581
+0.06,1.0,0.2,16.36,61.124694,0058.png,0.997021
+0.06,1.0,0.25,18.71,53.447354,0059.png,0.998095
+0.06,1.25,0.05,12.28,81.433225,0060.png,0.971476
+0.06,1.25,0.1,12.55,79.681275,0061.png,0.981756
+0.06,1.25,0.15,12.97,77.101002,0062.png,0.988902
+0.06,1.25,0.2,13.73,72.833212,0063.png,0.993966
+0.06,1.25,0.25,15.94,62.735257,0064.png,0.997032
+0.06,1.5,0.05,10.31,96.99321,0065.png,0.961927
+0.06,1.5,0.1,10.56,94.69697,0066.png,0.972575
+0.06,1.5,0.15,11.02,90.744102,0067.png,0.980996
+0.06,1.5,0.2,11.72,85.324232,0068.png,0.988437
+0.06,1.5,0.25,13.53,73.90983,0069.png,0.994149
+0.06,1.75,0.05,9.06,110.375276,0070.png,0.951541
+0.06,1.75,0.1,9.26,107.991361,0071.png,0.962561
+0.06,1.75,0.15,9.71,102.986612,0072.png,0.972131
+0.06,1.75,0.2,10.07,99.304866,0073.png,0.98102
+0.06,1.75,0.25,12.02,83.194676,0074.png,0.989198
+0.06,2.0,0.05,8.32,120.192308,0075.png,0.942953
+0.06,2.0,0.1,8.64,115.740741,0076.png,0.953542
+0.06,2.0,0.15,8.8,113.636364,0077.png,0.963267
+0.06,2.0,0.2,9.27,107.874865,0078.png,0.972877
+0.06,2.0,0.25,10.64,93.984962,0079.png,0.982895
+0.11,0.25,0.05,53.33,18.751172,0080.png,0.996976
+0.11,0.25,0.1,53.45,18.709074,0081.png,0.997033
+0.11,0.25,0.15,53.55,18.674136,0082.png,0.997034
+0.11,0.25,0.2,53.75,18.604651,0083.png,0.996946
+0.11,0.25,0.25,54.52,18.341893,0084.png,0.996958
+0.11,0.5,0.05,27.49,36.376864,0085.png,0.994583
+0.11,0.5,0.1,27.85,35.906643,0086.png,0.99682
+0.11,0.5,0.15,27.94,35.790981,0087.png,0.996998
+0.11,0.5,0.2,28.31,35.323207,0088.png,0.997045
+0.11,0.5,0.25,29.51,33.886818,0089.png,0.997044
+0.11,0.75,0.05,19.02,52.576236,0090.png,0.989371
+0.11,0.75,0.1,19.07,52.438385,0091.png,0.994651
+0.11,0.75,0.15,19.34,51.706308,0092.png,0.996514
+0.11,0.75,0.2,19.81,50.479556,0093.png,0.996901
+0.11,0.75,0.25,21.26,47.036689,0094.png,0.996881
+0.11,1.0,0.05,14.74,67.842605,0095.png,0.980529
+0.11,1.0,0.1,15.04,66.489362,0096.png,0.988861
+0.11,1.0,0.15,15.36,65.104167,0097.png,0.993832
+0.11,1.0,0.2,15.75,63.492063,0098.png,0.996077
+0.11,1.0,0.25,16.84,59.382423,0099.png,0.996908
+0.11,1.25,0.05,12.16,82.236842,0100.png,0.97108
+0.11,1.25,0.1,12.31,81.234768,0101.png,0.981096
+0.11,1.25,0.15,12.6,79.365079,0102.png,0.987986
+0.11,1.25,0.2,13.06,76.569678,0103.png,0.992897
+0.11,1.25,0.25,14.14,70.721358,0104.png,0.995832
+0.11,1.5,0.05,10.19,98.135427,0105.png,0.961661
+0.11,1.5,0.1,10.34,96.711799,0106.png,0.972167
+0.11,1.5,0.15,10.63,94.073377,0107.png,0.980316
+0.11,1.5,0.2,11.08,90.252708,0108.png,0.987633
+0.11,1.5,0.25,12.28,81.433225,0109.png,0.993304
+0.11,1.75,0.05,8.86,112.866817,0110.png,0.951287
+0.11,1.75,0.1,8.63,115.874855,0111.png,0.962176
+0.11,1.75,0.15,9.04,110.619469,0112.png,0.971603
+0.11,1.75,0.2,9.41,106.269926,0113.png,0.980168
+0.11,1.75,0.25,10.66,93.80863,0114.png,0.98827
+0.11,2.0,0.05,8.04,124.378109,0115.png,0.942686
+0.11,2.0,0.1,8.46,118.20331,0116.png,0.953185
+0.11,2.0,0.15,8.57,116.686114,0117.png,0.962736
+0.11,2.0,0.2,8.87,112.739572,0118.png,0.972205
+0.11,2.0,0.25,9.69,103.199174,0119.png,0.982099
+0.16,0.25,0.05,53.31,18.758207,0120.png,0.995808
+0.16,0.25,0.1,53.4,18.726592,0121.png,0.995702
+0.16,0.25,0.15,53.45,18.709074,0122.png,0.995768
+0.16,0.25,0.2,53.39,18.730099,0123.png,0.995682
+0.16,0.25,0.25,53.71,18.618507,0124.png,0.995718
+0.16,0.5,0.05,27.4,36.49635,0125.png,0.99381
+0.16,0.5,0.1,27.78,35.99712,0126.png,0.995528
+0.16,0.5,0.15,27.77,36.010083,0127.png,0.995593
+0.16,0.5,0.2,28.09,35.599858,0128.png,0.995611
+0.16,0.5,0.25,28.48,35.11236,0129.png,0.995614
+0.16,0.75,0.05,18.77,53.276505,0130.png,0.988901
+0.16,0.75,0.1,19.09,52.383447,0131.png,0.993727
+0.16,0.75,0.15,19.21,52.056221,0132.png,0.995435
+0.16,0.75,0.2,19.34,51.706308,0133.png,0.995631
+0.16,0.75,0.25,20.21,49.480455,0134.png,0.995684
+0.16,1.0,0.05,14.94,66.934404,0135.png,0.980139
+0.16,1.0,0.1,14.86,67.294751,0136.png,0.988085
+0.16,1.0,0.15,15.01,66.622252,0137.png,0.992747
+0.16,1.0,0.2,15.37,65.061809,0138.png,0.994865
+0.16,1.0,0.25,16.05,62.305296,0139.png,0.99551
+0.16,1.25,0.05,12.08,82.781457,0140.png,0.97069
+0.16,1.25,0.1,12.29,81.366965,0141.png,0.980368
+0.16,1.25,0.15,12.42,80.515298,0142.png,0.987134
+0.16,1.25,0.2,12.66,78.988942,0143.png,0.991892
+0.16,1.25,0.25,13.35,74.906367,0144.png,0.994662
+0.16,1.5,0.05,10.18,98.231827,0145.png,0.961414
+0.16,1.5,0.1,10.29,97.18173,0146.png,0.97165
+0.16,1.5,0.15,10.47,95.510984,0147.png,0.979676
+0.16,1.5,0.2,10.74,93.10987,0148.png,0.98678
+0.16,1.5,0.25,11.47,87.183958,0149.png,0.992204
+0.16,1.75,0.05,9.11,109.769484,0150.png,0.950966
+0.16,1.75,0.1,8.62,116.009281,0151.png,0.961572
+0.16,1.75,0.15,9.21,108.577633,0152.png,0.970792
+0.16,1.75,0.2,9.34,107.066381,0153.png,0.979323
+0.16,1.75,0.25,10.12,98.814229,0154.png,0.987197
+0.16,2.0,0.05,8.38,119.331742,0155.png,0.942567
+0.16,2.0,0.1,8.19,122.100122,0156.png,0.95285
+0.16,2.0,0.15,8.44,118.483412,0157.png,0.962194
+0.16,2.0,0.2,8.68,115.207373,0158.png,0.971533
+0.16,2.0,0.25,9.28,107.758621,0159.png,0.981184
+0.21,0.25,0.05,53.36,18.74063,0160.png,0.994481
+0.21,0.25,0.1,53.43,18.716077,0161.png,0.994242
+0.21,0.25,0.15,53.43,18.716077,0162.png,0.994389
+0.21,0.25,0.2,53.37,18.737118,0163.png,0.994533
+0.21,0.25,0.25,53.47,18.702076,0164.png,0.994286
+0.21,0.5,0.05,27.54,36.310821,0165.png,0.992945
+0.21,0.5,0.1,27.44,36.443149,0166.png,0.994239
+0.21,0.5,0.15,27.75,36.036036,0167.png,0.994315
+0.21,0.5,0.2,27.72,36.075036,0168.png,0.994327
+0.21,0.5,0.25,28.22,35.435861,0169.png,0.994404
+0.21,0.75,0.05,18.56,53.87931,0170.png,0.988134
+0.21,0.75,0.1,19.03,52.548607,0171.png,0.992662
+0.21,0.75,0.15,19.1,52.356021,0172.png,0.994181
+0.21,0.75,0.2,19.18,52.137643,0173.png,0.994229
+0.21,0.75,0.25,19.66,50.8647,0174.png,0.99428
+0.21,1.0,0.05,14.8,67.567568,0175.png,0.979666
+0.21,1.0,0.1,14.89,67.159167,0176.png,0.987201
+0.21,1.0,0.15,14.94,66.934404,0177.png,0.991718
+0.21,1.0,0.2,15.06,66.401062,0178.png,0.993559
+0.21,1.0,0.25,15.67,63.816209,0179.png,0.994131
+0.21,1.25,0.05,12.1,82.644628,0180.png,0.970338
+0.21,1.25,0.1,12.18,82.101806,0181.png,0.979753
+0.21,1.25,0.15,12.35,80.97166,0182.png,0.986335
+0.21,1.25,0.2,12.45,80.321285,0183.png,0.990858
+0.21,1.25,0.25,12.98,77.041602,0184.png,0.993384
+0.21,1.5,0.05,10.25,97.560976,0185.png,0.961003
+0.21,1.5,0.1,10.39,96.246391,0186.png,0.97102
+0.21,1.5,0.15,10.42,95.96929,0187.png,0.979003
+0.21,1.5,0.2,10.67,93.720712,0188.png,0.985902
+0.21,1.5,0.25,11.18,89.445438,0189.png,0.991085
+0.21,1.75,0.05,8.61,116.144019,0190.png,0.9508
+0.21,1.75,0.1,9.13,109.529025,0191.png,0.961241
+0.21,1.75,0.15,9.13,109.529025,0192.png,0.970255
+0.21,1.75,0.2,9.15,109.289617,0193.png,0.978823
+0.21,1.75,0.25,9.92,100.806452,0194.png,0.986409
+0.21,2.0,0.05,8.13,123.00123,0195.png,0.94228
+0.21,2.0,0.1,8.22,121.654501,0196.png,0.952347
+0.21,2.0,0.15,8.41,118.906064,0197.png,0.961575
+0.21,2.0,0.2,8.62,116.009281,0198.png,0.970709
+0.21,2.0,0.25,8.6,116.27907,0199.png,0.98025