pulse2percept.stimuli.AmplitudeEncoder

class pulse2percept.stimuli.AmplitudeEncoder(implant=None, amp_range=(0, 50), freq=20, **kwargs)[source]

Encode gray levels as pulse amplitudes

Every electrode emits a pulse train of the same fixed frequency, and the gray level of the pixel it sees sets the amplitude of those pulses. This is how most retinal prostheses encode a video.

Because every electrode shares one pulse period, a raster costs no frequency here: the groups hold fixed offsets from one another and so can never drift together, which means nothing has to be quantized and freq is delivered exactly. With no explicit group_dur the groups also divide that period evenly, one turn each per pulse; an explicit group_dur packs them into a shorter sweep at the start of every period instead. Either way no two groups are ever active at the same instant.

Added in version 0.10.0.

Parameters:

  • implant (Implant, optional) – The implant to encode for. See PulseEncoder.

  • amp_range ((min_amp, max_amp), optional) –

    Range of pulse amplitudes, in uA or in multiples of perceptual threshold (xTh). A gray level of 0 maps onto min_amp and a gray level of 1 onto max_amp.

    Bare numbers mean uA. Both endpoints must carry the same dimension, so a threshold-relative range is spelled (0 * xTh, 3 * xTh); the half spelling (0, 3 * xTh) is rejected rather than guessed at. A threshold-relative range encodes to a xTh stimulus, which an implant converts to current when it has thresholds for every driven electrode.

    Changed in version 0.11.0: Accepts xTh as well as current.

  • freq (float, optional) –

    Pulse train frequency (Hz), the same for every electrode. The pulse clock runs independently of the video, so the frame rate has no say in the rate delivered. Because every electrode shares this one period, a raster does not quantize it either: the groups keep a fixed offset from one another and cannot drift together. Only clock can lower it, by rounding the period up to a whole number of cycles.

    Note

    A frequency below the frame rate is realizable, but wasteful: some frames then receive no pulse at all and their gray levels are never delivered. Encoding warns when this happens.

  • phase_dur – See PulseEncoder.

  • interphase_dur – See PulseEncoder.

  • cathodic_first – See PulseEncoder.

  • frame_dur – See PulseEncoder.

  • stretch – See PulseEncoder.

Notes

  • Arguments may be given as plain numbers in the units documented above, or as unitful quantities (e.g. 0.05 * mA, 460 * us, 0.02 * kHz), which are converted to those units. See pulse2percept.units.

Examples

Encode a movie for Argus II, mapping gray levels onto 0-50 uA at 20 Hz:

>>> import numpy as np
>>> import pulse2percept as p2p
>>> video = p2p.stimuli.VideoStimulus(np.random.rand(16, 20, 30),
...                                   metadata={'fps': 20})
>>> implant = p2p.implants.retina.ArgusII()
>>> encoder = p2p.stimuli.AmplitudeEncoder(implant, amp_range=(0, 50))
>>> stim = encoder.encode(video)

The same thing, with the implant encoding its own input:

>>> implant.encoder = p2p.stimuli.AmplitudeEncoder(amp_range=(0, 50))
>>> stim = implant.prepare_stim(video)
__init__(implant=None, amp_range=(0, 50), freq=20, **kwargs)[source]

Methods

__init__([implant, amp_range, freq])

encode(source)

Encode an image or a video as a train of electrical pulses

Attributes

amp_range

freq

amp_unit

Unit of amplitudes returned by _modulate

cathodic_first

clock

frame_dur

implant

The implant this encoder is bound to, or None (read-only)

interphase_dur

n_levels

phase_dur

pulse

stretch

amp_unit

Unit of amplitudes returned by _modulate

encode(source)[source]

Encode an image or a video as a train of electrical pulses

Parameters:

source (Stimulus) – The image or video to encode. Gray levels are expected in [0, 1], which is what ImageStimulus and VideoStimulus produce. It must be dimensionless: this method is the boundary at which a picture becomes stimulation, so an electrical stimulus is not a valid source for it.

Returns:

stim – The encoded stimulus, ready for the implant to deliver. Its amplitudes are in microamps, or in threshold multiples (xTh) if the encoder’s amplitude parameters were, and its time axis is in milliseconds, whatever units the encoder’s own parameters were given in.

Return type:

Stimulus

Raises:

DimensionMismatchError – If source is not dimensionless.

property implant

The implant this encoder is bound to, or None (read-only)