Integrating Teledyne DALSA GigE Cameras with Python

Introduction

Here’s an enhanced introduction section incorporating area scan camera fundamentals and SDK criticality, synthesized from authoritative sources:

---

The Essential Role of Area Scan Cameras in Industrial Vision

Area scan cameras capture complete 2D images through pixel matrix sensors during each exposure cycle, making them indispensable for high-precision inspection tasks. Unlike line-scan alternatives, they excel at:

• Static/Object Inspection: Capturing dimensional measurements and surface defects on stationary or slow-moving items
• Robotics Guidance: Providing spatial coordinates for automated assembly and bin picking
• Rapid Quality Control: Freezing motion artifacts in high-speed production (e.g., electronics, automotive)

Industrial variants (e.g., Teledyne’s Blackfly S, Basler’s ace 2) deliver VGA–127MP resolutions with hardened enclosures (IP65/IP67), operating under extreme temperatures and vibrations . GigE models dominate machine vision due to:

• RAW data transfer for uncompressed image integrity
• PoE (Power over Ethernet) capabilities simplifying cabling
• Microsecond-precise triggering for high-speed conveyor applications

Why SDKs Are the Backbone of Vision Systems

Software Development Kits (SDKs) bridge hardware capabilities and application-specific logic. Robust vision SDKs like Teledyne’s Sapera/FlyCapture or Basler’s pylon provide:

• Unified Hardware Abstraction
  Common APIs for GigE/USB3/FireWire cameras across OSs (Windows/Linux)
• Accelerated Development
  Prebuilt tools for camera configuration, I/O control, and image acquisition
• Multilingual Support
  C++, C#, Python, and MATLAB interfaces with sample code
• Third-Party Integration
  Compliance with GenICam standards and OpenCV/ROS compatibility

However, Teledyne’s Sapera SDK historically lacked native Python bindings—creating barriers for AI/ML-centric workflows. This gap necessitated custom C++-to-Python interfaces .

---

Key Industrial Applications Enabled by Area Scan Cameras

Industry	Use Case	Camera Requirements
Automotive	Assembly verification	High-res 3D (e.g., Cognex 3D-A5000)
Electronics	Solder joint inspection	5+ MP resolution, HDR mode
Medical Diagnostics	Microscopy/cell analysis	>95% QE, cooling for low noise
Logistics	Package dimensioning	Global shutter, 100+ fps capability
Agriculture	Fruit defect detection	SWIR sensors for bruise identification

---

The SDK Integration Challenge

While vendors like Teledyne offer FlyCapture SDK (supporting Python) for newer cameras , legacy GigE systems often rely on Sapera—a C++-only framework. This forces:

1. Complex Workarounds: Wrapping C++ libraries via DLLs and ctypes
2. Resource Contention Risks: “Resource in use” errors during improper handle release
3. Cross-Version Fragility: API inconsistencies between Sapera LT versions

Our solution overcomes these by combining:

• Hardware-Agnostic C++ Wrappers with Python bindings
• Resource Locking Mechanisms via SapManager::CleanServer()
• Dynamic Pixel Format Handling adapting to Mono8/Mono16/RGB modes

Why This Matters: Direct SDK control enables 200ms 3D scans for robotic sorting and µm-level battery electrode inspections —impossible with generic webcams.

---

This foundation contextualizes the technical hurdles addressed in our integration architecture, positioning the solution within industrial imaging’s evolving demands. For deployment specifics, proceed to the Implementation section.

Architecture Overview

Our solution uses a three-layer architecture:

Key Challenges and Solutions

1. Sapera SDK Integration Issues

Problem: Sapera SDK headers were located in non-standard paths across different versions
Solution: Adaptive CMake configuration

set(SAPERA_BASE "C:/Program Files/Teledyne DALSA/Sapera")
set(SAPERA_INCLUDES
    "${SAPERA_BASE}/Classes/Basic"
    "${SAPERA_BASE}/Classes/Core"
    "${SAPERA_BASE}/Include"
)

2. Resource Management Errors

Problem: “Server index out of range” and “Resource in use” errors
Solution: Proper camera discovery and resource cleanup

