A-SPACE is a client-server toolkit for controlling VR experiences from MATLAB or any other environment capable of TCP/IP messaging. Transparently compatible with HTC Vive and Oculus Rift.
VR offers an exciting new paradigm for perception science. Auditory and visual stimuli can be presented in a stable egocentric (user-centered) space, transcending the limits of small desktop displays and within-head stereo sound. Spatial scenes and perceptual tasks can be made more realistic without sacrificing experimental control.
A-SPACE offers a way to easily add VR components to your existing experimental framework. A-SPACE implements a simple but flexible VR arena which is controlled entirely using TCP/IP messages. There is no need to recode your experiments in C or C#, or to learn 3D game development tools before implementing a VR version of your study. A-SPACE runs without modification on Oculus Rift and HTC Vive.
And A-SPACE is continually evolving. The current version is highly functional and actively used in funded research projects. But features are being added rapidly in response to feedback from the scientific community. Using A-SPACE and adding your voice will help shape the direction of these tools and also help encourage manufacturers to stay responsive to the needs of perception scientists.
A-SPACE was developed in Unity 3D, a popular and well-supported framework for 3D game development. VR components of A-SPACE make use of the Oculus Integration Plugin for Unity, which is compatible with Oculus Rift/Rift S, HTC Vive, Oculus Quest, and Oculus Go. To run A-SPACE on Rift or Vive with touch controls, you will need a PC conforming to the hardware requirements of your headset. A desktop PC, running Windows and sporting a mid-range graphics card (NVIDIA GTX 1060 / AMD Radeon RX 480 or greater) works well, as should most gaming laptops. For standalone VR experiences, A-SPACE is installed directly onto the headset and no other hardware is required.
Because A-SPACE uses TCP/IP messaging, the server (e.g., MATLAB) and client (A-SPACE) can run on the same PC or on different machines. For example, A-SPACE might run on a dedicated PC (or on a standalone VR device) but be controlled by a Mac Pro that uses MATLAB to deliver sound in a high-density loudspeaker array. Use of a dedicated LAN is recommended if possible, though not required.
Oculus Go is a standalone VR device that supports 3-DOF tracking (rotation, but not translation) of the head and a single hand controller. A-SPACE Go was the first release of A-SPACE for standalone VR hardware, and supported a limited feature set compared to A-SPACE on Vive or Rift. As of A-SPACE 0.60, however, all platforms (Rift, Vive, Quest, and Go) run identical software, and A-SPACE Go is no longer supported as a separate product.
For standalone devices (Oculus Quest and Go), A-SPACE uses wi-fi to communicate with another host running MATLAB, Python, or Max/MSP, using the same TCP/IP commands as A-SPACE. Although all features of A-SPACE are supported by the software, keep in mind that the Oculus Go does not offer translation tracking, although it remains an excellent choice for seated VR experiences on a limited budget. For standalone experiences with 6DOF tracking (rotation + translation), consider running A-SPACE on Oculus Quest.
As of version 0.6, A-SPACE is in public beta release. Upon registration, early beta users will be provided the software without charge. Click here to register and obtain a download link.
Once you download the distribution .zip file, simply extract the files and move the extracted folder to a convenient place. You can run A-SPACE directly by launching the .exe file. For standalone devices (Oculus Quest and Go), you will need to install the Android package (.apk) file directly through a process called “sideloading.” This can be done using readily available programs such as sidequest (sidequestvr.com) or adb (developer.android.com). Note that your device will need to have “developer mode” enabled via the Oculus mobile app used to set up the device. More detailed installation instructions are included in the file README.txt included in the distribution folder.
A-SPACE was developed in Unity 3D and uses the Oculus VR API for Unity. Once installed, launching the A-SPACE application will display a blank space with instructions on a visible text panel. Pressing the start button tells the A-SPACE server to wait for a connection from a software client, such as MATLAB. Make sure that both devices are on the same network (wi-fi or wired LAN) and note the “Local IP” listed in A-SPACE, then make a TCP/IP client connection to the A-SPACE server. In MATLAB, for example, enter the following command to connect to A-SPACE running on device with local IP 192.168.0.10:
t = tcpip('192.168.0.10',4040); fopen(t);
Be sure to replace ‘192.168.0.10’ with your own local IP. If A-SPACE and MATLAB are running on the same PC, you can use 127.0.0.1. Once you execute the fopen(t) command, the A-SPACE GUI should disappear and the VR headset should display the A-SPACE default layout (white floor and front wall, all compass lines, homebox active, default Unity skybox). A command console is also visible (but can be hidden on command). The console can help when debugging A-SPACE commands sent by your client program. At this point, commands can be sent from MATLAB using fprintf():
fprintf(t,'WALL NONE\n'); % turn off wall and floor fprintf(t,'PANO ON\n'); % turn on panosphere (default image) fprintf(t,'PANO http://www.pensionflora.it/en/panorama-360/#\n'); % load from URL fprintf(t,'TARG NEW 15 10 0\n'); % place a target marker fprintf(t,'TARG 0 COLOR BLUE\n'); % color it blue
etc. Data can also be read from A-SPACE using fread() or fgetl():
fprintf(t,'READTIME\n'); % Time stamp (seconds) time = sscanf(fgetl(t),'%f\n'); fprintf(t,'READHEAD\n'); % read head position and orientation headPositionString = fgetl(t);
A-SPACE supports many more behaviors and commands. More detailed documentation is included in the distribution folder.
A high-level MATLAB interface class is currently under development. It will provide a simple set of MATLAB function calls to manipulate and monitor A-SPACE without low-level TCP/IP messaging.
A different direction is to skip MATLAB entirely. Any system capable of sending and receiving TCP/IP messages can control A-SPACE: interactive Max/MSP patches, Python scripts, tablet apps, or even terminal emulators can be used.
An example python client, textclient.py, is included in the distribution folder. It offers a very simple command-line interface that allows one to type and send A-SPACE commands directly. You are welcome to modify textclient.py to build your own client application to run an experiment, game, or other experience.
Although “stock” A-SPACE is capable of handling almost anything you might want in a single-subject psychophysical paradigm, we recognize that some experimental designs require greater customization. APE and A-SPACE were originally developed and refined over time to support consulting projects, catering to the specific needs of our clients. Perhaps your project has specific needs that our software can be extended to address.
- Synchronizing with audio capture or brain imaging (EEG, fNIRS) data?
- Coordinating multiple concurrent VR users to study personal interaction?
- Using an iPad app to monitor and control an experiment interactively?
- Replacing the VR arena with a dynamic scene containing obstacles and objectives?
Please contact us to discuss consulting services including custom software development to meet the unique needs of you project.