Shading Correction#

The Shading Correction camera feature allows you to reduce non-uniformities in the image caused by differing light sensitivities of the sensor pixels. Also artifacts caused by the illumination and illumination optics can be minimized.

Shading correction is based on files that are stored on the camera and contain appropriate correction data. During image acquisition, these are applied to the original pixel values, which results in an improved image.

The Shading Correction feature is only available on racer 2 cameras.

Using the Feature#

How It Works#

DSNU and PRNU Correction#

Shading correction minimizes image artifacts caused by dark signal non-uniformities (DSNU) and photo response non-uniformities (PRNU). The following two types of shading correction are available on the camera:

• DSNU correction: When the camera captures a line in complete darkness, all of the pixel values in the line should be near zero and they should be equal. In practice, slight variations in the performance of the pixels in the sensor will cause some variation in the pixel values output from the camera when the camera is capturing lines in darkness. DSNU correction corrects for this type of variation. It works by adding an individual gray value (offset) to each pixel value in the lines acquired.

• PRNU correction: When the camera captures a line while being pointed at a bright, homogeneously illuminated surface, all of the pixel values in the line should be near their maximum gray value and they should be equal. In practice, slight variations in the performance of the pixels in the sensor as well as variations in the optics and in lighting will cause variations in the pixel values output from the camera. PRNU correction corrects for this type of variation. It works by applying an individual multiplier (gain) to each pixel value in the lines acquired.

Shading correction is a pixel-to-pixel calibration method, i.e., a correction value is calculated for each single pixel.

Shading Correction Sets#

The correction values used for DSNU and PRNU correction are stored in files referred to as shading correction sets. There are the following two types:

• Factory correction set: Contains correction values that were stored on the camera during the camera production process. The factory correction set can only reduce image artifacts caused by dark signal non-uniformities (DSNU).

• User correction set: Contains correction values that must be created by the user and stored on the camera. You can upload or download a shading correction file.

  Depending on your camera model, you can create up to 32 User correction sets.

Uploading a Shading Correction File#

To upload a user shading correction file using the pylon Viewer:

1. In the Camera menu of the pylon Viewer, click File Access.
2. In the Camera File drop-down box, select PRNU Correction or DSNU Correction.
   If there's no PRNU Correction or DSNU correction entry, uploading a correction file is not supported by your camera.
3. Click Upload and navigate to the file that you want to upload.
4. Click Open.

To apply the shading correction file after uploading, make sure that the BslShadingCorrectionMode parameter is set to User.

Downloading a Shading Correction File#

To download a shading correction file using the pylon Viewer:

1. In the Camera menu of the pylon Viewer, click File Access.
2. In the Camera File drop-down box, select PRNU Correction or DSNU Correction depending on which file you want to download.
   If there's no appropriate entry, downloading a shading correction file is not supported by your camera.
3. Click Download, navigate to the directory where you want to save the file, and enter the desired file name.
4. Click Open.

Shading Correction Mode#

The shading correction mode determines whether shading correction is based on the values stored in the factory or the user correction set.

To set the shading correction mode, set the BslShadingCorrectionMode parameter to one of the following values:

• Factory (default): Shading correction is based on the values stored in the factory correction set.
• User: Shading correction is based on the values stored in the user correction set.
• Off: The camera does not perform shading corrections.

Creating a Shading Correction Set#

You need the following items before you start creating a user-defined shading correction set:

• An appropriate object to completely cover the lens, e.g., the lens cap
• A target with a uniform background, e.g., a white sheet of paper

DSNU Correction Set#

To create a shading correction set for DSNU correction:

1. Prevent any light from hitting the camera’s sensor, e.g., by placing a plastic cap on the lens.
2. Set the BslShadingCorrectionSelector parameter to DSNU.
3. Set the BslShadingCorrectionMode parameter to User.
4. Set the BslShadingCorrectionSetIndex parameter to the desired index number of the set to be created, e.g., 1.
5. Set the BslShadingCorrectionROISelector parameter to the desired ROI, e.g., ROI 1.

