Skip to content

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.

Info

The value range of the user-defined LUT (0–1 024 or 0–4 096) is not dependent on the currently selected pixel format. it is dependent on the maximum pixel bit depth of the camera.

If your camera supports 12-bit pixel formats, but currently uses an 8-bit pixel format, you will still be able to enter pixel values between 0 and 4 096. The camera uses these values for conversion. Then, it drops the 4 least significant bits of the converted values and transmits the 8 most significant bits.

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:

Original Pixel Value Value Stored in LUT Interpolated Value New Pixel Value (Rounded)
24 20 20 20
25 - 21.25 21
26 - 22.5 22
27 - 23.75 23
28 - 25 25
29 - 26.25 26
30 - 27.5 27
31 - 28.75 28
32 30 30 30

Info

Pixel values above 4088 are not interpolated. Instead, all pixel values between 4 088 and 4 095 are replaced by the pixel value entered at LUT index position 4 088.

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.

Info

The LUTValueAll parameter is only available via the pylon API, not via the pylon Viewer feature tree.

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).

Info

  • The endianness of the 4-byte words (lut values) depends on your camera model.
  • If the LUT is limited to 512 entries, only every eighth 4-byte word (0, 8, 16, 24, …, 4088) is actually used by the camera. The other 4-byte words are ignored. Example:

    LUTValueAll Parameter Structure (12-Bit Camera Models)

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).

Info

  • The endianness of the 4-byte words (lut values) depends on your camera model.
  • If the LUT is limited to 512 entries, only every second 4-byte word (0, 2, 4, 6, …, 1022) is actually used by the camera. The other 4-byte words are ignored. Example:

    LUTValueAll Parameter Structure (10-Bit Camera Models)

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

