A deep-learning-based web tool for translational and real-time pupillometry
⭐ MEYE is available on MATLAB! Check it out here
Check out pupillometry.it for a ready-to-use web-based mEye pupillometry tool!
This branch provides the Python code to make predictions and train/finetune models.
If you are interested in the code of the pupillometry web app, check out the gh-pages
branch.
You need a Python 3 environment with the following packages installed:
If you want to train models, you also need
We provide a Dockerfile for building an image with docker.
You can make predictions with pretrained models on pre-recorded videos or webcam streams.
Download the pretrained model. If you want to use the old model, check out version v0.1
of this branch. See available models in Releases.
Check out the pupillometry-offline-videos.ipynb
notebook for a complete example of pupillometry data analysis.
In alternative, we provide also the predict.py
script that implements the basic loop to make predictions on video streams. E.g.:
# input: webcam (default)
# prediction roi: biggest central square crop (default)
# outputs: predictions.mp4, predictions.csv (default)
predict.py path/to/model
# input: video file
# prediction roi: left=80, top=80, right=208, bottom=208
# outputs: video_with_predictions.mp4, pupil_metrics.csv
predict.py path/to/model path/to/video.mp4 -rl 80 -rt 80 -rr 208 -rb 208 -ov video_with_predictions.mp4 -oc pupil_metrics.csv
# check all parameters with
predict.py -h
Download our dataset (NN_human_mouse_eyes.zip, 246.4 MB) or prepare your dataset following our dataset's structure.
If you need to annotate your dataset, check out pLabeler, a MATLAB software for labeling pupil images.
The dataset should be placed in data/<dataset_name>
.
If you are using a custom dataset, edit train.py
to perform the train/validation/test split of your data.
Train with default parameters:
python train.py -d data/<dataset_name>
python train.py -h
Starting from MATLAB version 2021b, MEYE is also available for use on MATLAB!
A fully functional class and a tutorial for its use is available here!
If you use our dataset, please cite:
@dataset{raffaele_mazziotti_2021_4488164,
author = {Raffaele Mazziotti and Fabio Carrara and Aurelia Viglione and Lupori Leonardo and Lo Verde Luca and Benedetto Alessandro and Ricci Giulia and Sagona Giulia and Amato Giuseppe and Pizzorusso Tommaso},
title = {{Human and Mouse Eyes for Pupil Semantic Segmentation}},
month = feb,
year = 2021,
publisher = {Zenodo},
version = {1.0},
doi = {10.5281/zenodo.4488164},
url = {https://doi.org/10.5281/zenodo.4488164}
}