Move random number generation to the GPU
[camsim.git] / README.md
1 # CamSim
2
3 ## Overview
4
5 This is a camera simulation library developed at the 
6 [Computer Graphics Group, University of Siegen](http://www.cg.informatik.uni-siegen.de).
7
8 Supported cameras types:
9
10 - RGB cameras, optionally physically plausible, with OpenGL-style materials and
11   lighting
12
13 - Amplitude-modulated continuous-wave Time-of-Flight cameras (AMCW ToF, e.g. PMD cameras),
14   with 4 phase images, physically plausible, reusing OpenGL-style materials and lighting
15   as far as it makes sense
16
17 Features:
18
19 - Simulation:
20   - light-transport based information (RGB, PMD phases and result)
21   - geometry information (positions, normals, depth and range, object/shape/
22     triangle indices)
23   - temporal flow information (2D and 3D flow)
24
25 - Scene:
26   - Arbitrary number of light sources (point lights, spot lights, and
27     directional lights)
28   - Light sources with measured intensity distribution and structured-light
29     projecting light sources
30   - Materials with ambient, diffuse, specular, gloss, emission and lightness maps;
31     transparency (but not translucency); bump or normal maps; BRDF-based lighting
32     (in the simplest case using the modified Phong model)
33   - Builtin functions to create scenes using simple geometries (quads, cubes,
34     cylinders, cones, spheres, tori, teapots, bunnies, etc)
35
36 - Animation:
37   - Simple linear animations of position, orientation, and scale
38   - For camera, light sources, and objects
39
40 - Oversampling:
41   - Spatial, with custom weights (especially useful for PMD simulation)
42   - Temporal (for correct motion artefacts in light-transport based
43     simulations)
44
45 - Noise and Effects:
46   - Gaussian white noise
47   - Lens distortion compatible to OpenCV (radial and tangential)
48   - Thins lens vignetting effect
49
50 - Import and Export:
51   - Import of arbitrary models via ASSIMP
52   - Export to RAW, CSV, PNM, PNG, PFS, GTA, MAT, HDF5
53
54 - Other:
55   - Multi-GPU support
56   - Multicore CPU support for export (data export is typically the bottleneck)
57
58
59 ## Requirements
60
61 Only [Qt](https://www.qt.io/) is required, nothing else. You can *optionally*
62 use external libraries to extent functionality:
63 - [libassimp](http://www.assimp.org/): import arbitrary 3D models
64 - [libmatio](https://sourceforge.net/projects/matio/): export to Matlab .mat files
65 - [libhdf5](https://support.hdfgroup.org/HDF5/): export to .h5 files
66 - [libgta](https://marlam.de/gta/): export to .gta files
67
68 First build *and install* libcamsim. Then compile and link your application
69 against the *installed* version of libcamsim (not against the files in its
70 build directories).
71
72
73 ## Usage
74
75 Libcamsim requires an OpenGL 4.5 core context. You should typically create
76 such a context using an offscreen surface (see the examples).
77
78 There is Doxygen-style documentation (build with `CAMSIM_BUILD_DOCUMENTATION=ON`
79 to generate HTML), but the best starting point is probably to look at the
80 example programs.
81
82 If you want to display results in an interactive application, create another
83 context that shares OpenGL objects with the libcamsim context, so that you can
84 render the textures that libcamsim produces. If you do this, you might need to
85 call glFinish() on the libcamsim context after calling simulate() to make sure
86 the result textures are finished before reusing them in another OpenGL
87 context, since there is no implicit synchronization between contexts.
88
89 If you want to use multiple GPUs, create offscreen contexts for each of them
90 (this step is system dependent). Contexts on different GPUs cannot share
91 objects, so each of these contexts must get its own scene and simulator
92 instances. For example, if you import a model file, you must add its contents
93 to all scene instances.
94
95 Note that the bottleneck is almost always the export, not the simulation
96 itself! Export data without compression, and use a write-efficient file
97 format! For example, simulating and exporting 125 floating point RGB frames of
98 size 800x600 took the following time in seconds for different file formats,
99 without compression: 1.5 (raw), 1.5 (gta), 4.9 (ppm), 7.0 (pfs), 7.0 (mat),
100 7.2 (png), 7.2 (h5), 118 (csv). Most of the time, it is a good idea to export
101 .raw or .gta and postprocess / convert these results afterwards.
102
103
104 ## Relevant Papers
105
106 The following papers are relevant for CamSim. If you use this software, please
107 cite the appropriate paper, depending on the features you are using:
108
109 - General simulation model, including AMCW ToF illumination and sensor:
110   M. Lambers, S. Hoberg, A. Kolb:
111   [Simulation of Time-of-Flight Sensors for Evaluation of Chip Layout Variants](http://ieeexplore.ieee.org/xpl/articleDetails.jsp?reload=true&arnumber=7054461).
112   In IEEE Sensors Journal, 15(7), 2015, pages 4019-4026.
113
114 - Extension of the illumination model to single-bounce indirect illumination via
115   reflective shadow maps:
116   D. Bulczak, M. Lambers, A. Kolb:
117   [Quantified, Interactive Simulation of AMCW ToF Camera Including Multipath Effects](http://doi.org/10.3390/s18010013).
118   In MDPI Sensors, 18(1), 2018, pages 1424-8220.
119
120 - Lens distortion simulation:
121   M. Lambers, H. Sommerhoff, A. Kolb: [Realistic Lens Distortion Rendering](http://wscg.zcu.cz/wscg2018/2018-WSCG-Papers-Separated.html).
122   In Proc. Int. Conf. in Central Europe on Computer Graphics, Visualization and
123   Computer Vision (WSCG), 2018.