bool discover_camera(const char* mac, SapLocation& location) {
    return SapManager::GetLocationFromMacAddress(mac, location);
}

void cleanup_resources(const char* mac) {
    SapLocation location;
    if (SapManager::GetLocationFromMacAddress(mac, location)) {
        SapManager::CleanServer(location);
        SapManager::UnloadServer(location.GetServerName());
    }
}

3. API Compatibility Issues

Problem: Sapera API differences between SDK versions
Solution: Version-adaptive implementation

int get_bytes_per_pixel(int format) {
    // Simplified format handling for compatibility
    if (format == SapFormatMono8) return 1;
    if (format == SapFormatRGB888) return 3;
    return 2; // Default for Mono16 and others
}

Complete C++ Wrapper Implementation

DalsaCamera.h

#pragma once
#include <SapClassBasic.h>
#include <SapManager.h>

#ifdef _WIN32
    #define API_EXPORT __declspec(dllexport)
#else
    #define API_EXPORT
#endif

extern "C" {
    API_EXPORT void* initialize_camera(const char* mac);
    API_EXPORT int capture_image(void* camera, unsigned char* buffer, int buffer_size);
    API_EXPORT void release_camera(void* camera);
    API_EXPORT int get_image_size(void* camera);
    API_EXPORT int get_image_width(void* camera);
    API_EXPORT int get_image_height(void* camera);
    API_EXPORT void cleanup_resources(const char* mac);
}

DalsaCamera.cpp

#include "DalsaCamera.h"
#include <cstring>
#include <string>

class CameraWrapper {
public:
    CameraWrapper(const char* mac) : mac_address(mac) {
        // Cleanup any existing resources
        cleanup_resources(mac_address.c_str());

        // Allow time for resource release
        SapManager::SetResourceTimeout(5000);

        // Discover camera location
        if (!SapManager::GetLocationFromMacAddress(mac_address.c_str(), location)) {
            throw std::runtime_error("Camera not found with MAC: " + mac_address);
        }

        // Initialize with discovered location
        acq_device = new SapAcqDevice(location);
        buffer = new SapBuffer(1, acq_device);
        transfer = new SapAcqDeviceToBuf(acq_device, buffer);

        // Create resources
        if(!acq_device->Create() || 
           !buffer->Create() || 
           !transfer->Create()) {
            throw std::runtime_error("Sapera initialization failed");
        }
    }

    ~CameraWrapper() {
        release_resources();
    }

    void release_resources() {
        if (transfer) {
            transfer->Destroy();
            delete transfer;
            transfer = nullptr;
        }
        if (buffer) {
            buffer->Destroy();
            delete buffer;
            buffer = nullptr;
        }
        if (acq_device) {
            acq_device->Destroy();
            delete acq_device;
            acq_device = nullptr;
        }
        SapManager::UnloadServer(location.GetServerName());
    }

    int capture(unsigned char* out_buffer, int buffer_size) {
        if(!transfer->Snap()) return -1;
        if(!transfer->Wait(5000)) return -2;

        // Get image parameters
        int width = buffer->GetWidth();
        int height = buffer->GetHeight();
        int format = buffer->GetFormat();
        int bytes_per_pixel = get_bytes_per_pixel(format);
        int required = width * height * bytes_per_pixel;

        if(buffer_size < required) return -3;

        // Retrieve image data
        void* image_data = nullptr;
        if(!buffer->GetAddress(0, &image_data)) return -4;

        memcpy(out_buffer, image_data, required);
        return required;
    }

    int image_size() { 
        int width = buffer->GetWidth();
        int height = buffer->GetHeight();
        int format = buffer->GetFormat();
        return width * height * get_bytes_per_pixel(format);
    }

    int width() { return buffer->GetWidth(); }
    int height() { return buffer->GetHeight(); }

private:
    std::string mac_address;
    SapLocation location;
    SapAcqDevice* acq_device = nullptr;
    SapBuffer* buffer = nullptr;
    SapAcqDeviceToBuf* transfer = nullptr;

    int get_bytes_per_pixel(int format) {
        // Simplified format handling for compatibility
        if (format == SapFormatMono8) return 1;
        if (format == SapFormatRGB888) return 3;
        return 2; // Default for Mono16 and others
    }
};

