pulse2percept.percepts

Visual percepts and phosphenes.

base

Percept
class pulse2percept.percepts.Percept(data, space=None, time=None, metadata=None, n_gray=None, noise=None)[source]

Visual percept

A visual percept in space and time (optional). Typically the output of a computational model.

Added in version 0.6.

Parameters:

  • data (3D NumPy array) – A NumPy array specifying the percept in (Y, X, T) dimensions

  • space (Grid2D, optional) – A grid object specifying the (x,y) coordinates in space

  • time (1D array, optional) – A list of time points

  • metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.

  • n_gray (int, optional) – The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.

  • noise (float or int, optional) – Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.

argmax(axis=None)[source]

Return the indices of the maximum values along an axis

Parameters:

axis (None or 'frames') – Axis along which to operate. By default, the index of the brightest pixel is returned. Set axis='frames' to get the index of the brightest frame.

Returns:

argmax (ndarray or scalar) – Indices at which the maxima of percept.data along an axis occur. If axis is None, the result is a scalar value. If axis is ‘frames’, the result is the time of the brightest frame.

max(axis=None)[source]

Brightest pixel or frame

Parameters:

axis (None or 'frames') – Axis along which to operate. By default, the value of the brightest pixel is returned. Set axis='frames' to get the brightest frame.

Returns:

pmax (ndarray or scalar) – Maximum of percept.data. If axis is None, the result is a scalar value. If axis is ‘frames’, the result is the brightest frame.

play(fps=None, repeat=True, annotate_time=True, ax=None, colorbar=True)[source]

Animate the percept as HTML with JavaScript

The percept will be played in an interactive player in IPython or Jupyter Notebook.

Parameters:

  • fps (float or None) – If None, uses the percept’s time axis. Not supported for non-homogeneous time axis.

  • repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.

  • annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.

  • ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object

  • colorbar ({True, False}) – Whether to show the colorbar

Returns:

ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the percept frame-by-frame.

plot(kind='pcolor', ax=None, **kwargs)[source]

Plot the percept

For a spatial percept, will plot the perceived brightness across the x, y grid. For a temporal percept, will plot the evolution of perceived brightness over time. For a spatiotemporal percept, will plot the brightest frame. Use percept.play() to animate the percept across time points.

Parameters:

  • kind ({ 'pcolor', 'hex' }, optional) –

    Kind of plot to draw:

    • ’pcolor’: using Matplotlib’s pcolor. Additional parameters (e.g., vmin, vmax) can be passed as keyword arguments.

    • ’hex’: using Matplotlib’s hexbin. Additional parameters (e.g., gridsize) can be passed as keyword arguments.

  • ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object

  • **kwargs – Other optional arguments passed down to the Matplotlib function

Returns:

ax (matplotlib.axes.Axes) – Returns the axes with the plot on it

rewind()[source]

Rewind the iterator

save(fname, shape=None, fps=None)[source]

Save the percept as an MP4 or GIF

Parameters:

  • fname (str) – The filename to be created, with the file extension indicating the file type. Percepts with time=None can be saved as images (e.g., ‘.jpg’, ‘.png’, ‘.gif’). Multi-frame percepts can be saved as movies (e.g., ‘.mp4’, ‘.avi’, ‘.mov’) or ‘.gif’.

  • shape ((height, width) or None, optional) – The desired width x height of the resulting image/video. Use (h, None) to use a specified height and automatically infer the width from the percept’s aspect ratio. Analogously, use (None, w) to use a specified width. If shape is None, width will be set to 320px and height will be inferred accordingly.

  • fps (float or None) – If None, uses the percept’s time axis. Not supported for non-homogeneous time axis.

Notes

  • shape will be adjusted so that width and height are multiples

    of 16 to ensure compatibility with most codecs and players.