6. Set the position and size of the shading correction ROI by using the following parameters:

   • BslShadingCorrectionROIOffsetX
   • BslShadingCorrectionROIWidth

7. Click the Continuous Shot button in the toolbar of the pylon Viewer to start image acquisition.

8. Execute the BslShadingCorrectionSetCreate command to create a new shading correction set.
   A total of 256 dark images are acquired and evaluated. The resulting DSNU correction data are generated, collected in the shading correction set defined, and saved to the camera's flash memory. If the shading correction set with, e.g., index number 1, already contains correction data, these are overwritten and replaced by the new correction values.

   Info

   If a PRNU correction set is enabled while creating DSNU correction data, the PRNU correction values will be ignored for the calculation.

   The created shading correction set is enabled automatically.

9. To verify the result of the shading correction set creation, get the value of the BslShadingCorrectionSetCreateResult parameter.

PRNU Correction Set#

To create a shading correction set for PRNU correction:

1. Illuminate the sensor homogeneously to 70 % saturation, e.g., by placing a white sheet of paper in the camera's entire field of view.
2. Set the BslShadingCorrectionSelector parameter to PRNU.
3. Set the BslShadingCorrectionMode parameter to User.
4. Set the BslShadingCorrectionSetIndex parameter to the desired index number of the set to be created, e.g., 2.
5. Set the BslShadingCorrectionROISelector parameter to the desired ROI, e.g., ROI 1.

6. Set the position and size of the shading correction ROI by using the following parameters:

   • BslShadingCorrectionROIOffsetX
   • BslShadingCorrectionROIWidth

7. Click the Continuous Shot button in the toolbar of the pylon Viewer to start image acquisition.

8. Execute the BslShadingCorrectionSetCreate command to create a new shading correction set.
   A total of 256 bright images are acquired and evaluated. The resulting PRNU correction data are generated, collected in the shading correction set selected, and saved to the camera's flash memory. If the shading correction set with, e.g., index number 2, already contains correction data, these are overwritten and replaced by the new correction values.

   Info

   If a DSNU correction set is enabled while creating PRNU correction data, the DSNU correction values are taken into account for the calculation.

   The created shading correction set is enabled automatically.

9. To verify the result of the shading correction set creation, get the value of the BslShadingCorrectionSetCreateResult parameter.

10. If required, adjust the target gray value for PRNU correction for each color channel separately and repeat step 7.

Adjusting the Target Gray Value for PRNU Correction#

During the creation of a PRNU correction set, the camera detects the maximum brightness value in the bright field image. However, you may want to adjust the relative target gray value of the sensor brightness you want to achieve. Possible reasons for this are, e.g.:

• Your shading correction set can't be created because the correction values are outside the allowed range.
• Bright spots on the image (e.g., caused by light reflections) result in a high maximum brightness value detected by the camera during the creation of the correction set. You may want to reduce this value, which is relevant for calculating the correction data, to improve your correction data.

To adjust the target gray value for PRNU correction:

1. Set the BslShadingCorrectionTargetSelector parameter to one of the following values:
   • All (for mono cameras): The target value is applied to all sensor lines.
   • Red, Green, Blue (for color cameras): The target value is applied to the selected color channel.
2. Set the BslShadingCorrectionTargetValue parameter to the desired relative target gray value.
3. For color cameras: Repeat steps 1. and 2. for the other color channels.

Further parameters:

• BslShadingCorrectionAbsoluteTargetValue: Absolute target value of the sensor brightness. This is the actual brightness value that has been calculated based on the sensor bit depth of your camera.
• BslShadingCorrectionMaximumMeasuredValue: Maximum brightness value detected by the camera during the creation of a PRNU correction set.

Enabling a Shading Correction Set#

To enable a shading correction set:

1. Set the BslShadingCorrectionMode parameter to User, if you want to enable a user-defined correction set, or to Factory, if you want to enable the factory correction set.

2. Set the BslShadingCorrectionSetIndex parameter to the index number of the set to be used, e.g., index number 2.

   The shading correction set is enabled automatically.

