Compression Beyond#

The Compression Beyond camera feature allows you to compress image data output by the camera.

Compressing image data may lower the camera's bandwidth usage, increase the frame rate, or both.

For more information, see the feature description on the Basler website.

Using the Feature#

How It Works#

Compression is performed automatically whenever the ImageCompressionMode parameter is set to BaslerCompressionBeyond.

When enabled, the feature always compresses images as much as possible. This lowers the amount of data ("payload") output by the camera, i.e., its bandwidth usage. This is especially useful for Basler GigE cameras in a multi-camera setup.

If you want the camera to also optimize the frame rate, further configuration is required. This is because the camera doesn't "know" how much it will be able to compress an image before exposure starts.

To get around this, you must tell the camera how much it will at least be able to compress images. Do this by specifying a compression ratio (BslImageCompressionRatio parameter).

For example, setting the BslImageCompressionRatio parameter to 90, tells the camera that it will be able to compress any image to at least 90 % of its original size. With this information, the camera can increase its frame rate by up to 10 %.

However, if you set the value too low, i.e., if the camera can't achieve the estimated compression ratio, frames will be skipped. In this case, you can change the ImageCompressionRateOption parameter from Lossless to FixRatio. This allows even lower compression rates, but reduces image quality.

Configuring Compression Beyond#

How to configure Compression Beyond depends on your requirements.

Optimize Bandwidth#

Assume you want the camera to do the following:

• Lower the bandwidth usage
• Increase the frame rate
• Preserve optimum image quality

To achieve this:

1. Make sure that the camera is idle, i.e., not capturing images.
2. Set the ImageCompressionMode parameter to BaslerCompressionBeyond.
3. Set the ImageCompressionRateOption parameter to Lossless.
4. Set the BslImageCompressionRatio parameter to 100.

With these settings, the camera compresses images as much as possible without sacrificing image quality.

Optimize Bandwidth and Frame Rate With Lossless Compression#

Assume you want the camera to do the following:

• Lower the bandwidth usage
• Increase the frame rate
• Preserve optimum image quality

To achieve this:

1. Make sure that the camera is idle, i.e., not capturing images.
2. Set the ImageCompressionMode parameter to BaslerCompressionBeyond.
3. Set the ImageCompressionRateOption parameter to Lossless.
4. Set the BslImageCompressionRatio parameter to a value lower than 100, e.g., 90.
5. Get the value of the BslResultingAcquisitionFrameRate parameter to determine the estimated frame rate.
6. If the frame rate is not high enough for your application, repeat steps 4 and 5 with a lower BslImageCompressionRatio parameter value.
7. Start image acquisition. If the camera can't acquire images without skipping frames, the desired frame rate can't be achieved. Try the following:
   • If a lower frame rate is acceptable, increase the value of the BslImageCompressionRatio parameter until the camera is able to acquire images continuously.
   • If a lower image quality is acceptable, carry out the procedure detailed below.

Optimize Bandwidth and Frame Rate With Lossy Compression#

Assume you want the camera to do the following:

• Lower the bandwidth usage
• Increase the frame rate
• Preserve optimum image quality

To achieve this:

1. Make sure that the camera is idle, i.e., not capturing images.
2. Set the ImageCompressionMode parameter to BaslerCompressionBeyond.
3. Set the ImageCompressionRateOption parameter to FixRatio.
4. Set the BslImageCompressionRatio parameter to 100.
5. Acquire at least one image.
6. Get the value of the BslImageCompressionLastRatio parameter.
   The value indicates the threshold between lossless and lossy image acquisition.
7. Set the BslImageCompressionRatio parameter to a value lower than the value of the BslImageCompressionLastRatio parameter.
   The lower the parameter value, the lower the image quality.
8. Start image acquisition. If the camera can't acquire images without skipping frames, increase the value of the BslImageCompressionRatio parameter until the camera is able to acquire images.

