expyriment.stimuli.Shape¶

class expyriment.stimuli.Shape(position=None, colour=None, line_width=None, anti_aliasing=None, vertex_list=None, debug_contour_colour=None)¶

A class implementing a shape.

__init__(position=None, colour=None, line_width=None, anti_aliasing=None, vertex_list=None, debug_contour_colour=None)¶

Create a shape.

A shape is an object described by vertices. For more details about vertex representations see: http://en.wikipedia.org/wiki/Vertex_(geometry)

The vertex representation describes the contour of an object. Think of it as if you would draw with a pen. You start somewhere and make movements in different directions. Shapes are always closed. Thus, a rectangle could be for instance described by a right, a down and a left. (The fours movement up to the origin is not required; see example below).

A shapes is conceptually a filled object. The vertices describe the contour of the object. That is, a shape object has no line_width and has thus no contour of different colour. Displaying the contour might be useful for debugging purposes. To do so, set the parameter ‘debug_contour_colour’. However, note that is affects the surface size inconsistently.

If you want to plot a contour-like stimulus (e.g. a frame) the vertices need to describe the contour shape, in other words “the contour of to-be-displayed contour”. Thus, a frame should be correct implemented as illustrated in example 2.

As always in Expyriment, the center of the surface of the shape is its position. That means, that with every new vertex, the shape size might change and the shape position will be realigned.

Parameters:

position(int, int), optional: position of the stimulus
colour(int, int, int), optional: colour of the shape or the fill colour
anti_aliasingint, optional: anti aliasing parameter (good anti_aliasing with 10)
vertex_list(int, int): list of vertices (int, int)
debug_contour_colour(int, int, int), optional: The colour of the contour of the shape. If None (default), contour colour is not displyed. Use this option only for debugging. The resulting surface size might be enlarged by one pixel large depending on the shape.

Notes

You can also use the convenience function vertices_triangle, vertices_rectangle, vertices_regular_polygon, vertices_frame defined in expyriment.misc.geometry to plot predefined geometrical shapes (see example 3).

Examples

EXAMPLE 1: >>> # drawing a rectangle with the size (100, 50) >>> r = stimuli.Shape() >>> r.add_vertices([(100,0), (0,-50),(-100,0) ]) >>> # three vertices are sufficient, because shapes are always closed >>> r.present()

EXAMPLE 2: >>> # drawing a frame >>> def vertices_frame(size, frame_thickness): >>> # this function is also available in the geometry module >>> return [ (size[0]-frame_thickness, 0), >>> (0, -size[1]), >>> (-size[0], 0), >>> (0, size[1]), >>> (frame_thickness, 0), >>> (0, -(size[1]-frame_thickness)), >>> (size[0]-2*frame_thickness, 0), >>> (0, size[1]-2*frame_thickness), >>> (-(size[0]-2*frame_thickness), 0)] >>> fr = stimuli.Shape(vertex_list=vertices_frame(size=(200, 100), >>> frame_thickness=10)) >>> fr.present()

EXAMPLE 3: >>> # using ‘vertices_regular_polygon’ from misc.geometry >>> from expyriment.misc import geometry >>> sh = stimuli.Shape(vertex_list=geometry.vertices_regular_polygon(5, 60)) >>> sh.present()

property 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_sizeint size of the grains for the noise percentageint percentage of covered area colour(int, int, int) colour (RGB) of the noise
Returns:	timeint the time it took to execute this method

Notes

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

add_vertex(xy)¶

Add a vertex to the shape.

Parameters:	xy(int, int) vertex as tuple

add_vertices(vertex_list)¶

Add a list of vertices to the shape.

Parameters:	vertex_list((int, int)) list of vertices ((int, int))

property anti_aliasing¶: Getter for anti_aliasing.

blur(level)¶

Blur the shape.

This blurs the stimulus, by scaling it down and up by the factor of ‘level’. Notes —– Depending on the blur level and the size of your stimulus, this method may take some time!

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

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:	timeint the time it took to execute this method

Notes

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

property 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:	timeint the time it took to execute this method

convert_expyriment_xy_to_surface_xy(point_xy)¶

