pulse2percept.stimuli.PRIMAEncoder

class pulse2percept.stimuli.PRIMAEncoder(implant=None, irradiance=3.5 mW/mm^2, freq=30 Hz, pulse_dur=9.8 ms, grayscale=True, threshold=0.5)

Encode image/video gray levels for the PRIMA projector.

PRIMA uses 880 nm illumination rather than injected current. The projector uses fixed peak irradiance and pulse-width modulation [Palanker2020], [Holz2026]. This encoder returns irradiance in mW/mm^2.

Unlike the generic PhotovoltaicEncoder, ON durations are quantized onto the projector’s own 0.7 ms duration grid, and normalized drive is referenced to the projector maximum rather than to these settings.

Added in version 0.11.0.

Parameters:

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

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

• freq (float or Quantity, optional) – Projector frame rate (Hz).

• pulse_dur (float or Quantity, optional) – Maximum ON duration (ms). Must lie on the pulse_step grid and not exceed max_pulse_dur.

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

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

Notes

• Pivotal-system defaults are 3.5 mW/mm^2, 30 Hz, and 14 nonzero ON durations from 0.7 to 9.8 ms.

• Grayscale mode maps normalized intensity linearly to these duration levels. The clinical camera-to-pulse-duration transfer function is not published.

• Videos are sampled at the projector clock using zero-order hold.

• _spatial_view returns normalized time-averaged optical drive for spatial models. It is neither retinal current nor perceptual brightness.

• Clinical image preprocessing is outside this encoder.

Examples

>>> from pulse2percept.implants.retina import PRIMAPivotal
>>> from pulse2percept.stimuli import PRIMAEncoder, samples
>>> PRIMAEncoder(PRIMAPivotal()).encode(samples.logo_bvl()).unit
mW/mm^2

__init__(implant=None, irradiance=3.5 mW/mm^2, freq=30 Hz, pulse_dur=9.8 ms, grayscale=True, threshold=0.5)

Methods

__init__([implant, irradiance, freq, ...])
encode(source)	Encode an image or a video as near-infrared irradiance

Attributes

freq
grayscale
implant	The implant this encoder is bound to, or None (read-only)
irradiance
max_duty_cycle	Largest documented duty cycle, max_freq * max_pulse_dur
max_freq	Frame rate (Hz) of the pivotal-trial projector
max_irradiance	Peak irradiance (mW/mm^2) of the pivotal-trial projector
max_pulse_dur	Longest documented ON duration (ms), i.e. 14 steps.
n_levels	Number of nonzero ON durations available up to pulse_dur
period	Pulse period (ms)
projector_wavelength	Wavelength (nm) the projector illuminates at
pulse_dur
pulse_step	Smallest nonzero ON duration (ms) the projector can produce; every other duration is a whole multiple of it
ref_drive	Time-averaged irradiance (mW/mm^2) the normalized spatial view calls 1.0.
threshold
wavelength

pulse_step = 0.7

Smallest nonzero ON duration (ms) the projector can produce; every other duration is a whole multiple of it

max_pulse_dur = 9.8

Longest documented ON duration (ms), i.e. 14 steps

projector_wavelength = 880.0

Wavelength (nm) the projector illuminates at

max_irradiance = 3.5

Peak irradiance (mW/mm^2) of the pivotal-trial projector

max_freq = 30.0

Frame rate (Hz) of the pivotal-trial projector

max_duty_cycle = 0.294

Largest documented duty cycle, max_freq * max_pulse_dur

ref_drive = 1.029

Time-averaged irradiance (mW/mm^2) the normalized spatial view calls 1.0. Fixed at the projector maximum, so lowering any setting lowers the normalized drive.

property n_levels

Number of nonzero ON durations available up to pulse_dur

encode(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)

property period

Pulse period (ms)