With these settings, you may be able to achieve lower bandwidth usage and higher frame rates compared to lossless compression. However, this will reduce image quality.

Sample Code#

// Enable Compression Beyond with lossless compression
camera.ImageCompressionMode.SetValue(ImageCompressionMode_BaslerCompressionBeyond);
camera.ImageCompressionRateOption.SetValue(ImageCompressionRateOption_Lossless);
// To increase the frame rate, tell the camera that it will be able
// to compress any image to at least 70 % of its original size
camera.BslImageCompressionRatio.SetValue(70);
// Get the resulting acquisition frame rate
double resultingFrameRate = camera.BslResultingAcquisitionFrameRate.GetValue();
if (resultingFrameRate < desiredFrameRate) {
    // Frame rate isn't high enough for the application.
    // Therefore, enable lossy compression. This allows even
    // lower compression rates, but reduces image quality.
    camera.ImageCompressionRateOption.SetValue(ImageCompressionRateOption_FixRatio);
    camera.BslImageCompressionRatio.SetValue(50);
}
// Start image acquisition
// ...
// (Implement your own image grabbing routine here.
// For example, the InstantCamera class provides the StartGrabbing() method.
// Note that you must decompress grabbed images using the CImageDecompressor class.)
// ...
// Determine the compression ratio of the last acquired image
double lastRatio = camera.BslImageCompressionLastRatio.GetValue();
// Determine the payload size of the last acquired image in bytes
int64_t lastSize = camera.BslImageCompressionLastSize.GetValue();

INodeMap& nodemap = camera.GetNodeMap();
// Enable Compression Beyond with lossless compression
CEnumParameter(nodemap, "ImageCompressionMode").SetValue("BaslerCompressionBeyond");
CEnumParameter(nodemap, "ImageCompressionRateOption").SetValue("Lossless");
// To increase the frame rate, tell the camera that it will be able
// to compress any image to at least 70 % of its original size
CIntegerParameter(nodemap, "BslImageCompressionRatio").SetValue(70);
// Get the resulting acquisition frame rate
double resultingFrameRate = CFloatParameter(nodemap, "BslResultingAcquisitionFrameRate").GetValue();
if(resultingFrameRate < desiredFrameRate){    
    // Frame rate isn't high enough for the application.
    // Therefore, enable lossy compression. This allows even
    // lower compression rates, but reduces image quality.
    CEnumParameter(nodemap, "ImageCompressionRateOption").SetValue("FixRatio");
    CIntegerParameter(nodemap, "BslImageCompressionRatio").SetValue(50);
}
// Start image acquisition
// ...
// (Implement your own image grabbing routine here.
// For example, the InstantCamera class provides the StartGrabbing() method.
// Note that you must decompress grabbed images using the CImageDecompressor class.)
// ...
// Determine the compression ratio of the last acquired image
double lastRatio = CFloatParameter(nodemap, "BslImageCompressionLastRatio").GetValue();
// Determine the payload size of the last acquired image in bytes
int64_t lastSize = CIntegerParameter(nodemap, "BslImageCompressionLastSize").GetValue();

