Preparing for Installation¶
PsychXR requires Python 3.6 and above, download it here. Since PsychXR will only build in 64-bit, ensure that the version of Python you install is also 64-bit.
PsychXR requires Windows 7, 8.1 or 10 (Windows 10 is recommended). If using the LibOVR driver, you must install the Oculus Desktop application and have an Oculus or Facebook account. If your PC hardware configuration is supported by the HMD you are using, then it should be adequate for running solutions which incorporate PsychXR.
Installing from PyPI¶
The latest source and binary packages are usually made available on Python Package Index (PyPI). They can be pulled from PyPI repository automatically and installed by issuing the following command:
python -m pip install psychxr
If the binaries are not available for some reason (eg. your version of Python is too new), pip will try to build the source distribution, it will likely fail since you need to setup your build environment. In that case, see the “Building from Source” section for more information.
Installing Pre-Compiled Binaries¶
Pre-compiled binaries for PsychXR are available as a Wheel packages which can be installed via pip. These releases are usually newer than those on PyPI. You may download these packages from the releases page on GitHub. After downloading, you can install PsychXR with the following command (no environment variables or compilers needed):
python -m pip install psychxr-<version>.whl
Note that the pre-compiled binaries are built on Windows 10 64-bit using the MSVC++ 19.0 64-bit, supporting Python versions 3.6 to 3.9. If your configuration differs, consider building from source.
Building from Source¶
Usually, you can simply download and install pre-built binaries which require no additional steps like regular Python packages. However, if you plan on developing PsychXR, use preview features (e.g., OpenHMD) or wish to run PsychXR on Python versions which do not have official packages up on PyPI or GitHub yet, you will need to build PsychXR from source. Doing so requires some preparation to create a suitable build environment on your computer. However, the process to actually build PsychXR is fairly straightforward once the environment is setup.
PsychXR is (mostly) written in Cython, a superset of the Python programming language, which is used to write the interface between Python and HMD drivers. Unlike regular Python code, Cython libraries must be ‘built’ using a C++ compiler. Afterwards, they can be installed and used like any other Python library.
Since the Oculus Rift on Microsoft Windows is the only supported HMD at this time, this guide will only cover building on that platform.
Setting up the build environment¶
If you choose to build PsychXR from source, you must have the appropriate environment setup on your computer. The software requires a C++ compiler to build. Microsoft Windows does not usually ship with the tools to build C++ applications, therefore you must use the Microsoft Visual Studio installer to get those features (the free “Community” edition will suffice). Upon downloading and running the “Visual Studio Installer” application, you will be presented with a pallet of optional features to install. Select “Desktop development with C++” feature and start the installation (see below).
Now create a folder somewhere accessible on your PC. For this example, we’ll
create a folder on our desktop called PsychXRBuild (the full path being
C:\Users\matth\Desktop\PsychXRBuild for this example). Download the Oculus
SDK for Windows
(version v23.0 is required) and extract the contents of the zip file to a folder
inside the PsychXRBuild called OculusSDK.
Due to licensing restrictions the Oculus Rift PC SDK cannot be shipped with PsychXR.
Finally get a copy of the latest source distribution package for PsychXR which can be downloaded from the releases page. Place that too into the PsychXRBuild folder. When you open the PsychXRBuild folder in Explorer it should look something like what’s shown below.
If you build PsychXR using a version of the Oculus PC SDK other than 23.0 (1.55), a warning will be raised upon importing the module. The software should work fine if the SDK version is newer and has no breaking changes. However, this may result in unexpected behaviour!
Building from a source distribution¶
Now that we have our build environment setup, we can now build PsychXR from its source distribution. To do so, open the “x64 Native Tools Command Prompt for VS 2019” (to find it, check your Start menu under “Visual Studio 2019” as shown below).
You should see the following a command prompt appear on-screen.
Within the prompt, change the directory to the PsychXRBuild folder created earlier using the cd command, making it the present working directory:
Now we need to configure the build script by setting environment variables. The build script needs these values to know which SDK we’re building extensions for and where any required files are located. We tell the installer to build extensions for the Oculus SDK (LibOVR) by issuing the following command:
The installer needs to know where the Oculus PC SDK files are located to build
the LibOVR extension. The SDK contains files needed to compile the interface
which are provided by the manufacturer. It does this by looking at the value of
the environment variable
PSYCHXR_LIBOVR_SDK_PATH. Since we placed the SDK
files in a folder called OculusSDK located inside PsychXRBuild, we simply
need to enter the following command:
Now we can build the source package by entering the following command (replacing <version> with the current version of the package, which is 0.2.4):
python -m pip install psychxr-<version>.tar.gz
Building the OpenHMD Extension¶
A preview version of the OpenHMD extension is available as of version 0.2.4 of PsychXR. If you want to try it out, you can tell the installer to build it by setting the following environment variable prior to building the source distribution:
You do not need to specify an SDK of OpenHMD path as PsychXR ships with the required files and the installer knows where to find them.
Testing the Installation¶
If everything goes well, PsychXR should be installed and ready to use. You can test it by plugging in your HMD issuing the following command into your Python interpreter:
>>> import psychxr.drivers.libovr as libovr >>> libovr.isHmdConnected() True
If you have an HMD connected and the Oculus runtime installed on your PC, the above statements will result in True being returned. False is returned if you just have the runtime installed but no HMD connected. That will still indicate a successful installation. If you get any exception raised when entering the above commands, the installation has likely failed at some point.
Help! I can’t get PsychXR installed¶
If this happens try the above steps again or another installation method. If you are really stuck, consider submitting an issue to the project’s GitHub page detailing the steps you took and were things began to fail. It is also likely that the any difficulty encountered is not your fault and might be due to unclear or erroneous documentation. Suggestions and fixes are always welcome to make the process smoother for everyone.