NoiseStim¶

Attributes¶

Details¶

class psychopy.visual.NoiseStim(win, mask='none', units='', pos=(0.0, 0.0), size=None, sf=None, ori=0.0, phase=(0.0, 0.0), noiseType='none', noiseElementSize='16', noiseBaseSf='1', noiseBW='1', noiseBWO='30', noiseFractalPower='0.0', noiseFilterUpper='50', noiseFilterLower='0', noiseFilterOrder='0.0', noiseClip='1', noiseImage='None', texRes=128, rgb=None, dkl=None, lms=None, color=(1.0, 1.0, 1.0), colorSpace='rgb', contrast=0.5, opacity=1.0, depth=0, rgbPedestal=(0.0, 0.0, 0.0), interpolate=False, blendmode='avg', name=None, autoLog=None, autoDraw=False, maskParams=None)¶

A stimulus with 2 textures: a radom noise sample and a mask

Example:

noise1 = noise = visual.NoiseStim(

win=win, name=’noise’,units=’pix’, noiseImage=’testImg.jpg’, mask=’circle’, ori=1.0, pos=(0, 0), size=(512, 512), sf=None, phase=0, color=[1,1,1], colorSpace=’rgb’, opacity=1, blendmode=’add’, contrast=1.0, texRes=512, noiseType=’Gabor’, noiseElementSize=4, noiseBaseSf=32.0/512, noiseBW=1.0, noiseBWO=30, noiseFractalPower=-1,noiseFilterLower=3/512, noiseFilterUpper=8.0/512.0, noiseFilterOrder=3.0, noiseClip=3.0, interpolate=False, depth=-1.0)

# gives a circular patch of noise made up of scattered Gabor elements with peak frequency = 32.0/512 cycles per pixel, # orientation = 0 , frequency bandwidth = 1 octave and orientation bandwidth 30 degrees

Types of noise available Binary, Normal, Uniform - pixel based noise samples drawn from a binary (blank and white), normal or uniform distribution respectively. Binary noise is always exactly zero mean, Normal and Uniform are approximately so.

Parameters - noiseElementSize - (can be a tuple) defines the size of the noise elements in the components units.

noiseClip the values in normally distributed noise are divided by noiseClip to limit excessively high or low values.

However, values can still go out of range -1 to 1 whih will throw a soft error message high values of noiseClip are recommended if using ‘Normal’

Gabor, Isotropic - Effectively a dense scattering of Gabor elements with random amplitude and fixed orientation for Gabor or random orientation for Isotropic noise.

Parameters - noiseBaseSf - centre spatial frequency in the component units.

noiseBW - spatial frequency bandwidth full width half height in octaves. ori - centre orientation for Gabor noise (works as for gratingStim so twists the final image at render time). noiseBWO - orientation bandwidth for Gabor noise full width half height in degrees.

In practice the desired amplitude spectrum for the noise is built in Fourier space with a random phase spectrum. DC term is set to zero - ie zero mean.

Filtered - A noise sample that has been filtered with a low, high or bandpass Butterworth filter. The initial sample can have its spectrum skewed towards low or high frequencies

The contrast of the noise falls by half its maximum (3dB) at the cutoff frequencies. Parameters - noiseFilterUpper - upper cutoff frequency - if greater than texRes/2 cycles per image low pass filter used.

noiseFilterLower - Lower cutoff frequency - if zero low pass filter used. noiseFilterOrder - The order of the filter controls the steepness of the falloff outside the passband is zero no filter is applied. noiseFractalPower - spectrum = f^noiseFractalPower - determines the spatial frequency bias of the initial noise sample. 0 = flat spectrum, negative = low frequency bias, positive = high frequency bias, -1 = fractal or brownian noise. noiseClip - determines clipping values and rescaling factor such that final rms contrast is close to that requested by contrast parameter while keeping pixel values in range -1, 1.

White - A short cut to obtain noise with a flat, unfiltered spectrum

noiseClip - determines clipping values and rescaling factor such that final rms contrast is close to that requested by contrast parameter while keeping pixel values in range -1, 1.

In practice the desired amplitude spectrum is built in the Fourier Domain with a random phase spectrum. DC term is set to zero - ie zero mean Note despite name the noise contains all grey levels.

Image - A noise sample whose spatial frequency spectrum is taken from the supplied image.

Parameters - noiseImage name of nparray or image file from which to take spectrum - should be same size as largest side requested for component if units is pix or texRes x texRes otherwise

noiseClip - determines clipping values and rescaling factor such that final rms contrast is close to that requested by contrast parameter while keeping pixel values in range -1, 1.

In practice the desired amplitude spectrum is taken from the image and paired with a random phase spectrum. DC term is set to zero - ie zero mean

Updating noise samples and timing The noise is rebuilt at next call of the draw function whenever a parameter starting ‘noise’ is notionally changed even if the value does not actually change every time. eg. setting a parameter to update every frame will cause a new noise sample on every frame but see below. A rebuild can also be forced at any time using the buildNoise() function. The updateNoise() function can be used at any time to produce a new random saple of noise without doing a full build. ie it is quicker than a full build. Both buildNoise and updateNoise can be slow for large samples. Samples of Binary, Normal or Uniform noise can usually be made at frame rate using noiseUpdate. Updating or building other noise types at frame rate may result in dropped frames. An alternative is to build a large sample of noise at the start of the routien and place it off the screen then cut a samples out of this at random locations and feed that as a numpy array into the texture of a visible gratingStim.

Notes on size If units = pix and noiseType = Binary, Normal or Uniform will make noise sample of requested size. If units = pix and noiseType is Gabor, Isotropic, Filtered, White, Coloured or Image will make square noise sample with side length equal that of the largest dimetions requested. if units is not pix will make square noise sample with side length equal to texRes then rescale to present.

Notes on interpolation For pixel based noise interpolation = nearest is usually best. For other noise types linear is better if the size of the noise sample does not match the final size of the image well.

Notes on frequency Frequencies for cutoffs etc are converted between units for you but can be counter intuitive. 1/size is always 1 cycle per image. For the sf (final spatial frequency) parameter itself 1/size (or None for units pix) will faithfully represent the image without further scaling.

Filter cuttoff and Gabor/Isotropic base frequencies should not be too high you should aim to keep them below 0.5 c/pixel on the screen. The function will produce an error when it can’t draw the stimulus in the buffer but it may still be wrong when displayed.

Notes on orientation and phase The ori parameter twists the final image so the samples in noiseType Binary, Normal or Uniform will no longer be alighned to the sides of the monitor if ori is not a multiple of 90. Most other noise types look broadly the same for all values of ori but the specific sample shown can be made to rotate by changing ori. The dominant orientation for Gabor noise is determined by ori at render time, not before.

The phase parameter similarly shifts the sample around within the display window at render time and will not choose new random phases for the noise sample.

mro() → list¶

return a type’s method resolution order