API Reference

The seekcamera package exposes all public classes, enumerations, and exceptions needed to discover Seek Thermal OEM camera cores, configure their image-processing pipelines, and consume thermal frame data in Python. Import directly from the top-level seekcamera namespace to access every symbol documented here. This reference covers every public type in version 1.3.0 of the library.

Most API entry points are methods on the SeekCameraManager and SeekCamera classes rather than module-level functions. The table below lists every constructable public class or enumeration and its constructor parameters where applicable.

Key SeekCamera methods

SeekCameraManager usage

SeekCameraManager is used as a context manager. Its constructor accepts a bitwise OR of SeekCameraIOType values.

SeekCameraColorPaletteData constructor

SeekCameraFirmwareVersion constructor

Return values depend on whether you are calling a getter method, a context manager, or registering a callback.

• SeekCameraManager.__enter__ — Returns the SeekCameraManager instance itself, allowing with SeekCameraManager(...) as manager: usage.
• SeekCamera.get_color_palette() — Returns a SeekCameraColorPalette enum member.
• SeekCamera.get_pipeline_mode() — Returns a SeekCameraPipelineMode enum member.
• SeekCamera.get_agc_mode() — Returns a SeekCameraAGCMode enum member.
• SeekCamera.get_thermography_window() — Returns a 4-tuple (x, y, width, height) of int.
• SeekCamera.get_firmware_version() — Returns a SeekCameraFirmwareVersion instance.
• SeekCamera.get_chipid() — Returns a str of up to 16 characters.
• SeekCamera.get_serial_number() — Returns a str of up to 16 characters.
• SeekCamera.get_core_part_number() — Returns a str of up to 32 characters.
• SeekCamera.get_io_type() — Returns a SeekCameraIOType enum member.
• SeekCamera.get_io_properties() — Returns a SeekCameraIOProperties instance whose .usb or .spi field is populated according to .type.
• Setter methods (set_color_palette, set_pipeline_mode, etc.) — Return None; they raise on failure.
• Frame callback (register_frame_available_callback) — Your callback receives (camera: SeekCamera, camera_frame: SeekCameraFrame, user_data: Any) and must return None.
• SeekFrame.data — A NumPy ndarray whose dtype and shape depend on the frame format requested at session start.
• SeekCameraColorPaletteData.__len__() — Always returns 256.
• is_error(status) — Returns bool; True when status != 0.
• error_from_status(status) — Returns the most-specific SeekCameraError subclass that matches the given status code, or SeekCameraError itself when no subclass matches.

All errors raised by this library are subclasses of SeekCameraError and originate from the underlying Seek Thermal C SDK status codes.

Import the package

All public symbols are available from the top-level namespace:

from seekcamera import (
    SeekCameraManager,
    SeekCameraIOType,
    SeekCameraManagerEvent,
    SeekCameraFrameFormat,
)

Connect to a USB camera and capture frames

The most common workflow: create a manager, register an event callback, start a capture session inside the CONNECT event, and process frames in a frame-available callback.

from seekcamera import (
    SeekCameraManager,
    SeekCameraIOType,
    SeekCameraManagerEvent,
    SeekCameraFrameFormat,
)

def on_frame(camera, camera_frame, user_data):
    # Retrieve the thermography floating-point frame
    frame = camera_frame.thermography_float
    print(f"Frame shape: {frame.data.shape}, dtype: {frame.data.dtype}")

def on_event(camera, event_type, error, user_data):
    if event_type == SeekCameraManagerEvent.CONNECT:
        camera.register_frame_available_callback(on_frame, user_data=None)
        camera.capture_session_start(SeekCameraFrameFormat.THERMOGRAPHY_FLOAT)

    elif event_type == SeekCameraManagerEvent.DISCONNECT:
        print(f"Camera disconnected: {camera.get_serial_number()}")

    elif event_type == SeekCameraManagerEvent.ERROR:
        print(f"Camera error: {error}")

    elif event_type == SeekCameraManagerEvent.READY_TO_PAIR:
        print("Camera is unpaired — pairing required before use.")

with SeekCameraManager(SeekCameraIOType.USB) as manager:
    manager.register_event_callback(on_event, user_data=None)
    input("Press ENTER to stop...\n")

Expected output (example):

Frame shape: (156, 206), dtype: float32
Frame shape: (156, 206), dtype: float32
...

Read camera identity information

def on_event(camera, event_type, error, user_data):
    if event_type == SeekCameraManagerEvent.CONNECT:
        print("Serial number :", camera.get_serial_number())
        print("Chip ID       :", camera.get_chipid())
        print("Part number   :", camera.get_core_part_number())
        print("Firmware      :", camera.get_firmware_version())
        print("IO type       :", camera.get_io_type())

Expected output:

Serial number : A1BC234567890DEF
Chip ID       : ABCD1234EFGH5678
Part number   : SX00X-0000-0000
Firmware      : 1.5.3.0
IO type       : USB

Set a color palette and AGC mode

from seekcamera import SeekCameraColorPalette, SeekCameraAGCMode

def on_event(camera, event_type, error, user_data):
    if event_type == SeekCameraManagerEvent.CONNECT:
        camera.set_color_palette(SeekCameraColorPalette.IRON)
        camera.set_agc_mode(SeekCameraAGCMode.HISTEQ)
        camera.capture_session_start(SeekCameraFrameFormat.COLOR_ARGB8888)

