"Installation type" screen of Mac OS X installer. Use "Customize" to get to the component selection.

Installation packages can be downloaded from the `S3A software download page <http://s3a-spatialaudio.org>`_ .

The VISR framework can be obtained in diffeent forms.
FOr most persons, however, downloading and installing an installer package is the most convenient way to use this framework.

Installation packages are available for the following platforms:

Windows (x86_64)
Recent versions (Windows 8 and Windows 10) 64 Bit only

Add a test with the **python_runner** application to check whether the
linked Python library is found and the setting of **PYTHONHOME** is sensible.

 application to check whether the
linked Python library is found and the setting of 

As explained in section :ref:`overview_python_integration`, the Python integration is an optional, albeit central, part of the VISR framework that enables a number of its functionalities, for example:

, the Python integration is an optional, albeit central, part of the VISR framework that enables a number of its functionalities, for example:

Using application that use Python internally, for instance the Binaural Synthesis Toolkit or metadata adaptation processes using the metadapter.

To use these functionalities, a Python 3 distribution must be installed on the computer, and some configuration steps are required.

We recommend `Anaconda <https://www.anaconda.com/download/>`_. Please make sure you install the  Python3 / 64-Bit variant.

Some Mac OS variants (for example 10.12) come with a pre-installed Python 3 variant in **/Library/Frameworks/Python.framework**.
In this case, care must be taken that it does not interferes with the chosen Python distribution. In particular, the **PYTHONHOME** environment variable must be set correctly.

Some Mac OS variants (for example 10.12) come with a pre-installed Python 3 variant in 

.
In this case, care must be taken that it does not interferes with the chosen Python distribution. In particular, the 

Two environment variables must be set to ensure the working of the VISR Python subsystem.

**PYTHONPATH** This variable is used to add the directory containing the VISR python modules to the system path.
To this end, the **python/** subdirectory of the installation folder must be added to **PYTHONPATH**.

Note that other ways exist to add to the system path, for example

.. code-block:: Python

   import sys
   sys.path.append( '<visr_installation_dir>/python' )

However, we recommend setting **PYTHONPATH** and assume this in the examples throughout this document.

 This variable is used to add the directory containing the VISR python modules to the system path.
To this end, the 

PYTHOMHOME
This variable is needed to locate the files and libraries of the Python distribution.
This is especially important if there are more than one distributions on the system, most often on Mac OS X.
Strictly speaking, this variable is required only if VISR Python code is executed from a C++ application, for instance some DAW plugins, **python_runner** standalone application (section ??), or the **visr_renderer** with metadata processing enabled. (see section :ref:`using_visr_using_standalone_renderers_visr_renderer`).

This variable has to be set to the root directory of the Python distribution, i.e.,
one level of hierarchy above the **bin/** folder conatining the Python interpreter.
Depending on the platform and the distribution, the correct value might be:

Windows with Anaconda
  **C:\ProgramData\Anaconda3**
Mac OS X with Anaconda
  **$HOME/anaconda3/**
Linux
  **/usr**

It is necessary to check whether these settings match with your directory layout.

If the Python distribution provides a **python-config** or **python3-config** binary, the command

.. code-block:: bash

  python-config --prefix

or

  python3-config --prefix

can be used to retrieve the required value for **PYTHONHOME**
On Linux, setting **PYTHONHOME** is not necessary in most cases, because there is only the system-provided Python installation available.

Strictly speaking, this variable is required only if VISR Python code is executed from a C++ application, for instance some DAW plugins, 

one level of hierarchy above the 

 folder conatining the Python interpreter.

 is not necessary in most cases, because there is only the system-provided Python installation available.

Depending on the operating system, these variables can be set as follows:

OPENBLAS_NUM_THREADS
It is advisable, in many cases, to set the value of this environment variable to 1. It controls how **numpy** numerical algebra functions are distributed to multiple CPU cores.
**numpy** is used by the VISR Python integration as well as in many Python-based VISR components performing mathematical or DSP operations.
For the matrix/vector sizes typically encountered in our code, the overhead for distributing the work over multiple cores typically exceeds the potential gains.
Multithreading is disabled by setting the maximum number of cores (or threads) to 1:

  OPENBLAS_NUM_THREADS = 1

This setting is optional. However, if you encounter excessive loads, for example a constant 100% load in the real-time thread, this setting can help to resolve the problem.