Convert a point from shape coordinates to surface coordinates.

Parameters:	point_xy(int, int) Expyriment screen coordinates (tuple)

copy()¶

Deep copy of the visual stimulus.

Returns:	copydeep copy of self

Notes

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

property debug_contour_colour¶: Getter for conture_colour.

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:	timeint 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:	otherstimulus the other visual stimulus
Returns:	distfloat distance between surface centers

erase_vertices()¶: Removes all vertices.

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:	timeint the time it took to execute this method

Notes

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

property flipping¶: “Getter for the total native flipping.

get_pixel_array()¶

Return a 2D array referencing the surface pixel data.

Returns:	pixel_array: Pygame.PixelArray a 2D array referencing the surface pixel data

Notes

see also reposition

native_flip(booleans)¶

Flip the shape.

Native flipping of shapes is a native operation (not a surface operation) and does therefore not go along with a quality loss. No surface will be created.

Parameters:	booleans(bool, bool) booleans to flip horizontally and vertically or not

native_overlapping_with_position(position)¶

Return True if the position is inside the shape.

Parameters position – Expyriment screen coordinates (tuple)

Returns:	valbool True if the position is inside the shape

native_rotate(degree)¶

Rotate the shape.

Native rotation of shape is a native operation (not a surface operation) and does therefore not go along with a quality loss. No surface will be created.

Parameters:	degreefloat degree to rotate counterclockwise (float)

native_scale(factors, scale_line_width=False)¶

Scale the shape.

Native scaling of shapes is a native operation (not a surface operation) and does therefore not go along with a quality loss. No surface will be created.

Negative scaling values will native_flip the stimulus.

Parameters:	factorsint or (int, int) x and y factors to scale

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 modemode (str), optional “visible”: based on non-transparent pixels or “rectangle”: based on pixels in pygame surface (default = visible”) use_absolute_positionbool, optional use absolute_position of stimulus (default) instead of position
Returns:	overlappingbool

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_shape(other)¶

Return true if shape overlaps with other shape.

Parameters:	otherstimuli.Shape the other shape object
Returns:	valbool True if overlapping

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

Check if stimulus is overlapping with another stimulus.

Parameters:	stimulusexpyriment stimulus the other stimulus modemode (str), optional “visible”: based on non-transparent pixels or “surface”: based on pixels in pygame surface (default = visible”) use_absolute_positionbool, optional use absolute_position of stimuli (default) instead of position
Returns:	overlappingbool 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:	stimulusexpyriment stimulus stimulus to whose surface should be plotted
Returns:	timeint the time it took to execute this method

Notes

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

property points¶

Returns shape as list of tuples (x, y) representing points.: see Shape.xy_points

The representation does not take into account the position. Use points_on_screen for position-depended representation.

In contrast to the vertex representation, the point representation takes into all the native transformations (rotation, scaling, flipping)

Returns:	val: list of tuples polygon as list of tuples (x,y) in Expyriment coordinates

property points_on_screen¶

Returns shape as list of tuples (x, y) resenting points on the screen. see Shape.xy_points_on_screen.

In contrast to Shape.points, it takes into account the position on screen.

In contrast to the vertex representation, the point representation takes into all the native transformations (rotation, scaling, flipping).

Returns:	val: list of tuples polygon as list of tuples (x,y) in Expyriment coordinates

property polar_position¶: Getter for the position in polar coordinates (radial, angle[degrees])

property 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 accurate presentation is needed!

Parameters:	inhibit_ogl_compressbool, optional inhibits OpenGL stimuli to be automatically compressed (default=False)
Returns:	timeint 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:

clearbool, optional: if True the screen will be cleared automatically (default = True)
updatebool, optional: if False the screen will be not be updated automatically (default = True)
log_event_tagnumeral 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:

timeint: the time it took to execute this method

property rect¶

Getter for bouncing rectangular rect = pygame.Rect(left, top, width, height)

Notes

Fom version 0.9.1 on, this is a pygame.Rect

remove_vertex(index)¶: Remove a vertex.

reposition(new_position)¶

Move stimulus to a new position.

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

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

Notes