MgenLutFunction

See also

User Guide:

Dealing with color Generating fully corrected depth and intensity maps Loading and generating data into LUTs Mathematics with images

Reference:

MbufAlloc1d MbufAllocColor MbufInquire

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

blobtransform.cpp
depthmapgoldentemplate.cpp
m3dgra.cpp
m3dgra.cs
m3dgra.vb
mgenlutfunction.cpp
pointcloudprojection.cpp
polarizationimaging.cpp
studinspection.cpp

Function Map

- LutBufId

- Func

Table:	For specifying the mathematical function
Table:	For specifying a colormap
+ combination:	For specifying to replace the colormap's first and/or last gray value

- a

Table:

For specifying the first constant or color replacement value

- b

Table:

For specifying the second constant or color replacement value

- c

Table:

For specifying the third constant

- StartIndex

Table:

For specifying the first index

- StartXValue

Table:

For specifying the initial x value

- EndIndex

Table:

For specifying the last index

Compilation information

Synopsis

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

Syntax

void MgenLutFunction(

MIL_ID LutBufId,	//in
MIL_INT Func,	//in
MIL_DOUBLE a,	//in
MIL_DOUBLE b,	//in
MIL_DOUBLE c,	//in
MIL_INT StartIndex,	//in
MIL_DOUBLE StartXValue,	//in
MIL_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.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

LutBufId

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 MbufAllocColor() with 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.

When filling the LUT buffer with a colormap, the buffer must be a 3-band, unsigned or floating-point LUT buffer.

Func

Specifies the mathematical function or colormap to use for calculations.

To fill the LUT using a mathematical function, set this parameter to one of the following:

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. (summarize) Uses the following formula for calculation: a cos (b x) + c . (more details...)
M_EXP	Uses the following formula for calculation: a b^x + c .
M_LOG	Uses the following formula for calculation: a log _b (x) + c .
M_POWER	Uses the following formula for calculation: a x ^b + c .
M_QUAD	Uses the following formula for calculation: a x ² + b x + c .
M_SIGMOID	Uses the following formula for calculation: b + ((c - b) / (1 + e^{- a x} )) . 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). (summarize) Uses the following formula for calculation: b + ((c - b) / (1 + e^{- a x} )) . (more details...)
M_SIN	Uses the following formula for calculation: a sin (b x) + c . x is considered to be in degrees. (summarize) Uses the following formula for calculation: a sin (b x) + c . (more details...)
M_TAN	Uses the following formula for calculation: a tan (b x) + c . x is considered to be in degrees. (summarize) Uses the following formula for calculation: a tan (b x) + c . (more details...)
M_TONE_MAPPING	Uses the following formula for calculation. This mathematical function generates a LUT mapping that distributes pixel intensity values within the specified range. Note that 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. Note that you can use the M_TONE_MAPPING formula to map a 16-bit image to an 8-bit image. Note that, to use the M_TONE_MAPPING mathematical function, you must set the StartXValue parameter to M_DEFAULT. (summarize) Uses the following formula for calculation. (more details...)

To fill the LUT with a colormap (pseudo-color palette), set this parameter to one of the following:

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. (summarize) Fills the LUT buffer with a distinct colormap. (more details...)
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. (summarize) Fills the LUT buffer with a hot colormap. (more details...)
M_COLORMAP_HUE +	Fills the LUT buffer with a hue colormap. This colormap 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 useful for displaying the hue component of an HSL image. (summarize) Fills the LUT buffer with a hue colormap. (more details...)
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. (summarize) Fills the LUT buffer with a jet colormap. (more details...)
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. (summarize) Fills the LUT buffer with a spectrum colormap. (more details...)
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. (summarize) Fills the LUT buffer with a turbo colormap. (more details...)

Combination values for the values listed in For specifying a colormap.

You can add one or more of the following values to the above-mentioned values to specify a replacement value for the color assigned to index 0 of the LUT and/or that assigned to the highest index of the LUT.

For specifying to replace the colormap's first and/or last gray value
Combination 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_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.

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. (summarize) Specifies that this parameter is not used. (more details...)
M_RGB888( MIL_INT Red, MIL_INT Green, MIL_INT Blue )	Specifies an RGB color replacement value. Each value (red, green, or blue) must not exceed 8 bits. 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 (MIL_UINT8). (summarize) Specifies an RGB color replacement value. (more details...)
		Parameters
		Red Specifies the red component, as a value between 0 and 255.
		Green Specifies the green component, as a value between 0 and 255.
		Blue Specifies the blue component, as a value between 0 and 255.
Value	Specifies the first constant's value, or specifies the color replacement value.

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. (summarize) Specifies that this parameter is not used. (more details...)
M_RGB888( MIL_INT Red, MIL_INT Green, MIL_INT Blue )	Specifies an RGB color replacement value. Each value (red, green, or blue) must not exceed 8 bits. 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 (MIL_UINT8). (summarize) Specifies an RGB color replacement value. (more details...)
		Parameters
		Red Specifies the red component, as a value between 0 and 255.
		Green Specifies the green component, as a value between 0 and 255.
		Blue Specifies the blue component, as a value between 0 and 255.
Value	Specifies the second constant's value, or specifies the color replacement value.

Specifies the constant c for the specified mathematical function, if applicable. If filling the LUT with a colormap, set this to M_DEFAULT.

For specifying the third constant
Value	Description
M_DEFAULT	Specifies that this parameter is not used. This setting is only applicable when filling the LUT with a colormap. In this case, this is the only possible option. (summarize) Specifies that this parameter is not used. (more details...)
Value	Specifies the third constant's value.

StartIndex

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). For colormaps, this setting is the only possible option; for tone mapping, M_DEFAULT specifies to use the LUT's full range. (summarize) Specifies the first index entry of the LUT (index 0). (more details...)
0 < = Value < LUT size	Specifies the first index entry to affect.

StartXValue

Specifies the initial value of x in the mathematical function. If filling the LUT with a colormap, set this to M_DEFAULT.

For specifying the initial x value
Value	Description
M_DEFAULT	Specifies the default value; the default value is 0.0. For colormaps, this setting is the only possible option and specifies to ignore the StartXValue parameter. (summarize) Specifies the default value; the default value is 0.0. (more details...)
Value	Specifies the first x value to use during calculation.

EndIndex

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; this setting is only applicable to colormaps, and is the only possible option.
StartIndex <= Value < LUT size	Specifies the last index entry to affect.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.