stimupy.utils.resolution

Functions

resolve	Resolves the full resolution, for 2 givens and 1 unknown
resolve_1D	Resolves the full resolution, for 2 givens and 1 unknown
resolve_dict	Resolves the full resolution ("shape", "ppd", "visual_size"), for 2 givens and 1 unknown in the input dictionary
visual_angle_from_length_ppd	Calculate visual angle (degrees) from length (pixels) and pixels-per-degree
visual_angles_from_lengths_ppd	Calculate visual sizes (degrees) from given shapes (pixels) and pixels-per-degree
visual_size_from_shape_ppd	Calculate visual size (degrees) from given shape (pixels) and pixels-per-degree
length_from_visual_angle_ppd	Calculate length (pixels) from visual angle (degrees) and pixels-per-degree
lengths_from_visual_angles_ppd	Calculate lengths (pixels) from visual angles (degrees) and pixels-per-degree
shape_from_visual_size_ppd	Calculate shape (pixels) from given visual size (degrees) and pixels-per-degree
ppd_from_shape_visual_size	Calculate resolution (ppd) from given shape (pixels) and visual size (degrees)
ppd_from_length_visual_angle	Calculate pixels-per-degree from length (pixels) and visual angle (degrees)
compute_ppd	Compute the pixels per degree in a presentation setup i.e., the number of pixels in the central one degree of visual angle
validate_shape	Put specification of shape (in pixels) in canonical form, if possible
validate_ppd	Put specification of ppd in canonical form, if possible
validate_visual_size	Put specification of visual size in canonical form, if possible
valid_1D	Asserts that the combined specification of resolution is geometrically valid.
valid_resolution	Asserts that the combined specification of resolution is geometrically valid.
valid_dict	Asserts that the combined specification of resolution in dict is geometrically valid.

resolve(shape=None, visual_size=None, ppd=None)

Resolves the full resolution, for 2 givens and 1 unknown

A resolution consists of a visual size in degrees, a shape in pixels, and specification of the number of pixels per degree. Since there is a strict geometric relation between these, shape = visual_size * ppd, if two are given, the third can be calculated using this function.

This function resolves the resolution in both dimensions.

Parameters:

• shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] in pixels

• visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] in degrees

• ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

Returns:

• Shape NamedTuple, with two attributes – .height: int, height in pixels .width: int, width in pixels See validate_shape

• Visual_size NamedTuple, with two attributes – .height: float, height in degrees visual angle .width: float, width in degrees visual angle See validate_visual_size

• ppd NamedTuple, with two attributes – .vertical: int, vertical pixels per degree (ppd) .horizontal: int, horizontal pixels per degree (ppd) see validate_ppd

resolve_1D(length=None, visual_angle=None, ppd=None, round=True)

Resolves the full resolution, for 2 givens and 1 unknown

A resolution consists of a visual size in degrees, a shape in pixels, and specification of the number of pixels per degree. Since there is a strict geometric relation between these, shape = visual_size * ppd, if two are given, the third can be calculated using this function.

This function resolves the resolution in a single dimension.

Parameters:

• length (Number, length in pixels, or None (default)) –

• visual_angle (Number, length in degrees, or None (default)) –

• ppd (Number, pixels per degree, or None (default)) –

Returns:

• length (int, length in pixels)

• visual_angle (float, length in degrees)

• ppd (float, pixels per degree)

resolve_dict(dct)

Resolves the full resolution (“shape”, “ppd”, “visual_size”), for 2 givens and 1 unknown in the input dictionary

A resolution consists of a visual size in degrees, a shape in pixels, and specification of the number of pixels per degree. Since there is a strict geometric relation between these, shape = visual_size * ppd, if two are given, the third can be calculated using this function.

This function resolves the resolution in both dimensions.

Parameters:

dct (dict) – dictionary with at least two out the three keys: “shape”, “ppd”, “visual_size”

Return type:

Resolved dict

See also

stimupy.utils.resolution

