MgenLutFunction

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Generate data into a LUT buffer using a specified standard mathematical function, or a specified colormap (pseudo-color palette).

Syntax

void MgenLutFunction(
    AIL_ID     LutBufId,     //out
    AIL_INT    Func,         //in
    AIL_DOUBLE a,            //in
    AIL_DOUBLE b,            //in
    AIL_DOUBLE c,            //in
    AIL_INT    StartIndex,   //in
    AIL_DOUBLE StartXValue,  //in
    AIL_INT    EndIndex      //in
)

Description

This function generates a value for each LUT index according to the specified mathematical function or colormap (pseudo-color palette).

When generating values based on a mathematical function, you can limit generation to a specified range of LUT indices (StartIndex to EndIndex inclusive). The supported mathematical functions take a single variable (x). The StartXValue parameter specifies the initial x value. The remaining entries of the index range are generated by incrementing the value of x by 1 for each index. All results are converted to integer by truncation, except when using a floating-point LUT buffer. Note, if the given parameters cause an overflow or underflow, indeterminate results will be written in the destination LUT.

When generating a colormap LUT, you can specify a replacement value for the color assigned to index 0 of the LUT and for the color assigned to the highest index of the LUT (M_FIRST_GRAY and M_LAST_GRAY, respectively). This helps to highlight invalid pixels when working with images produced from cameras or 3D sensors that set such pixels to 0 or to the highest possible intensity value. You can also specify the number of times the basic colormap pattern is to be repeated (c parameter). This is useful to visualize small local intensity variations in depth maps or 3D data. It is best to use a colormap that has the same color on both ends (cyclic) for a seamless transition between the repeating colormap pattern (for example, M_COLORMAP_WHEEL).

Parameters

`LutBufId` (out, AIL_ID)

Specifies the identifier of the LUT in which to generate values. This parameter must be given a valid LUT buffer identifier, allocated using MbufAlloc1d or MbufAllocColorwith M_LUT. If the LUT is a multi-band LUT (allocated with MbufAllocColor), the same data is written to all bands, except when filling the LUT buffer with a colormap. For a LUT buffer allocated with MbufAllocColor, the buffer height (SizeY parameter) must have been set to a value of 1.

`Func` (in, AIL_INT)

Specifies the mathematical function or colormap to use for calculations.

For specifying the mathematical function

Value	Description
`M_COS`	Uses the following formula for calculation: `_a_ cos (_b_ _x_) + _c_`. x is considered to be in degrees.
`M_EXP`	Uses the following formula for calculation: `_a_ _b <sup> _x_ </sup> _ + _c_`.
`M_LOG`	Uses the following formula for calculation: `_a_ log <sub> _b_ </sub> (_x_) + _c_`.
`M_POWER`	Uses the following formula for calculation: `_a_ _x_ <sup>b</sup> + _c_`.
`M_QUAD`	Uses the following formula for calculation: `_a_ _x_ <sup>2</sup> + _b_ _x_ + _c_`.
`M_SIGMOID`	Uses the following formula for calculation: `_b_ + ((_c_ - _b_) / (1 + e<sup>-_a_ _x_ </sup>))`.

Note that b and c are, respectively, the minimum and maximum possible values of the destination LUT buffer.

If a is positive, the sigmoidal curve increases from b to c.

If a is negative, the sigmoidal curve decreases from c to b.

If b and c are not equal, a must not be 0.

Note that you can set the StartXValue parameter such that the curve shifts left or right (that is, in the negative or positive X directions, respectively). | | M_SIN | Uses the following formula for calculation: _a_ sin (_b_ _x_) + _c_. x is considered to be in degrees. | | M_TAN | Uses the following formula for calculation: _a_ tan (_b_ _x_) + _c_. x is considered to be in degrees. | | M_TONE_MAPPING | Uses the following formula for calculation.

[Image: reg_ToneMapping_formula.png]

This mathematical function generates a LUT mapping that distributes pixel intensity values within the specified range.

MaxDstVal and MinDstVal represent the highest and lowest possible values of the destination LUT buffer. For example, for an 8-bit buffer, the maximum and minimum values are 255 and 0, respectively. For a floating-point LUT buffer, the maximum and minimum values are 1.0 and 0.0, respectively.

