The Disney BRDF Explorer is an application that allows the development and analysis
of bidirectional reflectance distribution functions (BRDFs). It can load and plot
analytic BRDF functions (coded as snippets of OpenGL GLSL programs), measured
material data from the MERL database, and anisotropic measured material data from
MIT CSAIL.

Most of the application should be (hopefully) self explanatory, so the goal here is to
document the less obvious bits of usage, as well as providing some useful info.

THIS FORK
------------------------------------
This is Moth Quantum's fork of Disney's BRDF Explorer
(https://github.com/wdas/brdf). Everything above is the original application,
unchanged; this fork adds a set of tools for modifying a BRDF's measured or
analytic data using Moth Quantum's own blur engine, described below. See
LICENSE for the terms this is shared under (Disney's original license
applies to the unmodified portions; see its trademark clause in particular).


MOTH QUANTUM BLUR TOOLS
------------------------------------
Any measured BRDF (loaded from a MERL .binary file) or analytic BRDF (loaded
from a .brdf file) has a moth-icon button next to its "solo" buttons in the
BRDF Parameters window. Clicking it opens a dialog that runs that BRDF's data
through Moth Quantum's blur-core-v1 engine (the same one used by the
merl_brdf_blur notebook in the blur-api repo) and adds the result to the BRDF
list as a new .binary file:

- For a measured BRDF, its 90x90x180 (theta_h, theta_d, phi_d) grid is sent
  as-is (per R/G/B channel).
- For an analytic BRDF, its GLSL formula is first discretized onto that same
  grid, at its current parameter values, via a GPU render pass -- so it's
  blurring exactly what's currently being rendered elsewhere in the app for
  that BRDF, not a re-derivation of the formula.

You'll need a Moth Quantum API key: use "Get Key..." (in the dialog, or
Utilities > Get Moth API Key... in the menu bar) to open
https://platform.mothquantum.com/keys, then "Set Moth API Key..." to store it.

The dialog's controls mirror the engine's own parameters:

- strength, reach: how strong the blur is, and how local (reach=0) vs.
  content-blind/global (reach=1) it is. Higher reach mixes the material more
  aggressively, at the cost of washing out contrast -- see the mean/std
  option below.
- style: which rotation gates the engine applies (x / y / xy / yx).
- axes to blur: which of theta_h / theta_d / phi_d the blur is applied along.
  theta_h is sampled non-linearly (dense near the specular peak), so blurring
  it isn't a uniform angular blur the way theta_d or phi_d are.

Two options affect how the result is reconstructed, both on by default:

- Smooth upsampling (cubic interpolation): the engine can't take the full
  90x90x180 grid over HTTP, so it's downsampled before sending and the
  low-resolution result is reconstructed back up to full resolution. This
  uses cubic interpolation instead of just repeating each downsampled value
  across its block, so the result isn't blocky. It's clamped to the local
  neighborhood's own range, so it can't invent values outside what the
  engine actually returned.
- Match original brightness (robust mean/std, ignores top outliers): the
  engine normalizes its response so its single brightest cell matches the
  request's brightest cell -- reasonable at low reach, but at reach near 1
  the response comes back nearly flat, and pinning a flat response to one
  peak drags almost everything up near it. This instead matches the
  response's mean/std to the request's (excluding the top 1% as outliers),
  so overall brightness tracks the source material rather than one cell.

The full MERL database (100 materials) isn't included in this repo -- fetch
it via the blur-api repo's merl_brdf_blur notebook, or the 1.3GB archive at
https://zenodo.org/records/8101681, and open the .binary files with
File > Open BRDF...


WHICH BRDF(S) YOU'RE SEEING
------------------------------------
In the BRDF Parameters window, each BRDF has a colored background. The plotted values
(for the 3D, polar, and cartesian plots) are drawn in the corresponding colors.

In the Image Slice, Lit Object, and Lit Sphere windows, you're seeing the first
(topmost in the parameters window) enabled BRDF.


NAVIGATING POLAR/CARTESIAN PLOTS
------------------------------------
Use the left mouse button to pan around in the plot. Right dragging will zoom in/out
around the centered location. Double-clicking anywhere resets the view to the default
zoom and location. For cartesian plots, Control+left drag stretches ONLY the x-axis,
while Control+right drag stretches only the y-axis.


