pulse2percept.percepts
Visual percepts and phosphenes.
- 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 spacetime (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
- 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 multiplesof 16 to ensure compatibility with most codecs and players.