API Reference

The public api of seabreeze is provided by the seabreeze.spectrometers submodule. The basic features to acquire a spectrum are provided for all spectrometer models independent of the backend.



Provides a list of available instances of SeaBreezeDevice

seabreeze.spectrometers.list_devices() list[SeaBreezeDevice][source]

returns available SeaBreezeDevices

list all connected Ocean Optics devices supported


devices (list[SeaBreezeDevice]) – connected Spectrometer instances


The Spectrometer class is used to access spectrometer features.

class seabreeze.spectrometers.Spectrometer(device: SeaBreezeDevice)[source]

Spectrometer class for all supported spectrometers

__init__(device: SeaBreezeDevice) None[source]

create a Spectrometer instance for the provided device

The Spectrometer class provides a thin abstraction layer for the basic spectrometer feature of the provided SeaBreezeDevice.


device (seabreeze.spectrometers.SeaBreezeDevice) – a SeaBreezeDevice as returned from list_devices

classmethod from_first_available() Spectrometer[source]

open first available spectrometer


spectrometer (Spectrometer) – the first available supported spectrometer

classmethod from_serial_number(serial: str | None = None) Spectrometer[source]

open the spectrometer matching the provided serial number

Allows to open a specific spectrometer if multiple are connected. Spectrometer serial numbers are visible in the repr string of each SeaBreezeDevice or their serial_number attribute.


serial (str, optional) – the spectrometer’s serial number. If None (default) it returns the first available unopened spectrometer.


spectrometer (Spectrometer) – the spectrometer with the requested serial number

wavelengths() NDArray[numpy.float_][source]

wavelength array of the spectrometer

wavelengths in (nm) corresponding to each pixel of the spectrometer


wavelengths (numpy.ndarray) – wavelengths in (nm)

intensities(correct_dark_counts: bool = False, correct_nonlinearity: bool = False) NDArray[numpy.float_][source]

measured intensity array in (a.u.)

Measured intensities as numpy array returned by the spectrometer. The measuring behavior can be adjusted by setting the trigger mode. Pixels at the start and end of the array might not be optically active so interpret their returned measurements with care. Refer to the spectrometer’s datasheet for further information.


Intensities are in arbitrary units and the range depends on the ADC bit resolution of the hardware used in the specific spectrometer. Some spectrometers store a saturation value in their eeprom, which is used to rescale the raw ADC output to the full bit range. (This is done in libseabreeze and therefore also in cseabreeze — for compatibility reasons the same is done in pyseabreeze) I.e. this means that a 16bit (max value 65535) spectrometer with a saturation value of ~30000 is effectively only returning ~15bit resolution raw readings. While most of the lower bits are dominated by noise anyways, it’s just something to keep in mind. Refer to pyseabreeze.features.spectrometer._SeaBreezeSpectrometerSaturationMixin for the implementation.

  • correct_dark_counts (bool) – If requested and supported the average value of electric dark pixels on the ccd of the spectrometer is subtracted from the measurements to remove the noise floor in the measurements caused by non optical noise sources.

  • correct_nonlinearity (bool) – Some spectrometers store non linearity correction coefficients in their eeprom. If requested and supported by the spectrometer the readings returned by the spectrometer will be linearized using the stored coefficients.


intensities (numpy.ndarray) – measured intensities in (a.u.)

property max_intensity: float

return the maximum intensity of the spectrometer


max_intensity (float) – the maximum intensity that can be returned by the spectrometer in (a.u.) It’s possible that the spectrometer saturates already at lower values.

spectrum(correct_dark_counts: bool = False, correct_nonlinearity: bool = False) NDArray[numpy.float_][source]

returns wavelengths and intensities as single array

Convenience method to allow:

>>> spec = Spectrometer.from_first_available()
>>> wavelengths, intensities = spec.spectrum()
  • correct_dark_counts (bool) – see Spectrometer.intensities

  • correct_nonlinearity (bool) – see Spectrometer.intensities


spectrum (numpy.ndarray) – combined array of wavelengths and measured intensities

integration_time_micros(integration_time_micros: int) None[source]

set the integration time in microseconds


integration_time_micros (int) – integration time in microseconds

property integration_time_micros_limits: tuple[int, int]

return the hardcoded minimum and maximum integration time


integration_time_micros_min_max (tuple[int, int]) – min and max integration time in micro seconds

trigger_mode(mode: int) None[source]

set the trigger mode of the device


mode (int) – refer to your spectrometer’s datasheet to determine the correct value for the trigger mode you want to use.

property serial_number: str

the spectrometer’s serial number

property model: str

the spectrometer’s model type

property pixels: int

the spectrometer’s number of pixels

property features: SeaBreezeFeatureDict

return a dictionary of all supported features

this returns a dictionary with all supported Features of the spectrometer and gives direct access to the features provided by the backend interface.


features – a dictionary mapping feature names to lists of feature instances. An empty list means the feature is not available.

property f: SeaBreezeFeatureAccessor

convenience assess to features via attributes

this allows you to access a feature like this:

>>> spec = Spectrometer.from_first_available()
>>> # via .features
>>> spec.features['eeprom'][0].eeprom_read_slot(4)
>>> # via .f
>>> spec.f.eeprom.eeprom_read_slot(4)
open() None[source]

open the connection to the SeaBreezeDevice


Normally you do not have to call this function manually. If you’re trying to use the same spectrometer from multiple processes (honestly, why would you?) then this might come in handy. But I’ll leave the lock/semaphore handling to you.

close() None[source]

close the connection to the SeaBreezeDevice


Normally you do not have to call this function manually. If you’re trying to use the same spectrometer from multiple processes (honestly, why would you?) then this might come in handy. But I’ll leave the lock/semaphore handling to you.


SeaBreezeError is the default exception raised by the backend libraries.

class seabreeze.spectrometers.SeaBreezeError(message=None, error_code=None)