a is the highest source value that maps to 0 in the destination LUT. This removes unnecessary intensity levels at the near-zero end (below the a threshold), and allows more intensity distribution elsewhere in the LUT.

b is the lowest source value that maps to the highest value in the destination LUT. This removes unnecessary intensity levels at the saturated end (above the b threshold), and allows more intensity distribution elsewhere in the LUT.

c is the tone mapping coefficient, which affects the intensity distribution in the destination LUT buffer. In terms of pixel values, a higher coefficient (closer to 1.0) gives a broader intensity range to bright areas, which improves bright area detail and lowers the overall brightness of the final image. Conversely, a lower coefficient (closer to 0.0), gives a broader intensity range to dark areas, improving dark area detail and increasing the overall brightness of the final image.

To use this mathematical function, you must set theStartIndex, StartXValue, and EndIndex parameters to M_DEFAULT.

Note: Note that you can use the M_TONE_MAPPING formula to map a 16-bit image to an 8-bit image. |

For specifying a colormap

Value	Description
`M_COLORMAP_DISTINCT_256`	Fills the LUT buffer with a distinct colormap. This colormap is designed to maximize the visual difference between consecutive colors. This colormap can be useful for colorizing images containing discrete objects, such as labeled blobs.

Note that this colormap is periodic, meaning that if the given LUT buffer has more than 256 entries, the remaining entries will be filled starting from the first color in the colormap.

[Image: Distinct_colormap.png] | | M_COLORMAP_GRAYSCALE | Fills the LUT buffer with a grayscale colormap. This colormap transitions from black to white as the indices increase. To transition from white to black, add the M_FLIP combination value.

[Image: colormap_grayscale.png] | | M_COLORMAP_HOT | Fills the LUT buffer with a hot colormap. This colormap transitions from black, to red, to yellow, and then, to white along the RGB cube as the indices increase. This colormap can be useful for displaying infrared images.

[Image: Hot_colormap.png] | | M_COLORMAP_HUE | Fills the LUT buffer with a hue colormap. This colormap is cyclic and transitions from red, to yellow, to green, to cyan, to blue, to magenta, and then, to red along the edge of the hue circle as the indices increase. This colormap is suitable to be repeated. This colormap is useful for displaying the hue band of an HSL image.

[Image: Hue_colormap.png] | | M_COLORMAP_JET | Fills the LUT buffer with a jet colormap. This colormap transitions from dark blue, to blue, to cyan, to yellow, to red, and then, to dark red along the RGB cube as the indices increase. This colormap can be useful for displaying 3D elevation maps and thermal imaging.

[Image: Jet_colormap.png] | | M_COLORMAP_SPECTRUM | Fills the LUT buffer with a spectrum colormap. This colormap transitions from red, to yellow, to green, to blue, and then, to violet along the RGB cube as the indices increase. This colormap is a representation of the visual spectrum according to wavelengths. It can also be useful for displaying 3D elevation maps and thermal imaging.

[Image: spectrum_colormap.png] | | M_COLORMAP_TURBO | Fills the LUT buffer with a turbo colormap. This colormap is an improved version of the jet colormap, with smoother color transitions. It transitions from dark blue, to blue, to cyan, to yellow, to red, and then, to dark red along the RGB cube as the indices increase. This colormap can be useful for displaying 3D elevation maps and thermal imaging.

[Image: Turbo_colormap.png] | | M_COLORMAP_WHEEL | Fills the LUT buffer with a colorwheel colormap. This colormap is cyclic and transitions from blue, to magenta, to yellow, to green and to blue again as the indices increase. This colormap is designed to be perceptually uniform (a given change in data is designed to be visually perceived as an equal change in color). This colormap is suitable to be repeated. This colormap can be useful for displaying 3D elevation maps.

[Image: Wheel_colormap.png] |

For specifying to replace the colormap's first and/or last color value, or to reverse the colors

