psychopy.layout - For working with vectors and points¶

Overview¶

Details¶

class psychopy.layout.Vector(value, units, win)[source]¶

Class representing a vector.

A vector is a mathematical construct that specifies a length (or magnitude) and direction within a given coordinate system. This class provides methods to manipulate vectors and convert them between coordinates systems.

This class may be used to assist in positioning stimuli on a screen.

Parameters:

• value (ArrayLike) – Array of vector lengths along each dimension of the space the vector is within. Vectors are specified as either 1xN for single vectors, and Nx2 or Nx3 for multiple vectors.

• units (str or None) – Units which value has been specified in. Applicable values are ‘pix’, ‘deg’, ‘degFlat’, ‘degFlatPos’, ‘cm’, ‘pt’, ‘norm’, ‘height’, or None.

• win (~psychopy.visual.Window or None) – Window associated with this vector. This value must be specified if you wish to map vectors to coordinate systems that require additional information about the monitor the window is being displayed on.

Examples

Create a new vector object using coordinates specified in pixel (‘pix’) units:

my_vector = Vector([256, 256], 'pix')

Multiple vectors may be specified by supplying a list of vectors:

my_vector = Vector([[256, 256], [640, 480]], 'pix')

Operators can be used to compare the magnitudes of vectors:

mag_is_same = vec1 == vec2  # same magnitude
mag_is_greater = vec1 > vec2  # one greater than the other

1xN vectors return a boolean value while Nx2 or Nx3 arrays return N-length arrays of boolean values.

property cm¶

Values in units of ‘cm’ (centimeters).

copy()[source]¶

Create a copy of this object

property deg¶

Values in units of ‘deg’ (degrees of visual angle).

property degFlat¶

Values in units of ‘degFlat’ (degrees of visual angle corrected for screen curvature).

When dealing with positions/sizes in isolation; ‘deg’, ‘degFlat’ and ‘degFlatPos’ are synonymous - as the conversion is done at the vertex level.

property degFlatPos¶

Values in units of ‘degFlatPos’.

When dealing with positions/sizes in isolation; ‘deg’, ‘degFlat’ and ‘degFlatPos’ are synonymous - as the conversion is done at the vertex level.

property dimensions¶

How many dimensions (x, y, z) are specified?

property direction¶

Direction of vector (i.e. angle between vector and the horizontal plane).

property height¶

Value in units of ‘height’ (normalized to the height of the window).

property magnitude¶

Magnitude of vector (i.e. length of the line from vector to (0, 0) in pixels).

property monitor¶

The monitor used for calculations within this object (~psychopy.monitors.Monitor).

property norm¶

Value in units of ‘norm’ (normalized device coordinates).

property pix¶

Values in units of ‘pix’ (pixels).

property pt¶

Vector coordinates in ‘pt’ (points).

Points are commonly used in print media to define text sizes. One point is equivalent to 1/72 inches, or around 0.35 mm.

set(value, units, win=None)[source]¶

validate(value, units)[source]¶

Validate input values.

Ensures the values are in the correct format.

Returns:

Parameters value and units.

Return type:

tuple

class psychopy.layout.Position(value, units, win=None)[source]¶

Class representing a position vector.

This class is used to specify the location of a point within some coordinate system (e.g., (x, y)).

Parameters:

• value (ArrayLike) – Array of coordinates representing positions within a coordinate system. Positions are specified in a similar manner to ~psychopy.layout.Vector as either 1xN for single vectors, and Nx2 or Nx3 for multiple positions.

• units (str or None) – Units which value has been specified in. Applicable values are ‘pix’, ‘deg’, ‘degFlat’, ‘degFlatPos’, ‘cm’, ‘pt’, ‘norm’, ‘height’, or None.

• win (~psychopy.visual.Window or None) – Window associated with this position. This value must be specified if you wish to map positions to coordinate systems that require additional information about the monitor the window is being displayed on.

property cm¶

Values in units of ‘cm’ (centimeters).

copy()¶

Create a copy of this object

property deg¶

Values in units of ‘deg’ (degrees of visual angle).

property degFlat¶

Values in units of ‘degFlat’ (degrees of visual angle corrected for screen curvature).

When dealing with positions/sizes in isolation; ‘deg’, ‘degFlat’ and ‘degFlatPos’ are synonymous - as the conversion is done at the vertex level.

property degFlatPos¶

Values in units of ‘degFlatPos’.

When dealing with positions/sizes in isolation; ‘deg’, ‘degFlat’ and ‘degFlatPos’ are synonymous - as the conversion is done at the vertex level.

property dimensions¶

How many dimensions (x, y, z) are specified?

property direction¶

Direction of vector (i.e. angle between vector and the horizontal plane).

property height¶

Value in units of ‘height’ (normalized to the height of the window).

property magnitude¶

Magnitude of vector (i.e. length of the line from vector to (0, 0) in pixels).

property monitor¶

The monitor used for calculations within this object (~psychopy.monitors.Monitor).

property norm¶

Value in units of ‘norm’ (normalized device coordinates).