NAVIGATING 3D PLOTS
------------------------------------
Left-drag spins around the origin (there's no current way to change this). Right drag
zooms in and out. Double clicking resets to the default view.


PARAMETER SLIDERS
------------------------------------
Parameters sliders (a slider plus a text entry box) are all over the application. To
reset one to its default value, Control+Click in the text box.


SOLOING BRDFS
------------------------------------
Pressing the "solo" (circle) button for a given BRDF makes ONLY that BRDF visible,
hiding all the others. The "Solo this BRDF's color channels" button also hides all
the other channels, but shows a separate plot for the red, green, and blue channels
(in their respective colors). Click the solo button again to exit solo mode.


LIT SPHERE VIEW
------------------------------------
You can drag the left mouse button on the surface of the sphere to change the
incident angle. If "Double Theta" is enabled, the specular highlight will track
the position of the mouse.


LIT OBJECT VIEW
------------------------------------
The lit object view allows an arbitrary object to be viewed under with a directional
light from the incident direction (in "No IBL" mode) or under illumination from an
arbitrary environment map. Left dragging rotates the object; right dragging zooms
the object; Control+left dragging rotates the environment probe.

The combo box lets you choose "No IBL", "IBL: No IS" (quasirandom sampling from
the environment map with no importance sampling) and "IBL: IBL IS" (importance
sampling from the IBL). Multiple importance sampling is planned but not implemented.
The "Keep Sampling" mode, when enabled, progressively refines the image until
4096 samples have been applied.

The buttons allow changing out the object (any OBJ should work) and the environment
probe (which must be in ptex format).


ALBEDO VIEW
------------------------------------
Albedo computation by brute force sampling proved too expensive to do interactively,
so the application can use several different sampling strategies to compute the albedo.
Use the combo box on the right to choose between these sampling strategies. The
Resample x10 button adds more samples to that view of the graph.


IMAGE SLICE VIEW
------------------------------------
An "image slice" is an alternative way of looking at BRDF data that we have found
helpful at Disney. Along the x-axis, the half angle is varied from zero to 90
degrees; along the y-axis, the difference angle is varied from 0 to 90 degrees.


BRDF FILES
------------------------------------
.brdf files consist of a set of parameters and a BRDF function written in GLSL.
At runtime, the application creates UI elements for each parameter, and creates
shaders for different views that incorporate the GLSL function.

The BRDF function looks like this (this example is for a lambertian BRDF):

::begin shader
vec3 BRDF( vec3 L, vec3 V, vec3 N, vec3 X, vec3 Y )
{
    return vec3(reflectance / 3.14159265);
}
::end shader

Anything valid in GLSL can go between "::begin shader" and "::end shader" as
long as it's valid GLSL.

The application allows float, color, and boolean parameters. The float parameters
have the form
float [name] [min val] [max val] [default val]
for example:
float reflectance 0.0 1.0 1.0

Boolean parameters have the form
bool [name] [default], where default is 0 or 1 (keywords such as true and
false aren't recognized)
for example:
bool hasDiffuse 0

Color parameters have the form
color [name] [defaultR] [defaultG] [defaultB], where defaultR/G/B are in [0..1]
for example:
color diffuseColor 0.5 0.1 1.0

Parameters are passed into the resulting GLSL shaders as uniforms of the same
name (so parameter names must be valid GLSL variable names, although the
application doesn't enforce this). Float parameters come in as uniform floats,
color parameters as vec3s, and boolean parameters as bools. The application
declares them when constructing shaders, so your GLSL BRDF functions can 
refer to them knowing that they'll exist and have the proper values at runtime.


LIGHT PROBE ATTRIBUTION
------------------------------------
HDR Light Probe Images Copyright 1998 courtesy of Paul Debevec,
www.debevec.org, used with permission.

Please see:
Paul Debevec.  Rendering Synthetic Objects Into Real Scenes: Bridging Traditional and 
Image-Based Graphics With Global Illumination and High Dynamic Range Photography.  
Proceedings of SIGGRAPH 98, Computer Graphics Proceedings, Annual Conference Series, 
July 1998, pp. 189-198.


WHERE TO GET MEASURED BRDF DATA
------------------------------------
MERL data can be requested here:
http://www.merl.com/brdf/

MIT CSAIL data is here:
http://people.csail.mit.edu/addy/research/brdf/


BUILD INSTRUCTIONs
------------------

To install brdf run:

    make install [prefix=<some-directory>]

If you do not specify "prefix=..." then brdf will be installed into the current directory.