3. To verify whether this process was successful, get the value of the BslShadingCorrectionSetStatus parameter. If the value is Ok, the shading set has been enabled successfully. The camera now performs shading correction based on the correction values in the shading correction set selected.

Disabling Shading Correction#

To disable shading correction, set the BslShadingCorrectionMode parameter to Off.

Specifics#

The following table shows the number of shading sets available for racer 2 cameras.

Sample Code#

// Set the type of shading correction to DSNU
camera.BslShadingCorrectionSelector.SetValue(BslShadingCorrectionSelector_DSNU);
// Or for PRNU: Set the type of shading correction to PRNU
camera.BslShadingCorrectionSelector.SetValue(BslShadingCorrectionSelector_PRNU);

// Note: Valid for DSNU and PRNU:
// Set the shading correction mode to User
camera.BslShadingCorrectionMode.SetValue(BslShadingCorrectionMode_User);
// Set the desired index number of the set to be created
camera.BslShadingCorrectionSetIndex.SetValue(1);
// Set the shading correction selector to ROI 1
camera.BslShadingCorrectionROISelector.SetValue(BslShadingCorrectionROISelector_ROI1);
// Set the offset X of the ROI to 0
camera.BslShadingCorrectionROIOffsetX.SetValue(0);
// Set the ROI width to 2048
camera.BslShadingCorrectionROIWidth.SetValue(2048);

// Note: Valid for PRNU only:
// Set the shading correction target value color/line selector to red
camera.BslShadingCorrectionTargetSelector.SetValue(BslShadingCorrectionTargetSelector_Red);
// Set the shading correction target value for red to 1000
camera.BslShadingCorrectionTargetValue.SetValue(1.0000);
// Set the shading correction target value color/line selector to green
camera.BslShadingCorrectionTargetSelector.SetValue(BslShadingCorrectionTargetSelector_Green);
// Set the shading correction target value for green to 1000
camera.BslShadingCorrectionTargetValue.SetValue(1.0000);
// Set the shading correction target value color/line selector to blue
camera.BslShadingCorrectionTargetSelector.SetValue(BslShadingCorrectionTargetSelector_Blue);
// Set the shading correction target value for blue to 1000
camera.BslShadingCorrectionTargetValue.SetValue(1.0000);

// Note: Valid for DSNU and PRNU:
// Create new shading correction data for the shading correction set selected
camera.BslShadingCorrectionSetCreate.Execute();
// Get the status of the shading correction set selected
BslShadingCorrectionSetStatus setStatus = camera.BslShadingCorrectionSetStatus.GetValue();

INodeMap& nodemap = camera.GetNodeMap();
// Set the type of shading correction to DSNU
CEnumParameter(nodemap, "BslShadingCorrectionSelector").SetValue("DSNU");
// Or for PRNU: Set the type of shading correction to PRNU
CEnumParameter(nodemap, "BslShadingCorrectionSelector").SetValue("PRNU");

// Note: Valid for DSNU and PRNU:
// Set the shading correction mode to User
CEnumParameter(nodemap, "BslShadingCorrectionMode").SetValue("User");
// Set the desired index number of the set to be created
CIntegerParameter(nodemap, "BslShadingCorrectionSetIndex").SetValue(1);
// Set the shading correction selector to ROI 1
CEnumParameter(nodemap, "BslShadingCorrectionROISelector").SetValue("ROI1");
// Set the offset X of the ROI to 0
CIntegerParameter(nodemap, "BslShadingCorrectionROIOffsetX").SetValue(0);
// Set the ROI width to 2048
CIntegerParameter(nodemap, "BslShadingCorrectionROIWidth").SetValue(2048);

// Note: Valid for PRNU only:
// Set the shading correction target value color/line selector to red
CEnumParameter(nodemap, "BslShadingCorrectionTargetSelector").SetValue("Red");
// Set the shading correction target value for red to 1000
CFloatParameter(nodemap, "BslShadingCorrectionTargetValue").SetValue(1.0000);
// Set the shading correction target value color/line selector to green
CEnumParameter(nodemap, "BslShadingCorrectionTargetSelector").SetValue("Green");
// Set the shading correction target value for green to 1000
CFloatParameter(nodemap, "BslShadingCorrectionTargetValue").SetValue(1.0000);
// Set the shading correction target value color/line selector to blue
CEnumParameter(nodemap, "BslShadingCorrectionTargetSelector").SetValue("Blue");
// Set the shading correction target value for blue to 1000
CFloatParameter(nodemap, "BslShadingCorrectionTargetValue").SetValue(1.0000);

// Note: Valid for DSNU and PRNU:
// Create new shading correction data for the shading correction set selected
CCommandParameter(nodemap, "BslShadingCorrectionSetCreate").Execute();
// Get the status of the shading correction set selected
String_t setStatus = CEnumParameter(nodemap, "BslShadingCorrectionSetStatus").GetValue();

// Set the type of shading correction to DSNU
camera.Parameters[PLCamera.BslShadingCorrectionSelector].SetValue(PLCamera.BslShadingCorrectionSelector.DSNU);
// Or for PRNU: Set the type of shading correction to PRNU
camera.Parameters[PLCamera.BslShadingCorrectionSelector].SetValue(PLCamera.BslShadingCorrectionSelector.PRNU);

// Note: Valid for DSNU and PRNU:
// Set the shading correction mode to User
camera.Parameters[PLCamera.BslShadingCorrectionMode].SetValue(PLCamera.BslShadingCorrectionMode.User);
// Set the desired index number of the set to be created
camera.Parameters[PLCamera.BslShadingCorrectionSetIndex].SetValue(1);
// Set the shading correction selector to ROI 1
camera.Parameters[PLCamera.BslShadingCorrectionROISelector].SetValue(PLCamera.BslShadingCorrectionROISelector.ROI1);
// Set the offset X of the ROI to 0
camera.Parameters[PLCamera.BslShadingCorrectionROIOffsetX].SetValue(0);
// Set the ROI width to 2048
camera.Parameters[PLCamera.BslShadingCorrectionROIWidth].SetValue(2048);

// Note: Valid for PRNU only:
// Set the shading correction target value color/line selector to red
camera.Parameters[PLCamera.BslShadingCorrectionTargetSelector].SetValue(PLCamera.BslShadingCorrectionTargetSelector.Red);
// Set the shading correction target value for red to 1000
camera.Parameters[PLCamera.BslShadingCorrectionTargetValue].SetValue(1.0000);
// Set the shading correction target value color/line selector to green
camera.Parameters[PLCamera.BslShadingCorrectionTargetSelector].SetValue(PLCamera.BslShadingCorrectionTargetSelector.Green);
// Set the shading correction target value for green to 1000
camera.Parameters[PLCamera.BslShadingCorrectionTargetValue].SetValue(1.0000);
// Set the shading correction target value color/line selector to blue
camera.Parameters[PLCamera.BslShadingCorrectionTargetSelector].SetValue(PLCamera.BslShadingCorrectionTargetSelector.Blue);
// Set the shading correction target value for blue to 1000
camera.Parameters[PLCamera.BslShadingCorrectionTargetValue].SetValue(1.0000);

// Note: Valid for DSNU and PRNU:
// Create new shading correction data for the shading correction set selected
camera.Parameters[PLCamera.BslShadingCorrectionSetCreate].Execute();
// Get the status of the shading correction set selected
string setStatus = camera.Parameters[PLCamera.BslShadingCorrectionSetStatus].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 */
size_t len = 0;
char setStatus_str[64] = {0};
/* Set the type of shading correction to DSNU */
errRes = PylonDeviceFeatureFromString(hdev, "BslShadingCorrectionSelector", "DSNU");
CHECK(errRes);
/* Or for PRNU: Set the type of shading correction to PRNU */
errRes = PylonDeviceFeatureFromString(hdev, "BslShadingCorrectionSelector", "PRNU");
CHECK(errRes);

