initial code drop

README.txt

@@ -0,0 +1,236 @@
+***********************************************************************
+*** An implementation of
+***
+*** Lehtinen, J., Aila, T., Laine, S., and Durand, F. 2012,
+*** Reconstructing the Indirect Light Field for Global Illumination,
+*** ACM Transactions on Graphics 31(4) (Proc. ACM SIGGRAPH 2012), article 51.
+***
+*** http://groups.csail.mit.edu/graphics/ilfr
+*** http://dx.doi.org/10.1145/2185520.2185547
+***********************************************************************
+
+System requirements
+===================
+
+- Microsoft Windows XP, Vista, or 7. Developed and tested only on 
+Windows 7 x64. 
+
+- An OpenGL 2.0+ capable GPU. Required for the user interface regardless
+of whether or not GPU reconstruction is used.
+
+- For filtering large sample sets, several gigabytes of memory and a 
+64-bit operating system. 
+
+- For GPU reconstruction: 
+
+	* NVIDIA CUDA-compatible GPU with compute capability 2.0 and at least 
+	512 megabytes of RAM. GeForce GTX 480 or above is recommended. The 
+	implementation is optimized for the Fermi architecture (e.g. GTX 480, 
+	580).
+
+	* NVIDIA CUDA 5.0 or later. Built and tested on 5.0 Release 
+	Candidate. (See http://developer.nvidia.com/cuda-toolkit-archive)
+
+	* Microsoft Visual Studio 2010 with Service Pack 1. Required even if you 
+	do not plan to build the source code, as CUDA compilation, which happens 
+	at runtime, requires it. 
+
+- This software runs and compiles only on Windows and Visual Studio 2010 
+Service Pack 1. We welcome contributions of ports to other versions of 
+Visual Studio and other OSs. 
+
+
+
+Instructions
+============
+
+General use
+-----------
+
+Launching reconstruction_app.exe will start the viewer application,
+which by default loads a sample buffer from the data/ directory. The
+default view (F1) shows the input samples with box filtering, which
+results in a noisy image.
+
+Pressing F2 (or clicking the corresponding button in the GUI) will run
+our GPU reconstruction algorithm using diffuse settings and display
+the result, provided you have a CUDA device with compute capability of
+2.0 or over installed. F3 performs reconstruction using the CPU version.
+
+F4 and F5 run the glossy code path (GPU/CPU). See notes below for details. 
+
+
+
+Sample Buffer Format
+--------------------
+
+Sample buffers are stored in two files: the main file that contains
+the sample data itself, and a second header file, whose name must
+match the main file. For example,
+
+	samplebuffer.txt
+	samplebuffer.txt.header
+
+form a valid pair.
+
+The header specifies all kinds of useful information. It looks like this:
+
+	Version 2.2
+	Width 362
+	Height 620
+	Samples per pixel 8
+	CoC coefficients (coc radius = C0/w+C1): -0.000000,0.000000
+	Pixel-to-camera matrix: 0.004132,0.000000,0.000000,-0.750000,0.000000,-0.004132,0.000000,1.652893,0.000000,0.000000,0.000000,1.000000,0.000000,0.000000,-99.999001,100.000000
+	Encoding = binary
+	x,y,w,u,v,t,r,g,b,pri_mv(3d),pri_normal(3d),albedo(3d),sec_origin(3d),sec_hitpoint(3d),sec_mv(3d),sec_normal(3d),direct(3d),sec_albedo(3d),sec_direct(3d)
+
+Width and Height specify the dimensions of the image, in pixels. Samples 
+per pixel says how many samples to expect. The CoC coefficients give 
+formulas for computing the slope dx/du and dy/dv given the camera space 
+depth (z) for a sample (see below). Pixel-to-camera matrix is a 4x4 
+projection matrix that maps pixel coordinates to points on the camera's 
+focal plane (in camera space coordinates) as seen from the center of the 
+lens. This information is only utilized in the DoF/motion reconstruction 
+pipeline (see below, Figure 11 and Section 3.4). The last row serves as 
+a reminder on how to interpret the numbers in the actual sample file. 
+
+The actual sample data file can be either text or binary. We recommend 
+generating your sample buffers in text format and using the 
+functionality in UVTSampleBuffer to convert it to binary; this can be 
+done by loading in the text version and serializing back to disk with 
+the binary flag turned on. 
+
+In the main sample file, each line describes one sample as a sequence 
+
+x and y are the sample's pixel coordinates, including fractional 
+subpixel offsets. 
+
+w is the angular bandwidth estimate of the reflectance function at the 
+secondary hit (see Section 2.5). IMPORTANT NOTE: The unintuitive naming 
+(w) in and the location as the third parameter is due to historical 
+reasons. 
+
+u and v are the lens coordinates at which the sample was taken, in the 
+range [-1,1]. Not used except in DoF/motion reconstruction. 
+
+t is the time coordinate in the range [0,1] denoting the instant the 
+sample was taken. Not used except in DoF/motion reconstruction. 
+
+r,g,b is the sample's radiance, in linear RGB. Corresponds to $L$ in 
+Section 2.1. 
+
+pri_mv is the 3D camera-space motion vector for the surface hit by the 
+primary ray. CURRENTLY UNUSED. 
+
+pri_normal is the 3D camera-space normal for the primary hit.
+
+albedo is the albedo for the primary hit. This variable is only used for 
+diffuse reconstruction where we need to know the primary hit's 
+reflectance in order to generate the final shaded value (glossy rays are 
+handled separately as explained above). 
+
+sec_origin is the origin of the secondary ray, and corresponds to 
+$\mathbf{o}$ in Section 2.1. 
+
+sec_hitpoint is the hit point of the secondary ray, and corresponds to 
+$\mathbf{h}$ in Section 2.1.
+
+sec_mv is the 3D camera-space motion vector for the secondary hit. 
+CURRENTLY UNUSED except in the DoF/motion reconstruction, which abuses 
+this field for motion of the primary hit. 
+
+sec_normal is the 3D camera space normal of the secondary hit point.
+
+direct is the RGB radiance of the direct lighting estimate at the 
+primary hit. CURRENTLY UNUSED.
+
+sec_albedo and sec_direct are the path throughput and direct radiance at 
+the secondary hit, respectively. These are used only in the experimental 
+recursive filtering (Sec. 4) in the CUDA reconstruction pipeline. 
+Recursive filtering can be enabled by setting "gatherPasses" to a 
+positive number in ReconstructionIndirectCUDA.cpp. 
+
+The "CoC coefficients" C0,C1 are constants that are used for computing
+the circle of confusion for a given depth, assuming a thin lens
+model. The CoC corresponds directly to the slopes dx/du and dy/dv for
+a given depth w. This is how to compute C0 and C1, illustrated using
+PBRT's perspective camera API:
+
+	float f = 1.f / ( 1 + 1.f / pCamera->getFocalDistance() );
+	float sensorSize = 2 * tan( 0.5f * pCamera->getFoVRadians() );
+	float cocCoeff1 = pCamera->getLensRadius() * f / ( pCamera->getFocalDistance() - f );
+	cocCoeff1 *= min( camera->film->xResolution, camera->film->yResolution ) / sensorSize;
+	float cocCoeff0 = -cocCoeff1 * pCamera->getFocalDistance();
+
+If you use another model, you must derive the constants C0 and C1 yourself.
+
+
+CUDA
+----
+
+The precompiled 64-bit executable is built with CUDA support, but
+it is by default disabled in the code to enable building without the
+CUDA SDK. To enable CUDA support, find the line
+
+	#define FW_USE_CUDA 0
+
+in src/framework/base/DLLImports.hpp and change it to
+
+	#define FW_USE_CUDA 1
+
+Provided you have a working install of CUDA Toolkit, this will enable 
+the GPU code path. The first time it is run, the application will 
+compile and cache the .cu file containing the reconstruction kernels. 
+This may take a few seconds. 
+
+If you get an error during initialization, the most probable
+explanation is that the application is unable to launch nvcc.exe
+contained in the CUDA Toolkit. In this case, you should:
+
+   - Set CUDA_BIN_PATH to point to the CUDA Toolkit "bin" directory, e.g.
+     "set CUDA_BIN_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v5.0\bin".
+
+   - Set CUDA_INC_PATH to point to the CUDA Toolkit "include" directory, e.g.
+     "set CUDA_INC_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v5.0\include".
+
+   - Run vcvars32.bat to setup Visual Studio paths, e.g.
+     "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat".
+
+
+Release notes
+=============
+
+The GPU version is recommended for its much higher performance, while 
+the CPU may provide better understanding of the code. The results are 
+mostly identical. 
+
+The CPU reconstruction code supports an optional scissor rectangle to 
+limit computation and thus aid debugging. It can be set from App.cpp 
+when calling the CPU reconstruction, e.g., tg.reconstructAO(...). 
+
+The CPU code path supports a motion bounding volume hierarchy 
+(motion-BVH) by default. We chose to default to this path as it 
+simplifies the dof/motion reconstruction comparisons as it results in 
+less code, but the generality adds approx. 10% of runtime compared to 
+the runs in the paper. 
+
+For glossy reconstruction, our prototype implements the generation of 
+reconstruction rays and their BRDF weights by reading them in from a 
+file ("ray dumps") generated using a modified version of PBRT, rather 
+than replicating the sampling code. Pressing F4/F5 pops up a dialog 
+asking for the ray buffer to use. 
+
+As the ray buffers are too large for inclusion in the distribution 
+package, we have provided a batch file in the "data/glossy-src" 
+directory that generates sample buffers, the corresponding ray dumps, 
+and ground truth images. Running the batch file will take a while and 
+produce a large ray dump file of around 20 gigabytes. You can replace 
+our reconstruction rays with yours from another source if desired, and 
+the ray dump file provides a tight interface for doing so. The GPU 
+version of the glossy ray dump renderer supports large files by 
+streaming through them. The CPU version only supports smaller in-memory 
+buffers. 
+
+The application uses CUDA for gamma correction. If CUDA is not 
+installed, the USE_CUDA define should be disabled. 
+

data/glossy-src/all.bat

@@ -0,0 +1,29 @@
+@echo off
+
+echo =======================================================
+echo GENERATING SAMPLE BUFFER for reconstruction
+echo =======================================================
+pbrt-dsb-x64_Release.exe --pnggamma 1.6 --dumpsamples mon-8spp.pbrt
+
+echo =======================================================
+echo GENERATING RAY BUFFER for 128 SPP glossy reconstruction
+echo =======================================================
+pbrt-dsb-x64_Release.exe --pnggamma 1.6 --dumpreconstructionrays --reconstruct samplebuffer.bin mon-128spp.pbrt
+move /Y rays.bin mon-rays-128spp.bin
+rem the resulting images are garbage, delete them
+del mon-gt-128spp.exr
+del mon-gt-128spp-gamma16.png
+
+echo =======================================================
+echo GENERATING RAY BUFFER for 512 SPP glossy reconstruction
+echo =======================================================
+pbrt-dsb-x64_Release.exe --pnggamma 1.6 --dumpreconstructionrays --reconstruct samplebuffer.bin mon-512spp.pbrt
+move /Y rays.bin mon-rays-512spp.bin
+rem the resulting images are garbage, delete them
+del mon-gt-512spp.exr
+del mon-gt-512spp-gamma16.png
+
+echo =======================================================
+echo RENDERING GROUND TRUTH 512 SPP
+echo =======================================================
+pbrt-dsb-x64_Release.exe --pnggamma 1.6 --indirectonly mon-512spp.pbrt

data/glossy-src/mon-128spp.pbrt

@@ -0,0 +1,93 @@
+Film "image" 
+	"integer xresolution" [1280] "integer yresolution" [720] 
+#	"integer xresolution" [640] "integer yresolution" [360] 
+"string filename" "mon-gt-128spp.exr"
+
+Sampler "lowdiscrepancy" "integer pixelsamples" [128]
+SurfaceIntegrator "path" "integer maxdepth" [1]
+#SurfaceIntegrator "directlighting"
+
+Scale 1 1.3 1
+Rotate -23 1 0 0
+Translate 0.2 -1 3
+Camera "perspective" "float fov" [26]
+	"float focaldistance" [.75] 
+	#"float lensradius" [.0075] 
+	"float lensradius" [.00] 
+
+WorldBegin
+
+AttributeBegin
+    LightSource "distant" "point from" [0.000000 100.000000 -50.000000 ] "point to" [0.000000 0.000000 0.000000 ] "color L" [10 10 10] 
+AttributeEnd
+
+AttributeBegin
+#	Rotate -90 1 0 0
+#	LightSource "infinite" "string mapname" ["textures/grace-new_latlong.exr"] "integer nsamples" [4]
+AttributeEnd
+
+
+ObjectBegin "square" # square with checkboard texture
+Material "metal"
+Shape "trianglemesh" "point P" [ -1 0 -1 1 0 -1 1 0 1 -1 0 1 ]
+      "float uv" [ 0 0 1 0 1 1 0 1 ]
+	"integer indices" [ 0 1 2 2 3 0]
+ObjectEnd
+
+
+ObjectBegin "monkey_head_1"
+Material "metal" "float roughness" [0.01] "color k" [.3 .3 .9]
+Shape "wavefront" "string filename" ["monkey_sub.obj"]
+ObjectEnd
+
+ObjectBegin "monkey_head_2"
+Material "metal" "float roughness" [0.05] "color k" [.9 .3 .3]
+Shape "wavefront" "string filename" ["monkey_sub.obj"]
+ObjectEnd
+
+ObjectBegin "monkey_head_3"
+Material "metal" "float roughness" [0.25] "color k" [.6 .9 .6]
+#Material "matte" "color Kd" [.9 .3 .3]
+#Material "substrate" "color Kd" [.7 .1 .1]
+Shape "wavefront" "string filename" ["monkey_sub.obj"]
+ObjectEnd
+
+
+AttributeBegin	# floor
+Translate 0 -1 2
+Scale 6 6 6
+ObjectInstance "square"
+AttributeEnd
+
+AttributeBegin	# monkeyhead 1
+Translate -1.4 -0.2 2
+Rotate 15 0 1 0
+Rotate 25 1 0 0
+Rotate 180 0 0 1
+Rotate -90 1 0 0
+Scale 0.5 0.5 0.5
+ObjectInstance "monkey_head_1"
+AttributeEnd
+
+AttributeBegin	# monkeyhead 2
+Translate 0 -0.2 2
+Rotate 15 0 1 0
+Rotate 25 1 0 0
+Rotate 180 0 0 1
+Rotate -90 1 0 0
+Scale 0.5 0.5 0.5
+ObjectInstance "monkey_head_2"
+AttributeEnd
+
+AttributeBegin	# monkeyhead 3
+Translate 1.4 -0.2 2
+Rotate 15 0 1 0
+Rotate 25 1 0 0
+Rotate 180 0 0 1
+Rotate -90 1 0 0
+Scale 0.5 0.5 0.5
+ObjectInstance "monkey_head_3"
+AttributeEnd
+
+
+WorldEnd