// C interface implementation
extern "C" {
    void* initialize_camera(const char* mac) {
        try { 
            return new CameraWrapper(mac); 
        } catch(...) { 
            return nullptr; 
        }
    }

    int capture_image(void* camera, unsigned char* buffer, int buffer_size) {
        return camera ? static_cast<CameraWrapper*>(camera)->capture(buffer, buffer_size) : -1;
    }

    void release_camera(void* camera) {
        if (camera) {
            static_cast<CameraWrapper*>(camera)->release_resources();
            delete static_cast<CameraWrapper*>(camera);
        }
    }

    int get_image_size(void* camera) {
        return camera ? static_cast<CameraWrapper*>(camera)->image_size() : -1;
    }

    int get_image_width(void* camera) {
        return camera ? static_cast<CameraWrapper*>(camera)->width() : -1;
    }

    int get_image_height(void* camera) {
        return camera ? static_cast<CameraWrapper*>(camera)->height() : -1;
    }

    void cleanup_resources(const char* mac) {
        SapLocation location;
        if (SapManager::GetLocationFromMacAddress(mac, location)) {
            SapManager::CleanServer(location);
            SapManager::UnloadServer(location.GetServerName());
        }
    }
}

Python Interface

import ctypes
import numpy as np
import cv2
import time

class DalsaCamera:
    ERROR_CODES = {
        -1: "Snap failed",
        -2: "Wait timeout",
        -3: "Buffer too small",
        -4: "Get address failed"
    }

    def __init__(self, mac_address, dll_path="DalsaCamera.dll"):
        self.mac = mac_address
        self.lib = ctypes.CDLL(dll_path)
        self.camera_ptr = None
        self.width = 0
        self.height = 0

        # Setup function prototypes
        self.lib.initialize_camera.restype = ctypes.c_void_p
        self.lib.initialize_camera.argtypes = [ctypes.c_char_p]
        self.lib.capture_image.argtypes = [ctypes.c_void_p, 
                                          ctypes.POINTER(ctypes.c_ubyte), 
                                          ctypes.c_int]
        self.lib.get_image_size.restype = ctypes.c_int
        self.lib.get_image_width.restype = ctypes.c_int
        self.lib.get_image_height.restype = ctypes.c_int
        self.lib.release_camera.argtypes = [ctypes.c_void_p]
        self.lib.cleanup_resources.argtypes = [ctypes.c_char_p]

    def initialize(self):
        # Force cleanup before initialization
        self.cleanup_resources()

        self.camera_ptr = self.lib.initialize_camera(self.mac.encode('utf-8'))
        if not self.camera_ptr:
            raise RuntimeError("Camera initialization failed")

        self.width = self.lib.get_image_width(self.camera_ptr)
        self.height = self.lib.get_image_height(self.camera_ptr)
        print(f"Initialized camera {self.mac}: {self.width}x{self.height}")
        return True

    def capture(self, timeout=5.0):
        if not self.camera_ptr:
            raise RuntimeError("Camera not initialized")

        size = self.lib.get_image_size(self.camera_ptr)
        if size <= 0:
            raise RuntimeError(f"Invalid image size: {size}")

        buffer = (ctypes.c_ubyte * size)()
        start_time = time.time()

        while time.time() - start_time < timeout:
            result = self.lib.capture_image(self.camera_ptr, buffer, size)
            if result > 0:
                return self._process_image(buffer, result)
            elif result < 0:
                err = self.ERROR_CODES.get(result, f"Unknown error {result}")
                print(f"Capture error: {err}")
            time.sleep(0.1)

        raise TimeoutError("Capture timed out")

    def _process_image(self, buffer, size):
        if size == self.width * self.height:
            # Mono8 image
            return np.frombuffer(buffer, dtype=np.uint8).reshape((self.height, self.width))
        elif size == self.width * self.height * 2:
            # Mono16 image
            return np.frombuffer(buffer, dtype=np.uint16).reshape((self.height, self.width))
        else:
            # Unsupported format - return raw bytes
            return bytes(buffer)

    def release(self):
        if self.camera_ptr:
            self.lib.release_camera(self.camera_ptr)
            self.camera_ptr = None
            print("Camera resources released")

    def cleanup_resources(self):
        self.lib.cleanup_resources(self.mac.encode('utf-8'))
        print(f"Force released resources for {self.mac}")

    def __enter__(self):
        self.initialize()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.release()
        time.sleep(0.5)  # Allow time for resource release

