Commit 6fcbe86f authored by fpa's avatar fpa
Browse files

changes till Control VA using Python

parent 598ef093
......@@ -505,7 +505,7 @@ Reproductions = MyDesktopHP, MySubwooferArray</pre></code>
<h5>Binaural artificial room acoustics renderer (class <code>BinauralArtificialReverb</code>) example</h5>
<p>
Values are specified in SI units (e.g., seconds, meters, watts, etc.), and angles are in degrees. The reverberation time may exceed the reverberation filter length (divided by the sampling rate) but the generated impulse response will be cropped. This renderer requires and uses sound receiver HRIR for spatialization, and adapts sound power correction to match with direct sound if used together with the binaural free field renderer.
Values and angles are specified in SI units (e.g., seconds, meters, watts, etc.) and angles, respectively. The reverberation time may exceed the reverberation filter length (divided by the sampling rate) resulting in a cropped impulse response. This renderer requires and uses the sound receiver HRIR for spatialization and applies a sound power correction to match with direct sound energy if used together with the binaural free field renderer.
<pre><code>[Renderer:MyBinauralArtificialRoom]
Class = BinauralArtificialReverb
Description = Low-cost per receiver artificial reverberation effect
......@@ -525,7 +525,7 @@ ScatteringCoefficient = 0.1</pre></code>
<h5>Binaural room acoustics renderer (class <code>BinauralRoomAcoustics</code>) example</h5>
<p>
Requires the Room Acoustics for Virtual ENvironments (RAVEN) software module or other room acoustics simulation backends [Reference???]. Note that the reverberation time may exceed the reverberation filter length (divided by the sampling rate) with the consequence that the generated impulse response will be cropped. Requires and uses sound receiver HRIR for spatialization. Adapt sound power correction to match with direct sound if combined with binaural free field renderer.
Requires the Room Acoustics for Virtual ENvironments (RAVEN) software module (see <a href="research.html">Research section</a>) or other room acoustics simulation backends. Note that the reverberation time may exceed the reverberation filter length (divided by the sampling rate) with the consequence that the generated impulse response will be cropped. This renderer requires and uses the specified sound receiver HRIR data set for spatialization and applies a sound power correction to match with direct sound energy if combined with binaural free field renderer.
<pre><code>[Renderer:MyBinauralRoomAcoustics]
Class = BinauralRoomAcoustics
Enabled = true
......@@ -551,7 +551,7 @@ DirectSoundPowerCorrectionFactor = 0.3</pre></code>
<h5>Prototype free field renderer (class <code>PrototypeFreeField</code>) example</h5>
<p>
Similar to binaural free field renderer, but can handle multi channel receiver directivities. Often used with output recording for microphone array simulations.
Similar to binaural free field renderer with the capability of handling multi-channel receiver directivities. This renderer can, for example, be used for recording the output of microphone array simulations.
<pre><code>[Renderer:MyPrototypeFreeField]
Class = PrototypeFreeField
Enabled = true
......@@ -568,7 +568,7 @@ SwitchingAlgorithm = linear</pre></code>
<h5>Prototype generic path renderer (class <code>PrototypeGenericPath</code>) example</h5>
<p>Channel number and length can be arbitrary, but is limited by the computational power available. Filtering is done for each source-receiver-pair individually.
<p>Channel count and length can be specified arbitrarily but is limited by the computational power available. Filtering is done individually for each source-receiver pair.
<pre><code>[Renderer:MyPrototypeGenericPath]
Class = PrototypeGenericPath
Enabled = true
......@@ -581,7 +581,7 @@ OutputMonitoring = true</pre></code>
<h5>Binaural air traffic noise renderer (class <code>BinauralAirTrafficNoise</code>) example</h5>
<p>Filtering is done for each source-receiver-pair individually. Effects can also be updates by user for prototyping (requires external simulation flags to be true).
<p>Filtering is done individually for each source-receiver pair. Involved filters the simulation of propagation paths can also be exchanged by the user for prototyping (requires a modification of simulation flags in the configuration file).
<pre><code>
[Renderer:MyAirTrafficNoiseRenderer]
Class = BinauralAirTrafficNoise
......@@ -606,7 +606,7 @@ SwitchingAlgorithm = cubicspline</pre></code>
<h5>Dummy renderer (class <code>PrototypeDummy</code>) example</h5>
<p>For starting your own prototype renderer. Can be quickly build upon.
<p>Useful for a quick configuration of your own prototype renderer.
<pre><code>[Renderer:MyDummyRenderer]
class = PrototypeDummy
Description = Dummy renderer for testing, benchmarking and building upon
......@@ -619,22 +619,22 @@ Reproductions = MyTalkthroughHeadphones</pre></code>
<h5>Other rendering 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.
Every specific rendering module has its own specific set of parameters. The discussion of every functional detail is out of scope of this introduction. As all configurations are parsed in the constructor of the respective module, their functionality can sometimes only be fully understood by investigating the source code. For facilitation, the Redstart GUI application includes dialogs to create and interact with those renderers, additionally offering information when hovering over the GUI elements.
</p>
<h4>Reproduction module configuration</h4>
<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.
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 reproduction modules require some obligatory definitions but for every specific parameter set, a detailed description is necessary. For typical reproduction modules, 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.
The reproduction class refers to the type of reproduction as provided in the section <a href="overview.html#reproduction">overview</a>.<br />
The parameter <code>Outputs</code> describes 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., different pairs of headphones). The only restriction is that the reproduction channel number has to match with the channel count of the output group(s).
</p>
<h5>Optional reproduction module parameters</h5>
......@@ -648,14 +648,14 @@ OutputDetectorEnabled = false
RecordOutputEnabled = false
RecordOutputFilePath = MyReproOutput_filename_may_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.
Reproduction modules can be <i>enabled and disabled</i> to speed up setup changes without copy & pasting larger parts of a configuration section as 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.
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, to be used in a GUI widget or so. The input of a reproduction module may include several superposed rendering streams (in constrast to the rendering output), for example, for direct sound and reverberant sound. The output of a reproduction can also be recorded and exported to a WAV file. The recording starts at initialization and is exported to hard drive after finalization implicating that data is kept in the RAM. If a lot of channel numbers are required and/or long recording sessions are planned it is recommended to route the output through a DAW using, for example, ASIO re-routing software devices like Reapers ReaRoute ASIO driver. Macros are useful to include a more versatile output file name.
</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>.
<p>The following example with all available key/value configuration pairs is taken from the default <code>VACore.ini</code> settings which 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
......@@ -670,7 +670,7 @@ RecordOutputFilePath = $(ProjectName)_Reproduction_MyTalkthroughHeadphones_Outpu
</p>
<h5>Low frequency / subwoofer mixing reproduction (class <code>LowFrequencyMixer</code>) example</h5>
<h5>Low-frequency / subwoofer mixing reproduction (class <code>LowFrequencyMixer</code>) example</h5>
<pre><code>[Reproduction:MySubwooferMixer]
Class = LowFrequencyMixer
Enabled = true
......@@ -679,7 +679,7 @@ Outputs = Cave_SW
MixingChannels = ALL # Can also be a single channel, e.g. zero order of Ambisonics stream</code></pre></p>
<h5>Equalized headphones reproduction (class <code>Headphones</code>) example</h5>
<p>Two-channel equalization using FIR filtering of given measured and post-processed inverse impulse response.
<p>Two-channel equalization using FIR filtering based on post-processed inverse headphone impulse responses measured through in-ear microphones.
<pre><code>[Reproduction:MyHD600]
Class = Headphones
Description = Equalized Sennheiser HD600 headphones
......@@ -692,7 +692,7 @@ HpIRInvCalibrationGainDecibel = 0.1
Outputs = MyHD600HP</code></pre></p>
<h5>Multi-channel cross-talk cancellation reproduction (class <code>NCTC</code>) example</h5>
<p>Requires an output called <code>MyDesktopLS</code>. In case of a dynamic NCTC reproduction, only one receiver can be tracked (indicated by <code>TrackedListenerID</code>, uses </i>real world pose</i>). <code>DelaySamples</code> shifts the final CTC filters to gain causality, should match with <code>CTCFilterLength</code> (e.g. half of filter length).
<p>Requires an output called <code>MyDesktopLS</code>. In case of a dynamic NCTC reproduction, only one receiver can be tracked (indicated by <code>TrackedListenerID</code> which is orientated and located based on a </i>real-world pose</i>). <code>DelaySamples</code> shifts the final CTC filters to obtain causal filters. The amount of the delay has to be set reasonably regarding <code>CTCFilterLength</code> (e.g., apply a shift of half the filter length).
<pre><code>[Reproduction:MyNCTC]
Class = NCTC
Enabled = true
......@@ -710,7 +710,7 @@ CTCDefaultHRIR = $(DefaultHRIR)
Optimization = OPTIMIZATION_NONE</pre></code></p>
<h5>Higher-order Ambisonics decoding (class <code>HOA</code>) example</h5>
<p>Creates decoding matrix based on given output. Can only be used for one output.
<p>Creates a decoding matrix based on a given output configuration, but can only be used for one output.
<pre><code>[Reproduction:MyAmbisonics]
Class = HOA
Enabled = true
......@@ -722,7 +722,7 @@ ReproductionCenterPos = AUTO # or x,y,z</pre></code></p>
<h5>Ambisonics binaural mixdown (class <code>AmbisonicsBinauralMixdown</code>) example</h5>
<p>Applies directions of loudspeaker setup using binaural technology based on <code>VirtualOutput</code> group. Can also be used for perfect virtual Ambisonics downmix.
<p>Encodes the individual orientations of loudspeakers in a loudspeaker setup using binaural technology based on the <code>VirtualOutput</code> group. It can also be used for a virtual Ambisonics downmix with ideal spatial sampling layout.
<pre><code>[Reproduction:AmbisonicsBinauralMixdown]
Class = AmbisonicsBinauralMixdown
Enabled = true
......@@ -736,7 +736,7 @@ HRIRFilterLength = 128</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.
Every specific reproduction module has its own specific set of parameters. The discussion of every functional detail is out of scope of this introduction. As all configurations are parsed in the constructor of the respective module, their functionality can sometimes only be fully understood by investigating the source code. For facilitation, the Redstart GUI application includes dialogs to create and interact with those renderers, additionally offering information when hovering over the GUI elements.
</p>
</section>
......@@ -749,28 +749,28 @@ HRIRFilterLength = 128</pre></code></p>
<h3>Controlling a Virtual Acoustics 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 />
Once your VA application is running as configured, you eventually want to create a virtual scene and modify its entities. Scene control is possible via scripts and tracking devices (e.g, NaturalPoint's OptiTrack). The VA interface provides a list of methods which lets you trigger updates and control settings.<br />
</p>
<h4>Control VA using Matlab</h4>
<p>
The most common way for prototyping, testing and for listening experiments is to use <b>Mathworks Matlab</b>. VA provides a Matlab binding and a convenience class called <code>itaVA</code>. It lets you connect to the VA server application over a TCP/IP 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.
The most common way to control VA for prototyping, testing, and in the scope of listening experiments is by using <b>MathWorks' Matlab</b>. VA provides a Matlab binding and a convenience class called <code>itaVA</code>. Once initialized, the class object can be connected to the VA server application over a TCP/IP 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 your platform), or if it is missing, look out for <code>build_itaVA*.m</code> scripts that will generate the convenience class around the <code>VAMatlab</code> executable. Adding this folder to the Matlab path list, will enable permanent access from the console, independently of 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
To get started, inspect the example files and use Matlab's bash completion on an instance of the <code>itaVA</code> 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.
The list of available methods is sorted by getter and setter nomenclature (<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.
<br />
<br />
<blockquote>
All example calls to control VA are shown in <b>Matlab code style</b>. The naming convention in other scripting languages, however, is very similar. C++ and C# methods use capitalized words without underscores.
Note: All example calls to control VA are shown in <b>Matlab code style</b>. The naming convention in other scripting languages, however, is very similar. C++ and C# methods use capitalized words without underscores.
</blockquote>
</p>
<h4>Control VA 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.
A Python VA module is available facilitating network access. It can be installed to run 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>Control VA using Unity</h4>
......
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