// Enable Compression Beyond with lossless compression
camera.Parameters[PLCamera.ImageCompressionMode].SetValue(PLCamera.ImageCompressionMode.BaslerCompressionBeyond);
camera.Parameters[PLCamera.ImageCompressionRateOption].SetValue(PLCamera.ImageCompressionRateOption.Lossless);
// To increase the frame rate, tell the camera that it will be able
// to compress any image to at least 70 % of its original size
camera.Parameters[PLCamera.BslImageCompressionRatio].SetValue(70);
// Get the resulting acquisition frame rate
double resultingFrameRate = camera.Parameters[PLCamera.BslResultingAcquisitionFrameRate].GetValue();
if(resultingFrameRate < desiredFrameRate){    
    // Frame rate isn't high enough for the application.
    // Therefore, enable lossy compression. This allows even
    // lower compression rates, but reduces image quality.
    camera.Parameters[PLCamera.ImageCompressionRateOption].SetValue(PLCamera.ImageCompressionRateOption.FixRatio);
    camera.Parameters[PLCamera.BslImageCompressionRatio].SetValue(50);
}
// Start image acquisition
// ...
// (Implement your own image grabbing routine here.
// For example, the InstantCamera class provides the StartGrabbing() method.
// Note that you must decompress grabbed images using the CImageDecompressor class.)
// ...
// Determine the compression ratio of the last acquired image
double lastRatio = camera.Parameters[PLCamera.BslImageCompressionLastRatio].GetValue();
// Determine the payload size of the last acquired image in bytes
Int64 lastSize = camera.Parameters[PLCamera.BslImageCompressionLastSize].GetValue();

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
double resultingFrameRate = 0;
double lastRatio = 0;
int64_t lastSize = 0;
/* Enable Compression Beyond with lossless compression */
errRes = PylonDeviceFeatureFromString(hdev, "ImageCompressionMode", "BaslerCompressionBeyond");
CHECK(errRes);
errRes = PylonDeviceFeatureFromString(hdev, "ImageCompressionRateOption", "Lossless");
CHECK(errRes);
/* To increase the frame rate, tell the camera that it will be able */
/* to compress any image to at least 70 % of its original size */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslImageCompressionRatio", 70);
CHECK(errRes);
/* Get the resulting acquisition frame rate */
errRes = PylonDeviceGetFloatFeature(hdev, "BslResultingAcquisitionFrameRate", &resultingFrameRate);
CHECK(errRes);
if(resultingFrameRate < desiredFrameRate){    
    /* Frame rate isn't high enough for the application. */
    /* Therefore, enable lossy compression. This allows even */
    /* lower compression rates, but reduces image quality. */
    errRes = PylonDeviceFeatureFromString(hdev, "ImageCompressionRateOption", "FixRatio");
    CHECK(errRes);
    errRes = PylonDeviceSetIntegerFeature(hdev, "BslImageCompressionRatio", 50);
    CHECK(errRes);
}
/* Start image acquisition */
/* ... */
/* (Implement your own image grabbing routine here. */
/* For example, the InstantCamera class provides the StartGrabbing() method. */
/* Note that you must decompress grabbed images using the CImageDecompressor class.) */
/* ... */
/* Determine the compression ratio of the last acquired image */
errRes = PylonDeviceGetFloatFeature(hdev, "BslImageCompressionLastRatio", &lastRatio);
CHECK(errRes);
/* Determine the payload size of the last acquired image in bytes */
errRes = PylonDeviceGetIntegerFeature(hdev, "BslImageCompressionLastSize", &lastSize);
CHECK(errRes);

# Enable Compression Beyond with lossless compression
camera.ImageCompressionMode.Value = "BaslerCompressionBeyond"
camera.ImageCompressionRateOption.Value = "Lossless"
# To increase the frame rate, tell the camera that it will be able
# to compress any image to at least 70 % of its original size
camera.BslImageCompressionRatio.Value = 70
# Get the resulting acquisition frame rate
resultingFrameRate = camera.BslResultingAcquisitionFrameRate.Value
if resultingFrameRate < desiredFrameRate:
    # Frame rate isn't high enough for the application.
    # Therefore, enable lossy compression. This allows even
    # lower compression rates, but reduces image quality.
    camera.ImageCompressionRateOption.Value = "FixRatio"
    camera.BslImageCompressionRatio.Value = 50
# Start image acquisition
# ...
# (Implement your own image grabbing routine here.
# For example, the InstantCamera class provides the StartGrabbing() method.
# Note that you must decompress grabbed images using the CImageDecompressor class.)
# ...
# Determine the compression ratio of the last acquired image
lastRatio = camera.BslImageCompressionLastRatio.Value
# Determine the payload size of the last acquired image in bytes
lastSize = camera.BslImageCompressionLastSize.Value

You can also use the pylon Viewer to easily set the parameters.