RetinoMapper Class

Introduction

The Experiment Manager Plug-in features a RetinoMapper class (derived from the ExperimentEngine class) that is created and optimized for displaying various Retinotopy stimuli. Configuration of these stimuli can be achieved through various available parameters that are described in this document.

Retinotopy Parameters

Retinotopy Pattern

There are various Retinotopy Parameters that can be configured for an object created from a RetinoMapper class, most parameters availability depend of other parameters and so not all of them are in use during the Retinotopy stimuli presentation. In this document we'll split up and describe the parameter groups that depend on the Retinotopy pattern (RetinoPattern parameter) separately. The available Retinotopy patterns are:

• Fixation
• PolarAngle
• Eccentricity
• MovingBar
• MovingDots

Universal parameters

Some of the parameters are always available for you to configure (independent of the Retinotopy pattern you choose), these are:

Color Format

The format specifies the RGB value for the color, which may be in one of these formats:

• #RGB (each of R, G, and B is a single hex digit) or #RRGGBB or #RRRGGGBBB or #RRRRGGGGBBBB.
• A name from the list of colors defined in the list of SVG color keyword names provided by the World Wide Web Consortium; for example, "steelblue" or "gainsboro". These color names work on all platforms.

Fixation specific parameters

The above picture shows stimuli presentation where the Fixation RetinoPattern parameter is used. The Retinotopy stimuli area (in grey) is smaller than the screen (black) output area. Within the Retinotopy stimuli area we can see a fixation point (red). There are no further parameters defined which only belong to this Fixation RetinoPattern.

PolarAngle specific parameters

The above picture shows a stimuli presentation where the PolarAngle RetinoPattern parameter is used. It's the same as the Fixation RetinoPattern plus an additional wedge consisting of different rings with checkers that can rotate around the center point. A full wedge rotation (360 degrees) is called one cycle. Special parameters that belong to this PolarAngle RetinoPattern are:

Wedge triggered cycles and rotation direction

The below picture shows the wedge rotated at an angle of 0 degrees (at the X axis pointed to the right, with the right wedge border aligned over the X axis) when the PolarRotationDirection parameter is set to -1 (=Counterclockwise).

When the PolarRotationDirection parameter is set to 1 (=Clockwise) then the wedge at an angle of 0 degrees is drawn like in the below picture.

A full wedge cycle is internally subdivided by the CycleTriggerAmount parameter. These steps can be randomized (see RandomizeTriggerSteps parameter) and empty (see EmptyTriggerSteps parameter) as explained in the above parameter table. Internally these sub-cycles are indexed from [0 ... (CycleTriggerAmount-1)]. The first index (with value 0) is always at 0 degree and is dependent of the PolarRotationDirection parameter, as explained above. These indexed are internally also used to keep track of the randomly chosen history and to output the result in the experiment output file (automatically generated in the /outputs directory for each run), see the RetinoMapper Output Export chapter. The below pictures show how the different indexes are set for each step of 12 steps (CycleTriggerAmount = 12) from one full wedge rotation for both directions.

PolarRotationDirection = 1 (Clockwise)

PolarRotationDirection = -1 (Counterclockwise).

Cortical Magnitude Factor

This factor defines how the polar rings are distributed from the outer wedge ring towards the center.

If for example the CorticalMagnitudeFactor = 0.2 then:

A = 0.2 * B
A' = 0.2 * B'
...

The most inner ring is automatically extended till the border of the defined gap diameter. If the CorticalMagnitudeFactor = 0.0 then the rings are also equally divided over the wedge (B).

Eccentricity specific parameters

The above picture shows a stimuli presentation where the Eccentricity RetinoPattern parameter is used. It's again the same as the Fixation RetinoPattern plus an additional ring inside the Retinotopy stimuli area in which its diameter can change (eccentricity). One cycle here means a full diameter change of the wedge. The ring consist out of several sub-ring(s) each divided in checkers of which it's color can again alternate. Again in the center of the screen a fixation point (red) is shown.

Cortical Magnitude Factor