visual_angle_from_length_ppd(length, ppd)

Calculate visual angle (degrees) from length (pixels) and pixels-per-degree

Parameters:

• length (int or None) – length in pixels

• ppd (int or None) – pixels per degree

Return type:

Length (pixels) translated to visual angle (degrees)

visual_angles_from_lengths_ppd(lengths, ppd)

Calculate visual sizes (degrees) from given shapes (pixels) and pixels-per-degree

Parameters:

• lengths (Sequence[int, int, ...] or None) – list of lengths

• ppd (int or None) – pixels per degree

Return type:

List with lengths (pixels) translated to visual angles (degrees)

visual_size_from_shape_ppd(shape, ppd)

Calculate visual size (degrees) from given shape (pixels) and pixels-per-degree

Parameters:

• shape (Sequence[int, int]; or int, or None) – each element has to be of type that can be cast to int, or None. See validate_shape

• ppd (Sequence[int, int]; or int, or None) – each element has to be of type that can be cast to int, or None. See validate_ppd

Returns:

.height: float, height in degrees visual angle .width: float, width in degrees visual angle See validate_visual_size

Return type:

Visual_size NamedTuple, with two attributes

length_from_visual_angle_ppd(visual_angle, ppd, round=True)

Calculate length (pixels) from visual angle (degrees) and pixels-per-degree

Parameters:

• visual_angle (float or None) – visual angle in degrees

• ppd (int or None) – pixels per degree

• round (bool) – if True, round output length to full pixels

Return type:

visual angle (degrees) translated to length (pixels)

lengths_from_visual_angles_ppd(visual_angles, ppd, round=True)

Calculate lengths (pixels) from visual angles (degrees) and pixels-per-degree

Parameters:

• visual_angles (Sequence[float, float, ...] or None) – list of visual angles

• ppd (int or None) – pixels per degree

• round (bool) – if True, round output length to full pixels

Return type:

List with visual angles (degrees) translated to lengths (pixels)

shape_from_visual_size_ppd(visual_size, ppd)

Calculate shape (pixels) from given visual size (degrees) and pixels-per-degree

Parameters:

• visual_size (Sequence[Number, Number]; or Number; or None) – each element has to be of type that can be cast to float, or None.

• ppd (Sequence[int, int]; or int, or None) – each element has to be of type that can be cast to int, or None. See validate_ppd

Returns:

.height: int, height in pixels .width: int, width in pixels See validate_shape

Return type:

Shape NamedTuple, with two attributes

ppd_from_shape_visual_size(shape, visual_size)

Calculate resolution (ppd) from given shape (pixels) and visual size (degrees)

Parameters:

• shape (Sequence[int, int]; or int, or None) – each element has to be of type that can be cast to int, or None. See validate_shape

• visual_size (Sequence[Number, Number]; or Number; or None) – each element has to be of type that can be cast to float, or None. See validate_visual_size

Returns:

.vertical: int, vertical pixels per degree (ppd) .horizontal: int, horizontal pixels per degree (ppd) see validate_ppd

Return type:

ppd NamedTuple, with two attributes

ppd_from_length_visual_angle(length, visual_angle)

Calculate pixels-per-degree from length (pixels) and visual angle (degrees)

Parameters:

• length (int or None) – length in pixels

• visual_angle (float or None) – visual angle in degrees

Return type:

visual angle (degrees) translated to length (pixels)

compute_ppd(screen_size, resolution, distance)

Compute the pixels per degree in a presentation setup i.e., the number of pixels in the central one degree of visual angle

Parameters:

• screen_size ((float, float)) – physical size, in whatever units you prefer, of the presentation screen

• resolution ((float, float)) – screen resolution, in pixels, in the same direction that screen size was measured in

• distance (float) – physical distance between the observer and the screen, in the same unit as screen_size

Returns:

ppd, the number of pixels in one degree of visual angle

Return type:

float

validate_shape(shape)

Put specification of shape (in pixels) in canonical form, if possible

