Pupil Helper

Michael Krause

Source code is available in our GitHub repository: https://github.com/InstituteOfErgonomics/pupille

No installation needed just download/copy all dll/exe files from folder ‘Release’. GitHub also provides a complete zip archive.

The open source tool provided here could help in some situations when working with the older Dikablis/D-Lab 2 versions. The official tool chain has a program (Analysis) that can be used to improve the pupil detection. If you look at the (many) parameters of the original software you see a threshold and a min/max radius. These are indications how the software probably works: Threshold the eye video to black/white and make a Hough transformation to find circles.

This approach is very fast but sometimes runs into problems.The tool has additionally a manual option where the user selects the center of the pupil for every ambiguous frame. This was done in the past by student assistants in hundreds of hours.

The tool presented here use another approach: Correlation template matching with an artificial pupil scaled to different sizes. Due to the unoptimized muti-scale (brute force) solution it is slow, but comparable to manual work (if you start parallel processes on a multi core, definitely faster than manual). Additionally, the eyelashes are a bit dilated and reflections are reduced by erosion. Please notice, that Dikablis is one of the eye trackers that search for the black pupil.

The here presented tool opens a so called Dikablis ‘journal’ file; then loads the related eye video. The original pupil detection is visualized with a green dot. If a template matching was carried out the new pupil detection is marked with a yellow dot. The template matching always chooses the location with the best fit (highest value); even if the pupil is not present (blink). Therefore, you have to adjust the threshold appropriately (the value is normalized 0–1000 a higher value is a better fit).

When you are pleased with the new detection (green rows) you can apply the changes and save the file. When saving the tool use the original name and append the current date and time. Before using this new journal file you have to manually backup the old one and rename the new. (Note! The journal columns pupil width, pupil height and pupil area values are not filled with new values. In case some of your scripts rely on these values)

Use at your own risk. Make backups of your experimental data before.

Dikablis and D-Lab are trademarks/products (eye tracking) of Ergoneers GmbH http://www.ergoneers.com They are used in the documents for description (nominative use). This is NOT an official Ergoneers tool!

This documentation is not in the public domain, but the following is valid for it:

THE DOCUMENTATION IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE DOCUMENTATION OR THE USE OR OTHER DEALINGS IN THE DOCUMENTATION.