It is advisable, in many cases, to set the value of this environment variable to 1. It controls how 

 numerical algebra functions are distributed to multiple CPU cores.

 is used by the VISR Python integration as well as in many Python-based VISR components performing mathematical or DSP operations.

Linux
Append the lines

  export PYTHONPATH=$PYTHONPATH:/usr/share/visr/python
  export OPENBLAS_NUM_THREADS=1

to **$HOME/.profile**.

export PYTHONPATH=$PYTHONPATH:/usr/share/visr/python
export OPENBLAS_NUM_THREADS=1

Windows
Add **PYTHONPATH** entries either as a user or system variable as described in :ref:`installation_windows` section.
The corrects setting are (assuming the default installation directory and the Anaconda distribution):

  .. code-block:: bash

  PYTHONPATH=c:\Program Files\VISR-X.X.X\python
  PYTHONHOME=c:\ProgramData\Anaconda3
  OPENBLAS_NUM_THREADS=1

Note that if there is already a **PYTHONPATH** variable, the recommended value should be appended, using a semicolon as a separator.

 section.

PYTHONPATH=c:\Program Files\VISR-X.X.X\python
PYTHONHOME=c:\ProgramData\Anaconda3
OPENBLAS_NUM_THREADS=1

PYTHONPATH=c:Program FilesVISR-X.X.Xpython
PYTHONHOME=c:ProgramDataAnaconda3

 variable, the recommended value should be appended, using a semicolon as a separator.

Mac OS X
In order to set the environment variables system-wide, without requiring that the applications in question is started from a shell, (e.g., a command-line terminal), we recommend a custom **launchd** property list file, as detailed, e.g., in this `StackExchange thread <https://apple.stackexchange.com/questions/106355/setting-the-system-wide-path-environment-variable-in-mavericks>`_.

To this end, create a **VISR-X.X.X.plist** file with this contents

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
    <key>Label</key>
    <string>my.startup</string>
    <key>ProgramArguments</key>
    <array>
      <string>sh</string>
      <string>-c</string>
      <string>
      launchctl setenv PYTHONPATH /Applications/VISR-X.X.X/python
      launchctl setenv OPENBLAS_NUM_THREADS 1
      launchctl setenv PYTHONHOME ${HOME}/anaconda3
      </string>
    </array>
    <key>RunAtLoad</key>
    <true/>
   </dict>
   </plist>

