pypylon Documentation

When using a queue to decouple acquisition from processing, you must manage backpressure. If the queue becomes full, the producer thread will block, which in turn slows down the acquisition process.

Strategies for managing backpressure:

• Increase queue size: Allows for larger bursts of processing delay.
• Drop frames manually: Implement logic to discard old frames if the queue is full.
• Use Grab Strategies:
  • LatestImageOnly: Reduces backlog by focusing on the most recent data. Best for responsive systems.
  • OneByOne: Ensures every frame is processed. Best for analysis systems where completeness is required.

Recommended Combinations:

• LatestImageOnly + queue $\rightarrow$ Responsive systems.
• OneByOne + logging $\rightarrow$ Analysis systems.

Grab strategies determine how the internal buffer queue handles images when the camera produces frames faster than the application can process them.

Available Strategies

• pylon.GrabStrategy_LatestImageOnly: Only the newest image is kept in the buffer. Older frames are discarded. This is ideal for live displays, GUIs, and low-latency systems where seeing the most recent state is more important than seeing every single frame.

• pylon.GrabStrategy_OneByOne: All frames are queued and processed in the order they were produced. No frames are dropped unless the buffers overflow. This is ideal for inspection systems, recording, and deterministic processing where every frame must be analyzed.

Always use the with statement when retrieving grab results. This ensures that the grab_result is automatically released even if an exception occurs within the block. Failing to release grab results can lead to unavailable buffers and cause the acquisition to stall.

with camera.RetrieveResult(...) as grab_result:
    image = grab_result.Array

Multi-camera systems require synchronization to ensure images are captured at the same time.

• Software Synchronization: Trigger cameras via software using camera.ExecuteSoftwareTrigger(). This has limited precision and is subject to OS scheduling delays.
• Hardware Synchronization (Recommended): Use a physical trigger signal (e.g., a Master camera triggering Slave cameras). This provides precise, deterministic timing required for stereo vision or measurement systems.

The acquisition process follows a decoupled flow where the camera operates asynchronously from the Python application. The data flows from the Camera through the Transport layer into a Buffer Queue, which is then consumed by the Application via RetrieveResult() calls.

Mental Model:

• Camera: Runs asynchronously.
• Python: Retrieves data synchronously.
• Buffers: Decouple the camera's production of frames from the application's consumption of frames.

pypylon uses a decoupled execution model to separate hardware acquisition from Python-level processing. The conceptual flow is:

Camera → Native Thread → Buffer Queue → Python Application

Key aspects of this model:

• Native Threading: Camera acquisition runs in a native C++ thread managed by pylon.
• Asynchronous Acquisition: Your Python code retrieves images from a buffer queue, allowing acquisition to continue even if your processing logic is temporarily delayed.
• Decoupling: This separation is critical when the camera frame rate (e.g., 100 FPS) exceeds your application's processing capability (e.g., 20 FPS). Without concurrency, buffers will fill up, frames will be dropped, and latency will increase.

To prevent blocking acquisition and improve CPU utilization, separate camera acquisition from image processing using a Producer–Consumer pattern.

1. Acquisition Thread (Producer): Grabs images and pushes them into a thread-safe queue.
2. Processing Thread(s) (Consumer): Pulls images from the queue for analysis.

Use queue.Queue for thread-safe communication between stages.

Recommended Pipeline Structure: Grab → Preprocess → Analyze → Output

import queue
q = queue.Queue()

The shape of the resulting NumPy array depends on the PixelType used. Common mappings include:

You can inspect the dimensions using image.shape or image.ndim.

Use snake_case for both sample folders and script names. The naming strategy depends on the module:

pylon module

Use a topic prefix to categorize the sample:

• grab_: Image grabbing illustrations.
• parametrize_: Camera parameter access and configuration.
• utility_: Usage of the optional pylon utility C++ library.
• gige_: GigE-specific features.
• No prefix: For all other purposes.

pylondataprocessing module

Do not use prefixes. Name the sample directly after the feature it demonstrates (e.g., barcode.py, ocr.py, region.py).