refactoring and update

.doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Opticka"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER = 2.05
+PROJECT_NUMBER = 2.06
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -821,11 +821,13 @@ EXCLUDE_SYMLINKS       = YES
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */+uix/* \
+EXCLUDE_PATTERNS       = */ui/* \
+                         */+uix/* \
                          */+uiextras/* \
                          */tools/* \
                          */ReadPLX/* \
-                         */nex/*
+                         */nex/* \
+                         */arduino/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -910,7 +912,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = readme.md
+USE_MDFILE_AS_MAINPAGE = README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

DoxygenLayout.xml

@@ -2,9 +2,10 @@
   <!-- Generated by doxygen 1.9.2 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
-    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="mainpage" visible="yes" title="Opticka Experiment Manager"/>
     <tab type="pages" visible="yes" title="" intro="">
-      <tab type="user" url="optickatest.html" title="Opticka Method of Constants Test Output"/>
+      <tab type="user" url="optickaBehaviourTest.html" title="Opticka State Machine Test Output"/>
+      <tab type="user" url="optickaTest.html" title="Opticka MOC Test Output"/>
       <tab type="user" url="https://github.com/iandol/opticka" title="Github Source Repo"/>
       <tab type="user" url="https://psychtoolbox.discourse.group/" title="PTB User Forum"/>
       <tab type="user" url="http://psychtoolbox.org" title="PTB Home Page"/>

INSTALL.md