By convention, these files are stored in **/Users/<loginname>/Library/LaunchAgents/**.
To activate the settings, call

  launchctl load <path-to-file>/VISR-X.X.X.plist

To take effect, all applications using these settings (e.g., terminals, Python interpreters, DAWs) must be quit and reopened.

These settings are preserved if the machine is restarted.
To deactivate them, the property list file must be unloaded:

    launchctl unload <path-to-file>/VISR-X.X.X.plist

If you made changes to the settings, you have to perform the **unload** command followed by a **load**.

For convenience, the installers create a pre-configured **VISR-X.X.X.plist** file in the **etc** subdirectory of the installation directory (e.g., **/Applications/VISR-X.X.X/etc/VISR-X.X.X.plist** ).
This file can be either loaded directly or copied to the **LaunchAgents/** directory first. Please check the values in this file first and adjust them accordingly.

In order to set the environment variables system-wide, without requiring that the applications in question is started from a shell, (e.g., a command-line terminal), we recommend a custom 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
 <key>Label</key>
 <string>my.startup</string>
 <key>ProgramArguments</key>
 <array>
   <string>sh</string>
   <string>-c</string>
   <string>
   launchctl setenv PYTHONPATH /Applications/VISR-X.X.X/python
   launchctl setenv OPENBLAS_NUM_THREADS 1
   launchctl setenv PYTHONHOME ${HOME}/anaconda3
   </string>
 </array>
 <key>RunAtLoad</key>
 <true/>
</dict>
</plist>

 directory first. Please check the values in this file first and adjust them accordingly.

Depending on the system, we suggest different Python distributions:

Binary installation packages are the suggested way to uses the VISR framework.
A binary installers enables all uses of the framework, including

Using the Python interfaces and creating new functionality in Python

Creating standalone applications and extension libraries in C++

Building the VISR from source is necessary only in these cases:

- Porting it to a platform where no binary installer exists
- Fixing or changing the internal workings of the framework.

Installation packages are available on the `S3A Software download page <http://s3a-audio.space>`_.

If you plan to use the Python integration of the VISR framework (see :ref:`overview_python_integration`), you need to select an installation package matching the Python version you are using, for example **VISR-X.X.X-python36-Windows.exe**.

If you plan to use the Python integration of the VISR framework (see 

), you need to select an installation package matching the Python version you are using, for example 

The graphical installer is provides as an **.exe** file and provides a dialog-based, component-enables installation.
Figure figure_windows_installer_ shows the component selection dialog of the installer. The choices are detailed below in section :ref:`installation_component_description`.

 file and provides a dialog-based, component-enables installation.
Figure 

 shows the component selection dialog of the installer. The choices are detailed below in section 

.. figure:: ../images/windows_installer.png
   :scale: 100 %
   :align: center

   Graphical Windows installer.

An executable installer (.exe) with a graphical user interface and corresponding uninstall functionality. Supported are 64-bit versions of Windows.
If required, install the "Microsoft Visual C++ Redistributable for Visual Studio 2017", package,
for example from the `Visual C++ downloads page <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_.

for example from the 

`Visual C++ downloads page <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_

On Windows, it is necessary to add the directory containing the VISR libraries (DLLs) as well as the directory containing third-party libraries shipped with the VISR installer to the **PATH** variable.
To this end, open the environment variable editor (Settings -> System -> Advanced system settings -> Environment variables).
The environment variable on Windows 10 is depicted in figure windows_environment_variables_editor .

On Windows, it is necessary to add the directory containing the VISR libraries (DLLs) as well as the directory containing third-party libraries shipped with the VISR installer to the 

 variable.

.. figure:: ../images/windows_environment_variables_editor.png
   :scale: 50 %

   Environment variable editor on Windows 10.

Append the value "C:\ Program Files\VISR-X.X.X\lib;C:\ Program Files\VISR-X.X.X\3rd" if the standard installation location was used. (Note: Replace **X.X.X** with the actual version number of VISR.
Depending on your system permissions and whether you VISR shall be used by all users of the computer, you can either set the **PATH** user variable or the **PATH** system variable.

Append the value "C:Program FilesVISR-X.X.Xlib;C:Program FilesVISR-X.X.X3rd" if the standard installation location was used. (Note: Replace 

Append the value "C:\ Program Files\VISR-X.X.X\lib;C:\ Program Files\VISR-X.X.X\3rd" if the standard installation location was used. (Note: Replace 

 with the actual version number of VISR.
Depending on your system permissions and whether you VISR shall be used by all users of the computer, you can either set the 

Any applications used to access VISR (for example command line terminals, Python development environments, or DAWs) must be closed and reopened before the changed paths take effect.

Append the path ''<install-directory>/lib'' to the path variable, where ''install_diectory'' is the directory specified during the installation.
For the default path, the setting would be ''c:\Program Files\VISR-N.N.N\lib'', where ''N.N.N is replaced by the actual version number.
If the **PATH** variable is edited as a string, subsequent paths are separated by semicolons.

For the default path, the setting would be ''c:Program FilesVISR-N.N.Nlib'', where ''N.N.N is replaced by the actual version number.
If the 

If the 

 variable is edited as a string, subsequent paths are separated by semicolons.

Future versions of the installer might adjust the paths automatically.
However, as pointed out in
`NSIS Path manipulation <http://nsis.sourceforge.net/Path_Manipulation>`_,
this needs an extremely cautious implementation to avoid potential damage to users' systems.

`NSIS Path manipulation <http://nsis.sourceforge.net/Path_Manipulation>`_

,

To use standalone applications (see section :ref:`using_visr_using_standalone_renderers`), it may be useful to add the **bin/** directory to the user or system path.
For the default installation location, add ''c:\Program Files\VISR-N.N.N\bin'' to the **%PATH%** environment variable.

 directory to the user or system path.
For the default installation location, add ''c:Program FilesVISR-N.N.Nbin'' to the 

For the default installation location, add ''c:\Program Files\VISR-N.N.N\bin'' to the 

An installer with a graphical user interface guides through the installation process and allows the selection of optional components.
Figure :ref:`figure_visr_macos_installer` shows a screenshot of this installer.
By default, it installs the VISR into the directory **/Applications/VISR-X.X.X/** where **X.X.X** denotes the version number.

Figure 

 shows a screenshot of this installer.
By default, it installs the VISR into the directory 

.. figure:: ../images/visr_macos_installer.png

   Component-based installer for Mac OS X.

To access the component selection dialog, use the button "Customize" on the "Installation Type" screen (see figure :ref:`figure_visr_macos_installer_customize`)

To access the component selection dialog, use the button "Customize" on the "Installation Type" screen (see figure 

.. figure:: ../images/visr_macos_installer_customize.png

   "Installation type" screen of Mac OS X installer. Use "Customize" to get to the component selection.

To use the standalone applications from the command line, the **bin/** subfolder of the installation directory, e.g., **/Applications/VISR-X.X.X/bin**.
This can be done, for example, by adding

