Occurity is a fully-featured patient visual acuity test software designed for use on the RaspBerry Pi hardware platform. It enables you to built an affordable visual acuity test system using a few pieces of hardware and basically any remote control. If you do not have the option to buy the infrared receiver, it can also be used with a keyboard.
- ETDRS, HOTV, numbers, Landolt C and Tumbling E charts
- Astigmatism dots and astigmatism rays charts
- Coincidence, Worth 4 dots and mirrored RED / GREEN charts
Occurity is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
In order to install a system running Occurity you need the following hardware:
Required
- A Raspberry Pi (3 or 4)
- At least a 2 GB SD flash card
- A monitor with at least 300 cd/m² brightness (preferably 350 cd/m²)
Optional
- A Flirc infrared reciever
- A remote control that works with flirc. Most do.
Occurity displays correctly on any monitor using any resolution provided the following two requirements are met:
- The physical length of the ruler must be set correctly in the Occurity Preferences dialog.
- The physical distance from the patients eyes to the monitor must be set correctly in the Occurity Preferences dialog.
To test if the monitor you are using reports its resolution correctly to the Occurity software, please set the width of the ruler in the Preferences dialog, temporarily set the patient distance to 600 cm and measure the width of any of the Sloan optotype symbols on the screen at chart size 0.1 and 0.25. At 0.1 the width must be 87 mm and at 0.25 the width must be 35 mm. If this is correct your monitor will work with Occurity.
To test if your monitor scales the distance correctly, you should also check the sizes at 400 cm patient distance. Here the width of a Sloan optotype symbol must be 58 mm at 0.1 and 23 mm at 0.25.
DISCLAIMER!!! This is only a guideline: Using a lux meter pushed up against the monitor surface, you should have a readout of about 277 lux. Hence the need for a monitor that is capable of a high brightness level.
- Asus VG248QE
- LG AKB75095344
- Samsung AA59-00818A
In theory most remote controls you might have lying around should work with the disclaimer that there are some remotes that use dual-output signals which makes them hard to use with the flirc interface. Only way to know is to just try.
Note! The Flirc infrared reciever emulates a keyboard. For the remote to work, you need to install the Flirc software on a supported OS and configure the buttons on your remote to correspond with these keyboard keys.
You have two options for installing and running Occurity. Either use the pre-built SDCard images or built one yourself from scratch.
If you require no customization of the image this is the easiest way to get up and running. Simply download the SDCard image corresponding to your Raspberry Pi from the latest release files. Decompress the image and flash it to an SDCard. Insert the SDCard in your Raspberry Pi and you are done! Be sure to check the rest of the documentation on how to use Occurity.
The step-by-step procedure for building an Occurity image that can be flashed to an SDCard for the Raspberry Pi hardware platform is described in detail below. The build is currently based on the scarthgap release of the very popular Yocto embedded platform.
The only pre-requisite is a working Ubuntu 22.04 installation with at least 150 GB available harddrive space. The final SDCard image will be about 1 GB. You might also be able to make this work on any previous or later Ubuntu LTS release. The main difference will probably be the package pre-requisites. Refer to the official Yocto documentation for further information.
Install the required packages by running the following two commands:
$ sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 python3-subunit zstd liblz4-tool file locales libacl1
$ sudo locale-gen en_US.UTF-8
Run the following commands to clone Yocto and the required layers. The source command sets up the environment required for building the image. If you wish to rebuilt the image later you need to re-run this source command in order for the bitbake related tools to be available and configured:
$ cd
$ git clone https://git.yoctoproject.org/poky
$ cd poky/
$ git checkout -t origin/scarthgap -b occurity
$ git clone -b scarthgap https://git.yoctoproject.org/meta-raspberrypi
$ git clone -b scarthgap https://github.com/openembedded/meta-openembedded
$ git clone -b scarthgap https://github.com/meta-qt5/meta-qt5
$ git clone https://github.com/muldjord/meta-occurity
$ source oe-init-build-env
$ bitbake-layers add-layer ../meta-raspberrypi
$ bitbake-layers add-layer ../meta-openembedded/meta-oe
$ bitbake-layers add-layer ../meta-qt5
$ bitbake-layers add-layer ../meta-occurity
You should now be at the poky/build directory. Edit conf/local.conf and add the following lines to the very top of the file:
LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch commercial"
WKS_FILE = "sdimage-raspberrypi.wks"
IMAGE_FSTYPES += "wic.gz wic.bmap"
DISABLE_OVERSCAN = "1"
MACHINE ?= "raspberrypi4-64"
NOTE!!! If you are building for a Raspberry Pi 3 change the MACHINE to raspberrypi3-64.
You are now ready to build the image. Depending on your host machine this can take a long time (several hours). Run the following commands to start the build. You should run this command from the poky/build directory:
$ bitbake core-image-sato
Bitbake is Yocto's build system. It pulls in all required source code and compiles and configures everything needed for an embedded Linux system running Occurity on a Raspberry Pi.
NOTE!!! During the bitbake procedure you might get warnings about TMPDIR references. These can be ignored.
If everything went well you will now have a working Occurity image that can be flashed onto an SDCard. Start by decompressing the image. You should run this command from the poky/build directory:
$ qzip -d --force tmp/deploy/images/raspberrypi4-64/core-image-sato-raspberrypi4-64.rootfs.wic.gz
Now insert your SDCard and flash it with the decompressed image using your favorite SDCard flashing tool (dd or similar). Insert the card into your Raspberry Pi and boot it up. After a little while Occurity will be automatically launched. Be sure to check the rest of the documentation on how to use Occurity.
NOTE!!! If you've already built the Raspberry Pi image as documented above you do not need to continue with these instructions. The following describes how to compile and run Occurity on Ubuntu for anyone who wishes to do so.
Run the following commands in a terminal on Ubuntu to install the prerequisites needed for Occurity to function correctly.
$ sudo apt update
$ sudo apt install qtbase5-dev libqt5svg5-dev qtmultimedia5-dev libqt5multimedia5-plugins
$ sudo apt remove gstreamer1.0-plugins-bad
The gstreamer1.0-plugins-bad package might not be installed already. But try removing it to be sure. Having it installed is known to break h.264 video playback needed by the Occurity attention video player.
Open a terminal on Ubuntu and run the following commands. Be sure to substitute LATEST with the version number of the latest Occurity release (eg. 1.2.0). Check here for the latest version.
$ cd
$ mkdir occurity
$ cd occurity
$ wget -N https://github.com/muldjord/occurity/archive/LATEST.tar.gz
$ tar xvzf LATEST.tar.gz --strip-components 1 --overwrite
$ qmake
$ make
You should now have a /home/USER/occurity/Occurity executable ready to run. Note that the first time Occurity runs it has no config.ini. It will therefore try to open up the Preferences dialog. The default pin-code is 4242.
Occurity comes with an optotype that was created from the ground up to adhere to the design characteristics of the original Sloan optotype created by Louise Sloan in 1959. Landolt C and tumbling E optotypes are also available. Licenses are designated in the optotypes subdirectories.
The following keyboard keys are in use when running Occurity.
q: Enable / disable standbyj: Open Job Runner dialog (requires pin-code, documented here)p: Open Preferences dialog (requires pin-code, documented here)s: Restart current attention videod: Play / pause current attention videof: Stop attention videog: Play next attention video
up: Change to next row with bigger sizedown: Change to next row with smaller sizeleft: Move entire row to the leftright: Move entire row to the rightPgUp: Skip n number of rows bigger (configure n in preferences)PgDn: Skip n number of rows smaller (configure n in preferences)c: Enable / disable crowdingm: Switch between single and multisymbol from the selected row. Use left / right to move between themr: Randomize symbols from selected rowa: Enable / disable attention animation (if one is defined for the chart in charts.xml)
left / right: Switch between SVG layers defined in charts.xml
The most important Occurity settings can be configured through the Preferences dialog. The dialog is opened by pressing p on a connected keyboard. Note that a pin-code must be entered to open Preferences. This is to avoid users inadvertently changing settings that could compromise the quality of the visual acuity results (default is 4242).
Options that aren't available in the Preferences dialog can be changed by opening the config.ini file in a text editor. For a complete description of all available options go here.
Occurity comes with a number of default charts. All charts can easily be customized through the charts.xml file. Go here for a complete description of the format.
- Now sets default size reset to 5 minutes instead of 240
- Added delay to sleep activated by
qkey press to avoid monitor instantly turning back on due to remote control double-presses.
- Improved the sleep key 'q' functionality to now work both for putting the monitor to sleep and making it wake up again. Any other key will also wake it up.
- Renamed all instances of hibernate to sleep as 'hibernate' is misleading. It only puts the monitor to sleep not the entire system.
- Added 'minutesBeforeSleep' to Preferences dialog.
- Size reset is now in minutes instead of seconds.
- Renamed 'General' config.ini section to 'main'
- Renamed 'sizeResetTime' config variable to 'minutesBeforeSizeReset' for better clarity.
- Removed obsolete 'aptinstall' and 'aptremove' jobrunner commands and all related functions and configs.
- Fixed bug in Slider where value would only be set in Preferences if config variable was in 'General' section.
- Added 'quit' command and 'Quit Occurity' job to jobrunner to allow admin to quit Occurity
- Added row caption support. This allows users to set a caption for each row of the optotype charts.
- Changed sleep scripts to use
xsetinstead ofxrandrfor (hopefully) better support for more monitors.
- Updated documentation
- Updated update job
- Added 'sync:' command to jobrunner which syncs the filesystem. This command is also auto-added at the end of all jobs
- Added '%ARCH%' hardcoded variable to jobrunner variables (becomes
aarch64when using Yocto on a Raspberry Pi 4) - Added '%HOSTNAME%' hardcoded variable to jobrunner variables (becomes
raspberrypi4-64when using Yocto on a Raspberry Pi 4) - Splash screen is now closed before preferences instantiation in cases where no 'config.ini' is found when Occurity is started
- Removed 'secret' functionality as it was no longer in use
- Updated JOBS to include note about USBPEN functionality
- Added on-screen touch controls
- Added astigmastism rays chart
- Fixed occasional ghosting when changing between optotype sizes on a chart
- Added
startingChartconfig variable to allow setting initially displayed chart - Added all charts to combo in preferences to allow setting
startingChartconfig variable - Added
fadetimingsandfadelevelsattributes to<chart>xml node - Splash screen now fades in
- Optotype symbols can now be optionally configured to fade in and out
- Rename VisuTest to Occurity
- Added category to jobs
- Changed
updatetojobeverywhere - Added custom MessageBox that works well with the remote control and keyboard controls
- Preferences dialog can now be closed with
p - Updater dialog can now be closed with
j - Fixed bug where
updateSrcPathandupdateDstPathweren't cleared when running two updates one after the other - Fixed bug where an excluded path copy would result in all subsequent paths not being investigated
- Added attention gif animation option to
optotypechart. Show / hide witha. Set withanimation="file.gif" - Added fullscreen attention video. Controls: Previous video
s, Play / Paused, Stopf, Next videog. Loads all .mp4 videos from the definedvideosFolder. Default is./videos. Be aware that the Raspberry Pi might struggle with Full-HD videos, so lower resolutions are recommended - Added option to skip multiple lines on
optotypecharts usingwands. Configure number of lines in Preferences - Added pincode dialog to preferences. Pincode can be set in config.ini with
pinCode=0000 - Changed mainSettings to reference instead of pointer
- Added scriptable updater allowing more update types than one
- Now shows job file contents in the output view
- Added a plehtora of commands that can be used in job files. All documents in
jobs/README.md
- Implemented randomize row with
rkey
- Moved reset timer to mainwindow instead of each chart
- MAJOR: Added
optotypechart type. This chart type obsoletes the oldfontchart and uses SVG's directly instead of requiring a ttf font. All SVG's should be calibrated as 100 pixels = 1 arc minute at a 6 meter patient distance. - Added crowding rectangle for all optotype charts using
ckey. - Now uses a 500 pixel width ruler in preferences to determine pixel to mm ratio.
- Now sizelocks between all charts instead of just in the same group.
- Crowding and single mode now follows chart changes.
- Added
Tto Sloan font - Added
HOTVcharts to charts.xml on numkey 7 - Updated deprecated Qt5 functions
- Now remembers size for all charts on same button even when switching between back and forth between charts on different buttons
- Fixed bug where chart resize would use letterrow from old size instead of switching to letters from size inherited from other chart on same button
- Added auto-hibernation after x minutes of inactivity
- Improved hibernation handling overall
- Now supports size locking between charts on same number key
- Added splash screen
- Updated icons
- Added chart size reset timer
- Added automated release and update scripts
- Initial release
- Added SVG chart type support
- Implemented red/green color customization
