Mask Stimulus¶

Description¶

A mask can truncate, obscure, or erase stimuli that lie below it.

Masks operate in two different modes. The first mode requires that the mask be contained in a layer and applies when the mask’s color parameter is omitted. In this mode, the “masked out” regions become transparent or semi-transparent “windows”, through which any stimuli below the layer are visible. If the mask is inverted, it will make a “hole” through the stimuli under it, allowing the stimuli beneath the layer to show through. For example, the following layer will produce a red ring with inner radius 5 and outer radius 10:

layer the_layer {
    circle (
        color = 1,0,0
        x_size = 20
        )
    mask (
        mask = ellipse
        inverted = true
        x_size = 10
        )
}

The second mode applies when a color is specified. In this mode, the “masked out” regions are blended with or replaced by the mask’s color; no layer is required. If the mask’s color matches the color of the background, the mask can effectively “fade” the stimuli below it in to the background. For example, when displayed together, the following stimuli produce a blue circle whose edge fades in to the default, 50% gray background:

rectangle the_rectangle (
    color = 0,0,1
    x_size = 10
    )

mask the_mask (
    mask = raised_cosine
    color = 0.5, 0.5, 0.5
    x_size = 10
    )

Signature¶

stimulus/mask

Required Parameters¶

mask¶

Options:: rectangle

ellipse

gaussian

raised_cosine

Mask type

Optional Parameters¶

inverted¶

Default:: NO

If YES, the effect of the mask is inverted: Areas of the display that normally would be visible through the mask are hidden, and areas that normally would be hidden are visible.

std_dev¶

Default:: 1.0

Standard deviation of Gaussian mask.

The Gaussian mask is computed on a 2x2 square, centered at the origin, using the equation:

exp(-1.0 * (dist - mean) * (dist - mean) / (2.0 * std_dev * std_dev))

where dist is distance from the center. The mask is then stretched to cover a rectangle of x_size by y_size degrees. If the x and y sizes are equal, then the mask is scaled by size/2 in both directions, so std_dev has units of size/2 degrees.

mean¶

Default:: 0.0

Mean of Gaussian mask.

This value determines the radial offset of the Gaussian peak from the center of the mask. If non-zero, the peak will be a circle, rather than a point, and luminance will decrease both inside and outside the circle, producing a toroidal mask.

normalized¶

Default:: NO

If YES, the Gaussian mask includes a multiplicative normalization term (1/(std_dev*sqrt(2*pi))). If NO, this term is omitted.

edge_width¶

Default:: 0.125

Edge width of raised cosine mask.

This value specifies the width of the sinusoidal edge as a fraction of the total width (i.e. diameter) of the mask. It should be greater than zero and less than or equal to 0.5.

color¶

Example:: 0.5,0.5,0.5

The color of the mask, expressed as a comma-separated list of red, green, and blue components. Each component may be described by any valid expression, but the expression must result in a value between 0 and 1 (inclusive).

x_size¶

Example:: 5.0

Horizontal size (degrees).

If omitted, the value of y_size is used. It is an error to omit both x_size and y_size (unless fullscreen is YES).

y_size¶

Example:: 5.0

Vertical size (degrees).

If omitted, the value of x_size is used. It is an error to omit both x_size and y_size (unless fullscreen is YES).

x_position¶

Default:: 0.0

Horizontal center position (degrees)

y_position¶

Default:: 0.0

Vertical center position (degrees)

rotation¶

Default:: 0.0

Rotation (degrees)

fullscreen¶

Default:: NO

If YES, the stimulus is sized to fill the display. In this mode, x_size, y_size, x_position, y_position, and rotation are ignored.

deferred¶

Options:: no

yes

explicit
Default:: no

Controls when the stimulus is loaded. If no, the stimulus is loaded at experiment load time. If yes, the stimulus is loaded the first time it is queued. If explicit, the stimulus must be loaded explictly with Load Stimulus.

display¶

Name of the display on which the stimulus will be presented. If omitted, the default display (if available) will be used.

Placement¶

Allowed at top level:	Yes
Allowed parent:	Compound Stimulus, Folder, Frame List Stimulus, Layer Stimulus, List Replicator, Movie Stimulus, Range Replicator, Stimulus Group