Commit 95545c5c authored by Laurent Belcour's avatar Laurent Belcour
Browse files

Updating the doxygen to incorporate as much as possible markdown langage.

parent 184ca3da
......@@ -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
......
......@@ -11,7 +11,8 @@ about its features, roadmap, and missing documentation.
<h2>Description</h2>
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 +27,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 +76,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.
After compiling the different programss and plugins, go to the sources directory and launch this command line (for Linux users only):
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.
$ ./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>
......@@ -129,7 +129,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>.
......@@ -157,11 +157,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>
......@@ -173,12 +173,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);
......@@ -205,7 +205,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.
......
......@@ -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() ;
......
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