.. _sample05:

Sample 05: Custmizing calibration target motion
=======================================================================

What does this sample do?
--------------------------

By default, calibration target moves over 1.0 second and stays for 1.0 second at each target position during calibration/validation process.
In version 0.6.0, this behavior can be customized by following new paramters in the TrackingTools configuration file.

* CALTARGET_DURATION_PER_POS (default value = 2.0)
* CALTARGET_MOTION_DURATION (default value = 1.0)

Let 't' stand for time from the calibration target starts moving to the current calibration position.
The range of t is 0<t<CALTARGET_DURATION_PER_POS. When 0 <= t < CALTARGET_MOTION_DURATION, the calibration target is moving to the current calibration position.
When CALTARGET_MOTION_DURATION <= t < CALTARGET_DURATION_PER_POS, the calibration target stays on the current calibration position.
If CALTARGET_MOTION_DURATION = 0, the calibration target jumps to the current calibration position.

.. figure:: sample05_001.png
    
    Figure 1

By default, 10 calibration samples are acquired 0.4 seconds after the calibration target has arrived at the current calibration position.
These values may need to be changed when CALTARGET_DURATION_PER_POS and CALTARGET_MOTION_DURATION are changed.
For example, if CALTARGET_DURATION_PER_POS=1.0, CALTARGET_MOTION_DURATION=0.5 and camera is 60fps, the calibration target starts moving before sample acquisition has been completed.
In such a case, sample acquisition behavior should be customized by following new paramters in the TrackingTools configuration file.

* NUM_SAMPLES_PER_TRGPOS (default value = 10)
* CAL_GETSAMPLE_DEALAY (default value = 0.4)

If these parameters need to be changed temporarily, :func:`~GazeParser.TrackingTools.BaseController.setCalTargetMotionParams` and :func:`~GazeParser.TrackingTools.BaseController.setCalSampleAcquisitionParams` are useful.
This example demonstrates how calibration target motion changes when these parameters are changed.


Codes (PsychoPy)
------------------

- :download:`Download source code (sample05_caltargetjump_PsychoPy.py)<sample05_caltargetjump_PsychoPy.py>`
- :download:`Download source code (sample05_caltargetslow_PsychoPy.py)<sample05_caltargetslow_PsychoPy.py>`

Similar to Sample04, these sample performs only calibration.
:func:`~GazeParser.TrackingTools.BaseController.setCalTargetMotionParams` and :func:`~GazeParser.TrackingTools.BaseController.setCalSampleAcquisitionParams` are called before starting calibration loop.

.. code-block:: python
    :emphasize-lines: 3,4
    
    #Jumping + getting samples immediately after jumping
    #Note: this setting is for demonstration. It is not recommended for actual use.
    tracker.setCalTargetMotionParams(durationPerPos=1.0, motionDuration=0.0)
    tracker.setCalSampleAcquisitionParams(numSamplesPerPos=30, getSampleDelay=0.0)
    msg.setText('durationPerPos=1.0, motionDuration=0.0\nnumSamplesPerPos=30, getSampleDelay=0.0\n\n(for demonstration only)')
    msg.draw()
    win.flip()
    psychopy.event.waitKeys()
    
    tracker.calibrationLoop()

Probably, quite poor calibration results will be obtained when running sample05_caltargetjump_PsychoPy.py.
Figure 2 shows a typical result obtained by sample05_caltargetjump_PsychoPy.py.

.. figure:: sample05_002.png
    
    Figure 2

The origin of such a poor result is extremely short (0.0 second!) getSampleDelay.
In Figure 2, sample acquisition started during saccadic eye movement toward the calibration target (Figure 3).
It would be safe to set 0.2-0.4 seconds as getSampleDelay especially when target motion is very quick.

.. figure:: sample05_003.png
    
    Figure 3


Codes (VisionEgg)
------------------

.. note::
     * VisionEgg backend is no longer supported by 0.11.0 or later.

- :download:`Download source code (sample05_caltargetjump_VisionEgg.py)<sample05_caltargetjump_VisionEgg.py>`
- :download:`Download source code (sample05_caltargetslow_VisionEgg.py)<sample05_caltargetslow_VisionEgg.py>`

Please read comments on the codes for PsychoPy.