This factor defines how the total width (see A) of all the visible rings compared to the eccentricity amount. This width is depending of the eccentricity (ring diameter) at that moment (this doesn't apply when the DisableCortMagFac parameter is set to true). The smallest ring eccentricity diameter is equal to the gap diameter (see C).

E.g. CorticalMagnitudeFactor = 0.2 ==> A = 0.2 * B

All individual ring widths are equal.

Eccentricity triggered cycles and direction

A full Eccentricity cycle is internally subdivided by the CycleTriggerAmount parameter. These steps can be randomized (see RandomizeTriggerSteps parameter) and empty (see EmptyTriggerSteps parameter) as explained in the above parameter table. Internally these sub-cycles are indexed from [0 ... (CycleTriggerAmount-1)]. The indexing is dependent of the EccentricityDirection parameter. These indexed are internally also used to keep track of the randomly chosen history and to output the result in the experiment output file (automatically generated in the /outputs directory for each run), see the RetinoMapper Output Export chapter. The below pictures show how the different indexes are set for each step of 12 steps (CycleTriggerAmount = 12) from one full eccentricity cycle for both directions.

EccentricityDirection = 1 (Increasing diameter)

EccentricityDirection = -1 (Decreasing diameter)

MovingBar specific parameters

The above picture shows a stimuli presentation where the MovingBar RetinoPattern parameter is used. It's the same as the Fixation RetinoPattern plus an additional bar consisting of different sub-bar(s) that can move within the Retinotopy stimuli area. Each sub-bar consists out of several checkers with an alternating color along its length (see below A). A full bar movement (see below C direction) is called one cycle. The moving bar has a set angle which remains the same during one cycle. Special parameters that belong to this MovingBar RetinoPattern are:

Moving Bar Coverage

We see above inside a full screen area(see total grey area) an Retinotopy stimuli area (see marker B, the red rectangle) covering the diagonal B. The bar is at its first initial position (first step of a full cycle) and moves along the direction of the yellow arrow(see marker A) until it reaches the orange border above the fixation dot and then the full cycle is complete. The MovingBarCoverage parameter defines the full cycle movement (independent of the MovingBarAngle parameter) in such way that:

A = MovingBarCoverage * B

MovingBar triggered cycles and MovingBar direction

A full MovingBar cycle is internally subdivided by the CycleTriggerAmount parameter. These steps can be randomized (see RandomizeTriggerSteps parameter) and empty (see EmptyTriggerSteps parameter) as explained in the above parameter table. Internally these sub-cycles are indexed from [0 ... (CycleTriggerAmount-1)]. The indexing is dependent of the MovingBarDirection. These indexed are internally also used to keep track of the randomly chosen history and to output the result in the experiment output file (automatically generated in the /outputs directory for each run), see the RetinoMapper Output Export chapter. The below pictures show how the different indexes are set for each step of 12 steps (CycleTriggerAmount = 12) from one full bar movement.

MovingBarDirection = 1(downwards), MovingBarAngle = 30

MovingBarDirection = -1(upwards), MovingBarAngle = 30

MovingDots specific parameters

The above picture shows a MovingDots screen example. Within the active Retinotopy stimuli area (grey) several dots are presented inside two areas (Hemi-fields). These dots can move around when they leave the Hemi-field they automatically appear again in the opposite corner moving with the same speed and direction/angle making sure that the amount of visible dots remains constant. In the above example the left and right hemi-fields are visible and divided by a distance from each other. Both Hemi-fields contain the dots at the same position (They are identical). The distance between the hemi-fields could also be made zero which would create one area with the dots smoothly moving from one area to the other. Again in the center of the screen a fixation point (red) is shown.

RetinoMapper Output Export

if the OutputTriggerFrame parameter is set to "true" (only applies for the "Fixation", "PolarAngle", "Eccentricity" or "MovingBar" RetinoPattern parameter) then the Experiment manager automatically saves for each trigger step the displayed Retinotopic stimuli to a file. This option is only usable in non-experimental modes where accurate timing is not an critical issue because enabling this option may dramatically slow down the experiment and may cause that the requested StimuliRefreshRate is not met! If you want to save the displayed result for each trigger step to a file then it's advised is to re-run the configured experiment with the same parameters set and the set this option to "true".

Output Directory

Exported files are saved (under subdirectories) inside the Output Directory, which is by default the Main User Directory\Outputs directory. You can override this output directory to which the RetinoMapper object saves these files to, you can do this by making use of the setCustomOutputDirectoryPath() slot. Finally the file(s) are saved to the output directory in a subdirectory called "RetinotopyMapper" with one or more subdirectories (for each run) containing the generated files.

Output Frame Format

By using the OutputFrameFormat parameter we can configure the format (and file extension) of the generated files.

DAT format

The custom graphical DAT format is created for users who need a easy to access/parse file format and don't mind it's file size that much. The file first always starts with a unique header (32 bits), containing the value (0xCAFE1234).

#define ARGB_FORMAT_HEADER 0xCAFE1234

After the header the next 8 bytes are reserved for the Image resolution (width (=32 bits) and height (=32 bits)).

quint32 width = image.width();
quint32 height = image.height();

Hereafter the actual Image data can be found per pixel as a Qt QRgb type.

QRgb type definition

An ARGB quadruplet on the format #AARRGGBB, equivalent to an unsigned int. The type also holds a value for the alpha-channel. The default alpha channel is ff, i.e. opaque.

Below you can find an example C++ file showing how you can open and process an (*.dat) file:

// ARGB_Test.cpp : Defines the entry point for the console application.
//
#include "stdafx.h"
#include 
#include 
using namespace std;
#define MAGIC_ARGB_FORMAT_HEADER 0xCAFE1234
#define ACTIVE_PIXEL 0xFFFFFFFF
#define INACTIVE_PIXEL 0xFF000000
#define MAX_VALUE 0xFFFF
#define MIN_VALUE 0x0000
struct HeaderData
{
	unsigned int magic;
	unsigned int width;
	unsigned int height;
};
//inline unsigned short swap_16bit(unsigned short us)
//{
//        return (unsigned short)(((us & 0xFF00) >> 8) |
//                ((us & 0x00FF) << 8));
//}
inline unsigned long swap_32bit_ulong(unsigned long ul)
{
	return (unsigned long)(((ul & 0xFF000000) >> 24) |
		((ul & 0x00FF0000) >>  8) |
		((ul & 0x0000FF00) <<  8) |
		((ul & 0x000000FF) << 24));
}
inline unsigned int swap_32bit_uint(unsigned int ui)
{
	return (unsigned long)(((ui & 0xFF000000) >> 24) |
		((ui & 0x00FF0000) >>  8) |
		((ui & 0x0000FF00) <<  8) |
		((ui & 0x000000FF) << 24));
}
int _tmain(int argc, _TCHAR* argv[])
{
	ifstream::pos_type size;
	char *filename = "1_2_0_8.dat";
	ifstream file (filename, ios::in|ios::binary|ios::ate);
	HeaderData *header = new HeaderData();
	//char pixelBuffer[4];//AARRGGBB,
	//see http://doc.qt.nokia.com/latest/qimage.html#image-formats
	unsigned short nPixelSubValue = 0;//2 bytes
	unsigned long lPixelValue = 0;//4 bytes
	int nBufferSize = sizeof(lPixelValue);
	int nRow = 0;
	int nColumn = 0;
	
	if (file.is_open())
	{
		size = file.tellg();
		if (size >= 16)//>=1 pixel
		{
			file.seekg (0, ios::beg);
			file.read((char*)header,sizeof(HeaderData));
			header->height = swap_32bit_uint(header->height);
			cout << "The height is " << header->height << endl;
			header->width = swap_32bit_uint(header->width);
			cout << "The width is " << header->width << endl;
			header->magic = swap_32bit_uint(header->magic);
			cout << "The magic number is " << header->magic << endl;
			if (header->magic == MAGIC_ARGB_FORMAT_HEADER)
			{
				while (!file.eof())
				{
					//file.read((char*)pixelBuffer,nBufferSize);
					file.read((char*)&lPixelValue,nBufferSize);  
					lPixelValue = swap_32bit_ulong(lPixelValue);
					 //BBGGRRAA -> AARRGGBB
					if (lPixelValue == ACTIVE_PIXEL)
					{
						lPixelValue = lPixelValue;
						cout << "X";
					}
					else if(lPixelValue == INACTIVE_PIXEL)
					{
						lPixelValue = lPixelValue;
						cout << " ";
					}
					else
					{
						lPixelValue = lPixelValue;
						cout << "?";
					}
					//For Accessing the sub pixel values A,R,G,B
					//for (int i=0;i<4;i++) />/{
					//        nPixelSubValue = (unsigned short)pixelBuffer[i];
					//        if (nPixelSubValue == MAX_VALUE)
					//        {
					//                nPixelSubValue = nPixelSubValue;
					//        }
					//        else if(nPixelSubValue == MIN_VALUE)
					//        {
					//                nPixelSubValue = nPixelSubValue;
					//        }
					//        else
					//        {
					//                nPixelSubValue = nPixelSubValue;
					//        }
					//}
					if ((nColumn + 1) == header->height)
					{
						cout << endl;
						nColumn = 0;
						if ((nRow + 1) == header->width)
						{
							nRow = 0;
							nColumn = 0;
							break;
						}
						else
						{
							nRow++;
						}
					}
					else
					{
						nColumn++;
					}
				}
			}
		}
		else
		{
			cout << "Too small file size";
			file.close();
			return 0;
		}
		file.close();
	}
	else
	{
		cout << "Unable to open file";
		return 0;
	}
	cout << "End-of-file reached.." << endl;
	return 0;
}

You can also make use of the ImageProcessor class to declare an object that can perform some simple (*.dat) file operations.

CDAT format

The CDAT format is like a sequential container for the DAT file(s). The file first always starts with a unique header (32 bits), containing the value (0xCAFE5678).

#define ARGB_FORMAT_HEADER 0xCAFE5678

After the header the next 8 bytes are reserved for the number of Images the files contains.

quint32 itemCount;

After the header the next 8 bytes are reserved for the Image(s) resolution (width (=32 bits) and height (=32 bits)).

quint32 width = image.width();
quint32 height = image.height();

Hereafter the actual Image(s) data can be found per pixel as a Qt QRgb type (image after image).