expyriment.stimuli.FixCross¶
-
class
expyriment.stimuli.
FixCross
(size=None, position=None, line_width=None, colour=None, anti_aliasing=None, cross_size=None)¶ A class implementing a general fixation cross.
-
__init__
(size=None, position=None, line_width=None, colour=None, anti_aliasing=None, cross_size=None)¶ Create a fixation cross.
Parameters: - size(int, int), optional
size of the cross
- position(int, int), optional
position of the stimulus
- line_widthint optional
width of the lines
- colour(int, int, int), optional
colour of the cross
- anti_aliasingint, optional
anti aliasing parameter (good anti_aliasing with 10)
Notes
The parameter cross_size is now OBSOLETE. Please use ‘size’ and specify x and y dimensions.
-
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
cross_size
¶ OBSOLETE property, please use size
-
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 set_surface
-
get_surface_array
(replace_transparent_with_colour=None)¶ Get a 3D array containing the surface pixel data.
Returns: - surface_arraynumpy.ndarray
a 3D array containing the surface pixel data using RGBA coding.
-
get_surface_copy
()¶ Returns a copy of the Pygame surface of the stimulus
Returns: - surface: Pygame.surface
Notes
see also set_surface
-
property
has_surface
¶ Getter for has_surface.
-
property
id
¶ Getter for id.
-
inside_stimulus
(stimulus, mode='visible')¶ Check if stimulus is inside 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”)
Returns: - outbool
Notes
Depending on the size of the stimulus, this method may take some time to compute!
-
property
is_compressed
¶ Getter for is_compressed.
-
is_point_inside
(point_xy)¶ “OBSOLETE METHOD: Please use ‘overlapping_with_position’.
-
property
is_preloaded
¶ Getter for is_preloaded.
-
is_shape_overlapping
(shape2)¶ OBSOLETE METHOD: Please use ‘overlapping_with_shape’.
-
property
line_width
¶ Getter for line_width.
-
property
logging
¶ Getter for logging.
-
move
(offset)¶ Moves the stimulus in 2D space.
When using OpenGL, this can take longer then 1ms!
Parameters: - offsettuple (x,y)
translation along x and y axis
Returns: - timeint
the time it took to execute this method
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
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: - degreeint
degree to rotate counterclockwise
- filterbool, optional
filter the surface content for better quality (default = True)
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
rotation
¶ “Getter for the total native rotation.
-
property
rotation_centre
¶ Getter for rotation_centre.
-
property
rotation_centre_display_colour
¶ Getter for rotation_centre_display_colour.
-
save
(filename)¶ Save the stimulus as image.
Parameters: - filenamestr
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: - 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!
-
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_ratioboolean, optional
if this boolean is False, stimulus will be stretched so that it fills out the whole screen (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!
-
property
scaling
¶ “Getter for the total native scaling.
-
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_sizeint or (int, int)
size of a grain (use tuple of integers for different width & height)
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!
-
set_logging
(onoff)¶ Set logging of this object on or off
Parameters: - onoffbool
set logging on (True) or off (False)
-
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 or Numpy 3D array (RGB or RGBA) representations.
Parameters: - surface: pygame.Surface or pygame.PixelArray or numpy.ndarray
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.
-
property
size
¶ Getter for size.
-
property
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_surfacebool, optional
keep the surface after unload (default=False)
Returns: - timeint
the time it took to execute this method
See also
Notes
Depending on the size of the stimulus, this method may take some time to compute!
-
property
vertices
¶ Getter for the polygon vertices.
-
property
xy_points
¶ Returns the shape as list of XYPoints.
The representation does not take into account the position. Use xy_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 XYPoints
polygon as list of XYPoints of the shape
-
property
xy_points_on_screen
¶ Returns the shape as list of XYPoints in Expyriment coordinates.
In contrast to xy_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 XYPoints
polygon as list of XYPoints of the shape
-