repository·main·Indexed 42 days ago
https://github.com/ap--/python-seabreezeA Python library for accessing Ocean Optics spectrometers. It provides a wrapper around the official SeaBreeze C library (cseabreeze) and a pyUSB-based pure Python reimplementation (pyseabreeze) for cross-platform compatibility and easier extension. The library includes the Spectrometer class for model-independent hardware interaction and the seabreeze_os_setup tool for automating driver and udev rule installation on Windows and Linux.
python-seabreeze is a Python module designed to provide easy access to Ocean Optics spectrometers. It acts as a wrapper around the official SeaBreeze library provided by Ocean Optics to facilitate communication with the hardware.
If the official SeaBreeze library is not available on the system, the module can fall back to a pyUSB-based reimplementation to maintain functionality.
The seabreeze_os_setup tool performs different actions based on your operating system:
It automates the installation of udev rules to grant permission to access the spectrometer:
10-oceanoptics.rules file./etc/udev/rules.d/ (with mode 644).sudo udevadm control --reload-rules to apply the changes.It automates the driver installation process:
windows-driver-files.zip archive.pnputil -i -a *.inf within the extracted folder using an administrative shell.No additional setup is required. Running seabreeze_os_setup on macOS is a no-op.
python-seabreeze provides two backend interfaces for communicating with spectrometers:
cseabreeze: The default backend. It is a wrapper around the official Ocean Optics seabreeze C++ library. It is highly feature-complete but difficult to extend if you are not familiar with C++ and Cython.pyseabreeze: A pure Python implementation that uses pyUSB to communicate via the Ocean Binary Protocol. It is easier to extend for Python developers but is currently less feature-complete than cseabreeze.Functionality for specific spectrometer tasks is organized into feature classes. You do not instantiate these classes directly. Instead, they are provided through the features property or the shorthand f property on a SeaBreezeDevice instance.
Example access pattern:
# Accessing features via the 'features' property
feature = device.features.SeaBreezeSpectrometerFeature
# Accessing features via the 'f' shorthand
feature = device.f.SeaBreezeSpectrometerFeatureYou can initialize a Spectrometer object using several methods depending on how you want to identify the device:
Spectrometer.from_first_available() to quickly connect to the first detected device.list_devices() to get a list of all available SeaBreezeDevice objects, then pass a specific device to the Spectrometer constructor.Spectrometer.from_serial_number("SERIAL_NUMBER") to connect to a specific device via its unique serial number.# option 1: first available
from seabreeze.spectrometers import Spectrometer
spec = Spectrometer.from_first_available()
# option 2: from a list of devices
from seabreeze.spectrometers import Spectrometer, list_devices
devices = list_devices()
spec = Spectrometer(devices[1])
# option 3: by serial number
from seabreeze.spectrometers import Spectrometer
spec = Spectrometer.from_serial_number("F01234")You can install seabreeze using pip. Depending on which backend you require, use one of the following commands:
# install only cseabreeze backend
pip install seabreeze
# install both cseabreeze and pyseabreeze backend
pip install seabreeze[pyseabreeze]
# install only pyseabreeze backend
pip install seabreeze[pyseabreeze] --no-use-pep517 --no-build-isolation --install-option="--without-cseabreeze"If you need to build python-seabreeze from source, follow these steps to install dependencies and compile the package.
Linux
Install a compiler and libusb development headers based on your distribution:
sudo apt-get install git-all build-essential libusb-devsudo yum install git-all gcc gcc-c++ make libusb-develsudo pacman -S base-devel libusb libusb-compat libusb-devel make gccOSX Ensure you have the latest XCode installed.
Windows
Using chocolatey, install the build environment and Windows Driver Kit:
choco install visualcpp-build-tools
choco install windows-sdk-10.1
choco install windowsdriverkit10Upgrade pip to the latest version:
python -m pip install --upgrade pipClone the repository and install using pip:
git clone https://github.com/ap--/python-seabreeze.git python-seabreeze
cd python-seabreeze
python -m pip install .# Example for Debian/Ubuntu
sudo apt-get install git-all build-essential libusb-dev
# Example for Windows (via Chocolatey)
choco install visualcpp-build-tools
choco install windows-sdk-10.1
choco install windowsdriverkit10
# Final build steps
git clone https://github.com/ap--/python-seabreeze.git python-seabreeze
cd python-seabreeze
python -m pip install .To allow user-space access to USB spectrometers, you must run the seabreeze_os_setup script provided with the installation. This script performs the following:
udev rules.Run the following command in your terminal:
$ seabreeze_os_setupInstall the seabreeze Python module using pip. Note that this module includes binary extensions.
$ pip install seabreezeAfter installing seabreeze via pip, conda, or manual build, you must run the provided setup script to complete operating system-specific configurations. This is a required step for the library to function correctly on your OS.
seabreeze_os_setupIt is recommended to install the conda-forge package when working within a conda environment instead of using pip. Note that the package name was changed from python-seabreeze to seabreeze to match PyPI naming.
Use the following command to install from the conda-forge channel:
conda install -c conda-forge seabreezeTo use the pyseabreeze backend (which requires pyusb), you must call seabreeze.use('pyseabreeze') before importing seabreeze.spectrometers.
import seabreeze
seabreeze.use('pyseabreeze')
import seabreeze.spectrometers as sb