pulse2percept.percepts

Visual percepts and phosphenes.

base

Percept

class pulse2percept.percepts.Percept(data, space=None, time=None, metadata=None)

Visual percept

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

New in version 0.6.

Parameters:

• data (3D NumPy array) – A NumPy array specifying the percept in (Y, X, T) dimensions
• space (Grid2D) – A grid object specifying the (x,y) coordinates in space
• time (1D array) – A list of time points
• metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.

argmax(axis=None)

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.

get_brightest_frame()

Deprecated since version 0.7: Function get_brightest_frame is deprecated since version 0.7, and will be removed in version 0.8. Use percept.max() instead.

Return the brightest frame

Looks for the brightest pixel in the percept, determines at what point in time it happened, and returns all brightness values at that point in a 2D NumPy array

frame : 2D NumPy array

A slice percept.data[..., tmax] where tmax is the time at which the percept reached its maximum brightness.

max(axis=None)

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)

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

Returns:

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

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

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()

Rewind the iterator

save(fname, shape=None, fps=None)

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.