Camera Discovery Utility

import ctypes

def discover_cameras():
    """Find available cameras using Sapera Manager"""
    sap_dir = r"C:\Program Files\Teledyne DALSA\Sapera"
    try:
        # Load SAP Manager library
        manager = ctypes.CDLL(f"{sap_dir}\\Libs\\Win64\\SapManager.dll")

        # Define function prototypes
        manager.GetServerCount.restype = ctypes.c_int
        manager.GetResourceCount.argtypes = [ctypes.c_int, ctypes.c_char_p]
        manager.GetResourceCount.restype = ctypes.c_int
        manager.GetResourceName.argtypes = [ctypes.c_int, ctypes.c_char_p, 
                                          ctypes.c_int, ctypes.c_char_p, ctypes.c_int]
        manager.GetResourceMacAddress.argtypes = [ctypes.c_int, ctypes.c_char_p,
                                                ctypes.c_int, ctypes.c_char_p, ctypes.c_int]

        # Get server count
        server_count = manager.GetServerCount()
        print(f"Found {server_count} servers")

        cameras = []
        for server_idx in range(server_count):
            # Get server name
            server_name = ctypes.create_string_buffer(256)
            manager.GetServerName(server_idx, server_name, 256)

            # Get resource count
            res_count = manager.GetResourceCount(server_idx, b"AcqDevice")
            print(f"Server {server_name.value.decode()} has {res_count} cameras")

            for res_idx in range(res_count):
                # Get resource name
                res_name = ctypes.create_string_buffer(256)
                manager.GetResourceName(server_idx, b"AcqDevice", res_idx, res_name, 256)

                # Get MAC address
                mac = ctypes.create_string_buffer(256)
                manager.GetResourceMacAddress(server_idx, b"AcqDevice", res_idx, mac, 256)

                cameras.append({
                    "server_index": server_idx,
                    "resource_index": res_idx,
                    "server": server_name.value.decode(),
                    "name": res_name.value.decode(),
                    "mac": mac.value.decode()
                })

        return cameras
    except Exception as e:
        print(f"Discovery failed: {str(e)}")
        return []

Best Practices for Reliable Operation

1. Resource Management

• Always use context managers (with statements) in Python
• Implement forced cleanup before initialization
• Destroy resources in reverse order of creation

2. Error Handling

• Check all Sapera API return values
• Implement comprehensive error codes
• Add timeout mechanisms for capture operations

3. Performance Optimization

// In capture function:
if(!transfer->Snap()) return -1;
if(!transfer->Wait(5000)) return -2;  // Timeout after 5 seconds

4. Configuration Management

Create SapConfig.ini:

[Server]
MaxAllowedConnections=1
ResourceLocking=1

[Acquisition]
ReuseBuffers=0

Troubleshooting Guide

Error Message	Solution
Server index out of range	Run discovery utility to find correct MAC
Resource in use	Implement forced resource cleanup
Cannot open include file	Verify Sapera SDK paths in CMake
SapClassBasic.lib not found	Check library path and architecture
CorXferStart error	Ensure proper resource release between captures
Black images	Check exposure settings and lens cap

Conclusion

This integration approach successfully bridges the gap between Teledyne DALSA’s Sapera SDK and Python, enabling:

• Direct camera control from Python applications
• Reliable image acquisition with proper resource management
• Compatibility with various Sapera SDK versions
• Robust error handling for industrial environments

The complete solution is available on GitHub, including build scripts and sample applications. Link to Code

Future Enhancements

1. Add support for camera parameter configuration
2. Implement asynchronous capture mode
3. Develop multi-camera synchronization
4. Create PyPI package for easy installation

By following this comprehensive guide, developers can successfully integrate Teledyne DALSA cameras into their Python-based machine vision systems while avoiding common pitfalls related to resource management and SDK compatibility.