/* Note: Valid for DSNU and PRNU: */
/* Set the shading correction mode to User */
errRes = PylonDeviceFeatureFromString(hdev, "BslShadingCorrectionMode", "User");
CHECK(errRes);
/* Set the desired index number of the set to be created */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslShadingCorrectionSetIndex", 1);
CHECK(errRes);
/* Set the shading correction selector to ROI 1 */
errRes = PylonDeviceFeatureFromString(hdev, "BslShadingCorrectionROISelector", "ROI1");
CHECK(errRes);
/* Set the offset X of the ROI to 0 */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslShadingCorrectionROIOffsetX", 0);
CHECK(errRes);
/* Set the ROI width to 2048 */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslShadingCorrectionROIWidth", 2048);
CHECK(errRes);

/* Note: Valid for PRNU only: */
/* Set the shading correction target value color/line selector to red */
errRes = PylonDeviceFeatureFromString(hdev, "BslShadingCorrectionTargetSelector", "Red");
CHECK(errRes);
/* Set the shading correction target value for red to 1000 */
errRes = PylonDeviceSetFloatFeature(hdev, "BslShadingCorrectionTargetValue", 1.0000);
CHECK(errRes);
/* Set the shading correction target value color/line selector to green */
errRes = PylonDeviceFeatureFromString(hdev, "BslShadingCorrectionTargetSelector", "Green");
CHECK(errRes);
/* Set the shading correction target value for green to 1000 */
errRes = PylonDeviceSetFloatFeature(hdev, "BslShadingCorrectionTargetValue", 1.0000);
CHECK(errRes);
/* Set the shading correction target value color/line selector to blue */
errRes = PylonDeviceFeatureFromString(hdev, "BslShadingCorrectionTargetSelector", "Blue");
CHECK(errRes);
/* Set the shading correction target value for blue to 1000 */
errRes = PylonDeviceSetFloatFeature(hdev, "BslShadingCorrectionTargetValue", 1.0000);
CHECK(errRes);

/* Note: Valid for DSNU and PRNU: */
/* Create new shading correction data for the shading correction set selected */
errRes = PylonDeviceExecuteCommandFeature(hdev, "BslShadingCorrectionSetCreate");
CHECK(errRes);
/* Get the status of the shading correction set selected */
len = sizeof(setStatus_str);
errRes = PylonDeviceFeatureToString(hdev, "BslShadingCorrectionSetStatus", setStatus_str, &len);
CHECK(errRes);

# Set the type of shading correction to DSNU
camera.BslShadingCorrectionSelector.Value = "DSNU"
# Or for PRNU: Set the type of shading correction to PRNU
camera.BslShadingCorrectionSelector.Value = "PRNU"

# Note: Valid for DSNU and PRNU:
# Set the shading correction mode to User
camera.BslShadingCorrectionMode.Value = "User"
# Set the desired index number of the set to be created
camera.BslShadingCorrectionSetIndex.Value = 1
# Set the shading correction selector to ROI 1
camera.BslShadingCorrectionROISelector.Value = "ROI1"
# Set the offset X of the ROI to 0
camera.BslShadingCorrectionROIOffsetX.Value = 0
# Set the ROI width to 2048
camera.BslShadingCorrectionROIWidth.Value = 2048

# Note: Valid for PRNU only:
# Set the shading correction target value color/line selector to red
camera.BslShadingCorrectionTargetSelector.Value = "Red"
# Set the shading correction target value for red to 1000
camera.BslShadingCorrectionTargetValue.Value = 1.0000
# Set the shading correction target value color/line selector to green
camera.BslShadingCorrectionTargetSelector.Value = "Green"
# Set the shading correction target value for green to 1000
camera.BslShadingCorrectionTargetValue.Value = 1.0000
# Set the shading correction target value color/line selector to blue
camera.BslShadingCorrectionTargetSelector.Value = "Blue"
# Set the shading correction target value for blue to 1000
camera.BslShadingCorrectionTargetValue.Value = 1.0000

# Note: Valid for DSNU and PRNU:
# Create new shading correction data for the shading correction set selected
camera.BslShadingCorrectionSetCreate.Execute()
# Get the status of the shading correction set selected
setStatus = camera.BslShadingCorrectionSetStatus.Value

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