baseStimulus Class Reference

baseStimulus is the superclass for all stimulus objects More...

Detailed Description

baseStimulus is the superclass for all stimulus objects

Superclass providing basic structure for all stimulus classes. This is a dynamic properties descendant, allowing for the temporary run variables used, which get appended "name"Out, i.e. speed is duplicated to a dymanic property called speedOut; it is the dynamic propertiy which is used during runtime, and whose values are converted from definition units like degrees to pixel values that PTB uses. The transient copies are generated on setup and removed on reset.

Todo:

build up animatorManager functions

Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md

Inheritance diagram for baseStimulus:

Public Types
enum	Events { readPanelUpdate }

Public Member Functions
virtual	setup (in runObject)
	ALL Children must implement these 5 methods!
virtual	draw (in runObject)
	draw to the screen buffer, ready for flip()
virtual	animate (in runObject)
	animate the stimulus, normally called after a draw
virtual	update (in runObject)
virtual	reset (in runObject)
function	baseStimulus (in varargin)
	Class constructor.
function set	colour (in me, in value)
	colour set method Allow 1 (R=G=B) 3 (RGB) or 4 (RGBA) value colour
function set	alpha (in me, in value)
	alpha set method
function get	delta (in me)
	delta Get method delta is the normalised number of pixels per frame to move a stimulus
function get	dX (in me)
	dX Get method X position increment for a given delta and angle
function get	dY (in me)
	dY Get method Y position increment for a given delta and angle
function	show (in me)
	Method to set isVisible=true.
function	hide (in me)
	Method to set isVisible=false.
function	setOffTime (in me, in time)
	set offTime
function	setDelayTime (in me, in time)
	set delayTime
function	resetTicks (in me)
	reset the various tick counters for our stimulus
function	getMousePosition (in me)
	get mouse position we make sure this is only called once per animation tick to improve performance and ensure all stimuli that are following mouse position have consistent X and Y per frame update This sets mouseX and mouseY and mouseValid if mouse is within PTB screen (useful for mouse override positioning for stimuli)
function	run (in me, in benchmark, in runtime, in s, in forceScreen, in showVBL)
	Run stimulus in a window to preview it.
function	makePanel (in me, in parent)
	make a GUI properties panel for this object
function	selectFilePanel (in me, in varargin)
	read values from a GUI properties panel for this object
function	readPanel (in me, in varargin)
	read values from a GUI properties panel for this object
function	showPanel (in me)
	show GUI properties panel for this object
function	hidePanel (in me)
	hide GUI properties panel for this object
function	closePanel (in me, in varargin)
	close GUI panel for this object
function	cleanHandles (in me, in ignoredArg)
	clean any handles
function	getP (in me, in name, in range)
	gets a property copy or original property
function	setP (in me, in name, in value)
	sets a property copy or original property
function	updateXY (in me, in x, in y, in useDegrees)
	Update only position info, faster and doesn't reset image etc.
Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor.
function get	fullName (in me)
function	getALF (in me, in subject, in lab, in create)
	get the ALF path
function	makeReport (in me, in rpt)
	Generate a detailed report for the opticka object.
function	findAttributes (in me, in attrName, in attrValue)
function	findAttributesandType (in me, in attrName, in attrValue, in type)
	find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical.
function	findPropertyDefault (in me, in propName)
	Return the declared default value for a class property.
function	clone (in me)
	Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore.
function	checkSuperclasses (in List)
function	editProperties (in me, in properties)
	method to modify a set of properties
function	setProp (in me, in property, in value)
	method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine.
function	initialiseSaveFile (in me, in varargin)
	just get date fragment for backwards compatibility
function	checkPaths (in me)
	checks the paths are valid

Static Public Member Functions
static function	mixColour (in c1, in c2, in contrast)
	linear interpolation between two colour arrays based on a contrast
static function	d2r (in degrees)
	degrees2radians
static function	r2d (in r)
	radians2degrees
static function	findDistance (in x1, in y1, in x2, in y2)
	findDistance in X and Y coordinates
static function	updatePosition (in delta, in angle)
	updatePosition returns dX and dY given an angle and delta
Static Public Member Functions inherited from optickaCore
static function	initialiseGlobals (in doReset, in doOpen)
static function	makeArgs (in args)
	Converts cell args to structure array.
static function	addDefaults (in args, in defs)
	regularises and adds default options to arg input
static function	hasKey (in in, in key)
	check if a struct / object has a propery / field
static function	getKeys (in device)
	PTB Get key presses, stops key bouncing.

Public Attributes
Property	type
	stimulus type
Property	xPosition
Property	yPosition
Property	size
Property	colour
Property	alpha
	Alpha (opacity) [0-1], this gets combined with the RGB colour.
Property	startPosition
Property	speed
Property	angle
	angle in degrees (0 - 360)
Property	delayTime
Property	offTime
	time to turn stimulus off, relative to stimulus onset
Property	isVisible
	true or false, whether to draw() this object
Property	mouseOverride
	override X and Y position with mouse input? Useful for RF mapping
Property	showOnTracker
	show the position on the Eyetracker display?
Property	verbose
	Do we log extra details to the command-line?
Property	xFinal
Property	yFinal
Property	mvRect
Property	szIsPx
Property	szPx
	computed size in pixels
Property	szD
	computed size in °
Property	xFinalD
	X and Y position in °
