expyriment.stimuli.Ellipse¶

class expyriment.stimuli.Ellipse(radii, colour=None, line_width=None, position=None, anti_aliasing=None)¶

A class implementing a basic 2D ellipse.

__init__(radii, colour=None, line_width=None, position=None, anti_aliasing=None)¶

Create an ellipse.

Parameters:	radii : (int, int) major and minor radii of the ellipse colour : (int, int, int), optional colour of the ellipse line_width : int, optional line width in pixels; 0 will result in a filled ellipse (as does a value < 0 or >= min(size)) position : (int, int), optional position of the stimulus anti_aliasing : int, optional anti aliasing parameter (good anti_aliasing with 10)

absolute_position¶

Getter for absolute_position.

Notes

The absolute position differs for instance from the (relative) position, if the stimulus is plotted ontop of another stimulus, which has not the position (0,0).

add_noise(grain_size, percentage, colour)¶

Add visual noise on top of the stimulus.

This function might take very long for large stimuli.

Parameters:	grain_size : int size of the grains for the noise percentage : int percentage of covered area colour : (int, int, int) colour (RGB) of the noise
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

anti_aliasing¶

Getter for anti_aliasing.

blur(level)¶

Blur the stimulus.

This blurs the stimulus, by scaling it down and up by the factor of ‘level’.

Parameters:	level : int level of bluring
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

clear_surface()¶

Clear the stimulus surface.

Surfaces are automatically created after any surface operation (presenting, plotting, rotating, scaling, flipping etc.) and preloading. If the stimulus was preloaded, this method unloads the stimulus. This method is functionally equivalent with unload(keep_surface=False).

Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

colour¶

Getter for colour.

compress()¶

“Compress the stimulus.

This will create a temporary file on the disk where the surface of the stimululs is written to. The surface will now be read from the disk to free memory. Compressed stimuli cannot do surface operations! Preloading comressed stimuli is possible and highly recommended. Depending on the size of the stimulus, this method may take some time to compute!

Returns:	time : int the time it took to execute this method

copy()¶

Deep copy of the visual stimulus.

Returns:	copy : deep copy of self

Notes

Depending on the size of the stimulus, this method may take some time to compute!

decompress()¶

Decompress the stimulus.

This will decompress the stimulus. The surface will now be read from memory again. Depending on the size of the stimulus, this method may take some time to compute!

Returns:	time : int the time it took to execute this method

distance(other)¶

Surface center distance.

This method computes the distance between the surface center of this and another visual stimulus.

Parameters:	other : stimulus the other visual stimulus
Returns:	dist : float distance between surface centers

flip(booleans)¶

Flip the stimulus.

This is a surface operation. After this, a surface will be present!

Parameters:	booleans : (bool, bool) booleans to flip or not
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

get_pixel_array()¶

Returns a PixelArray representation of surface of the stimulus

Returns:	pixel_array: Pygame.PixelArray a copy of the PixelArray is returned

Notes

see also set_surface

get_surface_copy()¶

Returns a copy of the Pygame surface of the stimulus

Returns:	surface: Pygame.surface

Notes

see also set_surface

has_surface¶

Getter for has_surface.

id¶

Getter for id.

inside_stimulus(stimulus, mode='visible')¶

Check if stimulus is inside another stimulus.

Parameters:	stimulus : expyriment stimulus the other stimulus mode : mode (str), optional “visible”: based on non-transparent pixels or “rectangle”: based on pixels in pygame surface (default = visible”)
Returns:	out : bool

Notes

Depending on the size of the stimulus, this method may take some time to compute!

is_compressed¶

Getter for is_compressed.

is_preloaded¶

Getter for is_preloaded.

line_width¶

Getter for line_width.

logging¶

Getter for logging.

move(offset)¶

Moves the stimulus in 2D space.

When using OpenGL, this can take longer then 1ms!

Parameters:	offset : tuple (x,y) translation along x and y axis
Returns:	time : int the time it took to execute this method

Notes

see also reposition

overlapping_with_position(position, mode='visible', use_absolute_position=True)¶

Check if stimulus is overlapping with a certain position.

Parameters:	position : (int, int) position to check for overlapping mode : mode (str), optional “visible”: based on non-transparent pixels or “rectangle”: based on pixels in pygame surface (default = visible”) use_absolute_position : bool, optional use absolute_position of stimulus (default) instead of position
Returns:	overlapping : bool

Notes

Depending on the size of the stimulus, this method may take some time to compute!

CAUTION: Please note that if a stimulus is plotted on another smaller stimulus, such that it is not fully visible on screen, this method will still check overlapping of the full stimulus! Due to a current bug in Pygame, we can right now not change this.

overlapping_with_stimulus(stimulus, mode='visible', use_absolute_position=True)¶

Check if stimulus is overlapping with another stimulus.

Parameters:	stimulus : expyriment stimulus the other stimulus mode : mode (str), optional “visible”: based on non-transparent pixels or “surface”: based on pixels in pygame surface (default = visible”) use_absolute_position : bool, optional use absolute_position of stimuli (default) instead of position
Returns:	overlapping : bool are stimuli overlapping or not overlap : (int, int) the overlap (x, y) in pixels. If mode is ‘surface’, the argument will always be None.

