Using Packet and Buffer Size to Adjust Frame Rate on Ladybug Cameras

Preparing for use

Before you use your camera, we recommend that you are aware of the following resources available from your product's webpage:

• Getting Started Manual for the camera—provides information on installing components and software needed to run the camera.
• Technical Reference for the camera—provides information on the camera’s specifications, features and operations, as well as imaging and acquisition controls.
• Firmware updates—ensure you are using the most up-to-date firmware for the camera to take advantage of improvements and fixes.
• Tech Insights—Subscribe to our monthly email updates containing information on new knowledge base articles, new firmware and software releases, and Product Change Notices (PCN).

Overview

It is recommended to keep the camera’s sensor running at maximum speed in order to achieve the best possible response time with the on-camera image quality adjustments. To change the frame rate without reducing the sensor speed, you can adjust the packet and buffer sizes.

Note: Due to system variance and rounding, the equations mentioned in this application note only provide approximate values. The frame rate may be slightly higher or lower than what is expected. This can be fixed by tweaking the calculated buffer and packet sizes. Note that the actual frame rate rarely differs more than 10% from the desired frame rate used in calculations.

If the frame rate is too high, either the packet size needs to be reduced or the buffer size needs to be increased. It is recommended to increase the buffer size if possible, because this allows space for less compressed images.

If the frame rate is too low, either the packet size needs to be increased or the buffer size needs to be reduced. It is recommended to increase the packet size if possible, because reducing the buffer size can result in a greater amount of compression required.

Choosing a Packet Size

For the Ladybug5+, the packet size range is from 500 to 56000. A valid packet size must be a multiple of the minimum, or 500.

Teledyne FLIR recommends using the largest packet size possible. A larger packet size allows for increased headroom to accommodate scenes that do not compress well using JPEG compression. Unless you are reducing the bandwidth, use packet size 56000.

Determining Buffer Size

The equation to find the corresponding buffer size given the desired frame rate and packet size is as follows:

(8000 * Packet Size) / (Desired FPS) ≈ Buffer Size

8000 is the amount of packets sent from the camera per second.

For example, given the recommended packet size of 56000, and a desired frame rate of 30 FPS, the following buffer size should be used:

(8000 * 56000) / 30 ≈ 14933333

If the desired frame rate is low and the calculated buffer size is larger than the maximum image size, the camera reduces the buffer size automatically and sends more frames than requested. In this situation, the buffer size should be set to the maximum image size, and the bandwidth must be reduced.

The maximum image sizes for each image format can be queried from the camera using register MAX_IMAGE_SIZE_INQ Base + 000h. See the Teledyne FLIR Machine Vision Camera Register Reference for details.

The following table provides some example maximum image sizes.

Reducing Bandwidth

You can limit the amount of data coming off the camera by reducing the bandwidth.

To calculate the correct bandwidth, use the following equation:

(Desired Frame Rate * Maximum Image Size) ≈ Bandwidth

For example, given a desired frame rate of 5 FPS and a maximum image size of 100 000 bytes, the bandwidth needs to be 500 000 bytes per second.

The Ladybug5+ camera always sends 8000 packets a second, so reducing the packet size limits the bandwidth. The equation to find the corresponding packet size given a desired bandwidth is as follows:

(Desired Bandwidth in Bytes) / 8000 ≈ Packet Size

For example, if the data coming off the camera needs to be limited to 300 000 000 bytes per second, the packet size used should be 37500.

Configuring Buffer Size when Triggering

When triggering, it is important to set packet and buffer sizes that can allow for the maximum desired trigger rate. As the camera will wait until a trigger to transfer an image, there is no risk of the camera sending more frames than requested. This means that the packet size should always be set to maximum when triggering. This is 56000 unless you are throttling the bandwidth.

To calculate the buffer size, a similar method to the one used for non-triggering modes is applied.

((8000 * Packet Size) / (Maximum Desired Trigger Rate)) * 0.9 ≈ Buffer Size

Note:The buffer size is reduced to 90% because of system variance and rounding. To ensure that the maximum desired trigger rate is possible the buffer size should be at least 10% smaller than the theoretical maximum.

Ladybug API

To change either the packet or buffer size, use the Ladybug API.

LADYBUGDLL_API LadybugError
ladybugStartLockNextEx(
LadybugContext context,
LadybugDataFormat format,
unsigned int uiPacketSize = 0,
unsigned int uiBufferSize = 0);

Example Settings

This section provides an example of the settings needed for the following situation:

• Use full bandwidth of the USB3 cable
• Support as close to, without going below,15 FPS
• Use data format LADYBUG_DATAFORMAT_COLOR_SEP_JPEG12

Step 1: Use a packet size of 56000. This is the maximum and recommended packet size.

Step 2: Calculate the buffer size ≈ (8000*56000) / 15 ≈ 29866666.

Step 3: Check that the buffer size is smaller than the maximum image size for the data format. 29866666 < 60565000. The buffer size is smaller than the maximum image size, so there is no reason to throttle the bandwidth.

Step 4: The calculated values allows for a frame rate close to 15 FPS but we need to account for potential system variance and round off error. This example assumes it is okay if we achieve a frame rate slightly greater than 15, but not below.

To increase the frame rate, we can either reduce the buffer size or increase the packet size. Since the packet size is already maximum, we must reduce the buffer size. The worst case scenario is a frame rate 10% lower than 15. By reducing the buffer size by 10% (29866666 * 0.9 ≈ 26879999) we achieve a frame rate close to 15, and guaranteed to be larger than 15 FPS.

Common Configurations

These values have been calculated using the methods above, and then adjusted until the desired frame rate was achieved.