source: GTP/trunk/Lib/Vis/Preprocessing/README.txt @ 1503

View Space Partitioning and PVS computation modules
===================================================


This directory contains a standalone application implementing the view
space partitioning and PVS computation modules of the GTP WP3.

The usage of the application is illustrated in the example scripts:

scripts/generate_viewcells    (view space partitioning)
scripts/preprocess_visibility (PVS computation)

These are simple shell scripts for usage with cygwin. It is easy to modify the
scripts for using with windows command shell.

The precompiled application binary as well as the linked libraries can be found in the
bin directory. Note that the bin directory should be included in your PATH in order to
run the application.


Using the View Space Partitioning module
=========================================

The view space partitioning is implemented as a standalone
application. Alternatively the module can be compiled as a library
which can be linked to a 3rd party code. An example of such an
application is the online occlusion culling module (integrated with
OGRE engine) which links the library in order to load the preprocessed
data and use them in runtime.

The module uses a number of parameters which can be specified by the
user through the "environment file" or command line parameters. The
parameters can have one of the following types: string, int, float,
and boolean. All parameters have implicit values set by the
preprocessor (listed in the table). This value can be redefined by the
environment file (see for example preprocess_visibility.env). This
value can further be overwritten by a command line argument. There are
two possibilieties how to specify the command parameter: using a
shorcut or define construct. The define construct uses the following
syntax: -Dparameter_name=value. With the exception of Boolean
parameters the shorcut version is specified as follows:
-paremter_shorcut=value. The boolean parameter shorcut is directly
followed by + or - sign (e.g.  -preprocessor_use_gl_render+).  The
usage of the parameters is illustrated in the example scripts and
environment files (preprocess_visibility, preprocess_visibility.env,
generate_viewcells, generate_viewcells.env).

Bellow we give a list of the most important parameters. For other
parameters see the environment file (generate_viewcells.env) and the
documentation included in the source code of the module.

Scene.filename (-scene_filename=) [string]

Scene description file. Currently simplified X3D (.x3d), Unigraphics
(.dat), UNC (.ply) formats are supported. This option has to be
specified!

Preprocessor.type (-preprocessor=) [string, one of: vss, rss, exact, sampling, render]

Type of the preprocessor to use. Currently only the "rss" type is
supported for PVS computation (rss stands for Ray Space Subdivision
explained in the previous chapters of the documentation). For view
cells construction the "vss" preprocessor should be used (vss stands
for View Space Subdivision).


Preprocessor.useGlRenderer (-preprocessor_use_gl_renderer) [boolean]

Tells the preprocessor to open an OpenGL window which serves for
visualization, testing and visual debugging of the preprocessor. This
functionality is currently implemented using Qt OpenGL widget.


ViewCells.type (-view_cells_type=)      [string, one of: vspBspTree, .....]

Type of view cells to be generated. Use "vspBspTree", which
corresponds to our optimized algorithm.

ViewCells.Construction.samples (-view_cells_construction_samples=) [int]

Number of visibility samples to be used for the view cell construction.

ViewCells.maxViewCells (-view_cells_max_view_cells=) [int]


Using the PVS computation module
=================================

The PVS computation module is implemented as a standalone application.
The parameters for the module can be specified by the user through the
"environment file" or on the command line as described for the view
space partioting module. Bellow we give a list of the most important
parameters. For other parameters see the environment file
(preprocess_visibility.env) and the documentation included in the
source code of the module.

Scene.filename (-scene_filename=) [string]

Scene description file. Currently simplified X3D (.x3d), Unigraphics
(.dat), UNC (.ply) formats are supported. This option has to be
specified!

Preprocessor.type (-preprocessor=) [string, one of: vss, rss, exact, sampling, render]

Type of the preprocessor to use. Currently only the "rss" type is
supported for PVS computation (rss stands for Ray Space Subdivision
explained in the previous chapters of the documentation). For view
cells construction the "vss" preprocessor should be used (vss stands
for View Space Subdivision).


Preprocessor.useGlRenderer (-preprocessor_use_gl_renderer) [boolean]

Tells the preprocessor to open an OpenGL window which serves for
visualization, testing and visual debugging of the preprocessor. This
functionality is currently implemented using Qt OpenGL widget and thus
requires compiling the preprocessor with Qt library.


Preprocessor.detectEmptyViewSpace (-preprocessor_detect_empty_viewspace=) [boolean]

Empty view space detection allows more efficient sampling for scenes
with properly modelled watertight objects (those which can be
correctly rendered with backface culling on).

Preprocessor.applyVisibilityFilter (-preprocessor_apply_visibility_filter) [boolean]

Tells the pre-processor if the visibility filter should be applied.

Preprocessor.visibilityFilterWidth (-preprocessor_visibility_filter_width=) [float]

Width of the visibility filter specified as a ratio of the size of the
bounding box of the scene. A reasonable value for common scenes is
0.01.

Preprocessor.visibilityFile (-preprocessor_visibility_file=) [string]

Name of the file into which the preprocessed visibility information
should be exported.

RssPreprocessor.initialSamples (-initial_samples=) [int]

Number of initial samples to use. These samples are distributed
uniformly in the whole view space.

RssPreprocessor.vssSamples (-rss_vss_samples=) [int]

Number of samples cast using importance and stratified sampling based
on RSS.


RssPreprocessor.useImportanceSampling (-rss_use_importance) [bool]

Tells the preprocessor whether to use RSS based sampling at all. If
false then even the RssPreprocessor.vssSamples are cast using the
uniform distribution.


RssPreprocessor.vssSamplesPerPass (-rss_vss_samples_per_pass=) [int]

Number of samples cast per pass of the RSS algortihm. After each pass
the RSS tree is updated and the new set of rays is generated according
to the estimated sample contributions.