WIP

parent 0a20cbb6
......@@ -859,7 +859,7 @@ ITA_FFT_WITH_FFTW3 (recommended)</code></pre>
<h5>Rendering module with room acoustics simulation backend</h5>
<p>
This module requires <code>RAVEN</code>, which is copyright protected and not available for the public. Please <a href="disclaimer.html">contact us</a> if you are working for a university and want to use it for academic purposes, only. If you have been granted access, obtain the source code using <pre><code>git clone --recursive http://git.rwth-aachen.de/ita/RAVEN</code></pre>
This module requires <code>RAVEN</code>, which is copyright protected and not available for the public. Please <a href="disclaimer.html">contact us</a> if you are working for a university and want to use it for academic purposes, only. If you have been granted access, obtain the source code using <pre><code>git clone --recursive http://git.rwth-aachen.de/ita/RAVEN</code></pre>
Configure, generate and build <code>RAVEN</code> using CMake.<br />
Now you can activate the room acoustics rendering module<br /><br />
<pre><code>ITA_VACORE_WITH_RENDERER_BINAURAL_ROOM_ACOUSTICS</code></pre>
......
......@@ -109,6 +109,7 @@
+ VAMatlab, VALua and VAC# bindings <br />
+ VAUnity and VAUnityExtensions <br />
+ VAServer command line interface application <br />
+ Redstart VA GUI application [BETA] <br />
- VAPython binding * <br />
<span style="font-size: 0.6em">* not available for this compiler version and Python 3.6</span> <br />
</p>
......@@ -118,6 +119,7 @@
+ VAPython binding for Python 3.6 <br />
+ VAUnity and VAUnityExtensions <br />
- VAServer command line interface application * <br />
- Redstart VA GUI application [BETA] * <br />
- VACore C++ developer package * <br />
<span style="font-size: 0.6em">* not available for this compiler version</span><br />
</p>
......@@ -155,6 +157,7 @@
+ VAMatlab, VALua and VAC# bindings <br />
+ VAUnity and VAUnityExtensions <br />
+ VAServer command line interface application <br />
+ Redstart VA GUI application [BETA] <br />
- VAPython binding * <br />
<span style="font-size: 0.6em">* not available for this compiler version and Python 3.6</span> <br />
</p>
......@@ -164,6 +167,7 @@
+ VAPython binding for Python 3.6 <br />
+ VAUnity and VAUnityExtensions <br />
- VAServer command line interface application * <br />
- Redstart VA GUI application [BETA] * <br />
- VACore * <br />
<span style="font-size: 0.6em">* not available for this compiler version</span><br />
</p>
......
......@@ -112,7 +112,7 @@
<ul>No.</ul>
<li><b>I am trying to use a VA binding, but I get a 'module not found' or 'library not found' error.</b> </li>
<ul>You are missing a dependent shared library (dll on Windows). Make sure to include the dependencies of you copy libraries. If you are a developer, the <i>Dependency Walker</i> is an excellent supporter for solving these problems on Windows platforms. Otherwise consider switching to static linking to avoid this problem with the VA bindings.
<ul>You are missing a dependent shared library (dll on Windows). Make sure to include the dependencies if you copy libraries. If you are a developer, the <i>Dependency Walker</i> is an excellent supporter for solving these problems on Windows platforms. Otherwise consider switching to static linking to avoid this problem with the VA bindings.
</ul>
<li><b>Can I use <code>SOFA</code> HRTFs in VA?</b></li>
......@@ -128,9 +128,9 @@
<h3>Issue tracker</h3>
Issues are very likely to appear. VA is a prototyping software, and the usage can hardly be foreseen by the developers. However, it is important to identify if the issues you have are usage-related or require a bug fix in the code. If you are insecure, go through the <a href="#faq">FAQ</a> and check with the <a href="#community">community</a> first. <br />
Issues are very likely to appear. VA is a prototyping software, and the usage can hardly be foreseen by the developers. However, it is important to identify if the issues you have are usage-related or require a bug fix in the code. If you are insecure, go through the <a href="#faq">FAQ</a> and discuss with the <a href="#community">community</a> first. <br />
<br />
If you have trouble configuring and using VA, there is a whole section about that in the <a href="start.html">getting started page</a>, which sould be carefully read first. <br >
If you have trouble configuring and using VA, there is a whole section about that in the <a href="start.html">getting started page</a>, which should be carefully read first. <br >
<br />
If you are sure it is a bug that should be fixed, then
<ul>
......
......@@ -100,7 +100,7 @@
</p>
<p>
<b>A technical report is currently in progress</b>. If you want to use VA for your research and would like refer to it in a scientific publication, this report will be the appropriate citation. Additionally we recommend to state the version used, e.g. <code>v2018a</code> or a GIT revision / tag.
<b>A technical report is currently in progress</b>. If you want to use VA for your research and would like refer to it in a scientific publication, this yet to be published report will be the appropriate citation. Additionally we recommend to state the version used, e.g. <code>v2018a</code> or a GIT revision / tag.
</p>
</section>
......
......@@ -107,6 +107,8 @@
<section id="configuration">
<p><!-- dummy spacer to unhide title on anchor access --><br /></p>
<!--<a href="#" class="image fit"><img src="images/pic05.jpg" alt="" /></a>-->
<h3>Virtual Acoustics configuration</h3>
......@@ -370,7 +372,7 @@ Devices = NeumannTLM170
<h4>Rendering module configuration</h4>
<p>
To instantiate a rendering module a section with a <code>Renderer:</code> suffix has to be included. The statement following <code>:</code> will be the unique identifier of this rendering instance. If you want to change parameters of this renderer during execution, this identifier is required to call the instance. All renderers requires some obligatory definitions, but for the specific parameter set a detailed description is necessary. For typical renderers, some examples are given below.
To instantiate a rendering module a section with a <code>Renderer:</code> suffix has to be included. The statement following <code>:</code> will be the unique identifier of this rendering instance. If you want to change parameters during execution, this identifier is required to call the instance. All renderers requires some obligatory definitions, but for the specific parameter set a detailed description is necessary. For typical renderers, some examples are given below.
</p>
<h5>Required rendering module parameters</h5>
<p>
......@@ -383,39 +385,172 @@ The <code>Reproductions</code> describe the connections to reproduction modules.
<h5>Optional rendering module parameters</h5>
<p>
<pre><code>Description = Some informative description of this rendering module instance
Enabled = TRUE # (default)</pre></code>
Enabled = true
OutputDetectorEnabled = false
RecordOutputEnabled = false
RecordOutputFilePath = MyRenderer_filename_maybe_including_$(ProjectName)_macro.wav
</pre></code>
Rendering modules can be <i>enabled and disabled</i> to fast setup changes without copy & pasting larger parts of a configuration section, because especially reproduction modules can only be instantiated if the sound card provides enough channels. This makes testing on a desktop and switching to a lab environment easier.
<br />
For rendering modules, only the <i>output</i> can be observed. A stream detector for the output can be activated that will produce level meter values, e.g. for a GUI widget. The output of the active listener can also be recorded and exported to a WAV file. Recording starts with initialization and is exported to harddrive after finalization, which implicits that data is kept in the RAM. If high channel numbers are required and/or long recording sessions are planned, it is recommended to route the output through a DAW, instead, i.e. with ASIO re-routing software devices like Reapers ReaRoute ASIO driver. To include a more versatile output file name, macros are allowed.
</p>
Renderung modules can be disabled to fast setup changes without copy & paste, because especially reproduction modules can only be instantiated if the sound card provides enough channels. This makes testing on a desktop and switching to a lab environment easier.
<h5>Binaural free field renderer (class <code>BinauralFreeField</code>)</h5>
<h5>Binaural free field renderer (class <code>BinauralFreeField</code>) example</h5>
<p>
<pre><code>HRIRFilterLength = 128
Enabled = TRUE # (default)</pre></code>
This example with all available key/value config pairs is taken from the default <code>VACore.ini</code> settings that is generated from the repository's <code>VACore.ini.proto</code> (by CMake). It requires a Reproduction called <code>MyTalkthroughHeadphones</code>, which is shown further below.
<pre><code>[Renderer:MyBinauralFreeField]
Class = BinauralFreeField
Enabled = true
Reproductions = MyTalkthroughHeadphones
HRIRFilterLength = 256
MotionModelNumHistoryKeys = 10000
MotionModelWindowSize = 0.1
MotionModelWindowDelay = 0.1
MotionModelLogInputSources = false
MotionModelLogEstimatedOutputSources = false
MotionModelLogInputListener = false
MotionModelLogEstimatedOutputListener = false
SwitchingAlgorithm = linear
OutputDetectorEnabled = false
RecordOutputEnabled = false
RecordOutputFilePath = MyRenderer_filename_maybe_including_$(ProjectName)_macro.wav</pre></code>
The deeper meaning of motion model and further parameters are described in the <a href="documentation">documentation</a> on how the rendering works.
</p>
<h5>Other renderer module examples</h5>
<p>
Every specific rendering module has its own specific set of parameters, and not everything can be covered here. In general, the configurations are parsed in the constructor of the module and the meaning can be extracted by investigating the source code. Furthermore, if the Redstart GUI application has implemented dialogs to create and interact with those renderers, more information can be found when hovering over the GUI elements.
</p>
<h4>Reproduction module configuration</h4>
<p></p>
<p>
To instantiate a reproduction module, a section with a <code>Reproduction:</code> suffix has to be included. The statement following <code>:</code> will be the unique identifier of this reproduction instance. If you want to change parameters during execution, this identifier is required to call the instance. All reproductions requires some obligatory definitions, but for the specific parameter set a detailed description is necessary. For typical reproductions, some examples are given below.
</p>
<h5>Required reproduction module parameters</h5>
<p>
<pre><code>Class = REPRODUCTION_CLASS
Outputs = OUTPUT_GROUP(S)</pre></code>
The reproduction class refers to the type of reproduction, which can be taken from the tables in the <a href="overview.html#reproduction">overview</a> section.<br />
The <code>Outputs</code> describe the connections to logical output groups that forward audio based on the configured channels. At least one output group has to be defined, but the reproduction stream can also be connected to multiple outputs of same or different type (e.g. a lot of different pairs of headphones). The only restriction is, that the reproduction channel number has to match with the output group(s) channel number.
</p>
<h5>Optional reproduction module parameters</h5>
<p>
<pre><code>Description = Some informative description of this reproduction module instance
Enabled = true
InputDetectorEnabled = false
RecordInputEnabled = false
RecordInputFilePath = MyReproInput_filename_maybe_including_$(ProjectName)_macro.wav
OutputDetectorEnabled = false
RecordOutputEnabled = false
RecordOutputFilePath = MyReproOutput_filename_maybe_including_$(ProjectName)_macro.wav
</pre></code>
Reproduction modules can be <i>enabled and disabled</i> to fast setup changes without copy & pasting larger parts of a configuration section, because especially output groups can only be instantiated if the sound card provides enough channels. This makes testing on a desktop and switching to a lab environment easier.
<br />
For reproduction modules, the <i>input and output</i> can be observed. A stream detector on input and output can be activated that will produce level meter values, e.g. for a GUI widget. The input of a reproduction module may include several superposed rendering streams (in constrast to the rendering output), e.g. for direct sound and reverberant sound. The output of a reproduction can also be recorded, and exported to a WAV file. Recording starts with initialization and is exported to harddrive after finalization, which implicits that data is kept in the RAM. If high channel numbers are required and/or long recording sessions are planned, it is recommended to route the output through a DAW, instead, i.e. with ASIO re-routing software devices like Reapers ReaRoute ASIO driver. To include a more versatile output file name, macros are allowed.
</p>
<h5>Talkthrough reproduction (class <code>Talkthrough</code>) example</h5>
<p>
This example with all available key/value config pairs is taken from the default <code>VACore.ini</code> settings that is generated from the repository's <code>VACore.ini.proto</code> (by CMake). It requires an output called <code>MyDesktopHP</code>.
<pre><code>[Reproduction:MyTalkthroughHeadphones]
Class = Talkthrough
Enabled = true
Name = Generic talkthrough to output group
Outputs = MyDesktopHP
InputDetectorEnabled = false
OutputDetectorEnabled = false
RecordInputEnabled = false
RecordInputFilePath = $(ProjectName)_Reproduction_MyTalkthroughHeadphones_Input.wav
RecordOutputEnabled = false
RecordOutputFilePath = $(ProjectName)_Reproduction_MyTalkthroughHeadphones_Output.wav</pre></code>
</p>
<h5>Other reproduction module examples</h5>
<p>
Every specific reproduction module has its own specific set of parameters, and not everything can be covered here. In general, the configurations are parsed in the constructor of the module and the meaning can be extracted by investigating the source code. Furthermore, if the Redstart GUI application has implemented dialogs to create and interact with those reproductions, more information can be found when hovering over the GUI elements.
</p>
</section>
<section id="control">
<h3>Controlling a VA instance</h3>
<p><!-- dummy spacer to unhide title on anchor access --><br /></p>
<h3>Controlling a VA instance ...</h3>
<p>
Once your VA application is running with the desired configuration, you want to control it, i.e. create a scene and modify the entities. You do this with scripts and tracking devices via the VA interface, a list of methods that lets you trigger updates and control settings.<br />
</p>
<h4>... using Matlab</h4>
<p>
The most common way for listening experiments is to use Matlab. VA provides a Matlab binding and a convenience class called <code>itaVA</code>. It lets you connect to the VA server application using a network connection (or the local network port), as already described in the <a href="overview.html">overview section on controlling VA</a>.<br />
You can find the </code>itaVA.m</code> Matlab class along with the required files for communication with VA in the <a href="download.html">VA package under the <code>matlab</code> folder</a>. In case you are building and deploying <code>VAMatlab</code> on your own (for you platform) or in case it is missing, look out for <code>build_itaVA*.m</code> scripts that will generate the convenience class around the <code>VAMatlab</code> executable. If that folder is added to the Matlab path list permanently, it can be accessed from the console independent from the current working directory.
<br />
To get started, inspect the example files and use Matlab's bash completion on an instance of the itaVA class to receive self explanatory functions, i.e. when executing
<pre><code>va = itaVA</code></pre>
The list of available methods is sorted by getter and setter (<code>va.get_*</code> and <code>va.set_*</code>) followed by the entity (<code>sound_receiver</code>, <code>sound_source</code>, <code>sound_portal</code>) and the actual action. To create an entity, directivities and more, use the <code>va.create_*</code> methods.
</p>
<h4>... using Python</h4>
<p>
The free and open source way includes Python. A Python VA module is available that provides network access. It can be installed to run in from anywhere, or it can be placed and imported from a local folder. To obtain the package and example scripts, look out for the <a href="download.html">download a package that includes the Python binding</a>. It's only available for Python 3.6 and recent compilers.
</p>
<h4>... using Unity</h4>
<p>
Once you VA application os running, you want to control it, i.e. create a scene and modify the entities. You do this with scripts and tracking devices.
A more intuitive and playful way to use VA is with Unity, a 3D and scripting development environment for games and Virtual Reality applications. The <code>VAUnity</code> C# scripts extend Unity <code>GameObject</code> and communicates properties to a VA server. Therefore, a C# VA binding is required, which comes with the <a href="download.html">binary packages in the download section</a>. No knowledge of a scripting or programming language is required with this method, just a copy of Unity. How to use VA and Unity is described <a href="https://git.rwth-aachen.de/ita/VAUnity">in the README of the project repository</a>.
</p>
</section>
<section id="scene_handling">
<h3>Scene handling</h3>
<p><!-- dummy spacer to unhide title on anchor access --><br /></p>
<h3>Update handling</h3>
<p>
In VA, everything that is not static is considered part of a dynamic <i>scene</i>. All sound sources, sound portals, sound receivers, geometry and directivities are potentially dynamic and therefore are stored and accessed with a history. During lifetime, they can be modified. Renderers are picking up modifications and react upon the new state, e.g. when a sound source is moved or a sound receiver is rotated.<br />
Updates are triggered asynchronously by the user or by another application and can also be synchronized, e.g. to assure that all signals are started within one audio frame.
</p>
<h4>Sound sources</h4>
<p>... @todo ...</p>
<h4>Sound receivers</h4>
<p>... @todo ...</p>
<h4>Sound portals</h4>
<p>Sound portals are added to the interface for future use and are currently not supported.</p>
<h4>Geometry</h4>
<p>Geometry interface calls are for future use and are currently not supported.</p>
<h4>Acoustic materials</h4>
<p>Acoustic material interface calls are for future use and are currently not supported.</p>
<h4>Scenes</h4>
<p>Scenes are a prototype-like definition to allow renderers to act differently depending on the requested scene identifier. This is useful to implement different behaviour based on a user-triggered scene that should be loaded, e.g. a room acoustic situation or a city soundscape. Most renderers will ignore these calls.</p>
</section>
<section id="inputdata">
<p><!-- dummy spacer to unhide title on anchor access --><br /></p>
<h3>Input data</h3>
<p>
</p>
</section>
......
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