pulse2percept.stimuli.PhotovoltaicEncoder

class pulse2percept.stimuli.PhotovoltaicEncoder(implant=None, *, irradiance, freq, pulse_dur, wavelength, grayscale=True, threshold=0.5)[source]

Encode image/video gray levels as pulsed optical stimulation

Photovoltaic subretinal arrays are driven by pulsed near-infrared light. This encoder samples an image or video at the implant’s pixel locations and returns irradiance in mW/mm^2. Peak irradiance is fixed; gray level sets the ON duration within each pulse period.

Added in version 0.11.0.

Changed in version 0.11.0: The implant is passed to the constructor rather than to encode(). The optical parameters are keyword-only.

Parameters:

  • implant (Implant, optional) – The implant to encode for. Its pixel locations are used to sample images and videos and its pixel names label the result. If None, every pixel of the source is its own photovoltaic pixel.

  • irradiance (float or Quantity) – Peak irradiance (mW/mm^2) while a pixel is on.

  • freq (float or Quantity) – Pulse repetition rate (Hz).

  • pulse_dur (float or Quantity) – ON duration (ms) of a fully lit pixel. Must fit into 1000 / freq.

  • wavelength (float or Quantity) – Wavelength (nm) of the illumination. Photovoltaic pixel response is wavelength dependent, so there is no generic default.

  • grayscale (bool, optional) – If True (default), map gray levels to ON duration. If False, use binary off/on encoding.

  • threshold (float, optional) – Binary-mode threshold. The default 0.5 is a pulse2percept convention.

Notes

  • Grayscale mode scales ON duration linearly, gray * pulse_dur. The studies these arrays come from report fixed-duration pulses and do not specify a natural-image grayscale transfer function, so this mapping is a pulse2percept simulation convention, not the experimental encoding protocol. Because durations are continuous, an image with many gray levels produces more distinct time points than a device that quantizes duration (see PRIMAEncoder).

  • Videos are sampled at the pulse rate using zero-order hold.

  • _spatial_view returns normalized time-averaged optical drive, where 1.0 is a fully lit pixel at these settings (ref_drive). It is neither retinal current nor perceptual brightness.

  • Photovoltaic conversion to retinal current is not modeled.

Examples

>>> from pulse2percept.implants.retina import Lorach2015Array
>>> from pulse2percept.stimuli import PhotovoltaicEncoder, samples
>>> encoder = PhotovoltaicEncoder(Lorach2015Array(), irradiance=4,
...                               freq=40, pulse_dur=4, wavelength=915)
>>> encoder.encode(samples.logo_bvl()).unit
mW/mm^2
__init__(implant=None, *, irradiance, freq, pulse_dur, wavelength, grayscale=True, threshold=0.5)[source]

Methods

__init__([implant, grayscale, threshold])

encode(source)

Encode an image or a video as near-infrared irradiance

Attributes

irradiance

freq

pulse_dur

wavelength

grayscale

threshold

implant

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

period

Pulse period (ms)

ref_drive

Time-averaged irradiance (mW/mm^2) the normalized view calls 1.0
property period

Pulse period (ms)

property ref_drive

Time-averaged irradiance (mW/mm^2) the normalized view calls 1.0

A fully lit pixel at these settings. Devices with a documented projector maximum normalize against that maximum instead.

encode(source)[source]

Encode an image or a video as near-infrared irradiance

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.

Returns:

stim – The projected irradiance, in mW/mm^2, with a time axis in milliseconds. The waveform is generated only when samples are asked for.

Return type:

Stimulus

Raises:

DimensionMismatchError – If source is not dimensionless.

property implant

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