Notes

Depending on the size of the stimulus, this method may take some time to compute!

CAUTION: Please note that if a stimulus is plotted on another smaller stimulus, such that it is not fully visible on screen, this method will still check overlapping of the full stimulus! Due to a current bug in Pygame, we can right now not change this.

picture()¶

Return the stimulus as Picture stimulus.

This will create a temporary file on the hard disk where the image is saved to.

Notes

Depending on the size of the stimulus, this method may take some time to compute!

plot(stimulus)¶

Plot the stimulus on the surface of another stimulus.

Use this to plot more than one stimulus and to present them at the same time afterwards by presenting the stimulus on which they were plotted on.

Parameters:	stimulus : expyriment stimulus stimulus to whose surface should be plotted
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

position¶

Getter for position.

preload(inhibit_ogl_compress=False)¶

Preload the stimulus to memory.

This will prepare the stimulus for a fast presentation. In OpenGL mode this method creates an OpenGL texture based on the surface of the stimulus. When OpenGL is switched off, this method will create a surface if it doesn’t exists yet. If stimuli are not preloaded manually, this will happen automatically during presentation. However, stimulus presentation will take some time then!

Always preload your stimuli when a timing acurate presentation is needed!

Parameters:	inhibit_ogl_compress : bool, optional inhibits OpenGL stimuli to be automatically compressed (default=False)
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

present(clear=True, update=True, log_event_tag=None)¶

Present the stimulus on the screen.

This clears and updates the screen automatically. When not preloaded, depending on the size of the stimulus, this method can take some time to compute!

Parameters:	clear : bool, optional if True the screen will be cleared automatically (default = True) update : bool, optional if False the screen will be not be updated automatically (default = True) log_event_tag : numeral or string, optional if log_event_tag is defined and if logging is switched on for this stimulus (default), a summary of the inter-event-intervalls are appended at the end of the event file
Returns:	time : int the time it took to execute this method

radii¶

Getter for radii.

reposition(new_position)¶

Move stimulus to a new position.

When using OpenGL, this can take longer then 1ms!

Parameters:	new_position : tuple (x,y) translation along x and y axis
Returns:	time : int the time it took to execute this method

Notes

see also move

rotate(degree, filter=True)¶

Rotate the stimulus.

This is a surface operation. After this, a surface will be present! Rotating goes along with a quality loss. Thus, rotating an already rotated stimulus is not a good idea.

Parameters:	degree : int degree to rotate counterclockwise filter : bool, optional filter the surface content for better quality (default = True)
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

save(filename)¶

Save the stimulus as image.

Parameters:	filename : str name of the file to write (possible extensions are BMP, TGA, PNG, or JPEG with TGA being the default)

Notes

Depending on the size of the stimulus, this method may take some time to compute!

scale(factors)¶

Scale the stimulus.

This is a surface operation. After this, a surface will be present! Negative scaling values will flip the stimulus. Scaling goes along with a quality loss. Thus, scaling an already scaled stimulus is not a good idea.

Parameters:	factors : (int, int) or (float, float) tuple representing the x and y factors to scale or a single number. In the case of a single number x and y scaling will be the identical (i.e., proportional scaling)
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

scale_to_fullscreen(keep_aspect_ratio=True)¶

Scale the stimulus to fullscreen.

This is a surface operation. After this, a surface will be present! Scaling goes along with a quality loss. Thus, scaling an already scaled stimulus is not a good idea.

Parameters:	keep_aspect_ratio : boolean, optional if this boolean is False, stimulus will be stretched so that it fills out the whole screen (default = False)
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

scramble(grain_size)¶

Scramble the stimulus.

Attention: If the surface size is not a multiple of the grain size, you may loose some pixels on the edge.

Parameters:	grain_size : int or (int, int) size of a grain (use tuple of integers for different width & height)
Returns:	time : int the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

set_logging(onoff)¶

Set logging of this object on or off

Parameters:	onoff : bool set logging on (True) or off (False)

Notes

See also design.experiment.set_log_level fur further information about event logging.

set_surface(surface)¶

Set the surface of the stimulus

This method overwrites the surface of the stimulus. It can also handle surfaces in form of pygame.PixelArray representations.

Parameters:	surface: pygame.Surface or pygame.PixelArray a representation of the new surface
Returns:	succeeded: boolean setting surface was successful or not

Notes

CAUTION: This is an expert’s method. The method can be used together with get_surface() & get_pixel_array() to apply low-level Pygame operations on stimuli. However, users should be aware of what they are doing, because the incorrect usage of this methods might affect the stability of the experiment.

surface_size¶

Getter for surface_size.

unload(keep_surface=False)¶

Unload the stimulus from memory.

This will unload preloaded stimuli. In OpenGL mode, this method will remove the reference to the OpenGL texture and the surface (when ‘keep_surface’ is False). When OpenGL is switched off, the reference to the surface will be removed (when ‘keep_surface’ is False).

Parameters:	keep_surface : bool, optional keep the surface after unload (default=False)
Returns:	time : int the time it took to execute this method

See also

clear_surface.

Notes

Depending on the size of the stimulus, this method may take some time to compute!