Value	Description
`M_FIRST_GRAY`	Specifies to replace the value for the color assigned to index 0 of the LUT with the value specified with the `a` parameter.
`M_FLIP`	Specifies to reverse the sequence of colors in the colormap.
`M_LAST_GRAY`	Specifies to replace the value for the color assigned to the highest index of the LUT with the value specified with the `b` parameter.

`a` (in, AIL_DOUBLE)

Specifies the constant a for the specified mathematical function, or specifies a replacement value for the color assigned to index 0 of the LUT, if filling the LUT with a colormap.

For specifying the first constant or color replacement value

Value	Description
`M_DEFAULT`	Specifies that this parameter is not used. This setting is only applicable when filling the LUT with a colormap, and `M_FIRST_GRAY` is not specified.
`M_RGB888`	Specifies an RGB color replacement value. Each value (red, green, or blue) must not exceed 8 bits.

Note: This setting is suitable only if the image to which the LUT is applied is stored in an unsigned, 3-band image buffer, where the data depth per band is 8-bit (AIL_UINT8). | | Value | Specifies the first constant's value, or specifies the color replacement value. |

`b` (in, AIL_DOUBLE)

Specifies the constant b for the specified mathematical function, or specifies a replacement value for the color assigned to the highest index of the LUT, if filling the LUT with a colormap.

For specifying the second constant or color replacement value

Value	Description
`M_DEFAULT`	Specifies that this parameter is not used. This setting is only applicable when filling the LUT with a colormap, and `M_LAST_GRAY` is not specified.
`M_RGB888`	Specifies an RGB color replacement value. Each value (red, green, or blue) must not exceed 8 bits.

Note: This setting is suitable only if the image to which the LUT is applied is stored in an unsigned, 3-band image buffer, where the data depth per band is 8-bit (AIL_UINT8). | | Value | Specifies the second constant's value, or specifies the color replacement value. |

`c` (in, AIL_DOUBLE)

Specifies the constant c for the specified mathematical function, or specifies a value for the number of times the basic pattern is to be repeated, if filling the LUT with a colormap.

For specifying the third constant or the value for the number of times the basic pattern is to be repeated

Value	Description
`M_DEFAULT`	Specifies the default value; the default value is 1 and the colormap will not repeat. This setting is only applicable when filling the LUT with a colormap.
`Value`	Specifies the third constant's value, or specifies the value for the number of times the basic pattern is to be repeated.

If filling the LUT with an M_COLORMAP_DISTINCT_256 colormap, the value must be set to M_DEFAULT.

If filling the LUT with a colormap other than M_COLORMAP_DISTINCT_256, the value must be set to a number greater than 0.

For values greater than 1, it is best to use a cyclic colormap (for example, M_COLORMAP_WHEEL).

Example LUTs filled with`M_COLORMAP_WHEEL` colormap and varying number of basic pattern repeat values.
Value = 1 (`M_DEFAULT`)
Value = 0.5
Value = 3.0
Value = 6.2

`StartIndex` (in, AIL_INT)

Specifies the first LUT index entry for which to generate values.

For specifying the first index

Value	Description
`M_DEFAULT`	Specifies the first index entry of the LUT (index 0).
`0 < = Value < LUT size`	Specifies the first index entry to affect.

`StartXValue` (in, AIL_DOUBLE)

Specifies the initial value of x in the mathematical function.

For specifying the initial

Value	Description
`M_DEFAULT`	Specifies the default value; the default value is 0.0.

Note: If filling the LUT with a colormap, specifies to ignore the initial x value. | | Value | Specifies the first x value to use during calculation. |

`EndIndex` (in, AIL_INT)

Specifies the last LUT index entry for which to generate values.

For specifying the last index

Value	Description
`M_DEFAULT`	Specifies the last index entry of the LUT.
`StartIndex <= Value < LUT size`	Specifies the last index entry to affect.

Syntax​

Description​

Parameters​

LutBufId (out, AIL_ID)​

Func (in, AIL_INT)​

a (in, AIL_DOUBLE)​

b (in, AIL_DOUBLE)​

c (in, AIL_DOUBLE)​

StartIndex (in, AIL_INT)​

StartXValue (in, AIL_DOUBLE)​

EndIndex (in, AIL_INT)​