Parameters:

shape (Sequence of length 1 or 2; or None) – if 2 elements: interpret as (height, width) if 1 element: use as both height and width if None: return (None, None) each element has to be of type that can be cast to int, or None.

Returns:

.height: int, height in pixels .width: int, width in pixels

Return type:

Shape NamedTuple, with two attributes

Raises:

• ValueError – if input does not have at least 1 element

• TypeError – if input is not a Sequence(int, int) and cannot be cast to one

• ValueError – if input has more than 2 elements

validate_ppd(ppd)

Put specification of ppd in canonical form, if possible

Parameters:

ppd (Sequence of length 1 or 2; or None) – if 2 elements: interpret as (vertical, horizontal) if 1 element: use as both vertical and horizontal if None: return (None, None) each element has to be of type that can be cast to int, or None.

Returns:

.vertical: int, vertical pixels per degree (ppd) .horizontal: int, horizontal pixels per degree (ppd)

Return type:

ppd NamedTuple, with two attributes

Raises:

• ValueError – if input does not have at least 1 element

• TypeError – if input is not a Sequence(int, int) and cannot be cast to one

• ValueError – if input has more than 2 elements

validate_visual_size(visual_size)

Put specification of visual size in canonical form, if possible

Parameters:

visual_size (Sequence of length 1 or 2; or None) – if 2 elements: interpret as (height, width) if 1 element: use as both height and width if None: return (None, None) each element has to be of type that can be cast to float, or None.

Returns:

.height: float, height in degrees visual angle .width: float, width in degrees visual angle

Return type:

Visual_size NamedTuple, with two attributes

Raises:

• ValueError – if input does not have at least 1 element

• TypeError – if input is not a Sequence(float, float) and cannot be cast to one

• ValueError – if input has more than 2 elements

valid_1D(length, visual_angle, ppd)

Asserts that the combined specification of resolution is geometrically valid.

Asserts the combined specification of shape (in pixels), visual_size (deg) and ppd. If this makes sense, i.e. (roughly), int(visual_size * ppd) == shape, this function passes without output. If the specification does not make sense, raises a ResolutionError.

Note that the resolution specification has to be fully resolved, i.e., none of the parameters can be None

Parameters:

• length (int, length in pixels) –

• visual_angle (float, size in degrees) –

• ppd (int, resolution in pixels-per-degree) –

Raises:

ResolutionError – if resolution specification is invalid, i.e. (roughly), if int(visual_angle * ppd) != length

valid_resolution(shape, visual_size, ppd)

Asserts that the combined specification of resolution is geometrically valid.

Asserts the combined specification of shape (in pixels), visual_size (deg) and ppd. If this makes sense, i.e. (roughly), int(visual_size * ppd) == shape, this function passes without output. If the specification does not make sense, raises a ResolutionError.

Note that the resolution specification has to be fully resolved, i.e., none of the parameters can be/contain None

Parameters:

• shape (2-tuple (height, width), or something that can be cast (see validate_shape)) –

• visual_size (2-tuple (height, width), or something that can be cast (see validate_visual_size)) –

• ppd (2-tuple (vertical, horizontal), or something that can be cast (see validate_ppd)) –

Raises:

ResolutionError – if resolution specification is invalid, i.e. (roughly), if int(visual_size * ppd) != shape

valid_dict(dct)

Asserts that the combined specification of resolution in dict is geometrically valid.

Asserts the combined specification of shape (in pixels), visual_size (deg) and ppd. If this makes sense, i.e. (roughly), int(visual_size * ppd) == shape, this function passes without output. If the specification does not make sense, raises a ResolutionError.

Note that the resolution specification has to be fully resolved, i.e., none of the parameters can be/contain None

Parameters:

dct (dict) – dictionary with at least the keys “shape”, “ppd”, “visual_size”

Raises:

ResolutionError – if resolution specification is invalid, i.e. (roughly), if int(visual_size * ppd) != shape