Camera Model Number of LUT Entries Endianness of the 4-Byte Words (LUT Values)
a2A1920-51gcBAS 4096 Big-endian
a2A1920-51gcPRO 4096 Big-endian
a2A1920-51gmBAS 4096 Big-endian
a2A1920-51gmPRO 4096 Big-endian
a2A1920-160ucBAS 4096 Little-endian
a2A1920-160ucPRO 4096 Little-endian
a2A1920-160umBAS 4096 Little-endian
a2A1920-160umPRO 4096 Little-endian
a2A2590-22gcBAS 4096 Big-endian
a2A2590-22gcPRO 4096 Big-endian
a2A2590-22gmBAS 4096 Big-endian
a2A2590-22gmPRO 4096 Big-endian
a2A2590-60ucBAS 4096 Little-endian
a2A2590-60ucPRO 4096 Little-endian
a2A2590-60umBAS 4096 Little-endian
a2A2590-60umPRO 4096 Little-endian
a2A3840-13gcBAS 4096 Big-endian
a2A3840-13gcPRO 4096 Big-endian
a2A3840-13gmBAS 4096 Big-endian
a2A3840-13gmPRO 4096 Big-endian
a2A3840-45ucBAS 4096 Little-endian
a2A3840-45ucPRO 4096 Little-endian
a2A3840-45umBAS 4096 Little-endian
a2A3840-45umPRO 4096 Little-endian
acA640-90gc 512 Big-endian
acA640-90gm 512 Big-endian
acA640-90uc 512 Little-endian
acA640-90um 512 Little-endian
acA640-120gc 512 Big-endian
acA640-120gm 512 Big-endian
acA640-120uc 512 Little-endian
acA640-120um 512 Little-endian
acA640-121gm 512 Big-endian
acA640-300gc 512 Big-endian
acA640-300gm 512 Big-endian
acA640-750uc 512 Little-endian
acA640-750um 512 Little-endian
acA720-290gc 512 Big-endian
acA720-290gm 512 Big-endian
acA720-520uc 512 Little-endian
acA720-520um 512 Little-endian
acA780-75gc 512 Big-endian
acA780-75gm 512 Big-endian
acA800-200gc 512 Big-endian
acA800-200gm 512 Big-endian
acA800-510uc 512 Little-endian
acA800-510um 512 Little-endian
acA1280-60gc 512 Big-endian
acA1280-60gm 512 Big-endian
acA1300-22gc 512 Big-endian
acA1300-22gm 512 Big-endian
acA1300-30gc 512 Big-endian
acA1300-30gm 512 Big-endian
acA1300-30uc 512 Little-endian
acA1300-30um 512 Little-endian
acA1300-60gc 512 Big-endian
acA1300-60gm 512 Big-endian
acA1300-60gmNIR 512 Big-endian
acA1300-75gc 512 Big-endian
acA1300-75gm 512 Big-endian
acA1300-200uc 512 Little-endian
acA1300-200um 512 Little-endian
acA1440-73gc 512 Big-endian
acA1440-73gm 512 Big-endian
acA1440-220uc 512 Little-endian
acA1440-220um 512 Little-endian
acA1600-20gc 512 Big-endian
acA1600-20gm 512 Big-endian
acA1600-20uc 512 Little-endian
acA1600-20um 512 Little-endian
acA1600-60gc 512 Big-endian
acA1600-60gm 512 Big-endian
acA1920-25gc 512 Big-endian
acA1920-25gm 512 Big-endian
acA1920-25uc 512 Little-endian
acA1920-25um 512 Little-endian
acA1920-40gc 512 Big-endian
acA1920-40gm 512 Big-endian
acA1920-40uc 512 Little-endian
acA1920-40ucMED 4096 Little-endian
acA1920-40um 512 Little-endian
acA1920-40umMED 4096 Little-endian
acA1920-48gc 512 Big-endian
acA1920-48gm 512 Big-endian
acA1920-50gc 512 Big-endian
acA1920-50gm 512 Big-endian
acA1920-150uc 512 Little-endian
acA1920-150um 512 Little-endian
acA1920-155uc 512 Little-endian
acA1920-155ucMED 4096 Little-endian
acA1920-155um 512 Little-endian
acA1920-155umMED 4096 Little-endian
acA2000-50gc 512 Big-endian
acA2000-50gm 512 Big-endian
acA2000-50gmNIR 512 Big-endian
acA2000-165uc 512 Little-endian
acA2000-165um 512 Little-endian
acA2000-165umNIR 512 Little-endian
acA2040-25gc 512 Big-endian
acA2040-25gm 512 Big-endian
acA2040-25gmNIR 512 Big-endian
acA2040-35gc 512 Big-endian
acA2040-35gm 512 Big-endian
acA2040-55uc 512 Little-endian
acA2040-55um 512 Little-endian
acA2040-90uc 512 Little-endian
acA2040-90um 512 Little-endian
acA2040-90umNIR 512 Little-endian
acA2040-120uc 512 Little-endian
acA2040-120um 512 Little-endian
acA2440-20gc 512 Big-endian
acA2440-20gm 512 Big-endian
acA2440-35uc 512 Little-endian
acA2440-35ucMED 4096 Little-endian
acA2440-35um 512 Little-endian
acA2440-35umMED 4096 Little-endian
acA2440-75uc 512 Little-endian
acA2440-75ucMED 4096 Little-endian
acA2440-75um 512 Little-endian
acA2440-75umMED 4096 Little-endian
acA2500-14gc 512 Big-endian
acA2500-14gm 512 Big-endian
acA2500-14uc 512 Little-endian
acA2500-14um 512 Little-endian
acA2500-20gc 512 Big-endian
acA2500-20gcMED 512 Big-endian
acA2500-20gm 512 Big-endian
acA2500-20gmMED 512 Big-endian
acA2500-60uc 512 Little-endian
acA2500-60um 512 Little-endian
acA3088-16gc 512 Big-endian
acA3088-16gm 512 Big-endian
acA3088-57uc 512 Little-endian
acA3088-57um 512 Little-endian
acA3800-10gc 512 Big-endian
acA3800-10gm 512 Big-endian
acA3800-14uc 512 Little-endian
acA3800-14um 512 Little-endian
acA4024-8gc 512 Big-endian
acA4024-8gm 512 Big-endian
acA4024-29uc 512 Little-endian
acA4024-29um 512 Little-endian
acA4096-11gc 512 Big-endian
acA4096-11gm 512 Big-endian
acA4096-30uc 512 Little-endian
acA4096-30ucMED 4096 Little-endian
acA4096-30um 512 Little-endian
acA4096-30umMED 4096 Little-endian
acA4096-40uc 512 Little-endian
acA4096-40ucMED 4096 Little-endian
acA4096-40um 512 Little-endian
acA4096-40umMED 4096 Little-endian
acA4112-8gc 512 Big-endian
acA4112-8gm 512 Big-endian
acA4112-20uc 512 Little-endian
acA4112-20ucMED 4096 Little-endian
acA4112-20um 512 Little-endian
acA4112-20umMED 4096 Little-endian
acA4112-30uc 512 Little-endian
acA4112-30ucMED 4096 Little-endian
acA4112-30um 512 Little-endian
acA4112-30umMED 4096 Little-endian
acA4600-7gc 512 Big-endian
acA4600-10uc 512 Little-endian
acA5472-5gc 512 Big-endian
acA5472-5gm 512 Big-endian
acA5472-17uc 512 Little-endian
acA5472-17um 512 Little-endian
boA4096-93cc 4096 Little-endian
boA4096-93cm 4096 Little-endian
boA4112-68cc 4096 Little-endian
boA4112-68cm 4096 Little-endian
daA1280-54lc LUT feature not supported LUT feature not supported
daA1280-54lm LUT feature not supported LUT feature not supported
daA1280-54uc LUT feature not supported LUT feature not supported
daA1280-54um LUT feature not supported LUT feature not supported
daA1600-60lc LUT feature not supported LUT feature not supported
daA1600-60lm LUT feature not supported LUT feature not supported
daA1600-60uc LUT feature not supported LUT feature not supported
daA1600-60um LUT feature not supported LUT feature not supported
daA1920-15um LUT feature not supported LUT feature not supported
daA1920-30uc LUT feature not supported LUT feature not supported
daA1920-30um LUT feature not supported LUT feature not supported
daA2500-14lc LUT feature not supported LUT feature not supported
daA2500-14lm LUT feature not supported LUT feature not supported
daA2500-14uc LUT feature not supported LUT feature not supported
daA2500-14um LUT feature not supported LUT feature not supported
daA2500-60mc LUT feature not supported LUT feature not supported
daA2500-60mci LUT feature not supported LUT feature not supported
daA4200-30mci LUT feature not supported LUT feature not supported
puA1280-54uc LUT feature not supported LUT feature not supported
puA1280-54um LUT feature not supported LUT feature not supported
puA1600-60uc LUT feature not supported LUT feature not supported
puA1600-60um LUT feature not supported LUT feature not supported
puA1920-30uc LUT feature not supported LUT feature not supported
puA1920-30um LUT feature not supported LUT feature not supported
puA2500-14uc LUT feature not supported LUT feature not supported
puA2500-14um LUT feature not supported LUT feature not supported

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 C++ Programmer's Guide and Reference Documentation
// delivered with the Basler pylon Camera Software Suite.
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.