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.
New 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. Ifaxis
is None, the result is a scalar value. Ifaxis
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
. Ifaxis
is None, the result is a scalar value. Ifaxis
is ‘frames’, the result is the brightest frame.
-
play
(fps=None, repeat=True, annotate_time=True, ax=None)[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
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.
- ’pcolor’: using Matplotlib’s
- 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
- kind ({ 'pcolor', 'hex' }, optional) –
-
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.