@@ -0,0 +1,36 @@
+# Detailed Install Instructions {#install}
+
+## Requirements:
+
+* Latest Psychophysics Toolbox (V3.0.18+) — please ensure it is kept up-to-date. Also consider donating to PTB to ensure its future development: <https://www.psychtoolbox.net/#future>
+* MATLAB 2017a+ (Opticka utilises object-oriented property validation first introduced in that version). While I would like to support Octave, its `classdef` support is currently incomplete...
+* Ubuntu V20.04+ strongly recommended, but also runs under macOS and Windows 10+
+* [Eyelink developer kit](https://www.sr-support.com) for Eyelink eyetrackers.
+* [Titta Toolbox](https://github.com/dcnieho/Titta) for Tobii Pro eyetrackers.
+* [LJM](https://labjack.com/support/software/installers/ljm) for LabJack T4 / T7 digital I/O devices.
+* [Exodriver](https://labjack.com/support/software/installers/exodriver) for LabJack U3/6 devices.
+
+Opticka is tested and mostly used on 64bit Ubuntu 20.04 (in the lab) & macOS 12.x (only development) under MATLAB 2021b. The older LabJack U3/U6 interface ([`labJack.m`](https://github.com/iandol/opticka/blob/master/communication/labJack.m)) currently only works under Linux and macOS (Labjack uses a different interface on Linux/macOS vs. Windows). The newer LabJack T4/T7 interface ([`labJackT.m`](https://github.com/iandol/opticka/blob/master/communication/labJackT.m)) does work cross-platform. Linux is the best OS according the PTB developer Mario Kleiner, and receives the majority of development work from him. It is **_strongly advised_** to use it for all real data collection. My experience is that Linux is *much more* robust and performs better than both macOS or Windows, and it is well worth the effort to use Linux for all PTB experimental computers.
+
+## Using the Git repository
+
+Using `git` to install is the recommended route; it makes it easy to update:
+
+* Create a parent folder to hold the code, I use `~/Code/` on Ubuntu and macOS and `C:/Code/` on windows.
+* `cd` to that parent folder in the terminal and run 
+```shell
+git clone https://github.com/iandol/opticka.git
+```
+* `cd` to the new `~/Code/opticka` folder in MATLAB and run `addOptickaToPath.m`
+
+To keep opticka up-to-date in the terminal: `git pull` — if you want to make local changes, then please create a new local branch to keep the main branch clean so you can pull without issue. If you do have issues pulling you can either (1) reset the repo losing any local changes: `git fetch -v; git reset --hard origin/master; git clean -f -d; git pull` — (2) stash your changes: `git fetch -v; git stash push; git pull`
+
+## Using the ZIP file
+
+I recommend using `git` as you can keep the code up-to-date by pulling from Github, but a ZIP install is easier:
+
+* Download the latest ZIP file: [GitHub ZIP File](https://github.com/iandol/opticka/archive/refs/heads/master.zip)
+* Unzip the **contents** of the `opticka-master` folder in the zip to a new folder (I use `~/Code/opticka`). You should end up with something like `~/Code/opticka/opticka.m` as a path.
+* In MATLAB, `cd` to that folder and run `addOptickaToPath.m`.
+
+To keep up-to-date you should manually keep downloading and unzipping the newest versions...

readme.md → README.md

@@ -1,8 +1,8 @@
-# Opticka: Behavioural Experiment Manager
+# Opticka: Behavioural Experiment Manager {#mainpage}
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.592253.svg)](https://doi.org/10.5281/zenodo.592253)  —  [![Open in Visual Studio Code](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/iandol/opticka)
 
-Opticka is an object oriented framework with optional GUI for the [Psychophysics toolbox (PTB)](http://psychtoolbox.org/), allowing full experimental presentation of complex visual or other stimuli. It is designed to work on Linux, macOS or Windows and interfaces via strobed words and ethernet for recording neurophysiological and behavioural data. Full behavioural control is available by use of a [Finite State-Machine](http://iandol.github.io/OptickaDocs/classstate_machine.html#details) controller, in addition to simple method of constants (MOC) experiments. Opticka uses the TCP interface to both Eyelink & Tobii Pro eyetrackers affording better control, reliability and data recording over using analog voltages alone (and doesn't require any DAQ cards for eye data). The various base classes can be used **_without_** the need to run the GUI (see [`optickatest.m`](http://iandol.github.io/OptickaDocs/optickatest.html) for an example), and plug-n-play stimuli provide a unified interface (`setup`, `animate`, `draw`, `update`, `reset`) to integrate into other PTB routines. The object methods take care of all the background geometry and normalisation, meaning stimuli are much easier to use than “raw” PTB commands alone. Analysis routines are also present for taking e.g. Plexon files (`.PL2` or `.PLX`), Eyelink files (`.EDF`), and behavioural responses and parsing them into a consistent structure, interfacing directly with [Fieldtrip](http://fieldtrip.fcdonders.nl/start) for further spike, LFP, and spike-LFP analysis. Opticka is more modular and affords much better graphics control (most stimuli are optimised OpenGL with advanced control via PTB) than [MonkeyLogic](http://www.brown.edu/Research/monkeylogic/). 
+Opticka is an object oriented framework with optional GUI for the [Psychophysics toolbox (PTB)](http://psychtoolbox.org/), allowing full experimental presentation of complex visual or other stimuli. It is designed to work on Linux, macOS or Windows and interfaces via strobed words and ethernet for recording neurophysiological and behavioural data. Full behavioural control is available by use of a [Finite State-Machine](http://iandol.github.io/OptickaDocs/classstate_machine.html#details) controller, in addition to simple method of constants (MOC) experiments. Opticka uses the TCP interface to both Eyelink & Tobii Pro eyetrackers affording better control, reliability and data recording over using analog voltages alone (and doesn't require any DAQ cards for eye data). The various base classes can be used _without_ the need to run the GUI (see [`optickatest.m`](http://iandol.github.io/OptickaDocs/optickatest.html) for an example), and plug-n-play stimuli provide a unified interface (`setup`, `animate`, `draw`, `update`, `reset`) to integrate into other PTB routines. The object methods take care of all the background geometry and normalisation, meaning stimuli are much easier to use than “raw” PTB commands alone. Analysis routines are also present for taking e.g. Plexon files (`.PL2` or `.PLX`), Eyelink files (`.EDF`), and behavioural responses and parsing them into a consistent structure, interfacing directly with [Fieldtrip](http://fieldtrip.fcdonders.nl/start) for further spike, LFP, and spike-LFP analysis. Opticka is more modular and affords much better graphics control (most stimuli are optimised OpenGL with advanced control via PTB) than [MonkeyLogic](http://www.brown.edu/Research/monkeylogic/). 
 
 ## Example hardware setup
 
@@ -12,7 +12,7 @@ The diagram below shows an example Opticka configuration setup,;note that the ey
 
 ## GUI
 
-The GUI can control the hardware, stimuli and variables needed for method of constant (MOC) and more complex behavioural tasks that use the state machine. The GUI is **_not required_** to use the underlying classes ([see example here](http://iandol.github.io/OptickaDocs/optickatest.html)).
+The GUI can control the hardware, stimuli and variables needed for method of constant (MOC) and more complex behavioural tasks that use the state machine. The GUI is **not required** to use the underlying classes ([see example here](http://iandol.github.io/OptickaDocs/optickatest.html)).
 
 ![Opticka Screenshot](https://github.com/iandol/opticka/raw/gh-pages/images/opticka.png)
 
@@ -33,14 +33,16 @@ For more complex behavioural tasks, a state machine is used. You can still load
 * **Photodiode boxes**: we prefer TSL251R light-to-voltage photodiodes, which can be recorded directy into your electrophysiology system or can generate digital triggers via an [Arduino interface](https://github.com/iandol/opticka/tree/master/tools/photodiode).
 
 ## Quick Documentation
-`optickatest.m` is a minimal example showing a simple method of constants (MOC) experiment with 11 different animated stimuli varying across angle, contrast and orientation. Read the Matlab-generated documentation here: [`optickatest.m` Report](http://iandol.github.io/OptickaDocs/optickatest.html). More complex behavioural control (gaze-contingent experiments with variable logic per trial) utilises a state machine. You can see examples in the [CoreProtocols]() folder, these are loaded into the GUI but the state machine `.m` files show you the logic.  
+`optickatest.m` is a minimal example showing a simple method of constants (MOC) experiment with 11 different animated stimuli varying across angle, contrast and orientation. Read the Matlab-generated documentation here: [`optickatest.m` Report](http://iandol.github.io/OptickaDocs/optickaTest.html). More complex behavioural control (gaze-contingent experiments with variable logic per trial) utilises a state machine, see [`optickaBehaviourTest.m` Report](http://iandol.github.io/OptickaDocs/optickaBehaviourTest.html) for a simple manual example. You can see further examples in the [CoreProtocols]() folder, these are loaded into the GUI by the state machine StateInfo `.m` files.  
 
 There is also auto-generated class documentation here: [Opticka Class Docs](http://iandol.github.io/OptickaDocs/inherits.html), that details the major classes and their methods and properties. This is generated from the comments in the code, which as always could be improved...  
 
 ## Basic Install Instructions
-Opticka prefers the latest Psychophysics Toolbox (V3.0.17+) and at least Matlab 2017a (it uses object-oriented property validation introduced in that version). It has been tested and is mostly used on 64bit Ubuntu 20.04 & macOS 10.15.x with Matlab 2021a. You can simply download the ZIP from Github, and add the contents/subdirectories to Matlab path (or run `addOptickaToPath.m` to do it for you). Or to keep easily up-to-date if you have git installed, clone this Github repo, CD to the folder then run run `addOptickaToPath.m`.
+See [**Detailed instructions**](INSTALL.md) for more details…
 
-Opticka currently works on Linux, macOS and Windows, though the older LabJack U3/U6 interface currently only works under Linux and macOS (Labjack uses a different interface on Windows and Linux/macOS; the LabJack T4/T7 does work cross-platform however). Linux is **by far** the best OS according the PTB developer Mario Kleiner, and receives the majority of development work from him, therefore it is *strongly advised* to use it for experiments. My experience is that Linux is much more robust and performant than macOS or Windows, and it is well worth the effort to use Linux for PTB experimental computers.
+Opticka prefers the latest Psychophysics Toolbox (V3.0.17+) and at least Matlab 2017a (it uses object-oriented property validation introduced in that version). It has been tested and is mostly used on 64bit Ubuntu 20.04 & macOS 12.x with **MATLAB 2021b** (newer versions are faster). You can simply download the [GitHub ZIP File](https://github.com/iandol/opticka/archive/refs/heads/master.zip), and add the contents of the `opticka-master` folder to the Matlab path (cd to the install folder and run `addOptickaToPath.m` to do it for you). Or to keep easily up-to-date if you have git installed, clone this Github repo, CD to the folder then run `addOptickaToPath.m`.
+
+Opticka currently works on Linux, macOS and Windows. The older LabJack U3/U6 interface currently only works under Linux and macOS; the LabJack T4/T7 does work cross-platform however. Linux is **by far** the best OS according the PTB developer Mario Kleiner, and receives the majority of development work from him, therefore it is *strongly advised* to use it for experiments. My experience is that Linux is much more robust and performant than macOS or Windows, and it is well worth the effort to use Linux for PTB experimental computers.
 
 ## Features
 * Values are always given in eye-relevant co-ordinates (degrees etc.) that are internally calculated based on screen geometry/distance

analysis/analysisCore.m

@@ -3,7 +3,7 @@
 %> analysisCore is itself derived from optickaCore. Provides a set of shared methods
 %> and some core properties and stats GUI for various analysis classes.
 %>
-%> Copyright ©2014-2021 Ian Max Andolina — released: LGPL3, see LICENCE.md
+%> Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md
 % ========================================================================
 classdef analysisCore < optickaCore
 

analysis/eyelinkAnalysis.m

@@ -5,7 +5,7 @@
 %> can also manually find microsaccades, and perform ROI/TOI filtering on the eye
 %> movements.
 %>
-%> Copyright ©2014-2021 Ian Max Andolina — released: LGPL3, see LICENCE.md
+%> Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md
 % ========================================================================
 classdef eyelinkAnalysis < analysisCore
 	% eyelinkAnalysis offers a set of methods to load, parse & plot raw EDF files.

analysis/tobiiAnalysis.m

@@ -5,7 +5,7 @@
 %> can also manually find microsaccades, and perform ROI/TOI filtering on the eye
 %> movements.
 %>
-%> Copyright ©2014-2021 Ian Max Andolina — released: LGPL3, see LICENCE.md
+%> Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md
 % ========================================================================
 classdef tobiiAnalysis < analysisCore
 	% eyelinkAnalysis offers a set of methods to load, parse & plot raw EDF files.

calibration/calibrateLuminance.m

@@ -24,7 +24,7 @@
 %> your programs. 
 %>
 %>
-%> Copyright ©2014-2021 Ian Max Andolina — released: LGPL3, see LICENCE.md
+%> Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md
 % ========================================================================
 classdef calibrateLuminance < handle
 

calibration/colourManager.m

@@ -1,7 +1,7 @@
 % ========================================================================
 %> @brief colourManager manages colours wrapping the CRS Color Toolbox
 %>
-%> Copyright ©2014-2021 Ian Max Andolina — released: LGPL3, see LICENCE.md
+%> Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md
 % ========================================================================
 classdef colourManager < optickaCore