pulse2percept.io¶

This module provides functions for I/O.

`image`
`video`

pulse2percept.io.image2stim(img, implant, coding='amplitude', valrange=[0, 50], max_contrast=False, const_val=20, invert=False, tsample=5e-06, dur=0.5, pulsedur=0.0005, interphasedur=0.0005, pulsetype='cathodicfirst')[source]¶

Converts an image into a series of pulse trains

This function creates an input stimulus from an RGB or grayscale image. The image is down-sampled to fit the spatial layout of the implant (currently supported are ArgusI and ArgusII arrays). Requires Scikit-Image.

Parameters:

img (str|array_like) – An input image, either a valid filename (string) or a numpy array (row x col x channels).
implant (ProsthesisSystem) – An ElectrodeArray object that describes the implant.
coding ({'amplitude', 'frequency'}, optional) –
A string describing the coding scheme:
- ’amplitude’: Image intensity is linearly converted to a current
  
  amplitude between valrange[0] and valrange[1]. Frequency is held constant at const_freq.
- ’frequency’: Image intensity is linearly converted to a pulse
  
  frequency between valrange[0] and valrange[1]. Amplitude is held constant at const_amp.
Default: ‘amplitude’
valrange (list, optional) – Range of stimulation values to be used (If coding is ‘amplitude’, specifies min and max current; if coding is ‘frequency’, specifies min and max frequency). Default: [0, 50]
max_contrast (bool, optional) – Flag wether to maximize image contrast (True) or not (False). Default: False
const_val (float, optional) – For frequency coding: The constant amplitude value to be used for all pulse trains. For amplitude coding: The constant frequency value to be used for all pulse trains. Default: 20
invert (bool, optional) – Flag whether to invert the grayscale values of the image (True) or not (False). Default: False
tsample (float, optional) – Sampling time step (seconds). Default: 0.005 / 1000 seconds.
dur (float, optional) – Stimulus duration (seconds). Default: 0.5 seconds.
pulsedur (float, optional) – Duration of single (positive or negative) pulse phase in seconds.
interphasedur (float, optional) – Duration of inter-phase interval (between positive and negative pulse) in seconds.
pulsetype ({'cathodicfirst', 'anodicfirst'}, optional) – A cathodic-first pulse has the negative phase first, whereas an anodic-first pulse has the positive phase first.

Returns:

pulses (list) – A list of p2p.stimuli.PulseTrain objects, one for each electrode in the implant.

pulse2percept.io.load_video(filename, as_timeseries=True, as_gray=False, ffmpeg_path=None, libav_path=None)[source]¶

Loads a video from file.

This function loads a video from file with the help of Scikit-Video, and returns the data either as a NumPy array (if as_timeseries is False) or as a TimeSeries object (if as_timeseries is True).

Parameters:

filename (str) – Video file name
as_timeseries (bool, optional, default: True) – If True, returns the data as a TimeSeries object.
as_gray (bool, optional, default: False) – If True, loads only the luminance channel of the video.
ffmpeg_path (str, optional, default: system's default path) – Path to ffmpeg library.
libav_path (str, optional, default: system's default path) – Path to libav library.

Returns:

video (ndarray | TimeSeries) – If as_timeseries is False, returns video data according to the Scikit-Video standard; that is, an ndarray of dimension (T, M, N, C), (T, M, N), (M, N, C), or (M, N), where T is the number of frames, M is the height, N is the width, and C is the number of channels (will be either 1 for grayscale or 3 for RGB).

If as_timeseries is True, returns video data as a TimeSeries object of dimension (M, N, C), (M, N, T), (M, N, C), or (M, N). The sampling rate corresponds to 1 / frame rate.

Examples

Load a video as a TimeSeries object:

>>> from skvideo import datasets
>>> video = load_video(datasets.bikes())
>>> video.tsample
0.04
>>> video.shape
(272, 640, 3, 250)

Load a video as a NumPy ndarray:

>>> from skvideo import datasets
>>> video = load_video(datasets.bikes(), as_timeseries=False)
>>> video.shape
(250, 272, 640, 3)

Load a video as a NumPy ndarray and convert to grayscale:

>>> from skvideo import datasets
>>> video = load_video(datasets.bikes(), as_timeseries=False, as_gray=True)
>>> video.shape
(250, 272, 640, 1)

pulse2percept.io.load_video_framerate(filename, ffmpeg_path=None, libav_path=None)[source]¶

Returns the video frame rate

This function returns the frame rate of the video, as given by its metadata field ‘@r_frame_rate’.

Parameters:	filename (str) – Video file name ffmpeg_path (str, optional, default: system's default path) – Path to ffmpeg library. libav_path (str, optional, default: system's default path) – Path to libav library.
Returns:	fps (float) – Video frame rate (frames per second).

pulse2percept.io.load_video_generator(filename, ffmpeg_path=None, libav_path=None)[source]¶

Returns a generator that can load a video from file frame-by-frame.

This function returns a generator reader that can load a video from a file frame-by-frame. Every call to reader.nextFrame() will return a single frame of the video as a NumPy array with dimensions (M, N) or (M, N, C), where M is the height, N is the width, and C is the number of channels (will be either 1 for grayscale or 3 for RGB).

Parameters:	filename (str) – Video file name ffmpeg_path (str, optional, default: system's default path) – Path to ffmpeg library. libav_path (str, optional, default: system's default path) – Path to libav library.
Returns:	reader (skvideo.io.FFmpegReader \| skvideo.io.LibAVReader) – A Scikit-Video reader object

Examples

>>> from skvideo import datasets
>>> reader = load_video_generator(datasets.bikes())
>>> for frame in reader.nextFrame():
...    pass

pulse2percept.io.load_video_metadata(filename, ffmpeg_path=None, libav_path=None)[source]¶

Returns a video files metadata

This function loads the metadata of a video file, which is returned as a dict. Among the available information are the width and height of the video, the aspect ratio, the frame rate, the bit rate, and the duration.

Parameters:	filename (str) – Video file name ffmpeg_path (str, optional, default: system's default path) – Path to ffmpeg library. libav_path (str, optional, default: system's default path) – Path to libav library.
Returns:	metadata (dict) – A dictionary containing all metadata.

pulse2percept.io.save_video(data, filename, width=None, height=None, fps=30, ffmpeg_path=None, libav_path=None)[source]¶

Saves a video to file.

This function stores a NumPy ndarray to file using Scikit-Video.

Parameters:

data (ndarray | TimeSeries) –
Video data as a NumPy ndarray must have dimension (T, M, N, C), (T, M, N), (M, N, C), or (M, N), where T is the number of frames, M is the height, N is the width, and C is the number of channels (must be either 1 for grayscale or 3 for RGB).

Video data as a TimeSeries object must have dimension (M, N, C, T) or (M, N, T). The sampling step will be used as the video’s frame rate.
filename (str) – Video file name.
width (int, optional) – Desired width of the movie. Default: Automatically determined based on height (without changing the aspect ratio). If height is not given, the percept’s original width is used.
height (int, optional) – Desired height of the movie. Default: Automatically determined based on width (without changing the aspect ratio). If width is not given, the percept’s original height is used.
fps (int, optional, default: 30) – Desired frame rate of the video (frames per second).
ffmpeg_path (str, optional, default: system's default path) – Path to ffmpeg library.
libav_path (str, optional, default: system's default path) – Path to libav library.

Notes

To distinguish between 3-D inputs of shape (T, M, N) and (M, N, C), the last dimension is checked: If it is small (<= 4), it is most likely a color channel - hence the input is interpreted as (M, N, C). Else it is interpreted as (T, M, N).

pulse2percept.io.save_video_sidebyside(videofile, percept, savefile, fps=30, ffmpeg_path=None, libav_path=None)[source]¶

Saves both an input video and the percept to file, side-by-side.

This function creates a new video from an input video file and a :py:class`~pulse2percept.stimuli.TimeSeries` object, assuming they correspond to model input and model output, and plots them side-by-side. Both input video and percept are resampled according to fps. The percept is resized to match the height of the input video.

Parameters:

videofile (str) – File name of input video.
percept (TimeSeries) – A TimeSeries object with dimension (M, N, C, T) or (M, N, T), where T is the number of frames, M is the height, N is the width, and C is the number of channels.
savefile (str) – File name of output video.
fps (int, optional, default: 30) – Desired frame rate of output video.
ffmpeg_path (str, optional, default: system's default path) – Path to ffmpeg library.
libav_path (str, optional, default: system's default path) – Path to libav library.