Getting PsychXR =============== 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. The PsychXR installer will automatically pull any Python package dependencies, such as `Cython `_ and `NumPy `_, prior to installation. System Requirements ------------------- *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-.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. .. note:: 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). .. image:: ./_static/build_on_windows1.png :alt: Feature "Desktop development with C++" selected in the Visual Studio Installer window. :align: center 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`. .. note:: 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. .. image:: ./_static/psychxr_build_windows4.PNG :alt: Feature "Desktop development with C++" selected in the Visual Studio Installer window. :align: center .. note:: 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). .. image:: ./_static/build_on_windows2.png :alt: Start menu item showing the "x64 Native Tools Command Prompt for VS 2019" icon. :align: center You should see the following a command prompt appear on-screen. .. image:: ./_static/build_on_windows3.PNG :align: center Within the prompt, change the directory to the `PsychXRBuild` folder created earlier using the `cd` command, making it the present working directory:: cd C:\Users\matth\Desktop\PsychXRBuild 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:: set PSYCHXR_BUILD_LIBOVR=1 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:: set PSYCHXR_LIBOVR_SDK_PATH=C:\Users\matth\Desktop\PsychXRBuild\OculusSDK Now we can build the source package by entering the following command (replacing with the current version of the package, which is **0.2.4**):: python -m pip install psychxr-.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:: set PSYCHXR_BUILD_OPENHMD=1 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.