Upload a custom color palette

Custom palettes must target one of the USER_0 – USER_4 slots.

from seekcamera import SeekCameraColorPalette, SeekCameraColorPaletteData

# Build a simple greyscale ramp
palette_data = SeekCameraColorPaletteData(
    data=[(i, i, i, 255) for i in range(256)]  # (b, g, r, a)
)

def on_event(camera, event_type, error, user_data):
    if event_type == SeekCameraManagerEvent.CONNECT:
        camera.set_color_palette_data(SeekCameraColorPalette.USER_0, palette_data)
        camera.set_color_palette(SeekCameraColorPalette.USER_0)
        camera.capture_session_start(SeekCameraFrameFormat.COLOR_ARGB8888)

Set the thermography ROI window

def on_event(camera, event_type, error, user_data):
    if event_type == SeekCameraManagerEvent.CONNECT:
        # Restrict thermography calculations to a 100×80 pixel window
        # starting at pixel (20, 10)
        camera.set_thermography_window(x=20, y=10, w=100, h=80)
        camera.capture_session_start(SeekCameraFrameFormat.THERMOGRAPHY_FLOAT)

Check the library version

from seekcamera import SeekCameraVersion

v = SeekCameraVersion()
print(v)        # 1.3.0
print(repr(v))  # SeekCameraVersion(1, 3, 0)

Expected output:

1.3.0
SeekCameraVersion(1, 3, 0)

Handle errors defensively

from seekcamera import SeekCameraError, SeekCameraNotPairedError

def on_event(camera, event_type, error, user_data):
    if event_type == SeekCameraManagerEvent.CONNECT:
        try:
            camera.capture_session_start(SeekCameraFrameFormat.THERMOGRAPHY_FLOAT)
        except SeekCameraNotPairedError:
            print("Camera must be paired before starting a capture session.")
        except SeekCameraError as exc:
            print(f"Unexpected camera error: {exc}")

Iterate a SeekCameraColorPaletteData object

from seekcamera import SeekCameraColorPaletteData

palette_data = SeekCameraColorPaletteData()
palette_data[0:3] = [(255, 0, 0, 255), (0, 255, 0, 255), (0, 0, 255, 255)]

for index, value in enumerate(palette_data):
    if index < 3:
        print(index, value)

Expected output:

0 (255, 0, 0, 255)
1 (0, 255, 0, 255)
2 (0, 0, 255, 255)

SeekCameraColorPalette — full member list

Shutter mode is Mosaic Core-only

SeekCameraShutterMode and any shutter-related API calls apply only to Mosaic Core devices. Calling shutter APIs on non-Mosaic devices raises SeekCameraNotSupportedError.

SeekCameraManager must be used as a context manager

Always use with SeekCameraManager(...) as manager: to guarantee that the underlying C handle is properly destroyed. Failing to exit the context manager cleanly can leave camera handles dangling, preventing reconnection until the process restarts.

Frame callbacks execute on an internal SDK thread

Your frame-available callback is invoked from a thread managed by the Seek Thermal C SDK, not from your main Python thread. Avoid blocking I/O, GUI updates, or long-running computations inside the callback. Copy or queue the data for processing on another thread if needed.

SeekCameraFrame lifetime

The SeekCameraFrame object (and the underlying pixel buffers it references) is only valid for the duration of the callback invocation. If you need to retain pixel data beyond the callback, copy frame.data (a NumPy array) using frame.data.copy().

READY_TO_PAIR vs. CONNECT

A freshly manufactured or factory-reset camera emits READY_TO_PAIR instead of CONNECT. In this state the camera has no stored calibration on the host. You must initiate pairing (e.g., call store_calibration_data) before the camera will transition to the CONNECT state on subsequent connections. Attempting to start a capture session on an unpaired camera raises SeekCameraNotPairedError.

Shared library discovery

The seekcamera package loads libseekcamera.so (Linux/macOS) or seekcamera.dll (Windows) at import time via ctypes. The library must be on the system library path or reachable through the SEEKTHERMAL_LIB_DIR environment variable. On Windows, if SEEKTHERMAL_LIB_DIR is not set, the loader searches the default install directory C:\Program Files\Seek Thermal\Seek Thermal SDK\ and requires SDK version ≥ 4.2.0. Import will raise RuntimeError — not a SeekCameraError — if the shared library cannot be found or if the runtime version requirement is not met.

SeekCameraColorPaletteData colour channel order

Tuples are ordered (b, g, r, a) — not the more common (r, g, b, a). Swapping channels will produce incorrect colours without raising an error.

SeekCameraLinearAGCLockMode affects output range mapping

Regardless of which lock mode is active, the output range is always linearly stretched across the interval [0, 255]. The lock mode only controls how the minimum and maximum bounding values are determined (automatically from the scene, or manually supplied by you).

error_from_status is for advanced use

error_from_status(status) and is_error(status) are low-level helpers used internally by the library to translate C SDK status integers into Python exceptions. You do not need to call these functions in normal application code — the library raises the appropriate exception automatically. They are useful if you are extending or wrapping the C layer yourself.