Property	yFinalD
Property	isRect
Property	tick
	tick updates +1 on each call of draw (even if delay or off is true and no stimulus is drawn, resets on each update
Property	drawTick
	draw tick only updates when a draw is actually performed, resets on each update
Property	ppd
	pixels per degree (normally inhereted from screenManager)
Property	delta
	What our per-frame motion delta is.
Property	dX
	X update which is computed from our speed and angle.
Property	dY
	X update which is computed from our speed and angle.
Public Attributes inherited from optickaCore
Property	name
	object name
Property	comment
	comment
Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false
Property	optickaVersion
	version number
Property	dateStamp
	clock() dateStamp set on construction
Property	uuid
	universal ID
Property	paths
	storage of various paths
Property	fullName
	The fullName is the object name combined with its uuid and class name.

Protected Member Functions
function	addRuntimeProperties (in me)
	These are transient properties that specify actions during runtime.
function	updateRuntimeProperties (in me)
	Update transient properties that specify actions during runtime.
function	computePosition (in me)
	compute xFinal and yFinal (in pixels) taking startPosition, xPosition, yPosition and direction/angle into account
function	setAnimationDelta (in me)
function	setRect (in me)
function	toStructure (in me, in tmp)
	Converts properties to a structure.
function	removeTmpProperties (in me)
	Finds and removes dynamic properties.
function	delete (in me)
Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	addArgs (in me, in args)
function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	getFonts (in me)
	set paths for object
function	toStructure (in me)
	Converts properties to a structure.
function	getType (in me, in in)
function	logOutput (in me, in in, in message, in override)
	Give a metaproperty return the likely property class.
function	salutation (in me, in varargin)
	Prints messages dependent on verbosity.

Protected Attributes
Property	family
	the stimulus family (grating, dots etc.)
Property	texture
	Our texture pointer for texture-based stimuli.
Property	handles
	handles for the GUI
Property	sM
	our screen manager
Property	animator
	animation manager
Property	screenVals
	screen settings generated by sM on setup
Property	isSetup
Property	isGUI
	is panel constructed?
Property	dstRect
	initial screen rectangle position [LEFT TOP RIGHT BOTTOM]
Property	mouseValid
	is mouse position within screen co-ordinates?
Property	mouseX
	mouse X position
Property	mouseY
	mouse Y position
Property	delayTicks
	delay ticks to wait until display
Property	offTicks
	ticks before stimulus turns off
Property	inSetup
	are we setting up?
Property	delta_
	delta cache
Property	dX_
	dX cache
Property	dY_
	dY cache
Property	isInSetColour
	deal with interaction of colour and alpha
Property	setLoop
Property	ignorePropertiesBase
	Which properties to ignore cloning when making transient copies in setup.
Property	ignorePropertiesUIBase
	Which properties to not draw in the UI panel.
Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object
Property	mversion
	Matlab version number, this is transient so it is not saved.
Property	sansFont
	sans font
Property	monoFont
	monoFont
Property	className
	class name
Property	savePrefix
	save prefix generated from clock time
Property	fullName_
	cached full name

Member Enumeration Documentation

Events

enum baseStimulus::Events

Enumerator
readPanelUpdate	triggered when reading from a UI panel,

                                            :3) + me.colour2(1:3))/2;
            end
            me.isInSetColour = false;
        end
 
        % ===================================================================
        %> @brief alpha set method
        %>
        % ===================================================================
        function set.alpha(me, value)
            if me.isSetup; warning('You should set alphaOut to affect drawing...'); end
            if value<0; value=0;elseif value>1; value=1; end
            me.alpha = value;
            if ~me.isInSetColour
                me.colour = me.colour(1:3); %force colour to be regenerated
                if ~isempty(findprop(me,'colour2')) && ~isempty(me.colour2)
                    me.colour2 = [me.colour2(1:3) me.alpha];
                end
                if ~isempty(findprop(me,'baseColour')) && ~isempty(me.baseColour)
                    me.baseColour = [me.baseColour(1:3) me.alpha];
                end
            end
        end
 
        % ===================================================================
        %> @brief delta Get method
        %> delta is the normalised number of pixels per frame to move a stimulus
        % ===================================================================
        function value = get.delta(me)
            value = (getP(me,'speed') * me.ppd) * me.screenVals.ifi;
        end
 
        % ===================================================================
        %> @brief dX Get method
        %> X position increment for a given delta and angle
        % ===================================================================
        function value = get.dX(me)
            value = 0;
            if ~isempty(findprop(me,'directionOut'))
                [value,~]=me.updatePosition(me.delta,me.directionOut);
            elseif ~isempty(findprop(me,'angleOut'))
                [value,~]=me.updatePosition(me.delta,me.angleOut);
            end
        end
 
        % ===================================================================
        %> @brief dY Get method
        %> Y position increment for a given delta and angle
        % ===================================================================
        function value = get.dY(me)
            value = 0;
            if ~isempty(findprop(me,'directionOut'))
                [~,value]=me.updatePosition(me.delta,me.directionOut);
            elseif ~isempty(findprop(me,'angleOut'))
                [~,value]=me.updatePosition(me.delta,me.angleOut);
            end
        end
 
        % ===================================================================
        %> @brief Method to set isVisible=true.
        %>
        % ===================================================================
        function show(me)
            me.isVisible = true;
        end
 
        % ===================================================================
        %> @brief Method to set isVisible=false.
        %>
        % ===================================================================
        function hide(me)
            me.isVisible = false;
        end
 
        % ===================================================================
        %> @brief set offTime
        %>
        % ===================================================================
        function setOffTime(me, time)
            me.offTime = time;
        end
 
        % ===================================================================
        %> @brief set delayTime
        %>
        % ===================================================================
        function setDelayTime(me, time)
            me.delayTime = time;
        end
 
        % ===================================================================
        %> @brief reset the various tick counters for our stimulus
        %>
        % ===================================================================
        function resetTicks(me)
            global mouseTick %#ok<*GVMIS> %shared across all stimuli
            if max(me.delayTime) > 0 %delay display a number of frames
                if length(me.delayTime) == 1
                    me.delayTicks = round(me.delayTime/me.screenVals.ifi);
                elseif length(me.delayTime) == 2
                    time = randi([me.delayTime(1)*1000 me.delayTime(2)*1000])/1000;
                    me.delayTicks = round(time/me.screenVals.ifi);
                end
            else
                me.delayTicks = 0;
            end
            if min(me.offTime) < Inf %delay display a number of frames
                if length(me.offTime) == 1
                    me.offTicks = round(me.offTime/me.screenVals.ifi);
                elseif length(me.offTime) == 2
                    time = randi([me.offTime(1)*1000 me.offTime(2)*1000])/1000;
                    me.offTicks = round(time/me.screenVals.ifi);
                end
            else
                me.offTicks = Inf;
            end
            mouseTick = 0;
            me.tick = 0;
            me.drawTick = 0;
        end
 
        % ===================================================================
        %> @brief get mouse position
        %> we make sure this is only called once per animation tick to
        %> improve performance and ensure all stimuli that are following
        %> mouse position have consistent X and Y per frame update
        %> This sets mouseX and mouseY and mouseValid if mouse is within
        %> PTB screen (useful for mouse override positioning for stimuli)
        % ===================================================================
        function getMousePosition(me)
            global mouseTick mouseGlobalX mouseGlobalY mouseValid
            if me.tick > mouseTick
                if ~isempty(me.sM) && isa(me.sM,'screenManager') && me.sM.isOpen
                    [me.mouseX, me.mouseY] = GetMouse(me.sM.win);
                else
                    [me.mouseX, me.mouseY] = GetMouse;
                end
                if me.mouseX > -1 && me.mouseY > -1
                    me.mouseValid = true;
                else
                    me.mouseValid = false;
                end
                mouseTick = me.tick; %set global so no other object with same tick number can call this again
                mouseValid = me.mouseValid;
                mouseGlobalX = me.mouseX; mouseGlobalY = me.mouseY;
            else
                if ~isempty(mouseGlobalX) && ~isempty(mouseGlobalY)
                    me.mouseX = mouseGlobalX; me.mouseY = mouseGlobalY;
                    me.mouseValid = mouseValid;
                end
            end
        end
 
        % ===================================================================
        %> @fn run
        %> @brief Run stimulus in a window to preview it
        %>
        %> @param benchmark true|false [optional, default = false]
        %> @param runtime time to show stimulus [optional, default = 2]
        %> @param screenManager to use [optional]
        %> @param forceScreen for a particulr monitor/screen to use
        %> @param showVBL show a plot of the VBL times
        % ===================================================================
        function run(me, benchmark, runtime, s, forceScreen, showVBL)
            arguments(Input)
                me %self
                benchmark logical   = false
                runtime double      = 2
                s                   = []
                forceScreen double  = -1
                showVBL logical     = false
            end
 
            if isempty(benchmark); benchmark = false; end
            if isempty(runtime); runtime = 2; end
            if isempty(forceScreen); forceScreen = -1; end
            if isempty(showVBL); showVBL = false; end
 
            try
 
                if ~isa(s,'screenManager')
                    if isempty(me.sM); me.sM=screenManager; end
                    s = me.sM;
                    s.blend = true;
                    s.disableSyncTests = true;
                    s.visualDebug = true;
                    s.bitDepth = '8bit';
                end
 
                oldscreen = s.screen;
                oldbitdepth = s.bitDepth;
                oldwindowed = s.windowed;
                if forceScreen >= 0
                    s.screen = forceScreen;
                    if forceScreen == 0
                        s.bitDepth = '8bit';
                    end
                end
                prepareScreen(s);
 
                if benchmark
                    s.windowed = false;
                elseif forceScreen > -1
                    if ~isempty(s.windowed) && (length(s.windowed) == 2 || length(s.windowed) == 4)
                        % use existing setting
                    else
                        s.windowed = [0 0 s.screenVals.screenWidth/2 s.screenVals.screenHeight/2]; %half of screen
                    end
                end
 
                if me.verbose; s.debug = true; end
 
                if ~s.isOpen; open(s);end
                sv = s.screenVals;
                setup(me,s); %setup our stimulus object
 
                Priority(MaxPriority(s.win)); %bump our priority to maximum allowed
 
                if ~any(strcmpi(me.family,{'movie','revcor'})); draw(me); resetTicks(me); end
                if benchmark
                    drawText(s, 'BENCHMARK: screen won''t update properly, see FPS in command window at end.');
                else
                    drawGrid(s); %draw degree dot grid
                    drawScreenCenter(s);
                    drawText(s, ['Preview ALL with grid = ±1°; static for 1 seconds, then animate for ' num2str(runtime) ' seconds...'])
                end
                if ismethod(me,'resetLog'); resetLog(me); end
                flip(s);
                if ~any(strcmpi(me.family,{'movie','revcor'})); update(me); end
                if benchmark
                    WaitSecs('YieldSecs',0.25);
                else
                    WaitSecs('YieldSecs',2);
                end
                if runtime < sv.ifi; runtime = sv.ifi; end
                nFrames = 0;
                notFinished = true;
                benchmarkFrames = floor(sv.fps * runtime);
                vbl = zeros(benchmarkFrames+1,1);
                startT = GetSecs; lastvbl = startT;
                while notFinished
                    nFrames = nFrames + 1;
                    draw(me); %draw stimulus
                    if ~benchmark && s.debug; drawGrid(s); end
                    finishDrawing(s); %tell PTB/GPU to draw
                    animate(me); %animate stimulus, will be seen on next draw
                    if benchmark
                        Screen('Flip',s.win,0,2,2);
                        notFinished = nFrames < benchmarkFrames;
                    else
                        vbl(nFrames) = flip(s, lastvbl + sv.halfifi); %flip the buffer
                        lastvbl = vbl(nFrames);
                        % the calculation needs to take into account the
                        % first and last frame times, so we subtract ifi*2
                        notFinished = lastvbl < ( vbl(1) + ( runtime - (sv.ifi * 2) ) );
                    end
                end
                endT = flip(s);
                if ~benchmark;startT = vbl(1);end
                diffT = endT - startT;
                WaitSecs(0.5);
                vbl = vbl(1:nFrames);
                if showVBL && ~benchmark
                    figure;
                    plot(diff(vbl)*1e3,'k*');
                    line([0 length(vbl)-1],[sv.ifi*1e3 sv.ifi*1e3],'Color',[0 0 0]);
                    title(sprintf('VBL Times, should be ~%.4f ms',sv.ifi*1e3));
                    ylabel('Time (ms)')
                    xlabel('Frame #')
                end
                Priority(0); ShowCursor; ListenChar(0);
                reset(me); %reset our stimulus ready for use again
                close(s); %close screen
                s.screen = oldscreen;
                s.windowed = oldwindowed;
                s.bitDepth = oldbitdepth;
                fps = nFrames / diffT;
                fprintf('\n\n======>>> Stimulus: %s\n',me.fullName);
                fprintf('======>>> <strong>SPEED</strong> (%i frames in %.3f secs) = <strong>%g</strong> fps\n\n',nFrames, diffT, fps);
                if ~benchmark;fprintf('\b======>>> First - Last frame time: %.3f\n\n',vbl(end)-startT);end
                clear s fps benchmark runtime b bb i vbl; %clear up a bit
            catch ERR
                try getReport(ERR); end
                try Priority(0); end
                if exist('s','var') && isa(s,'screenManager')
                    try close(s); end
                end
                clear fps benchmark runtime b bb i; %clear up a bit
                reset(me); %reset our stimulus ready for use again
                rethrow(ERR)
            end
        end
        
        % ===================================================================
        %> @brief make a GUI properties panel for this object
        %>
        % ===================================================================
        function handles = makePanel(me, parent)
            if ~isempty(me.handles) && isfield(me.handles, 'root') && isa(me.handles.root,'matlab.ui.container.Panel')
                fprintf('---> Panel already open for %s\n', me.fullName);
                return
            end
            
            handles = [];
            setPaths(me); % refresh our paths for the current machine
            if isempty(me.sansFont); getFonts(me); end
            
            if ~exist('parent','var')
                parent = uifigure('Tag','gFig',...
                    'Name', [me.fullName 'Properties'], ...
                    'Position', [ 10 10 800 500 ],...
                    'MenuBar', 'none', ...
                    'CloseRequestFcn', @me.closePanel, ...
                    'NumberTitle', 'off');
                me.handles(1).parent = parent;
                handles(1).parent = parent;
            end
            
            bgcolor = [0.95 0.95 0.95];
            bgcoloredit = [1 1 1];
            fsmall = 11;
            fmed = 12;
            handles.root = uipanel('Parent', parent,...
                'Units', 'normalized',...
                'Position', [0 0 1 1],...
                'Title', me.fullName,...
                'TitlePosition','centertop',...
                'FontName', me.sansFont,...
                'FontSize', fmed,...
                'FontAngle', 'italic',...
                'BackgroundColor', [0.94 0.94 0.94]);
            handles.grid = uigridlayout(handles.root,[1 3],'ColumnSpacing',2,'RowSpacing',2,'Padding',[2 2 2 2],'BackgroundColor',bgcolor);
            handles.grid1 = uigridlayout(handles.grid,'ColumnSpacing',2,'RowSpacing',2,'Padding',[2 2 2 2],'BackgroundColor',bgcolor);
            handles.grid2 = uigridlayout(handles.grid,'ColumnSpacing',2,'RowSpacing',2,'Padding',[2 2 2 2],'BackgroundColor',bgcolor);
            handles.grid.ColumnWidth = {'1x','1x',130};
            handles.grid1.ColumnWidth = {'2x','1x'};
            handles.grid2.ColumnWidth = {'2x','1x'};
            
            idx = {'handles.grid1','handles.grid2','handles.grid3'};
            
            disableList = 'fullName';
 
            mc = metaclass(me);
            pl = string({mc.PropertyList.Name});
            d1 = {mc.PropertyList.Description};
            d2 = {mc.PropertyList.DetailedDescription};
            for i = 1:length(d1)
                a = regexprep(d1{i},'^\s*>\s*','');
                a = regexprep(a,'''','`');
                b = d2{i};
                if isempty(b)
                    dl{i} = string(a);
                else
                    b = strsplit(b,'\n');
                    for j = 1:length(b)
                        b{j} = regexprep(b{j},'^\s*>\s*','');
                        b{j} = regexprep(b{j},'''','`');
                    end
                    dl{i} = string([{a} b(:)']);
                end
            end
            pr = findAttributesandType(me,'SetAccess','public','notlogical');
            pr = sort(pr);
            igA = {}; igB = {};
            val = findPropertyDefault(me,'ignorePropertiesUI');
            if ~isempty(val)
                igA = val;
            elseif isprop(me,'ignorePropertiesUI')
                igA = me.ignorePropertiesUI;
            end
            if isprop(me,'ignorePropertiesUIBase'); igB = findPropertyDefault(me,'ignorePropertiesUIBase'); end
            if ischar(igA);igA = strsplit(igA,'|');end
            if ischar(igB); igB = {'animator','fullName','mvRect','xFinal','yFinal','xFinalD','yFinalD'}; end
            excl = [igA igB];   
            eidx = [];
            for i = 1:length(pr)
                if matches(pr{i}, excl)
                    eidx = [eidx i];
                end
            end
            pr(eidx) = [];
            lp = ceil(length(pr)/2);
            
            pr2 = findAttributesandType(me,'SetAccess','public','logical');
            pr2 = sort(pr2);
            eidx = [];
            for i = 1:length(pr2)
                if matches(pr2{i},excl)
                    eidx = [eidx i];
                end
            end
            pr2(eidx) = [];
            lp2 = length(pr2);
            if lp2 > 0; handles.grid3 = uigridlayout(handles.grid,[lp2 1],'Padding',[1 1 1 1],'BackgroundColor',bgcolor); end
 
            for i = 1:2
                for j = 1:lp
                    cur = lp*(i-1)+j;
                    if cur <= length(pr)
                        nm = pr{cur};
                        val = me.(nm);
                        % this gets descriptions
                        ix = find(pl == nm);
                        if ~isempty(ix)
                            desc = dl{ix};
                        else
                            desc = nm;
                        end
                        if ischar(val)
                            if isprop(me,[nm 'List'])
                                if strcmp(me.([nm 'List']),'filerequestor')
                                    val = regexprep(val,'\s+','  ');
                                    handles.([nm '_char']) = uieditfield(...
                                        'Parent',eval(idx{i}),...
                                        'Tag',[nm '_char'],...
                                        'HorizontalAlignment','center',...
                                        'ValueChangedFcn',@me.readPanel,...
                                        'Value',val,...
                                        'FontName',me.monoFont,...
                                        'Tooltip', desc, ...
                                        'BackgroundColor',bgcoloredit);
                                    if ~isempty(regexpi(nm,disableList,'once')) 
                                        handles.([nm '_char']).Enable = false; 
                                    end
                                else
                                    txt=findPropertyDefault(me,[nm 'List']);
                                    if contains(val,txt)
                                        handles.([nm '_list']) = uidropdown(...
                                        'Parent',eval(idx{i}),...
                                        'Tag',[nm '_list'],...
                                        'Items',txt,...
                                        'ValueChangedFcn',@me.readPanel,...
                                        'Value',val,...
                                        'Tooltip', desc, ...
                                        'BackgroundColor',bgcolor);
                                        if ~isempty(regexpi(nm,disableList,'once')) 
                                            handles.([nm '_list']).Enable = false; 
                                        end
                                    else
                                        handles.([nm '_list']) = uidropdown(...
                                        'Parent',eval(idx{i}),...
                                        'Tag',[nm '_list'],...
                                        'Items',txt,...
                                        'Tooltip', desc, ...
                                        'ValueChangedFcn',@me.readPanel,...
                                        'BackgroundColor',bgcolor);
                                    end
                                end
                            else
                                val = regexprep(val,'\s+','  ');
                                handles.([nm '_char']) = uieditfield(...
                                    'Parent',eval(idx{i}),...
                                    'Tag',[nm '_char'],...
                                    'HorizontalAlignment','center',...
                                    'ValueChangedFcn',@me.readPanel,...
                                    'Value',val,...
                                    'Tooltip', desc, ...
                                    'BackgroundColor',bgcoloredit);
                                if ~isempty(regexpi(nm,disableList,'once')) 
                                    handles.([nm '_char']).Enable = false; 
                                end
                            end
                        elseif isnumeric(val)
                            val = num2str(val);
                            val = regexprep(val,'\s+','  ');
                            handles.([nm '_num']) = uieditfield('text',...
                                'Parent',eval(idx{i}),...
                                'Tag',[nm '_num'],...
                                'HorizontalAlignment','center',...
                                'Value',val,...
                                'Tooltip', desc, ...
                                'ValueChangedFcn',@me.readPanel,...
                                'FontName',me.monoFont,...
                                'BackgroundColor',bgcoloredit);
                            if ~isempty(regexpi(nm,disableList,'once')) 
                                handles.([nm '_num']).Enable = false; 
                            end
                        else
                            uilabel('Parent',eval(idx{i}),'Text','','BackgroundColor',bgcolor,'Enable','off');
                        end
                        if isprop(me,[nm 'List'])
                            if strcmp(me.([nm 'List']),'filerequestor')
                                handles.([nm '_button']) = uibutton(...
                                'Parent',eval(idx{i}),...
                                'HorizontalAlignment','left',...
                                'Text','Select file...',...
                                'FontName',me.sansFont,...
                                'Tag',[nm '_button'],...
                                'Tooltip', desc, ...
                                'Icon', [me.paths.root '/ui/images/edit.svg'],...
                                'ButtonPushedFcn', @me.selectFilePanel,...
                                'FontSize', 8);
                            else
                                uilabel(...
                                'Parent',eval(idx{i}),...
                                'HorizontalAlignment','left',...
                                'Text',nm,...
                                'FontName',me.sansFont,...
                                'FontSize', fsmall,...
                                'BackgroundColor',bgcolor);
                            end
                        else
                            uilabel(...
                            'Parent',eval(idx{i}),...
                            'HorizontalAlignment','left',...
                            'Text',nm,...
                            'FontName',me.sansFont,...
                            'FontSize', fsmall,...
                            'BackgroundColor',bgcolor);
                        end
                    else
                        uilabel('Parent',eval(idx{i}),'Text','','BackgroundColor',bgcolor,'Enable','off');
                    end
                end
            end
            for j = 1:lp2
                nm = pr2{j};
                val = me.(nm);
                % this gets descriptions
                ix = find(pl == nm);
                if ~isempty(ix)
                    desc = dl{ix};
                else
                    desc = nm;
                end
                if j <= length(pr2)
                    handles.([nm '_bool']) = uicheckbox(...
                        'Parent',eval(idx{end}),...
                        'Tag',[nm '_bool'],...
                        'Text',nm,...
                        'Tooltip', desc, ...
                        'FontName',me.sansFont,...
                        'FontSize', fsmall,...
                        'ValueChangedFcn',@me.readPanel,...
                        'Value',val);
                end
            end
            %handles.readButton = uibutton(...
            %   'Parent',eval(idx{end}),...
            %   'Tag','readButton',...%'Callback',@me.readPanel,...
            %   'Text','Update');
            me.handles = handles;
            me.isGUI = true;
        end
        
        % ===================================================================
        %> @brief read values from a GUI properties panel for this object
        %>
        % ===================================================================
        function selectFilePanel(me,varargin)
            if nargin > 0
                hin = varargin{1};
                if ishandle(hin)
                    [f,p] = uigetfile('*.*','Select File:');
                    re = regexp(get(hin,'Tag'),'(.+)_button','tokens','once');
                    hout = me.handles.([re{1} '_char']);
                    if ishandle(hout)
                        set(hout,'Value', [p f]);
                        me.readPanel(hout);
                    end
                end
            end
        end
        
        % ===================================================================
        %> @brief read values from a GUI properties panel for this object
        %>
        % ===================================================================
        function readPanel(me,varargin)
            if isempty(me.handles) || ~(isfield(me.handles, 'root') && isa(me.handles.root,'matlab.ui.container.Panel'))
                return
            end
            if isempty(varargin) || isempty(varargin{1}); return; end
            source = varargin{1};
            tag = source.Tag;
            if isempty(tag); return; end
            tagName = regexprep(tag,'_.+$','');
            tagType = regexprep(tag,'^.+_','');
            
            pList = findAttributes(me,'SetAccess','public'); %our public properties
            
            if ~any(contains(pList,tagName)); return; end
            
            switch tagType
                case 'list'
                    me.(tagName) = source.Value;
                case 'bool' 
                    me.(tagName) = logical(source.Value);
                case 'num'
                    me.(tagName) = str2num(source.Value);
                case 'char'
                    me.(tagName) = source.Value;
                otherwise
                    warning('Can''t set property');
            end
            
            if strcmpi(tagName,'name')
                me.handles.fullName_char.Value = me.fullName;
                me.handles.root.Title = me.fullName;
            end
            
            if strcmpi(tagName,'alpha')
                me.handles.colour_num.Value = num2str(me.colour, '%g ');
                if isprop(me,'colour2') 
                    me.handles.colour2_num.Value = num2str(me.colour2, '%g ');
                end
                if isprop(me,'baseColour') 
                    me.handles.baseColour_num.Value = num2str(me.baseColour, '%g ');
                end
            end
 
            if strcmpi(tagName,'alpha2')
                if isprop(me,'colour2');me.handles.colour2_num.Value = num2str(me.colour2, '%g ');end
            end
            
            if strcmpi(tagName,'colour')
                me.handles.alpha_num.Value = num2str(me.alpha, '%g ');
                if isprop(me,'correctBaseColour') && me.correctBaseColour
                    me.handles.baseColour_num.Value = num2str(me.baseColour, '%g ');
                end
            end
 
            if strcmpi(tagName,'colour2')
                if isprop(me,'alpha2');me.handles.alpha2_num.Value = num2str(me.alpha2, '%g ');end
                if isprop(me,'correctBaseColour') && me.correctBaseColour
                    me.handles.baseColour_num.Value = num2str(me.baseColour, '%g ');
                end
            end
 
            if strcmpi(tagName,'filePath') && isa(me,'imageStimulus')
                me.checkfilePath();
            end
            
            notify(me,'readPanelUpdate');
        end
            
        % ===================================================================
        %> @brief show GUI properties panel for this object
        %>
        % ===================================================================
        function showPanel(me)
            if isempty(me.handles)
                return
            end
            set(me.handles.root,'Enable','on');
            set(me.handles.root,'Visible','on');
        end
        
        % ===================================================================
        %> @brief hide GUI properties panel for this object
        %>
        % ===================================================================
        function hidePanel(me)
            if isempty(me.handles)
                return
            end
            set(me.handles.root,'Enable','off');
            set(me.handles.root,'Visible','off');
        end
        
        % ===================================================================
        %> @brief close GUI panel for this object
        %>
        % ===================================================================
        function closePanel(me,varargin)
            if isfield(me.handles,'root') && isgraphics(me.handles.root)
                delete(me.handles.root);
            end
            if isfield(me.handles,'parent') && isgraphics(me.handles.parent,'figure')
                delete(me.handles.parent)
            end
            me.cleanHandles();
            me.isGUI = false;
        end
        
        % ===================================================================
        %> @fn cleanHandles
        %> @brief clean any handles
        %>
        %> @param
        %> @return
        % ===================================================================
        function cleanHandles(me, ~)
            if isprop(me,'handles')
                me.handles = [];
            end
            if isprop(me,'h')
                me.h = [];
            end
            fprintf('===>>> baseStimulus: Ran clean handles!!!\n')
            me.isGUI = false;
        end
 
        % ===================================================================
        %> @fn getP
        %> @brief gets a property copy or original property
        %>
        %> When stimuli are run, their properties are copied, so e.g. angle
        %> is copied to angleOut and this is used during the task. This
        %> method checks if the copy is available and returns that, otherwise
        %> return the original.
        %>
        %> @param name of property
        %> @param range of property to return
        %> @return value of property
        % ===================================================================
        function [value, nameOut] = getP(me, name, range)
            arguments(Input)
                me
                name char
                range = []
            end
            arguments(Output)
                value
                nameOut char
            end
            value = []; nameOut = [];
            if isprop(me, [name 'Out']) && ~isempty(me.([name 'Out']))
                nameOut = [name 'Out'];
                value = me.(nameOut);
                if ~isempty(range); value = value(range); end
            elseif isprop(me, name)
                value = me.(name);
                nameOut = name;
                if ~isempty(range); value = value(range); end
            elseif me.verbose
                fprintf('!!! Property %s doesn''t exist...\n',name)
            end
        end
 
        % ===================================================================
        %> @fn setP
        %> @brief sets a property copy or original property
        %>
        %> When stimuli are run, their properties are copied, so e.g. angle
        %> is copied to angleOut and this is used during the task. This
        %> method checks if the copy is available and returns that, otherwise
        %> return the original.
        %>
        %> @param name of property
        %> @param range of property to return
        %> @return value of property
        % ===================================================================
        function setP(me, name, value)
            arguments(Input)
                me
                name char
                value
            end
            if isprop(me,[name 'Out'])
                me.([name 'Out']) = value;
            elseif isprop(me, name)
                me.(name) = value;
            elseif me.verbose
                fprintf('!!! Property %s doesn''t exist...\n',name);
            end
        end
 
        % ===================================================================
        %> @fn updateXY
        %> @brief Update only position info, faster and doesn't reset image etc.
        %>
        %> @param x X position
        %> @param y Y position
        %> @param useDegrees where the input is in degrees (true) or pixels (false)
        % ===================================================================
        function updateXY(me,x,y,useDegrees)
            arguments(Input)
                me
                x double = NaN
                y double = NaN
                useDegrees logical = false
            end
            if ~me.isSetup; warning("updateXY: Need to setup stimulus first!"); return; end
            if isnan(x) || isnan(y); return; end
            if ~isempty(x) && ~isscalar(x); x = x(1); end; if ~isempty(y) && ~isscalar(y); y = y(1); end
            if useDegrees
                if ~isempty(x); me.xFinal = me.sM.toPixels(x, 'x'); me.xFinalD = x; me.xPositionOut = x; end
                if ~isempty(y); me.yFinal = me.sM.toPixels(y, 'y'); me.yFinalD = y; me.yPositionOut = y; end
            else
                if ~isempty(x); me.xFinal = x; me.xFinalD = me.sM.toDegrees(x, 'x'); me.xPositionOut = me.xFinalD; end
                if ~isempty(y); me.yFinal = y; me.yFinalD = me.sM.toDegrees(y, 'y'); me.yPositionOut = me.yFinalD; end
            end
            if me.isRect && length(me.mvRect) == 4
                me.mvRect=CenterRectOnPointd(me.mvRect, me.xFinal, me.yFinal);
            end
        end
 
    end %---END PUBLIC METHODS---%
 
    %=======================================================================
    methods ( Static ) %----------STATIC METHODS
    %=======================================================================
 
        % ===================================================================
        %> @brief linear interpolation between two colour arrays based on a contrast
        %>
        % ===================================================================
        function out = mixColour(c1, c2, contrast)
            arguments(Input)
                c1 (1,3) double 
                c2 (1,3) double
                contrast (1,1) double {mustBeNonnegative, mustBeLessThanOrEqual(contrast,1)}
            end
            out = c1(1:3) * (1 - contrast) + c2(1:3) * contrast;
        end
 
        % ===================================================================
        %> @brief degrees2radians
        %>
        % ===================================================================
        function r = d2r(degrees)
        % d2r(degrees)
            r=degrees*(pi/180);
        end
 
        % ===================================================================
        %> @brief radians2degrees
        %>
        % ===================================================================
        function degrees = r2d(r)
        % r2d(radians)
            degrees=r*(180/pi);
        end
 
        % ===================================================================
        %> @brief findDistance in X and Y coordinates
        %>
        % ===================================================================
        function distance = findDistance(x1, y1, x2, y2)
        % findDistance(x1, y1, x2, y2)
            distance=sqrt((x2 - x1)^2 + (y2 - y1)^2);
        end
 
        % ===================================================================
        %> @brief updatePosition returns dX and dY given an angle and delta
        %>
        % ===================================================================
        function [dX, dY] = updatePosition(delta, angle)
        % updatePosition(delta, angle)
            dX = delta .* cos(baseStimulus.d2r(angle));
            if length(dX)== 1 && abs(dX) < 1e-3; dX = 0; end
            dY = delta .* sin(baseStimulus.d2r(angle));
            if length(dY)==1 && abs(dY) < 1e-3; dY = 0; end
        end
 
    end%---END STATIC METHODS---%
 
    %=======================================================================
    methods ( Access = protected ) %-------PRIVATE (protected) METHODS-----%
    %=======================================================================
 
        % ===================================================================
        %> @fn addRuntimeProperties
        %> @brief These are transient properties that specify actions during runtime
        % ===================================================================
        function addRuntimeProperties(me)
            if isempty(me.findprop('doFlash')); me.addprop('doFlash');end
            if isempty(me.findprop('doDots')); me.addprop('doDots');end
            if isempty(me.findprop('doMotion')); me.addprop('doMotion');end
            if isempty(me.findprop('doDrift')); me.addprop('doDrift');end
            if isempty(me.findprop('doAnimator')); me.addprop('doAnimator');end
            updateRuntimeProperties(me);
        end
 
        % ===================================================================
        %> @fn updateRuntimeProperties
        %> @brief Update transient properties that specify actions during runtime
        % ===================================================================
        function updateRuntimeProperties(me)
            me.doDots       = false;
            me.doMotion     = false;
            me.doDrift      = false;
            me.doFlash      = false;
            me.doAnimator   = false;
 
            if isprop(me, 'tf')
                [v,n] = getP(me,'tf');
                if ~isempty(n) && v > 0; me.doDrift = true; end
            end
 
            if isprop(me, 'speed')
                [v,n] = getP(me,'speed');
                if ~isempty(n) && v > 0; me.doMotion = true; end
            end
 
            if strcmpi(me.family,'dots'); me.doDots = true; end
 
            if strcmpi(me.type,'flash'); me.doFlash = true; end
 
            if ~isempty(me.animator) && isa(me.animator,'animationManager')
                me.doAnimator = true;
            end
        end
 
        % ===================================================================
        %> @brief compute xFinal and yFinal (in pixels) taking startPosition,
        %> xPosition, yPosition and direction/angle into account
        %>
        % ===================================================================
        function computePosition(me)
            if me.mouseOverride && me.mouseValid
                me.xFinal = me.mouseX; me.yFinal = me.mouseY;
            else
                sP = getP(me, 'startPosition');
                if isprop(me,'direction')
                    [dx, dy]=pol2cart(me.d2r(getP(me,'direction')), sP);
                else
                    [dx, dy]=pol2cart(me.d2r(getP(me,'angle')), sP);
                end
                me.xFinal = me.xPositionOut + (dx * me.ppd) + me.sM.xCenter;
                me.yFinal = me.yPositionOut + (dy * me.ppd) + me.sM.yCenter;
                me.xFinalD = me.sM.toDegrees(me.xFinal,'x');
                me.yFinalD = me.sM.toDegrees(me.yFinal,'y');
                if me.verbose; fprintf('---> computePosition: %s X = %gpx | %gpx | %gdeg <> Y = %gpx | %gpx | %gdeg\n',me.fullName, me.xFinal, me.xPositionOut, dx, me.yFinal, me.yPositionOut, dy); end
            end
            setAnimationDelta(me);
        end
 
        % ===================================================================
        %> @fn setAnimationDelta
        %> setAnimationDelta for performance better not to use get methods for dX dY and
        %> delta during animation, so we have to cache these properties to private copies so that
        %> when we call the animate method, it uses the cached versions not the
        %> public versions. This method simply copies the properties to their cached
        %> equivalents.
        % ===================================================================
        function setAnimationDelta(me)
            me.delta_ = me.delta;
            me.dX_ = me.dX;
            me.dY_ = me.dY;
        end
 
        % ===================================================================
        %> @fn setRect
        %> setRect makes the PsychRect based on the texture and screen
        %> values, you should call computePosition() first to get xFinal and
        %> yFinal.
        % ===================================================================
        function setRect(me)
            if isempty(me.texture); me.mvRect = [0 0 100 100]; return; end
            if isprop(me,'scale')
                me.dstRect = ScaleRect(Screen('Rect',me.texture(1)), me.scale, me.scale);
            else
                me.dstRect=Screen('Rect',me.texture(1));
            end
            if me.mouseOverride && me.mouseValid
                me.dstRect = CenterRectOnPointd(me.dstRect, me.mouseX, me.mouseY);
            else
                me.dstRect=CenterRectOnPointd(me.dstRect, me.xFinal, me.yFinal);
            end
            me.mvRect=me.dstRect;
            if me.isRect; me.szPx=RectWidth(me.mvRect); end
            if me.verbose
                fprintf('---> %s setRect = [%.2f %.2f %.2f %.2f] width = %.2f height = %.2f\n',...
                    me.fullName, me.dstRect(1), me.dstRect(2),me.dstRect(3),me.dstRect(4),...
                    RectWidth(me.dstRect),RectHeight(me.dstRect));
            end
        end
 
        % ===================================================================
        %> @fn toStructure
        %> @brief Converts properties to a structure
        %>
        %> @param me this instance object
        %> @param tmp is whether to use the temporary or permanent properties
        %> @return out the structure
        % ===================================================================
        function out=toStructure(me,tmp)
            if ~exist('tmp','var')
                tmp = 0; %copy real properties, not temporary ones
            end
            fn = fieldnames(me);
            for j=1:length(fn)
                if tmp == 0
                    out.(fn{j}) = me.(fn{j});
                else
                    out.(fn{j}) = me.([fn{j} 'Out']);
                end
            end
        end
 
        % ===================================================================
        %> @fn removeTmpProperties
        %> @brief Finds and removes dynamic properties
        %>
        %> @param me
        %> @return
        % ===================================================================
        function removeTmpProperties(me)
            allprops = properties(me);
            for i=1:numel(allprops)
                m = findprop(me, allprops{i});
                if isa(m,'meta.DynamicProperty')
                    delete(m)
                end
            end
            me.xFinal   = [];
            me.xFinalD  = [];
            me.yFinal   = [];
            me.yFinalD  = [];
            me.szPx     = [];
            me.szD      = [];
            me.isSetup  = false;
        end
 
        % ===================================================================
        %> @fn Delete method
        %>
        %> @param me
        %> @return
        % ===================================================================
        function delete(me)
            if ~isempty(me.texture)
                for i = 1:length(me.texture)
                    if Screen(me.texture, 'WindowKind')~=0 ;try Screen('Close',me.texture); end; end %#ok<*TRYNC>
                end
            end
            if isprop(me,'buffertex') && ~isempty(me.buffertex)
                if Screen(me.buffertex, 'WindowKind')~=0 ; try Screen('Close',me.buffertex); end; end
            end
            
            if me.verbose; fprintf('--->>> Delete: %s\n',me.fullName); end
        end
        
    end%---END PRIVATE METHODS---%
end

Constructor & Destructor Documentation

baseStimulus()

function baseStimulus::baseStimulus

(

in

varargin

)

Class constructor.

Parameters

varargin

are passed as a structure / cell of properties which is parsed.

Returns

instance of class.

Member Function Documentation

addRuntimeProperties()

baseStimulus::addRuntimeProperties ( in  me )

protected

These are transient properties that specify actions during runtime.

alpha()

function set baseStimulus::alpha	(	in	me,
		in	value
	)

alpha set method

animate()

virtual baseStimulus::animate ( in  runObject )

virtual

animate the stimulus, normally called after a draw

Reimplemented in pupilCoreStimulus, aprilTagStimulus, barStimulus, checkerboardStimulus, colourGratingStimulus, discStimulus, dotlineStimulus, dotsStimulus, exampleStimulus, fixationCrossStimulus, gaborStimulus, gratingStimulus, imageStimulus, logGaborStimulus, movieStimulus, ndotsStimulus, polarBoardStimulus, polarGratingStimulus, revcorStimulus, spotStimulus, apparentMotionStimulus, and targetInducerStimulus.

cleanHandles()

baseStimulus::cleanHandles	(	in	me,
		in	ignoredArg
	)

clean any handles

Parameters

return

closePanel()

function baseStimulus::closePanel	(	in	me,
		in	varargin
	)

close GUI panel for this object

colour()

function set baseStimulus::colour	(	in	me,
		in	value
	)

colour set method Allow 1 (R=G=B) 3 (RGB) or 4 (RGBA) value colour

computePosition()

function baseStimulus::computePosition ( in  me )

protected

compute xFinal and yFinal (in pixels) taking startPosition, xPosition, yPosition and direction/angle into account

d2r()

static function baseStimulus::d2r ( in  degrees )

static

degrees2radians

delete()

function baseStimulus::delete ( in  me )

protected

delta()

function get baseStimulus::delta

(

in

me

)

delta Get method delta is the normalised number of pixels per frame to move a stimulus

draw()

virtual baseStimulus::draw ( in  runObject )

virtual

draw to the screen buffer, ready for flip()

Reimplemented in pupilCoreStimulus, barStimulus, colourGratingStimulus, discStimulus, dotsStimulus, exampleStimulus, fixationCrossStimulus, gaborStimulus, gratingStimulus, logGaborStimulus, movieStimulus, ndotsStimulus, polarBoardStimulus, polarGratingStimulus, revcorStimulus, spotStimulus, apparentMotionStimulus, and targetInducerStimulus.

dX()

function get baseStimulus::dX

(

in

me

)

dX Get method X position increment for a given delta and angle

dY()

function get baseStimulus::dY

(

in

me

)

dY Get method Y position increment for a given delta and angle

findDistance()

static function baseStimulus::findDistance ( in  x1, in  y1, in  x2, in  y2  )

static

findDistance in X and Y coordinates

getMousePosition()

function baseStimulus::getMousePosition

(

in

me

)

get mouse position we make sure this is only called once per animation tick to improve performance and ensure all stimuli that are following mouse position have consistent X and Y per frame update This sets mouseX and mouseY and mouseValid if mouse is within PTB screen (useful for mouse override positioning for stimuli)

getP()

baseStimulus::getP	(	in	me,
		in	name,
		in	range
	)

gets a property copy or original property

When stimuli are run, their properties are copied, so e.g. angle is copied to angleOut and this is used during the task. This method checks if the copy is available and returns that, otherwise return the original.

Parameters

name	of property
range	of property to return

Returns

value of property

hide()

function baseStimulus::hide

(

in

me

)

Method to set isVisible=false.

hidePanel()

function baseStimulus::hidePanel

(

in

me

)

hide GUI properties panel for this object

makePanel()

function baseStimulus::makePanel	(	in	me,
		in	parent
	)

make a GUI properties panel for this object

mixColour()

static function baseStimulus::mixColour ( in  c1, in  c2, in  contrast  )

static

linear interpolation between two colour arrays based on a contrast

r2d()

static function baseStimulus::r2d ( in  r )

static

radians2degrees

readPanel()

function baseStimulus::readPanel	(	in	me,
		in	varargin
	)

read values from a GUI properties panel for this object

removeTmpProperties()

baseStimulus::removeTmpProperties ( in  me )

protected

Finds and removes dynamic properties.

Parameters

me

Returns

reset()

virtual baseStimulus::reset ( in  runObject )

virtual

reset back to pre-setup state (removes the transient cache properties, resets the various timers etc.)

Reimplemented in pupilCoreStimulus, aprilTagStimulus, barStimulus, checkerboardStimulus, colourGratingStimulus, discStimulus, dotlineStimulus, dotsStimulus, exampleStimulus, fixationCrossStimulus, gaborStimulus, gratingStimulus, imageStimulus, logGaborStimulus, movieStimulus, ndotsStimulus, polarBoardStimulus, polarGratingStimulus, revcorStimulus, spotStimulus, apparentMotionStimulus, and targetInducerStimulus.

resetTicks()

function baseStimulus::resetTicks

(

in

me

)

reset the various tick counters for our stimulus

run()

baseStimulus::run	(	in	me,
		in	benchmark,
		in	runtime,
		in	s,
		in	forceScreen,
		in	showVBL
	)

Run stimulus in a window to preview it.

Parameters

benchmark	true|false [optional, default = false]
runtime	time to show stimulus [optional, default = 2]
screenManager	to use [optional]
forceScreen	for a particulr monitor/screen to use
showVBL	show a plot of the VBL times

selectFilePanel()

function baseStimulus::selectFilePanel	(	in	me,
		in	varargin
	)

read values from a GUI properties panel for this object

setAnimationDelta()

baseStimulus::setAnimationDelta ( in  me )

protected

setAnimationDelta for performance better not to use get methods for dX dY and delta during animation, so we have to cache these properties to private copies so that when we call the animate method, it uses the cached versions not the public versions. This method simply copies the properties to their cached equivalents.

setDelayTime()

function baseStimulus::setDelayTime	(	in	me,
		in	time
	)

set delayTime

setOffTime()

function baseStimulus::setOffTime	(	in	me,
		in	time
	)

set offTime

setP()

baseStimulus::setP	(	in	me,
		in	name,
		in	value
	)

sets a property copy or original property

When stimuli are run, their properties are copied, so e.g. angle is copied to angleOut and this is used during the task. This method checks if the copy is available and returns that, otherwise return the original.

Parameters

name	of property
range	of property to return

Returns

value of property

setRect()

baseStimulus::setRect ( in  me )

protected

setRect makes the PsychRect based on the texture and screen values, you should call computePosition() first to get xFinal and yFinal.

setup()

virtual baseStimulus::setup ( in  runObject )

virtual

ALL Children must implement these 5 methods!

initialise the stimulus with the PTB screenManager

Reimplemented in plaidStimulus.

show()

function baseStimulus::show

(

in

me

)

Method to set isVisible=true.

showPanel()

function baseStimulus::showPanel

(

in

me

)

show GUI properties panel for this object

toStructure()

baseStimulus::toStructure ( in  me, in  tmp  )

protected

Converts properties to a structure.

Parameters

me	this instance object
tmp	is whether to use the temporary or permanent properties

Returns

out the structure

update()

virtual baseStimulus::update ( in  runObject )

virtual

update the stimulus, normally called between trials if any variables have changed

Reimplemented in pupilCoreStimulus, aprilTagStimulus, barStimulus, checkerboardStimulus, colourGratingStimulus, discStimulus, dotlineStimulus, dotsStimulus, exampleStimulus, fixationCrossStimulus, gaborStimulus, gratingStimulus, imageStimulus, logGaborStimulus, movieStimulus, ndotsStimulus, polarBoardStimulus, polarGratingStimulus, revcorStimulus, spotStimulus, apparentMotionStimulus, and targetInducerStimulus.

updatePosition()

static function baseStimulus::updatePosition ( in  delta, in  angle  )

static

updatePosition returns dX and dY given an angle and delta

updateRuntimeProperties()

baseStimulus::updateRuntimeProperties ( in  me )

protected

Update transient properties that specify actions during runtime.

updateXY()

baseStimulus::updateXY	(	in	me,
		in	x,
		in	y,
		in	useDegrees
	)

Update only position info, faster and doesn't reset image etc.

Parameters

x	X position
y	Y position
useDegrees	where the input is in degrees (true) or pixels (false)

Member Data Documentation

alpha

Property baseStimulus::alpha

Alpha (opacity) [0-1], this gets combined with the RGB colour.

angle

Property baseStimulus::angle

angle in degrees (0 - 360)

animator

Property baseStimulus::animator

protected

animation manager

colour

Property baseStimulus::colour

Colour as a 0-1 range RGB or RGBA vector (if you pass A it also modifies alpha and visa-versa

delayTicks

Property baseStimulus::delayTicks

protected

delay ticks to wait until display

delayTime

Property baseStimulus::delayTime

delay time to display relative to stimulus onset, can set upper and lower range for random interval. This allows for a group of stimuli some to be delayed relative to others for a global stimulus onset time.

delta

Property baseStimulus::delta

What our per-frame motion delta is.

delta_

Property baseStimulus::delta_

protected

delta cache

drawTick

Property baseStimulus::drawTick

draw tick only updates when a draw is actually performed, resets on each update

dstRect

Property baseStimulus::dstRect

protected

initial screen rectangle position [LEFT TOP RIGHT BOTTOM]

dX

Property baseStimulus::dX

X update which is computed from our speed and angle.

dX_

Property baseStimulus::dX_

protected

dX cache

dY

Property baseStimulus::dY

X update which is computed from our speed and angle.

dY_

Property baseStimulus::dY_

protected

dY cache

family

Property baseStimulus::family

protected

the stimulus family (grating, dots etc.)

handles

Property baseStimulus::handles

protected

handles for the GUI

ignorePropertiesBase

Property baseStimulus::ignorePropertiesBase

protected

Which properties to ignore cloning when making transient copies in setup.

ignorePropertiesUIBase

Property baseStimulus::ignorePropertiesUIBase

protected

Which properties to not draw in the UI panel.

inSetup

Property baseStimulus::inSetup

protected

are we setting up?

isGUI

Property baseStimulus::isGUI

protected

is panel constructed?

isInSetColour

Property baseStimulus::isInSetColour

protected

deal with interaction of colour and alpha

isRect

Property baseStimulus::isRect

is PTB stimulus type position defined via rect [true] or point [false] mvRect is the property used for rect based stimuli xFinal and yFinal are used for point-based positioninng

isSetup

Property baseStimulus::isSetup

protected

isVisible

Property baseStimulus::isVisible

true or false, whether to draw() this object

mouseOverride

Property baseStimulus::mouseOverride

override X and Y position with mouse input? Useful for RF mapping

mouseValid

Property baseStimulus::mouseValid

protected

is mouse position within screen co-ordinates?

mouseX

Property baseStimulus::mouseX

protected

mouse X position

mouseY

Property baseStimulus::mouseY

protected

mouse Y position

mvRect

Property baseStimulus::mvRect

current screen rectangle position [LEFT TOP RIGHT BOTTOM] in pixels

offTicks

Property baseStimulus::offTicks

protected

ticks before stimulus turns off

offTime

Property baseStimulus::offTime

time to turn stimulus off, relative to stimulus onset

ppd

Property baseStimulus::ppd

pixels per degree (normally inhereted from screenManager)

screenVals

Property baseStimulus::screenVals

protected

screen settings generated by sM on setup

setLoop

Property baseStimulus::setLoop

protected

showOnTracker

Property baseStimulus::showOnTracker

show the position on the Eyetracker display?

size

Property baseStimulus::size

Size in visual degrees (°), can also be used to scale images/movies or define width+height of a bar etc.

sM

Property baseStimulus::sM

protected

our screen manager

speed

Property baseStimulus::speed

speed in °/s - this mostly afffects linear motion, but with an animationManager is also used to define initial motion value

startPosition

Property baseStimulus::startPosition

For moving stimuli do we start "before" our initial XY position? This allows you to center a stimulus at a screen location, but then drift it across that location, so if xyPosition is 0,0 and startPosition is -2 then the stimulus will start at -2 drifing towards 0.

szD

Property baseStimulus::szD

computed size in °

szIsPx

Property baseStimulus::szIsPx

whether sizeOut is degrees or pixels, see .szPx .szD for copies in pixels and degrees respectively

szPx

Property baseStimulus::szPx

computed size in pixels

texture

Property baseStimulus::texture

protected

Our texture pointer for texture-based stimuli.

tick

Property baseStimulus::tick

tick updates +1 on each call of draw (even if delay or off is true and no stimulus is drawn, resets on each update

type

Property baseStimulus::type

stimulus type

verbose

Property baseStimulus::verbose

Do we log extra details to the command-line?

xFinal

Property baseStimulus::xFinal

computed X position in pixel coordinates PTB uses: 0,0 top-left see computePosition(); a copy in degrees is made in xFinalD

xFinalD

Property baseStimulus::xFinalD

X and Y position in °

xPosition

Property baseStimulus::xPosition

initial X Position ± visual degrees (°) relative to screen center (0,0) in opticka +X is from left-to-right

yFinal

Property baseStimulus::yFinal

computed Y position in pixel coordinates PTB uses: 0,0 top-left see computePosition(); ; a copy in degrees is made in yFinalD

yFinalD

Property baseStimulus::yFinalD

yPosition

Property baseStimulus::yPosition

initial Y Position ± visual degrees (°) relative to screen center (0,0) in opticka +Y is from top-to-bottom

---

The documentation for this class was generated from the following file:

• stimuli/baseStimulus.m