# psychopy.layout - For working with vectors and points¶

Classes and functions for working with coordinates systems.

## Overview¶

 Vector(value, units, win) Class representing a vector. Position(value, units[, win]) Class representing a position vector. Size(value, units[, win]) Class representing a size. Vertices(verts[, obj, size, pos, units, …]) Class representing an array of vertices.

## 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).