Commit 16b22100 authored by PACANOWSKI Romain's avatar PACANOWSKI Romain
Browse files

Merge

parents 4cf3b5c0 dbfb10e8
......@@ -8,4 +8,111 @@
<tab type="user" url="@ref license" title="License"/>
<tab type="user" url="@ref contacts" title="Contacts"/>
</navindex>
<class>
<briefdescription visible="no"/>
<detaileddescription title=""/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<inheritancegraph visible="$CLASS_GRAPH"/>
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<services title=""/>
<interfaces title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<services title=""/>
<interfaces title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<allmemberslink visible="yes"/>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>
<!-- Layout definition for a group page -->
<group>
<briefdescription visible="yes"/>
<groupgraph visible="$GROUP_GRAPHS"/>
<detaileddescription title=""/>
<memberdecl>
<nestedgroups visible="yes" title=""/>
<dirs visible="yes" title=""/>
<files visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<pagedocs/>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>
</doxygenlayout>
/*!
\page features Features
<h3>Data formats</h3>
Data formats
------------
ALTA can open common BRDF data formats such as
<a href="http://www.merl.com/brdf/">MERL</a> binary files and ASTM format
(used in the Cornell BRDF database). We also provide our text-based data
format that is compatible with <a href="http://www.gnuplot.info">
Gnuplot</a>.
<br />
<h3>Rational interpolation</h3>
Rational interpolation
----------------------
ALTA can perform rational interpolation in the sense of
<a href="http://hal.inria.fr/hal-00678885/en" />Pacanowski et al.
[2012]</a>. Multiple implementations are provided with various library
for the quadratic solver:
<ul>
<li><a href="http://www.cgal.org">CGAL</a>. Warning: due to the internal
representation of floatting point numbers by CGAL, this plugin is very
slow).</li>
<li><a href="http://www.mathworks.fr/products/matlab/">Matlab</a>.</li>
<li><a href="http://quadprog.sourceforge.net/">QuadProg++</a>. Note:
we provide modified sources of QuadProg++ with ALTA. You should be able
to use at least this plugin.</li>
</ul>
+ <a href="http://www.cgal.org">CGAL</a>. Warning: due to the internal representation of floatting point numbers by CGAL, this plugin is very slow).
+ <a href="http://www.mathworks.fr/products/matlab/">Matlab</a>.
+ <a href="http://quadprog.sourceforge.net/">QuadProg++</a>. Note: we provide modified sources of QuadProg++ with ALTA. You should be able to use at least this plugin.
We also provide plugin to perform least-square interpolation of rational
functions. Those plugins are based on Eigen's solvers. Due to the ill-posed
......@@ -33,31 +32,34 @@ formulation of the least-square method, the solution provided by those
plugins might have singularities (denominator equals to zero) in the
definition domain.
<br />
<h3>Non-linear fitting</h3>
Non-linear fitting
------------------
ALTA can perform non-linear optimisation to fit parametric BRDF models
to data. It supports a wide variety of non-linear optimizers such as:
<ul>
<li><a href="https://code.google.com/p/ceres-solver/">CERES</a>
solver</li>
<li>MIT NlOpt</li>
<li>CoinOr IpOpt</li>
<li><a href="http://eigen.tuxfamily.org">Eigen</a> implementation of
the Levenberg-Marquardt algorithm</li>
</ul>
<br />
+ <a href="https://code.google.com/p/ceres-solver/">CERES</a> solver
+ MIT NlOpt
<h3>Analytic BRDF models</h3>
+ CoinOr IpOpt
+ <a href="http://eigen.tuxfamily.org">Eigen</a> implementation of the Levenberg-Marquardt algorithm
Analytic BRDF models
--------------------
We try to provide as much parametric BRDF models as possible. You will find
the list of currently supported models in the \ref functions page.
<br />
<h3>Scripting mechanisms</h3>
Scripting mechanisms
--------------------
Writing command lines can be burdensome. To avoid having to write lengthy
command lines, we provide a scripting mechanism to launch ALTA's commands
......
/*!
\page format Format
<h2>Common notations</h2>
_Warning: this document is currently not up to date and should not be followed._
Common notations
----------------
Data and function files have the same format. They are text file very close to dump.
Each file starts with a header containing :
Each file starts with a header containing information about the input and output space described. Every header line starts by a '#' symbol. The following information are described:
<h3> Parametrization format </h3>
- Whether the file describe a function or a data,
- Command line used to generate the file (optional),
- Input and output domain dimensions,
- Input domain parametrization,
- And output domain parametrization.
<ul>
<li> \verbatim #PARAM_IN input_parametrization_name \endverbatim </li>
<li> \verbatim #PARAM_OUT output_parametrization_name \endverbatim </li>
</ul>
Here is an exemple of a BRDF header:
#ALTA FUNC HEADER
#CMD --L2 0.0282467 --Linf 0.0935969 --fitter ./librational_fitter_parallel.dylib --input ../../data/1d/NIST/Kirby2/Kirby2.dat --output ../Kirb2.brdf
#DIM 1 1
#PARAM_IN UNKNOWN_INPUT
#PARAM_OUT UNKNOWN_OUTPUT
#ALTA HEADER END
Parametrization format
----------------------
- `#PARAM_IN input_parametrization_name`
- `#PARAM_OUT output_parametrization_name`
<h3>Input Parametrization</h3>
Input Parametrization
---------------------
ALTA can automaticaly convert samples (either data sample or BRDF
evaluation) into a different coordinate system. Here is a non-complete
list of possible parametrizations:
\verbatim
RUSIN_TH_PH_TD,
RUSIN_TH_TD_PD,
RUSIN_TH_PH_TD_PD,
COS_TH_TD, // cosine theta_h, cosine theta_d
ISOTROPIC_TV_TL_DPHI, // isotropic formulation with theta view, theta light and |dphi|
CARTESIAN, // 6D (directions: 3d + 3d)
SPHERICAL_TL_PL_TV_PV
ISOTROPIC_TV_PROJ_DPHI //2D Param. (theta_v * cos(|\delta \Phi|), theta_v * sin(|\delta \Phi)|)
\endverbatim
<h3> Output Parametrization </h3>
RUSIN_TH_PH_TD,
RUSIN_TH_TD_PD,
RUSIN_TH_PH_TD_PD,
COS_TH_TD, // cosine theta_h, cosine theta_d
ISOTROPIC_TV_TL_DPHI, // isotropic formulation with theta view, theta light and |dphi|
CARTESIAN, // 6D (directions: 3d + 3d)
SPHERICAL_TL_PL_TV_PV
ISOTROPIC_TV_PROJ_DPHI //2D Param. (theta_v * cos(|\delta \Phi|), theta_v * sin(|\delta \Phi)|)
Output Parametrization
----------------------
In the current version of ALTA, we cannot handle different output
parametrizations (like LAB color space). Fitting will be performed
......
......@@ -8,10 +8,12 @@ You can <a href="contacts.html">contact us</a> to get more information
about its features, roadmap, and missing documentation.
</center>
<h2>Description</h2>
<h3>Description</h3>
ALTA is a multi-platform software library to analyze, fit and understand
BRDFs. It provides a set of command line softwares to fit measured data to
analytical forms, tools to understand models and data.
analytical forms, tools to understand models and data. You can find an
overview presentation of ALTA <a href="http://hal.inria.fr/hal-01016531">here</a>.
ALTA is part of the <a href="http://maverick.inria.fr/Projets/ALTA/ ">
ANR 11-BS02-006</a>, a research project on light transport analysis.
......@@ -26,13 +28,17 @@ and models</b>, or just perform <b>statistical analysis</b> on your data.
Here is a list of the major features in the ALTA library (you can find
the complete list in the \ref features page):
<ul>
<li>Open common BRDF data formats (MERL, ASTM)</li>
<li>Non-linear fitting of BRDF (using third party packages)</li>
<li>Rational interpolation</li>
<li>Analytic BRDF models (see \ref functions)</li>
<li>Scripting mechanism to automatize fitting</li>
</ul>
+ Open common BRDF data formats (MERL, ASTM)
+ Non-linear fitting of BRDF (using third party packages)
+ Rational interpolation of BRDF
+ Analytic BRDF models (see \ref functions)
+ Scripting mechanism to automatize fitting
<h3>Sample results</h3>
......@@ -71,61 +77,43 @@ the complete list in the \ref features page):
<h3>Obtain sources</h3>
To access the sources of ALTA, you can download the alpha sources:
<center><a href="http://alta.gforge.inria.fr/downloads/alta-alpha.tar.gz">http://alta.gforge.inria.fr/downloads/alta-alpha.tar.gz</a></center>
<center>[http://alta.gforge.inria.fr/downloads/alta-alpha.zip](http://alta.gforge.inria.fr/downloads/alta-alpha.tar.gz)</center>
<h3>Build</h3>
You can build ALTA using either <a
href="http://qt-project.org/downloads">QMake</a> or <a
href="http://www.scons.org/">Scons</a>. To start, we advise to use Scons as it
is lightweight and only requires Python to be installed (ALTA uses Python for
its high level scripting mechanism). To build using scons, go to the root
directory of ALTA and type:
\verbatim
$ scons --cfg [filename] -i
\endverbatim
You need to provide a plateform dependant configuration file. You will find
examples of such configuration files in the $ALTA/configs/scons directory.
Running this command should obtain some of ALTA's dependencies (such as Eigen)
and compile the main package of the library (i.e. the core, the command line
tools, and some plugins).
To use QMake, or for a more detailed view of ALTA's building scripts and
dependencies, please refer to \ref install.
You can build ALTA using either [qmake](http://qt-project.org) or [scons](http://www.scons.org). To start, we advise to use scons as it is lightweight and only requires Python to be installed (ALTA uses Python for its high level scripting mechanism). To build using scons, go to the root directory of ALTA and type:
$ scons --cfg=[filename] -i
You need to provide a platform dependant configuration file. You will find examples of such configuration files in the $ALTA/configs/scons directory. Running this command should obtain some of ALTA's dependencies (such as Eigen) and compile the main package of the library (i.e. the core, the programs, and some plugins).
To use qmake, or for a more detailed view of ALTA's building scripts and dependencies, please refer to \ref install.
<br />
<h2>How to use it</h2>
After compiling the different command line tools and associated plugins,
go to the sources directory and launch this command line (for Linux users only):
\verbatim
$ ./build/data2brdf --input ../data/1d/NIST/Kirby2/Kirby2.dat --output Kirby.brdf --fitter ./build/librational_fitter_eigen.so
\endverbatim
ALTA uses command line programs to perform actions such as BRDF fitting, data conversion, etc. Each program needs plugins to handle its inputs and outputs. We provide three kind of plugins: \ref functions which correspond to BRDF models, \ref datas which correspond to BRDF measurments, and \ref fitters which correspond to fitting algorithms. In the following, we illustrate the use of programs and plugins.
Tada! You have produced your first fit. The produced output is a 1D rational
function, using a monomial basis, interpolating the <a
href="http://www.itl.nist.gov/div898/strd/nls/data/kirby2.shtml">Kirby 2</a>
dataset. You can find an ALTA compatible version of this dataset <a
href="http://alta.gforge.inria.fr/data/Kirby2.dat">here</a>. Note that this
fit is not a BRDF.
After compiling the different programss and plugins, go to the sources directory and launch this command line (for Linux users only):
$ ./build/data2brdf --input ../data/1d/NIST/Kirby2/Kirby2.dat --output Kirby.brdf --fitter ./build/librational_fitter_eigen.so
Tada! You have produced your first fit. The produced output is a 1D rational function, using a monomial basis, interpolating the [Kirby2](http://www.itl.nist.gov/div898/strd/nls/data/kirby2.shtml) dataset. You can find an ALTA compatible version of this dataset [here](http://alta.gforge.inria.fr/data/Kirby2.dat). Note that this fit is not a BRDF.
\image html Kirby2.png
The \a data2brdf is one of many \ref commands available in ALTA. It
allows to perform a fitting procedure by converting a \ref data object into a
brdf object (also named \ref function).
The \a data2brdf is one of many \ref commands available in ALTA. It allows to perform a fitting procedure by converting a \ref data object into a brdf object (also named \ref function).
To convert this brdf file (in ALTA \ref format), you will need another command:
\verbatim
$ ./build/brdf2brdf --input Kirby.brdf --output Kirby.m --export matlab
\endverbatim
$ ./build/brdf2brdf --input Kirby.brdf --output Kirby.m --export matlab
\a brdf2brdf converts an ALTA brdf file into another format such as
Matlab m file, C++ code, or BRDF Explorer shader. Note that this tool cannot
convert to another ALTA file (e.g. converting a Blinn lobe to a Beckmann
distribution).
Matlab m file, C++ code, or BRDF Explorer shader. Note that this tool cannot convert to another ALTA file (e.g. converting a Blinn lobe to a Beckmann distribution).
You can find more examples of how to use ALTA on the \ref tutorials page.
......
......@@ -102,7 +102,7 @@ Here is the script to perform the same fitting as the previous example. It
performs the fitting of the blue metallic paint from the MERL database using
a Beckmann lobe (note there is no shadowing term, nor Fresnel term):
\verbatim
~~~{.xml}
<?xml version="1.0"?>
<alta>
<configuration>
......@@ -128,7 +128,7 @@ a Beckmann lobe (note there is no shadowing term, nor Fresnel term):
<parameter name="export" value="explorer" />
</action>
</alta>
\endverbatim
~~~
In this XML example, it is possible to perform fit using a compound function by concatenating multiple function plugins. This is equivalent to providing a list of plugins to the <code>\-\-func</code> argument: <code>\-\-func [libnonlinear_function_diffuse.so, libnonlinear_function_lafortune.so]</code>.
......@@ -156,11 +156,11 @@ function along its different axis.
<h2>Using the C++ interface</h2>
It is possible to create your own programs and make use of ALTA's plugin possibilities. To do so, you only need to link you program with the core library (<code>libcore.a</code> on GNU/Linux). The core library provides all the generic objects for \ref function, \ref data, and \ref fitter. You can load a plugin and create an object using the \ref plugins_manager.
It is possible to create your own programs and make use of ALTA's plugin possibilities. To do so, you only need to link you program with the core library (`libcore.a` on GNU/Linux). The core library provides all the generic objects for \ref function, \ref data, and \ref fitter. You can load a plugin and create an object using the \ref plugins_manager.
The following program produces slices of data files and outputs it on a gnuplot compliant data file. It requires an interpolant data format such as \ref data_merl, \ref data_interpolant (our internal data format is not):
\verbatim
~~~{.cpp}
#include <core/args.h>
#include <core/data.h>
#include <core/function.h>
......@@ -172,12 +172,12 @@ The following program produces slices of data files and outputs it on a gnuplot
#include <cmath>
int main(int argc, char** argv) {
arguments args(argc, argv);
arguments args(argc, argv);
ptr<data> d = plugins_manager::get_data(args["data"]);
d->load(args["data-file"]);
ptr<data> d = plugins_manager::get_data(args["data"]);
d->load(args["data-file"]);
std::ofstream file(args["output"].c_str(), std::ios_base::trunc);
std::ofstream file(args["output"].c_str(), std::ios_base::trunc);
double theta_in = -(M_PI/180) * (double)args.get_float("theta", 0.0f);
double phi_in = (M_PI/180) * (double)args.get_float("phi", 0.0f);
......@@ -204,7 +204,7 @@ int main(int argc, char** argv) {
file << std::endl ;
}
}
\endverbatim
~~~
The \ref arguments object allow to parse the command line and read options. The \ref plugins_manager allows to create plugin objects from shared object files. In this example, when data objects are not defined in the same parametrization than the data point we want to evaluate, the convert function from the \ref params class can be used. We advise to use it all the time.
......
......@@ -63,7 +63,7 @@ if compile_test:
#end
#cmake_cmd = 'cmake -DGLOG_LIB=' + build_dir + 'lib' + os.sep + libname + ' -DGLOG_INCLUDE=' + build_dir + 'include -DGFLAGS=OFF ' + '-DEIGEN_INCLUDE=' + build_dir + 'include -DCMAKE_INSTALL_PREFIX=' + build_dir + ' .' + ' -DDISABLE_TR1=ON -DBUILD_EXAMPLES=OFF ' + '-DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release -DMINIGLOG=OFF'
cmake_cmd = 'cmake -DBUILD_SHARED_LIBS=OFF -DGLOG_LIB=' + build_dir + 'lib' + ' -DGLOG_INCLUDE=' + build_dir + 'include -DGFLAGS=OFF ' + '-DEIGEN_INCLUDE=' + build_dir + 'include -DCMAKE_INSTALL_PREFIX=' + build_dir + ' .' + ' -DDISABLE_TR1=ON -DBUILD_EXAMPLES=OFF ' + '-DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release -DMINIGLOG=ON'
cmake_cmd = 'cmake -DBUILD_SHARED_LIBS=ON -DGLOG_LIB=' + build_dir + 'lib' + ' -DGLOG_INCLUDE=' + build_dir + 'include -DGFLAGS=OFF ' + '-DEIGEN_INCLUDE=' + build_dir + 'include -DCMAKE_INSTALL_PREFIX=' + build_dir + ' .' + ' -DDISABLE_TR1=ON -DBUILD_EXAMPLES=OFF ' + '-DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release -DMINIGLOG=ON'
if os.name == 'nt':
ret = os.system(cmake_cmd + ' -G \"NMake Makefiles\"')
......
......@@ -148,8 +148,15 @@ class rational_function_1d : public function
bool _separable;
} ;
/*! \brief Rational function define a BRDF model using a ratio of polynomials
* \ingroup core
*
* \details
* A rational function define a BRDF model using a ratio of polynomials.
*/
class rational_function : public function
{
public: // methods
rational_function() ;
......
......@@ -10,12 +10,13 @@ data_brdf_slice::data_brdf_slice()
{
// Allocate data
width = 512; height = 512;
_data = new double[3*width*height];
slice = 1;
_data = new double[3*width*height*slice];
// Set the input and output parametrization
_in_param = params::RUSIN_TH_TD;
_in_param = params::RUSIN_TH_TD_PD;
_out_param = params::RGB_COLOR;
_nX = 2;
_nX = 3;
_nY = 3;
}
......@@ -37,7 +38,7 @@ void data_brdf_slice::load(const std::string& filename, const arguments&)
void data_brdf_slice::save(const std::string& filename) const
{
if(!t_EXR_IO<double>::SaveEXR(filename.c_str(), width, height, _data))
if(!t_EXR_IO<double>::SaveEXR(filename.c_str(), width, slice*height, _data))
{
std::cerr << "<<ERROR>> unable to save image file" << std::endl;
}
......@@ -46,16 +47,18 @@ void data_brdf_slice::save(const std::string& filename) const
// Acces to data
vec data_brdf_slice::get(int id) const
{
vec res(5) ;
vec res(6) ;
const int i = id % width;
const int j = id / width;
const int k = id / (width*height);
const int j = (id - k*width*height) / width;
res[0] = 0.5*M_PI*(i+0.5) / double(width);
res[1] = 0.5*M_PI*(j+0.5) / double(height);
res[2] = 0.5*M_PI*(k+0.5) / double(slice);
res[2] = _data[3*id + 0];
res[3] = _data[3*id + 1];
res[4] = _data[3*id + 2];
res[3] = _data[3*id + 0];
res[4] = _data[3*id + 1];
res[5] = _data[3*id + 2];
return res ;
}
......@@ -67,18 +70,18 @@ vec data_brdf_slice::operator[](int i) const
//! \todo Test this function
void data_brdf_slice::set(vec x)
{
assert(x.size() == 5);
assert(x.size() == 6);
assert(x[0] <= 0.5*M_PI && x[0] >= 0.0);
assert(x[1] <= 0.5*M_PI && x[1] >= 0.0);
const int i = floor(x[0] * width / (0.5*M_PI));
const int i = floor(x[0] * width / (0.5*M_PI));
const int j = floor(x[1] * height / (0.5*M_PI));
const int k = floor(x[2] * slice / (0.5*M_PI));
const int id = i + j*width + k*width*height;
const int id = i + j*width;
_data[3*id + 0] = x[2];
_data[3*id + 1] = x[3];
_data[3*id + 2] = x[4];
_data[3*id + 0] = x[3];
_data[3*id + 1] = x[4];
_data[3*id + 2] = x[5];
}
vec data_brdf_slice::value(vec, vec) const
......@@ -91,9 +94,10 @@ vec data_brdf_slice::value(vec x) const
assert(x[0] <= 0.5*M_PI && x[0] >= 0.0);
assert(x[1] <= 0.5*M_PI && x[1] >= 0.0);
const int i = floor(x[0] * width / (0.5*M_PI));
const int i = floor(x[0] * width / (0.5*M_PI));
const int j = floor(x[1] * height / (0.5*M_PI));
const int id = i + j*width;
const int k = floor(x[2] * slice / (0.5*M_PI));
const int id = (i + j*width)*k;
if(i < 0 || i >= width) { std::cerr << "<<ERROR>> out of bounds: " << x << std::endl; }
if(j < 0 || j >= height) { std::cerr << "<<ERROR>> out of bounds: " << x << std::endl; }
......@@ -108,7 +112,7 @@ vec data_brdf_slice::value(vec x) const
// Get data size, e.g. the number of samples to fit
int data_brdf_slice::size() const
{
return width*height;
return width*height*slice;
}
// Get min and max input space values
......@@ -117,6 +121,7 @@ vec data_brdf_slice::min() const
vec res(2);
res[0] = 0.0 ;
res[1] = 0.0 ;
res[2] = 0.0 ;
return res ;
}
vec data_brdf_slice::max() const
......@@ -124,12 +129,13 @@ vec data_brdf_slice::max() const
vec res(2);
res[0] = M_PI / 2 ;
res[1] = M_PI / 2 ;
res[2] = M_PI / 2;
return res ;
}
int data_brdf_slice::dimX() const
{
return 2 ;
return 3 ;
}
int data_brdf_slice::dimY() const
{
......
......@@ -40,5 +40,6 @@ class data_brdf_slice : public data
private: // data
double* _data;
int width, height;
int slice;
} ;
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment