LUT#

The LUT camera feature allows you to replace the pixel values in your images by values defined by you.

This is done by creating a user-defined lookup table (LUT).

Using the Feature#

How It Works#

LUT is short for "lookup table", which is basically an indexed list of numbers. For Basler cameras, you can create a user-defined "luminance lookup table" to replace the pixel values, i.e., the luminance or gray values, in your images.

In the lookup table you can define replacement values for individual pixel values. For example, you can replace a gray value of 4 095 (= maximum gray value for 12-bit pixel formats) by a gray value of 0 (= minimum gray value). This changes all completely white pixels in your images to completely black pixels.

Setting up a user-defined LUT can be useful, e.g., if you want to optimize the luminance of your images. By defining the replacement values in advance and storing them in the camera, you avoid time-consuming calculations by your application. Instead, the camera can simply look up the desired new value in the LUT based on the pixel's initial value.

Replacing Individual LUT Entries#

To replace individual entries in the lookup table:

1. Set the LUTIndex parameter to the pixel value that you want to replace with a new value.
2. Set the LUTValue parameter to the new pixel value.
3. Repeat steps 1 and 2 for all pixel values that you want to replace.
4. Set the LUTEnable parameter to true.

Basler recommends using a programming loop (e.g., a for-loop) to iterate through the values. See the sample code below.

Number of LUT Entries#

The number of entries available in the LUT varies by camera model.

Depending on the number of LUT entries, it is not always possible to store replacement values for all possible pixel values.

LUT with 512 Entries#

On most Basler cameras, the user-defined LUT can store up to 512 entries. This size is not sufficient for storing the 1 024 or 4 096 replacement values.

Therefore, the following limitations apply:

• On cameras with a maximum pixel bit depth of 10 bit, you can only set the LUTIndex parameter to multiples of two (0, 2, 4, 6, …, 1022). This means that only pixel values of 0, 2, 4, 6, and so on, can be replaced.
• On cameras with a maximum pixel bit depth of 12 bit, you can only set the LUTIndex parameter to multiples of eight (0, 8, 16, 24, …, 4088). This means that only pixel values of 0, 8, 16, 24, and so on, can be replaced.

To determine the remaining pixel values, the camera performs a straight line interpolation.

Example: Assume that the camera has a maximum pixel bit depth of 12 bit. Also assume that you have created a LUT that converts a gray value of 24 to a gray value of 20 and a gray value of 32 to a value of 30. In this case, the camera determines the pixel values between 24 and 32 as follows:

LUT with 1 024 or 4 096 Entries#

On some Basler cameras, the user-defined LUT can store entries for all replacement values. Dependent on the maximum pixel bit depth of the camera, 1 024 or 4 096 entries are available.

This means that the limitations described in the section above don't apply: You can set the LUTIndex parameter in increments of 1, and no interpolation is performed.

Replacing All LUT Entries#

You can replace all entries in the lookup table with a single operation. In many cases, this is faster than repeatedly changing individual entries in the LUT.

To replace all entries in the lookup table:

1. Set the LUTValueAll parameter to the desired value.
   Make sure to apply the correct endianness of the 4-byte words (LUT values).
2. Set the LUTEnable parameter to true.

The parameter structure depends on the maximum pixel bit depth of your camera.

12-bit Camera Models#

On cameras with a maximum pixel bit depth of 12 bit, the LUTValueAll parameter is an array that consists of 4096 x 4 bytes. Each 4-byte word represents a LUTValue parameter value.

The LUTValue parameter values are sorted by the LUTIndex number in ascending order (0 through 4095).

10-bit Camera Models#

On cameras with a maximum pixel bit depth of 10 bit, the LUTValueAll parameter is an array that consists of 1024 x 4 bytes. Each 4-byte word represents a LUTValue parameter value.

The LUTValue parameter values are sorted by the LUTIndex number in ascending order (0 through 1023).

Additional Parameters#

The LUTSelector parameter allows you to select a lookup table.

Because there is only one user-defined lookup table available on Basler cameras, the parameter currently serves no function.

Specifics#

Show all camera models

Sample Code#

// ** Replacing individual LUT entries **
// The following lookup table causes an inversion of the pixel values
// (bright -> dark, dark -> bright)
// Only applies to cameras with a maximum pixel bit depth of 12 bit
for (int i=0; i<4096; i+=8)
{
    camera.LUTIndex.SetValue(i);
    camera.LUTValue.SetValue(4095-i);
}
// Enable the LUT
camera.LUTEnable.SetValue(true);

// ** Replacing all LUT entries in a single operation **
// The following lookup table inverts the pixel values
// (bright -> dark, dark -> bright)
// Only applies to cameras with a maximum pixel bit depth of 12 bit
// Note: This is a simplified code sample.
// You should always check the camera interface and
// the endianness of your system before using LUTValueAll.
// For more information, see the 'LUTValueAll' code sample
// in the pylon API Documentation.
uint32_t lutValues[4096];
for (int i=0; i<4096; i+=8)
{
   lutValues[i] = 4095-i;
}
camera.LUTValueAll.SetValue(lutValues);
// Enable the LUT
camera.LUTEnable.SetValue(true);

This sample code is only available in C++ language.

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