to the file **$HOME/\.bash_profile**.
However, this works only for running standalone applications from a shell (i.e., a terminal window).
If you need this path also from applications that are not started from a shell, we recommend the solution used in section :ref:`installation_python_setup_configuration`.

.
If you need this path also from applications that are not started from a shell, we recommend the solution used in section 

For Linux, installation packages are provided as *.deb* (Debian) packages.
At the moment, this package is monolithic, i.e., it contains all components.
They are installed via the command

 (Debian) packages.

If this command reports missing dependencies, these can be installed subsequently with the command

With the dialog-based, component-enabled installers, parts of the framework can be chosen depending on the intended use of the framework.

Shared Libraries
The core VISR libraries. This component is mandatory and cannot be unselected.

Standalone applications.
Renderers and small tools to be run as command-line applications.

Python externals
Python modules that give access to the functionality of the framework from Python.
Also needed to run applications that use Python internally (e.g., the binaural synthesis toolkit or metadapter-enabled rendering).

Python Packages
VISR extensions implemented in Python. This group of components requires the component "Python externals".

Development files
Header files and CMake build support - Needed to extend the VISR with components using C++ or use the framework in external C++ applications.

Loudspeaker configurations
A set of standard loudspeaker configuration files and additional example files from actual locations.

Python templates
A set of commented template files for different types of VISR components.

Documentation
User and code reference documentation as PDF documents.
The Doxygen code documentation covering the complete source code can be optionally selected. However, the latter documentation is deprecated and will be contained in the code reference documentation in the future.

Hyperlink target "windows-environment-variables-editor" is not referenced.

Hyperlink target "figure-visr-macos-installer" is not referenced.

Hyperlink target "figure-visr-macos-installer-customize" is not referenced.

Hyperlink target "installation-component-description" is not referenced.

Hyperlink target "installation-python-setup-configuration" is not referenced.

We suggest some basic tests to verify that the VISR framework has been correctly installed and configured.

This test is to ensure that that the installation is successful, and that the VISR shared libraries can be located and are compatible with the system.
When using the component-enabled installers, the component ``Standalone applications`` must have been selected in order to perform this check.

When using the component-enabled installers, the component 

In a terminal (Linux shell, Mac OS Terminal application, Windows command line **cmd**),
execute this command:

In a terminal (Linux shell, Mac OS Terminal application, Windows command line 

For the different platforms, the full commands are (assuming the default installation directory)
Windows

  "c:\Program Files\VISR-X.X.X\bin\matrix_convolver.exe" --version

Note that the quotes are necessary to cope with the space in the path.

If there is an error message about a missing shared library (or DLL), you should consult the respective section about installation.
In particular this applies Windows, where the **PATH** variable needs to be set accordingly.

In particular this applies Windows, where the 

This test ensures that the VISR framework can be used interactively from Python interpreters.

First start a Python 3 interpreter (for example **python** or **ipython**).
Depending on the system, the binaries might be called **python3** or **ipython3**, respectively
It must be the interpreter of the Python distribution you intend to use (e.g., Anaconda).

, respectively

This command should return without an error message.
In this case, you can check whether the module is loaded from the correct location:

The directory of the resulting file path should be **<visr-installation-dir>/python**.
For example, on Windows this returns **C:\Program Files\VISR 0.10.0\\python\\visr.pyd**.

Setting up a build environment, including the required software tools, and compiling the source code is detailed in the `VISR API documentation <http://s3a-spatialaudio.org>`_.

Setting up a build environment, including the required software tools, and compiling the source code is detailed in the 

Alternatively, the VISR framework can be installed and build from source code.
It is hosted at the GitLab repository https://gitlab.eps.surrey.ac.uk:s3a/VISR.git

It is hosted at the GitLab repository 

visr::objectmodel::PointSource::channelLockDistance (C++ function)

visr::objectmodel::PointSource::mChannelLockDistance (C++ member)