DeepMReye: magnetic resonance-based eye tracking using deep neural networks
This Jupyter Notebook provides a step-by-step walkthrough of the code. It includes eyeball coregistration, voxel extraction, model training and test as well as basic performance measures. Alternatively, here is a Colab Notebook.
This Data Repository includes exemplary data for model training and test, source data of all paper figures as well as pre-trained model weights.
Moreover, here are additional User Recommendations as well as a Frequently-Asked-Questions (FAQ) page. If you have other questions, please reach out to us.
Installation - Option 1: CPU version
Pip installation
Install DeepMReye with a CPU version of TensorFlow using the following command.
pip install git+https://github.com/DeepMReye/DeepMReye.git
Anaconda / Miniconda installation
Install Anaconda or miniconda and clone this repository:
git clone https://github.com/DeepMReye/DeepMReye.git
cd DeepMReye
Create a virtual environment for DeepMReye with the following commands:
conda create --name deepmreye python=3.7
conda install --file requirements.txt
conda activate deepmreye
If installation of ANTsPy fails try to manually install it via:
git clone https://github.com/ANTsX/ANTsPy
cd ANTsPy
python3 setup.py install
This CPU version runs on Windows, Mac and Linux, but it takes substantially more time to compute than the GPU version (see below).
Installation - Option 2: GPU version (recommended)
Install DeepMReye with a GPU version of TensorFlow using following command. This version is substantially faster than the CPU version, but it requires CUDA and a NVIDIA GPU (not supported by Mac). The GPU version runs on Windows and Linux.
conda install tensorflow-gpu
Note that you might need to install cudnn first (conda install -c conda-forge cudnn). After installing the GPU version of tensorflow in the conda environment install DeepMReye via pip:
pip install git+https://github.com/DeepMReye/DeepMReye.git
Installation - Option 3: Colab
We provide a Colab Notebook showcasing model training and evaluation on a GPU provided by Google Colab. To use your own data, preprocess your data locally and upload only the extracted eyeball voxels. This saves space and avoids data privacy issues. See the Jupyter Notebook for the preprocessing and eyeball-extraction code.
Data formats
The fMRI data should be organized in 4D NIFTI files (.nii), containing the realigned 3D images acquired over time. The pipeline then extracts the eyeball voxels automatically and saves them as Python Pickle files, which serve as model input. For model training, you additionally need training labels, a numpy array containing 10 gaze coordinates per functional volume. These gaze coordinates can either be camera-based eye-tracking labels or the coordinates of a fixation target, and many file formats can be easily read (e.g. .npy, .npz, .mat, .csv etc.).
Please see our FAQ page for more details on data formats and preprocessing.
Hardware requirements
The GPU version of DeepMReye requires a NVIDIA GPU.
Software requirements
The following python dependencies are being automatically installed when installing DeepMReye (specified in requirements.txt):
tensorflow-gpu (2.2.0)
numpy (1.19.1)
pandas (1.0.5)
matplotlib (3.2.2)
scipy (1.5.0)
ipython (7.13.0)
plotly (4.14.3)
Version in parentheses indicate the ones used for testing the framework. Its extensively tested on Linux 16.04 but should run on all OS (Windows, Mac, Linux) supporting a Python version >3.6 and pip. It is recommended to install the framework and dependencies in a virtual environment (e.g. conda).
Correspondence
If you have questions, comments or inquiries, please check out the online User documention and reach out to us: markus.frey[at]ntnu.no and matthias.nau[at]ntnu.no