ECTtracker - Settings and additional parameters
Advanced Settings Guide
- Localization file name
- Wlim 10..100% of frame and sample matching
- Frames per second 1..60
- Maximum target shift per 1 frame
- In case of target loss, count frames before searching
- Coefficient of previous target proximity influence (in percent)
- Video mirror flip
- Searching area alignment (C – center, F - actual)
- Structure file name
- Maximum amount of structure key points
- Structure key point width (pixel block, from 0 to 255)
- Structure key point height (pixel block, from 0 to 255)
- Intensity (weight) of each channel (9 numbers, from 0 to 9)
- Structure color in main window (in #FFFFFF format)
- Structure scale, when showing in color channel table
- Sample size – width (in pixels)
- Sample size – height (in pixels)
- Matrix of Samples size – width (amount of columns)
- Matrix of Samples size – height (amount of rows)
- Target size – width (in pixels)
- Target size – height (in pixels)
- Target position – left margin (in pixels)
- Target position – top margin (in pixels)
- Debug – structure visibility
- Debug – statistics visibility
- Debug – video output visibility
- Debug – height of panel with recognized samples
- Activate automatic recognition (1-enable, 0-disable)
- Time interval between writing operation status to file (in seconds)
- Brightness changing threshold during automatic calibration
- Full path to automatic calibration script
- Time Frame – amount of analyzed frames per one emulated action
- Full path to the current Matrix of samples
- Show About window
- Show settings window
- Show Matrix of Samples window
- Show stripes diagram
- Show structures diagram
- Show channels intensity diagram
- Show events log window
- Show structure editor window
- 100. Name of receiving software (to receive emulated keystrokes)
- 101. Method of sending data to the receiving software (S-sendmessage, P-postmessage)
- Key and action for positive shift on X-axis (+X)
- Key and action for positive shift on Y-axis (+Y)
- Key and action for negative shift on X-axis (-X)
- Key and action for negative shift on Y-axis (-Y)
- Key and action for negative shift on X-axis (-X)
- Key and action when sample is matching with row #0
- Key and action when sample is matching with row #1
- Key and action when sample is matching with row #2
- Key and action when sample is matching with row #3
- Key and action when sample is matching with row #4
All the adjustable parameters of ECTtracker are available through the settings window of the program. The user can open it by using the F3 hot key or Settings – Show Settings menu items.
All settings are grouped by categories:
- 1-9 – basic program settings. This group includes localization settings, the matching level between samples and the analyzed image, the frame per second rate of the captured video, the maximum image shift for 1 frame, time of recognition restoring after losing the matching, video mirror flipping, etc.
- 11-15 – recognition settings. This group includes: the recognition structure file name, the maximum amount of the recognition structure points, the width and the height of the area of each point, the color channels priority formula, the color of the structure in the main window of the program, as well as the scale in the SCO9 window.
- 20-27 – Matrix of Samples settings. The size of samples and the amount of samples in each row or column. This group also includes all target window settings that affect its size and position.
- 31-34 – debugging elements settings for the main window of ECTtracker. Visibility of the elements and the size of the area with information about recognized samples.
- 45-50 – settings for paths, time intervals and automatic start of the recognition process.
- 60-67 – visibility setting of the additional windows of the program.
- 100-115 – settings for keys and actions for the receiving software.
All the settings are grouped in several columns. From left to the right: a number, a parameter value and its short description.
Let's look closer at the settings of the program.
Localization and image analysis settings
1. Localization file name. The name of the file that contains the description of interface elements and program settings in a required language. In this field, the user has to specify the full path for the localization file and its name.
3. Wlim 10..100% of frame and sample matching. Wlim – is the limit of the matching degree of a sample and the analyzed image. The value of this parameter can stay in the range from 10 to 100. It's recommended to use values from 18 to 25 (depending on the lighting, mobility of the user, camera settings and other parameters). The default level of Wlim is 20. The higher the value selected by the user, the more accurate the matching level of the sample and the recognized image fragment under the structure will be. Wlim can be increased only in the case of proper lighting and high resolution of the camera. This value can also be increased in cases where the program finds several corresponding samples for one image. This situation can be easily seen on debugging lines, when two or more lines are simultaneously filled with the green color. Vice versa, when the level of recognition is low and there are no adequately corresponding samples, the user has to decrease the Wlim value. The proper value for this parameter has to be selected in such a way that only one green debugging line appears in the stripes diagram at any given time.
4. Frames per second 1..60. Speed of the video processing and capturing for tracking purposes. ECTtracker receives the image from a source located under the target window (it can be the ECTcamera application or any other software that captures video from any camera, media player, Skype or other source). A fragment of the image is shown in the main window of ECTtracker and compared with previously loaded or created samples using key points of the structure, followed by information updates in the main and debugging windows. Basing on the received information, ECTtracker determines key codes to be sent to receiving software. After finishing this stage, the program switches to the next image and this cycle is repeated. Despite the resource-intensive process, the program can handle up to several dozens of frames per second. The default value of this parameter is 20 frames per second. This parameter value can stay in the range from 1 to 60 frames per second. It's recommended to decrease this parameter below 6 frames per second for computers with low technical characteristics. It's worth noting that this parameter directly affects the speed of the video capturing process. E.g. if the video feed of the user has a rate of 20 frames per second, there's no need to set a higher value for this parameter. This will not increase the quality level, but will increase the overall load on the computer resources during work with ECTtracker.
5. Maximum target shift per 1 frame. The maximum shift of the user's eye for one frame. If the user has not totally lost mobility or the user is suffering from uncontrolled muscle activity (teak, tremor), it can result in an unstable image from the camera. Inclinations of the head and various movements can result in a change in the face position, thus the program needs to correct the location of the structure in such a way that it can follow the user's eyes. Thus, the central coordinates of corresponding samples will also change. The faster and more notable the movements of the user, the higher the shift value for 1 frame to be selected. To avoid loss of the target, it's recommended to increase the maximum shift value even for close-up shots. The value of this parameter has to be selected from the range of 0 to 100 pixels. The default value of the maximum shift is 3 pixels. This value can also be increased in cases when the program can't keep focus on the user's eye, as well as decreased for working on low-end computers. This software was initially created for totally paralyzed patients; that's why it's strictly recommended to minimize the amount of any possible movements in the analyzed area. In order to avoid head movements, the user can use a chair with a high backrest or an armchair with a headrest. This approach allows the user to obtain almost complete immobility during the operation of ECTtracker.
6. In case of target loss, count frames before searching. The idle time for the program when target is lost. In cases where the analyzed image does not correspond with any sample from the Matrix of Samples, ECTtracker has to skip a predefined amount of frames. After that, the program will move the search point to the center of the image (if parameter 9 has the C value) or to the place of the last successful matching (if parameter 9 has the F value). The structure is hidden during the idle time, allowing the user to see that the target is lost. The default value of this parameter is 20 and it's usually equal to the analyzed video frame rate. In other words, when ECTtracker loses focus, it will resume searching for corresponding samples in 1 second. The user can select any desired value in the range from 1 to 1000 frames.
7. Coefficient of previous target proximity influence (in percent). During the comparison of the current image and samples, the program may take the distance to matched samples into account and choose the closest of them. The value of this parameter can be selected from the range of 1 to 100, thus changing the coefficient of the previous target proximity from 1% to 100%. The default value is 0, i.e. ECTtracker selects corresponding samples irrespective of their position.
8. Video mirror flip. The value of this parameter can be equal to 1 or 0. When the 0 value is selected, the ECTtracker main window shows the video in the same way as in the application under the target window. When the value of this parameter is equal to 1, the video in ECTtracker window is flipped horizontally. The default value of this parameter is 0.
9. Searching area alignment (C – center, F - actual). Alignment of the search area to the center or according to the last successful coordinates. When the C value is selected and the sample is lost, ECTtracker starts searching from the center of the analyzed image. This mode implies total immobility of the patient (in case of paralysis, as well as in case of any uncontrolled head movements with return to its original position). When a sample goes out of the tracking area, ECTtracker returns the searching area to the center of the image. This feature allows the user to avoid such situations when software switches to another similar object or searches an object in the area of loss, while it's already in the center of the image. When the F value is selected for parameter 9, software is searching the sample in the area of its loss and not getting back to the center of the image. This mode was invented to use the head (or any other marker) as the mouse cursor. In such cases the user has to select a bigger tracking area and create samples for an eye or a marker. After doing so, the user is able to control the cursor with their head movements. Parameters 51-54 are responsible for this mode. In cases where a sample goes beyond the limit of the analyzed area, ECTtracker will try to find it at the same area, without moving to the center of the image. This feature allows the program to perform a fast search of the lost object that left the area and returned in a while. The F value was created to compensate possible tremors and various repetitive movements of the patient. This working mode is more complex. Thus, it's recommended to use the C mode whenever possible.
Recognition settings
11. Structure file name. The program can work with one of several recognition structures to analyze images and compare their fragments with the predefined samples. This field shows the structure file name. If this field is empty, the program will use the integrated recognition structure.
12. Maximum amount of structure key points. The maximum possible amount of recognition structure points of ECTtracker. Higher amounts can improve the tracking quality level, while lower can decrease the overall load on the processor. The default value of this parameter - 100.
13. Structure key point width (pixel block, from 0 to 255). The recognition structure in the latest versions of ECTtracker can include not only separate points, but separate rectangular areas with centers in such points. This parameter defines the analyzed pixel block width. The matching level with samples will be identified using average values. Thus, there's no need to increase the amount of structure points to make the analyzed area bigger. The default value of this parameter is 1.
14. Structure key point height (pixel block, from 0 to 255. Similar to the previous parameter, this variable allows the user to define the analyzed pixel block height in the range from 0 to 255 pixels. The default value of this parameter is also 1.
15. Intensity (weight) of each channel (9 numbers, from 0 to 9). This parameter allows the user to set the priority level for each of the color channels (R, G, B, dR, dG, dB, H. S. L). Thus, the user can increase the priority level of channels with the most significant intensity difference for various states (rows in the Matrix of Samples) and almost no difference for the similar state (samples in one row of the Matrix). A properly selected channel priority formula makes it possible to improve the recognition quality and the overall efficiency of the program operation. The default value of this parameter is 111111111, i.e. all channels have the same level of priority.
17. Structure color in main window (in #FFFFFF format). Depending on the lighting conditions, eye color and skin color of the user, key points of the structure may look unclear during the creation of the Matrix of Samples. The user can select the most contrast colors by using this parameter, thus making the key points clearly visible on the image. This feature allows the user to perform the initial calibration process more easily. The default value of this parameter is FFFFFF, which is white.
18. Structure scale, when showing in color channel table. This parameter allows the user to define the recognition structure size in the SCO9 window, using a percentage of the original size. The default value of this parameter is 80. The user can decrease this value to reduce the space that is taken by the SCO9 window. The user can also increase the size for continuous operation of the recognition file structure, when it's required to perform a thorough analysis of the information in order to add or remove recognition structure points.
Target window and Matrix of Samples settings
20. Sample size – width (in pixels). The height and the width of a sample in the Matrix have to be selected properly in order to contain the biggest part of structure key points and provide proper recognition, but not make it too big, and to stay in the limits of the target window during movements of the user. The width can be selected in the range from 10 pixels up to the current width of the target window. The default value during the first start of the program is 120 pixels.
21. Sample size – height (in pixels). This parameter of the settings window works similarly to the previous one. The length can be selected in the range from 10 pixels up to the current length of the target window of ECTtracker. The default value of the sample height is 60 pixels. Key points of the structure have to be placed on the most frequently changing area.
22. Matrix of Samples size – width (amount of columns). This parameter determines the vertical amount of samples. The default value of this parameter is 4. That means the user can create no more than 4 samples with the same state (e.g. images with an open eye of the patient).
23. Matrix of Samples size – height (amount of rows). This parameter determines the horizontal amount of samples. The default value of this parameter is 4. When only two states of the user's eye are analyzed, the user can decrease the height of the Matrix of Samples to 2 in order to save some space. Each row of the Matrix must contain samples with a similar state. The first row - all the images with an open eye, the second row - with a closed eye. This rule was invented to provide proper generation of action codes and key codes, which will be sent to the receiving software.
24. Target size – width (in pixels). The target window width in pixels. The default value of this parameter is 140. The higher the value selected by the user, the wider the target window and the image analyzing area. The user can increase the size of the target window in cases when the patient retained some kind of motor activity and samples in the Matrix have a bigger size. When the target window is small, the analyzed area may go beyond the borders of the target window, thus ECTtracker will lose its focus. The target window size can be decreased on low-end computers with low technical characteristics. More detailed information about the proper selection of the target window size can be found in the 'Changing the target window size in order to improve the quality' section of the 'Hints and tricks' chapter of this manual.
25. Target size – height (in pixels). The target window vertical size in pixels. Works similarly to the previous parameter and defines the height of the target window, allowing the user to increase the size of the analyzed area. Keeping in mind that the target window has to capture a small area of the analyzed video to identify the eye state, it's not recommended to use extremely high values. The default value of this parameter is 160.
26. Target position – left margin (in pixels). This parameter saves information about the horizontal position of the target window. The value determines the distance between the left border of the screen and the left border of the target window in pixels.
27. Target position – top margin (in pixels). This parameter saves information about the vertical position of the target window. The value determines the distance between the upper border of the screen and the upper border of the target window in pixels.
Main window debugging elements settings
31. Debug – structure visibility. This parameter is responsible for the visibility of the structure above the image in the video window of the program. The structure is visible by default during the first start of the program, allowing the user to control the position of the searching zone in real time and identify cases when the program is losing the image.
32. Debug – statistics visibility. This parameter controls visibility of the statistic panel in the window of ECTtracker and makes it visible by default. It displays the coordinates of the most appropriate sample, as well as its position in the Matrix of Samples, matching level and the speed of video processing in frames per second.
33. Debug – video output visibility. This parameter controls the video visibility in the main window of ECTtracker. The default value of this parameter is 1 and the current frame is shown in the program. It's recommended to disable this parameter only in cases when ECTtracker is working on computers with extremely low technical characteristics, because absence of the video stream can speed up the program in such cases.
PRO34. Debug – height of panel with recognized samples. The default value of this parameter is 0, i.e. the panel with recognized samples is not visible to the user. It's recommended to set the value of this parameter to 70 when working with a Matrix of Samples that contains 4 different states. The main window of the program will show information about filling the Matrix of Samples (the left area) and matching images (the right area).
Paths, time intervals and automatic recognition settings
45. Activate automatic recognition (1-enable, 0-disable). The automatic recognition feature is disabled by default, because the user may need to perform the setting procedure during the first launch, i.e. change parameters, choose a structure, load samples from a previously saved file or perform automatic calibration in cases where the Matrix of Samples is empty. In case all settings have been made already and the Matrix of Samples is loading automatically, the user can enable the automatic recognition feature by changing the value of this parameter to 1. This parameter is very useful for work with totally paralyzed patients. By putting the shortcut of the program into the automatic startup section of the operating system, the user can create a totally automatic launching process for ECTtracker and image recognition after starting the computer. Such an approach allows the user to start working without pushing any physical keys or buttons.
PRO46. Time interval between writing operation status to file (in seconds). The program creates the events log, which includes various important events, including automatic recognition start and stop, structure selection and many other operations. By using this parameter, the user is able to select the time gap between the 'status' event's saving process. The default value is 10 seconds. The user can set any desired value between 1 and 1000 seconds. This feature gives the user another opportunity to check the current working state of the program. If the program is freezing or showing a dialog box that can't be closed by the user (due to full paralysis), then the program terminates events saving into the log. As a result, the log file stops increasing in size and it can be a signal that the program is not working properly. In conjunction with other programs (e.g. HandyFileMonitor – an application that controls file size changes periodically and notifies the user if there's no changes in a while) the user can perform an automatic restart of the program. Fortunately, ECTtracker is usually pretty stable and this feature is used in extremely rare cases.
47. Brightness changing threshold during automatic calibration. The brightness change threshold during the automatic calibration. This parameter can be selected in the range from 1 to 200 and defines brightness change during the automatic calibration. The default value of this parameter is 0.
48. Full path to automatic calibration script. In case the automatic calibration script file is located in the same folder as the main file of ECTtracker, the user can indicate only the name of it. The default calibration script file of the program is Eye_2S1P2M.dat (two eye states – opened and closed, two rows of the Matrix are filled, the auxiliary icon is shown in only one location - the center of the screen).
49. Time Frame – amount of analyzed frames per one emulated action. This parameter works as some kind of a filter. It allows the user to block keystroke emulation for all matching images that last less than the period of time indicated in this parameter. For example, if the patient is suffering from uncontrolled lash twitches, such actions have to be separated and filtered from the controlled eye closing. If the value of this parameter is 20 (the same value as in parameter 4), then all matching samples that last for less than one second will be ignored by the program. Such an approach allows the user to separate conscious actions from uncontrolled ones.
50. Full path to the current Matrix of samples. Allows the ECTtracker to open samples from a predefined folder during the launch of the program. This feature can be handy for cases where ECTtracker is already set up for automatic recognition after launching. The default value of this parameter is empty.
Additional program windows visibility settings
Parameters from 60 to 67 may have only one of the following values: 0 or 1. 0 means that an additional window is not shown, while 1 means the window is shown.
60. Show About window. This parameter controls the visibility of the "About" window. The default value of this parameter is 0 and the window with information about the program is hidden during the start and operation of ECTtracker.
61. Show settings window. This parameter controls the visibility of the settings window. The default value of this parameter is 1 and the settings window is visible to the user. If the user sets the 0 value, the settings window is going to be hidden during each start of the program. Hiding the settings window can be necessary and useful in cases where ECTtracker is working on computers with low resolution and lack of free space on the screen, as well as in cases when settings are not changed very often.
62. Show Matrix of Samples window. This parameter controls the visibility of the window with the Matrix of Samples. This window is visible by default, allowing the user to see the current set of samples. Also, the most appropriate sample is highlighted with a red border in the video window during the normal operation of the program. This feature allows the user to identify the best samples faster and change them if necessary, or perform automatic calibration in order to update the Matrix of Samples.
63. Show stripes diagram. This parameter controls the visibility of the debugging stripes diagram and makes it visible by default. At the same time, the debugging window is open and shows the group of samples that is the most consistent with the analyzed image from the video window of ECTtracker.
PRO64. Show structures diagram. This parameter is enabled by default and allows the user to show the SCO9 window that contains information about color channels intensity changes for each separate point of the current recognition structure of ECTtracker. All information is updated in real time with every new frame.
65. Show channels intensity diagram. This parameter is enabled by default. A special window with intensity indicators for each of the channels is shown during every launch of the program (3 RGB channels, 3 delta RGB and 3 HSL). All information is updated in real time with every new frame.
PRO66. Show events log window. The events log is visible by default in order to show the main actions of the program.
PRO67. Show structure editor window. This parameter controls the visibility of the recognition structure editor window. The editor is not available in the actual public version of the program.
Receiving software keys and actions setting
100. Name of receiving software (to receive emulated keystrokes). During its operation, ECTtracker emulates key strokes, based on samples corresponding with the analyzed image and their position in the Matrix of Samples. Such keystrokes are transmitted into receiving software, which is going to use the received codes and perform specific actions. In this field of the settings window, the user can specify the name (caption/title of the main window) of the receiving software. The following value is used by default: 'ECTkeyboard by www.eyecomtec.com', which is the name of the matrix of symbols (the virtual keyboard) from the EyeComTec assistive software complex.
101. Method of sending data to the receiving software (S-sendmessage, P-postmessage). The ECTtracker application supports two types of message transmitting to receiving software, i.e. SendMessage and PostMessage. The S value stands for SendMessage. In this case, ECTtracker sends messages to the receiving software and waits for an answer. The P value stands for PostMessage. In that case, ECTtracker sends messages to the receiving software without waiting for any confirmation. The PostMessage method is selected by default in the application.
The groups of parameters from 102 to 105 and from 110 to 115 allow the user to change the transmitted key codes and actions for receiving software. Key codes and actions are sent in accordance with the current corresponding sample in the video window of the program. Thus, the program emulates key strokes.
Codes transmitted by ECTtracker contain two numbers divided by spaces. The first number is the keyboard button code. Each button from the keyboard has its own unique number. For example, space button is 32, Enter is 13. The user can find the complete list of all codes through an internet search engine by entering "keyboard button codes".
The second number in the ECTtracker code determines a required state of the button: pressed or released. It can take the following values:
- 0 – no action performed (deactivate key);
- 1 – press and hold the key;
- 2 – release the key;
- 3 – press and release the key.
Parameters from 102 to 105 allow the user to set ECTtracker to control the cursor by moving the head of the user (if the value of parameter 9 is F). By moving an image that corresponds with a sample along the horizontal axis (X) and vertical axis (Y), ECTtracker can generate actions and send them to receiving software. Default codes and actions for these parameters are not defined.
PRO102. Key and action for positive shift on X-axis (+X) .
PRO103. Key and action for positive shift on Y-axis (+Y).
PRO104. Key and action for negative shift on X-axis (-X) .
PRO105. Key and action for negative shift on Y-axis (-Y) .
110. Key and action when no sample found. The key code and the action code which are sent to receiving software in cases where none of the samples from the Matrix correspond to the current image in the window of ECTtracker. This functionality allows the user to work with ECTtracker using only one sample in the Matrix. The default value is 32 2 (release space button). Let's look at one example. The user created a sample with a closed eye and added it into the second row of the Matrix of Samples. The user starts the recognition process. When the user closes the eye, the program registers a match between the image and the sample, and sends the key code and the action code to hold the space button (32 1). When the user opens the eye, ECTtracker can't find any matching samples and sends a code to release the space button (32 2). Thus, the user only needs one sample in the Matrix in order to emulate a keystroke. It's recommended to increase the wlim value (parameter 3) for this mode, making it higher than 30 in order to obtain a high level of recognition quality.
111. Key and action when sample is matching with row #0. Row #0 – represents the first row of the Matrix of Samples. The default value is 32 2 (release space button).
112. Key and action when sample is matching with row #1. Row #1 – the second row of the Matrix of Samples. The default value is 32 1 (press and hold space button).
113. Key and action when sample is matching with row #2. Row #2 – the third row of the Matrix of Samples. The default value is 32 1 (press and hold space button).
114. Key and action when sample is matching with row #3. Row #3 – the fourth row of the Matrix of Samples. The default value is not defined.
PRO115. Key and action when sample is matching with row #4. Row #4 - the fifth row of the Matrix of Samples. The default value is not defined.