Defect Pixel Correction#
In acquired images, some pixels may appear significantly brighter or darker than the rest, even if uniform light is used. This problem is caused by differences in sensitivity of the individual pixels which in turn are due to production tolerances.
Using the Feature#
The implementation of this feature varies by camera series:
ace 2 R/X, boost R, and dart M Cameras#
Basler ace 2 R, ace 2 X, boost R, and dart M cameras support static defect pixel correction. This correction is based on files that are stored on the camera and contain a list of defect pixel coordinates.
"Static" means that always the same specified defect pixel coordinates are used for the correction process. During image acquisition, the intensity values of exactly these pixels are replaced based on the intensity values of their neighboring pixels.
The following defect pixel correction files can be stored on the camera:
- Factory file: Contains the coordinates of defect pixels that were detected during camera production.
- User file: Contains user-defined coordinates. You can upload this file to the camera. This allows you to define new defect pixels that might have occurred over time.
Info
Basler ace 2 X cameras also support dynamic pixel defect correction. For more information, see Pixel Correction Beyond.
Correcting Defect Pixels Using the pylon Viewer#
→ See Static Defect Pixel Correction (pylon Viewer).
Correcting Defect Pixels Using the pylon API#
Info
Basler recommends performing defect pixel correction using the pylon Viewer.
Only use the pylon API if you want to implement defect pixel correction in your own application.
Setting the Static Defect Pixel Correction Mode#
To set the static defect pixel correction mode, set the BslStaticDefectPixelCorrectionMode
parameter to one of the following values:
Factory
(default): Static defect pixel correction is based on the defect pixels stored in the factory correction file.User
: Static defect pixel correction is based on the defect pixels stored in the user correction file.
Note that when setting this mode via the pylon API, only the user-defined pixels will be used. When setting the User incl. Factory correction mode via the pylon Viewer, user-defined pixels will be used in addition to the pixels stored in the factory file.Off
: The camera does not perform static defect pixel corrections.
Uploading a User Defect Pixel Correction File#
Before uploading a user defect pixel correction file, make sure that the file conforms to the following file format:
The file must start with a 4-byte header containing four bytes with value 0. Following the header, the file must contain defect pixel entries (up to 4096 defect pixels can be specified). Each entry consists of 32 bits with the following order: 14 bits y-coordinate, 14 bits x-coordinate, 4 bits type
Example: Defect pixel entry with the coordinate x = 1 and y = 2
To upload a user defect pixel correction file using the pylon Viewer:
- In the Camera menu of the pylon Viewer, click File Access.
- In the Camera File drop-down box, select User Defect Pixel Correction.
If there's no User Defect Pixel Correction entry, uploading correction files is not supported by your camera. - Click Upload and navigate to the file that you want to upload.
- Click Open.
To apply the user defect pixel correction file after uploading, make sure that the BslStaticDefectPixelCorrectionMode
parameter is set to User
and execute the BslStaticDefectPixelCorrectionReload
command.
Downloading a Defect Pixel Correction File#
Downloading a defect pixel correction file, e.g., the factory correction file, might be useful if you want to add your own measured defect pixels to the downloaded file. You can store the complete list of defect pixel entries in a new user correction file.
To download a defect pixel correction file using the pylon Viewer:
- In the Camera menu of the pylon Viewer, click File Access.
- In the Camera File drop-down box, select Static Factory Defect Pixel Correction or Static User Defect Pixel Correction depending on which file you want to download.
If there's no appropriate entry, downloading files is not supported by your camera. - Click Download, navigate to the directory where you want to save the file, and enter the desired file name.
- Click Open.
Static Defect Pixel Correction File Status#
The StaticDefectPixelCorrectionFileStatus
parameter can take the following values:
FileStatusUnknown
: The status of the defect pixel correction file is unknown. Acquire an image to change the file status.FileOk
: The defect pixel correction file is valid.FileNotFound
: The defect pixel correction file can't be found. It has never been uploaded or was deleted.FileEmpty
: The defect pixel correction file has no entries. The file header is valid but the file doesn't contain any defect pixels. The defect pixel correction process is aborted.InvalidHeader
: The defect pixel correction file header is invalid. The file must have a 4-byte file header.InvalidSize
: The defect pixel correction file size is invalid. The maximum number of defective pixels must not exceed 4096.InvalidSorting
: The sorting of entries in the defect pixel correction file is invalid. The defect pixel correction process is aborted.InvalidFileEntry
: At least one entry in the defect pixel correction file has an invalid size. The defect pixel correction process is aborted.InvalidClustering
: An invalid cluster has been found. Three or more adjacent pixels in a row are considered an invalid cluster. Any defect pixels between other defect pixels can't be corrected.
The defect pixel correction file can contain a maximum number of defect pixels. To get the number, get the value of the BslStaticDefectPixelCorrectionMaxDefects
parameter.
boost V Cameras#
Basler boost V cameras support static defect pixel correction. This correction is based on files that are stored on the camera and contain a list of defect pixel coordinates.
"Static" means that always the same specified defect pixel coordinates are used for the correction process. During image acquisition, the intensity values of exactly these pixels are replaced based on the intensity values of their neighboring pixels.
Performing Defect Pixel Correction#
Info
The pylon Viewer's built-in Static Defect Pixel Correction feature doesn't support boost V cameras.
Use the feature tree of the pylon Viewer or the pylon API to perform defect pixel correction on boost V cameras.
To perform defect pixel correction on boost V cameras:
-
Set the
BslStaticDefectPixelCorrectionMode
parameter to the desired correction mode:Factory
: Only defect pixels whose coordinates are stored in the factory file are corrected. The factory file is generated during camera production and can't be changed.User
: You can specify custom defect pixel coordinates.Off
: The camera does not perform static defect pixel corrections.
-
If you selected
User
:- Find pixel errors in your images and write down the x and y coordinates of the defect pixels.
- Set the
BslStaticDefectPixelCorrectionYCoordinate
parameter to the y coordinate of the first defect pixel. - Set the
BslStaticDefectPixelCorrectionXSelector
parameter toX0
. - Set the
BslStaticDefectPixelCorrectionXCoordinate
parameter to the x coordinate of the first defect pixel. - If there's another defect pixel with the same y coordinate, but a different x coordinate, set the
BslStaticDefectPixelCorrectionXSelector
parameter to the next entry, e.g.,X1
, and enter the next x coordinate. - Repeat steps b to for all other pixel errors.
- Execute the
BslStaticDefectPixelCorrectionSave
command to save changes to flash memory.
Info
- You can use the
BslStaticDefectPixelCorrectionCount
parameter to check how many image pixels are currently being corrected. - You can set the
BslStaticDefectPixelCorrectionTestMode
parameter toOn
to set all corrected pixels to completely white. This helps to find pixels that are being corrected in your images.
Removing Defect Pixel Coordinates#
Pixel coordinates in the factory file can't be removed.
However, you can remove custom defect pixel coordinates, i.e., coordinates entered in "User" correction mode (see above). To do so:
-
If you want to remove a single custom defect pixel coordinate:
- Set the
BslStaticDefectPixelCorrectionYCoordinate
parameter to the y coordinate of the defect pixel. - Set the
BslStaticDefectPixelCorrectionXSelector
parameter to the entry that holds the x coordinate of the defect pixel, e.g.,X0
. - Set the
BslStaticDefectPixelCorrectionXCoordinate
parameter to 0xFFFF. - Execute the
BslStaticDefectPixelCorrectionSave
command to save changes to flash memory.
- Set the
-
If you want to remove all custom defect pixel coordinates:
- Execute the
BslStaticDefectPixelCorrectionClearAll
command. This sets allBslStaticDefectPixelCorrectionXCoordinate
parameter values to 0xFFFF. - Execute the
BslStaticDefectPixelCorrectionSave
command to save changes to flash memory.
- Execute the
dart and pulse Cameras#
Basler dart and pulse cameras can perform two types of pixel corrections:
- The static pixel correction corrects pixels that have significantly lesser intensity values than their neighboring pixels, including completely black pixels.
- The dynamic pixel correction corrects pixels that have significantly higher intensity values than their neighboring pixels, including completely white pixels. An internal threshold value defines when a pixel is detected as a "hot pixel". "Dynamic" means that the defect pixel correction is calculated individually for each acquired image.
Setting the Defect Pixel Correction Mode#
To set the defect pixel correction mode, set the BslDefectPixelCorrectionMode
parameter to one of the following values:
On
(default): The camera performs static and dynamic pixel corrections.StaticOnly
: The camera performs the static pixel correction only.Off
: The camera does not perform pixel corrections.
Sample Code#
ace 2 R/X, boost R, and dart M Cameras#
/* 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 */
/* Set static user defect pixel correction */
errRes = PylonDeviceFeatureFromString(hdev, "BslStaticDefectPixelCorrectionMode", "User");
CHECK(errRes);
/* Reload static defect pixel correction file */
errRes = PylonDeviceExecuteCommandFeature(hdev, "BslStaticDefectPixelCorrectionReload");
CHECK(errRes);
boost V Cameras#
// Set the defect pixel correction mode to User
camera.BslStaticDefectPixelCorrectionMode.SetValue(BslStaticDefectPixelCorrectionMode_User);
// Assume there are two defect pixels at coordinates (120,430) and (182,430)
// Set the y coordinate to 430
camera.BslStaticDefectPixelCorrectionYCoordinate.SetValue(430);
// Select entry X0 and assign the first x coordinate
camera.BslStaticDefectPixelCorrectionXSelector.SetValue(BslStaticDefectPixelCorrectionXSelector_X0);
camera.BslStaticDefectPixelCorrectionXCoordinate.SetValue(120);
// Select entry X1 and assign the second x coordinate, which is in the same line
camera.BslStaticDefectPixelCorrectionXSelector.SetValue(BslStaticDefectPixelCorrectionXSelector_X1);
camera.BslStaticDefectPixelCorrectionXCoordinate.SetValue(182);
// Save changes to flash memory
camera.BslStaticDefectPixelCorrectionSave.Execute();
INodeMap& nodemap = camera.GetNodeMap();
// Set the defect pixel correction mode to User
CEnumParameter(nodemap, "BslStaticDefectPixelCorrectionMode").SetValue("User");
// Assume there are two defect pixels at coordinates (120,430) and (182,430)
// Set the y coordinate to 430
CIntegerParameter(nodemap, "BslStaticDefectPixelCorrectionYCoordinate").SetValue(430);
// Select entry X0 and assign the first x coordinate
CEnumParameter(nodemap, "BslStaticDefectPixelCorrectionXSelector").SetValue("X0");
CIntegerParameter(nodemap, "BslStaticDefectPixelCorrectionXCoordinate").SetValue(120);
// Select entry X1 and assign the second x coordinate, which is in the same line
CEnumParameter(nodemap, "BslStaticDefectPixelCorrectionXSelector").SetValue("X1");
CIntegerParameter(nodemap, "BslStaticDefectPixelCorrectionXCoordinate").SetValue(182);
// Save changes to flash memory
CCommandParameter(nodemap, "BslStaticDefectPixelCorrectionSave").Execute();
// Set the defect pixel correction mode to User
camera.Parameters[PLCamera.BslStaticDefectPixelCorrectionMode].SetValue(PLCamera.BslStaticDefectPixelCorrectionMode.User);
// Assume there are two defect pixels at coordinates (120,430) and (182,430)
// Set the y coordinate to 430
camera.Parameters[PLCamera.BslStaticDefectPixelCorrectionYCoordinate].SetValue(430);
// Select entry X0 and assign the first x coordinate
camera.Parameters[PLCamera.BslStaticDefectPixelCorrectionXSelector].SetValue(PLCamera.BslStaticDefectPixelCorrectionXSelector.X0);
camera.Parameters[PLCamera.BslStaticDefectPixelCorrectionXCoordinate].SetValue(120);
// Select entry X1 and assign the second x coordinate, which is in the same line
camera.Parameters[PLCamera.BslStaticDefectPixelCorrectionXSelector].SetValue(PLCamera.BslStaticDefectPixelCorrectionXSelector.X1);
camera.Parameters[PLCamera.BslStaticDefectPixelCorrectionXCoordinate].SetValue(182);
// Save changes to flash memory
camera.Parameters[PLCamera.BslStaticDefectPixelCorrectionSave].Execute();
/* 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 */
/* Set the defect pixel correction mode to User */
errRes = PylonDeviceFeatureFromString(hdev, "BslStaticDefectPixelCorrectionMode", "User");
CHECK(errRes);
/* Assume there are two defect pixels at coordinates (120,430) and (182,430) */
/* Set the y coordinate to 430 */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslStaticDefectPixelCorrectionYCoordinate", 430);
CHECK(errRes);
/* Select entry X0 and assign the first x coordinate */
errRes = PylonDeviceFeatureFromString(hdev, "BslStaticDefectPixelCorrectionXSelector", "X0");
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslStaticDefectPixelCorrectionXCoordinate", 120);
CHECK(errRes);
/* Select entry X1 and assign the second x coordinate, which is in the same line */
errRes = PylonDeviceFeatureFromString(hdev, "BslStaticDefectPixelCorrectionXSelector", "X1");
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslStaticDefectPixelCorrectionXCoordinate", 182);
CHECK(errRes);
/* Save changes to flash memory */
errRes = PylonDeviceExecuteCommandFeature(hdev, "BslStaticDefectPixelCorrectionSave");
CHECK(errRes);
# Set the defect pixel correction mode to User
camera.BslStaticDefectPixelCorrectionMode.Value = "User"
# Assume there are two defect pixels at coordinates (120,430) and (182,430)
# Set the y coordinate to 430
camera.BslStaticDefectPixelCorrectionYCoordinate.Value = 430
# Select entry X0 and assign the first x coordinate
camera.BslStaticDefectPixelCorrectionXSelector.Value = "X0"
camera.BslStaticDefectPixelCorrectionXCoordinate.Value = 120
# Select entry X1 and assign the second x coordinate, which is in the same line
camera.BslStaticDefectPixelCorrectionXSelector.Value = "X1"
camera.BslStaticDefectPixelCorrectionXCoordinate.Value = 182
# Save changes to flash memory
camera.BslStaticDefectPixelCorrectionSave.Execute()
dart and pulse Cameras#
/* 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 */
/* Disable defect pixel correction */
errRes = PylonDeviceFeatureFromString(hdev, "BslDefectPixelCorrectionMode", "Off");
CHECK(errRes);
You can also use the pylon Viewer to easily set the parameters.