property pix¶

Values in units of ‘pix’ (pixels).

property pt¶

Vector coordinates in ‘pt’ (points).

Points are commonly used in print media to define text sizes. One point is equivalent to 1/72 inches, or around 0.35 mm.

set(value, units, win=None)¶

validate(value, units)¶

Validate input values.

Ensures the values are in the correct format.

Returns:

Parameters value and units.

Return type:

tuple

class psychopy.layout.Size(value, units, win=None)[source]¶

Class representing a size.

Parameters:

• value (ArrayLike) – Array of values representing size axis-aligned bounding box within a coordinate system. Sizes are specified in a similar manner to ~psychopy.layout.Vector as either 1xN for single vectors, and Nx2 or Nx3 for multiple positions.

• units (str or None) – Units which value has been specified in. Applicable values are ‘pix’, ‘deg’, ‘degFlat’, ‘degFlatPos’, ‘cm’, ‘pt’, ‘norm’, ‘height’, or None.

• win (~psychopy.visual.Window or None) – Window associated with this size object. This value must be specified if you wish to map sizes to coordinate systems that require additional information about the monitor the window is being displayed on.

property cm¶

Values in units of ‘cm’ (centimeters).

copy()¶

Create a copy of this object

property deg¶

Values in units of ‘deg’ (degrees of visual angle).

property degFlat¶

Values in units of ‘degFlat’ (degrees of visual angle corrected for screen curvature).

When dealing with positions/sizes in isolation; ‘deg’, ‘degFlat’ and ‘degFlatPos’ are synonymous - as the conversion is done at the vertex level.

property degFlatPos¶

Values in units of ‘degFlatPos’.

When dealing with positions/sizes in isolation; ‘deg’, ‘degFlat’ and ‘degFlatPos’ are synonymous - as the conversion is done at the vertex level.

property dimensions¶

How many dimensions (x, y, z) are specified?

property direction¶

Direction of vector (i.e. angle between vector and the horizontal plane).

property height¶

Value in units of ‘height’ (normalized to the height of the window).

property magnitude¶

Magnitude of vector (i.e. length of the line from vector to (0, 0) in pixels).

property monitor¶

The monitor used for calculations within this object (~psychopy.monitors.Monitor).

property norm¶

Value in units of ‘norm’ (normalized device coordinates).

property pix¶

Values in units of ‘pix’ (pixels).

property pt¶

Vector coordinates in ‘pt’ (points).

Points are commonly used in print media to define text sizes. One point is equivalent to 1/72 inches, or around 0.35 mm.

set(value, units, win=None)¶

validate(value, units)¶

Validate input values.

Ensures the values are in the correct format.

Returns:

Parameters value and units.

Return type:

tuple

class psychopy.layout.Vertices(verts, obj=None, size=None, pos=None, units=None, flip=None, anchor=None)[source]¶

Class representing an array of vertices.

Parameters:

• verts (ArrayLike) – Array of coordinates specifying the locations of vertices.

• obj (object or None) –

• size (ArrayLike or None) – Scaling factors for vertices along each dimension.

• pos (ArrayLike or None) – Offset for vertices along each dimension.

• units (str or None) – Units which verts has been specified in. Applicable values are ‘pix’, ‘deg’, ‘degFlat’, ‘degFlatPos’, ‘cm’, ‘pt’, ‘norm’, ‘height’, or None.

• flip (ArrayLike or None) – Array of boolean values specifying which dimensions to flip/mirror. Mirroring is applied prior to any other transformation.

• anchor (str or None) – Anchor location for vertices, specifies the origin for the vertices.

property anchor¶

Anchor location (str).

Possible values are on of ‘top’, ‘bottom’, ‘left’, ‘right’, ‘center’. Combinations of these values may also be specified (e.g., ‘top_center’, ‘center-right’, ‘topleft’, etc. are all valid).

property anchorAdjust¶

Map anchor values to numeric vertices adjustments.

property cm¶

Get absolute positions of vertices in ‘cm’ units.

property deg¶

Get absolute positions of vertices in ‘deg’ units.

property degFlat¶

Get absolute positions of vertices in ‘degFlat’ units.

property flip¶

1x2 array for flipping vertices along each axis; set as True to flip or False to not flip (ArrayLike).

If set as a single value, will duplicate across both axes. Accessing the protected attribute (._flip) will give an array of 1s and -1s with which to multiply vertices.

property flipHoriz¶

Apply horizontal mirroring (bool)?

property flipVert¶

Apply vertical mirroring (bool)?

getas(units)[source]¶

property height¶

Get absolute positions of vertices in ‘height’ units.

property norm¶

Get absolute positions of vertices in ‘norm’ units.

property pix¶

Get absolute positions of vertices in ‘pix’ units.

property pos¶

Positional offset of the vertices (~psychopy.layout.Vector or ArrayLike).

setas(value, units)[source]¶

property size¶

Scaling factors for vertices (~psychopy.layout.Vector or ArrayLike).

property units¶

Units which the vertices are specified in (str).