| Customize Help
| Save Settings

MbufBayer


Function Map
Syntax
Description
Parameters
- SrcImageBufId
- DestImageBufId
Table: For the destination buffer
- CoefOrExpId
Table: For white balancing and gamma correction
- ControlFlag
Table: For the Bayer pattern
+ combination: For white balancing the source image
+ combination: For bit shifting the result
+ combination: For overriding the bilinear interpolation demosaicing algorithm
+ combination: For M_ADAPTIVE
Compilation information
Synopsis
Decode the color information of a single-band, Bayer color-encoded image.
Syntax
void MbufBayer(
MIL_ID SrcImageBufId, //in
MIL_ID DestImageBufId, //in
MIL_ID CoefOrExpId, //in
MIL_INT64 ControlFlag //in
)
Description

This function converts a single-band, Bayer color-encoded image into a 1- or 3-band image. When using a single-band buffer as the destination, the destination will be filled with the Y-component obtained from the RGB to Y conversion when the Bayer image is decoded.

Optionally, you can specify to perform gamma correction and/or white balancing on the image if the appropriate exponents and coefficients are provided, respectively. First, gamma correction is applied to the raw RGB values of the Bayer color-encoded image. Second, white balancing is performed on the gamma corrected RGB values. Third, the demosaicing process converts the single-band, Bayer color-encoded image to a 1- or 3-band image. Finally, color correction is performed if M_COLOR_CORRECTION is specified. Color correction can only be used with the M_ADAPTIVE algorithm.

Note that you can use MbufBayer() to automatically calculate the appropriate white balancing coefficients. To do so, specify a Bayer color-encoded source image that in reality should be a uniform shade of gray that is not too saturated, and add M_WHITE_BALANCE_CALCULATE to the ControlFlag parameter. After converting the image and calculating the appropriate coefficients, the coefficients are written to the specified MIL array buffer and the converted image is then corrected using these automatically calculated coefficients. Alternatively, you could fill an array with custom values, and then load these values (in order) into the MIL array using MbufPut1d() or MbufPut2d(). For more information, see White balancing your Bayer images. Ensure that the image was grabbed under the same lighting conditions as subsequent source images.

Note that you cannot calculate the white balance coefficients and specify an adaptive demosaicing in the same call to MbufBayer().

For more information on Bayer color-encoded images, the conversion, and the actual equations used to perform white balancing and gamma correction, see the Using images acquired with a Bayer color filter section of Chapter 21: Data buffers.

Note that if the scale of the image is changed (using MdigControl() with M_GRAB_SCALE...) to a value other than 1 prior to grabbing a Bayer image, the Bayer image will not be converted properly; some of the Bayer pattern is lost during the scaling process, rendering color recovery impossible.

[Matrox Iris GTR (introduced U28); Matrox Radient eCL; Matrox Solios eA/XA; Matrox Solios ecl/xcl/ev-cl]

When using a digitizer that supports on-board Bayer conversion, the conversion of a single-band, Bayer color-encoded image into a 1- or 3-band image can be performed using either on-board buffers, or off-board (Host) buffers. When the operation is performed using both source and destination on-board image buffers, your digitizer must be able to perform the Bayer conversion on-board; otherwise, the operation will be performed on the Host.

In addition, the Bayer operation can only be performed on-board if there is sufficient memory for the operation to complete (for example, to hold internal buffers); otherwise, the operation will be performed on the Host, and the results copied to your on-board destination buffer. This will result in a speed-decrease of the Bayer operation.

To force the Bayer operation to be performed on-board, use MdigControl(). For more information, refer to the MIL Hardware-specific Notes and the Installation and Hardware Reference for your product. Note that, when using MdigControl(), gamma correction is not available.

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
SrcImageBufId

Specifies the identifier of the source image buffer. To achieve maximum conversion performance, the source image buffer should be an unsigned 1-band image buffer. If you specify a 3-band buffer, only the first band will be used.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

The source buffer must be an 8- or 16-bit buffer.

[Matrox Radient eCL]

The source buffer must be allocated in an on-board SDRAM memory bank (using MbufAllocColor() with M_FPGA_ACCESSIBLE).

If the source buffer is 16-bit, use MbufControl() with M_MAX to specify the maximum value in the buffer.

DestImageBufId

Specifies the identifier of the destination image buffer. The results of the white balancing, gamma correction, and color correction are clipped, if necessary, to the maximum value of the source buffer.

function map For the destination buffer
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize M_NULL

Specifies the destination buffer will not be used. Note that this can only be used when calculating white balance coefficients (using M_WHITE_BALANCE_CALCULATE). In this case, the white balance coefficients are calculated but the source image is not converted.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize MIL destination Image buffer ID

Specifies the identifier of the destination image buffer.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

When you convert the image using the adaptive algorithm (specified using M_ADAPTIVE), it is recommended that you use a planar RGB buffer (any RGB color buffer format + M_PLANAR). The other destination formats mentioned above can be used, but require an extra conversion operation that increases processing time.

The RGB result is saturated according to the source buffer's maximum value, set using MbufControl() with M_MAX. With YUV or 1-band destination buffers, the saturation is applied to the intermediate RGB result, before doing the color conversion.

The destination buffer should be either an 8- or 16-bit monochrome, or a 3-band color buffer in one of the following formats:

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
MIL system specific

On specific boards, the destination image can also be any RGB color buffer format + M_PLANAR.

 ‡ a g h i l m t
U28		 u
U36

The destination buffer must be allocated in an on-board SDRAM memory bank, or the Host's non-paged memory (using MbufAllocColor() with M_FPGA_ACCESSIBLE + M_HOST_MEMORY).

 ‡ j
CoefOrExpId

Specifies whether white balancing and gamma correction are performed, and the coefficients and exponents used to perform these corrections, respectively.

This parameter can be set to one of the following:

function map For white balancing and gamma correction
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize M_DEFAULT

Performs no white balancing or gamma correction on the source image; only the conversion is performed.

 ‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize MIL array buffer identifier

Specifies the MIL array buffer which contains the coefficients and exponents to perform the corrections. The buffer must be allocated with MbufAlloc1d() or MbufAlloc2d(), as a single-band 32-bit floating-point buffer with an M_ARRAY attribute.

The first 3 elements in the MIL array buffer specify the coefficients to perform the white balancing on the gamma corrected RGB values (if gamma correction is performed at all). If you add M_WHITE_BALANCE_CALCULATE to the ControlFlag parameter, these three elements are overwritten with the coefficients that are automatically calculated. Note that white balancing coefficients must be positive.

The next 3 elements, if any, specify the exponents to perform the gamma correction on the raw RGB values, respectively. Note that the gamma correction exponents must be positive, are typically in the range of 0.0 to 1.0, and are most commonly specified as 0.45.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
MIL system specific

The buffer must have either a 3x1 or 6x1 dimension. If a 3x1 MIL array buffer is specified, no gamma correction is performed.

 ‡ a c
M10		 g h l m o t
U28		 v
ControlFlag

Specifies the Bayer pattern to use in the conversion, and whether the white balancing coefficients will be calculated. This parameter can be set to one of the following:

function map For the Bayer pattern
Click to summarizeValue Description
Click to summarize M_BAYER_BG +

Specifies the Bayer pattern that has the top-left pixel as the blue component and the next pixel as the green component. That is, pixel [0,0] is blue, pixel [1,0] is green and pixel [1,1] is red in the source image.

(summarize)
Click to summarize M_BAYER_GB +

Specifies the Bayer pattern that has the top-left pixel as the green component and the next pixel as the blue component. That is, pixel [0,0] is green, pixel [1,0] is blue and pixel [0,1] is red in the source image.

(summarize)
Click to summarize M_BAYER_GR +

Specifies the Bayer pattern that has the top-left pixel as the green component and the next pixel as the red component. That is, pixel [0,0] is green, pixel [1,0] is red and pixel [0,1] is blue in the source image.

(summarize)
Click to summarize M_BAYER_RG +

Specifies the Bayer pattern that has the top-left pixel as the red component and the next pixel as the green component. That is, pixel [0,0] is red, pixel [1,0] is green and pixel [1,1] is blue in the source image.

(summarize)
Combination value for the values listed in For the Bayer pattern.

You can add the following value to the above-mentioned values to set whether to automatically calculate the appropriate white balance coefficients.

function map For white balancing the source image
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_WHITE_BALANCE_CALCULATE

Determines the 3 coefficients required to white balance the source image, and writes these coefficients into the CoefOrExpId array. The image is then white balanced using the 3 calculated coefficients. If gamma exponents are specified, the image is first gamma corrected before the white balance coefficients are calculated. Note that to use M_WHITE_BALANCE_CALCULATE, the source image must be a uniform shade of gray that is not too saturated.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
MIL system specific

This value is not supported on the FPGA, although precalculated coefficients can still be applied.

 ‡ j k
M10		 p r
U27		 y
U75		 aa
Combination value for the values listed in For the Bayer pattern.

You can add the following value to the above-mentioned values to set whether to bit-shift the result.

function map For bit shifting the result
Click to summarizeCombination value Description
Click to summarize

Indicates to shift the result by the specified number of bits.

Note that this operation is applied to the RGB values resulting from the demosaicing process (after the color conversion); with YUV or 1-band destination buffers, the shift is applied to the intermediate RGB result, before doing the color conversion.

Signed buffers are considered as unsigned.

(summarize)
Parameters

This parameter specifies the number of bits by which to shift the result. You can set this parameter to the following:
0 <= Value < Depth of source buffer

Specifies the number of bits by which to shift the result.
Combination values for the values listed in For the Bayer pattern.

You can add one of the following values to the above-mentioned values to set whether to override the use of the bilinear interpolation demosaicing algorithm.

function map For overriding the bilinear interpolation demosaicing algorithm
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_ADAPTIVE +

Specifies to use the adaptive demosaicing algorithm for the conversion process. Using this algorithm minimizes false colors and the zipper effect.

Note you cannot use this constant in combination with M_WHITE_BALANCE_CALCULATE.

(summarize)
‡ a c
M10		 g h i l o t
U28		 u
U36		 v
Click to summarize M_ADAPTIVE_FAST +

Specifies to use a fast version of the adaptive demosaicing algorithm for the conversion process; using this algorithm gives you a good compromise between speed of the default bilinear algorithm and M_ADAPTIVE quality.

Note you cannot use this constant in combination with M_WHITE_BALANCE_CALCULATE.

(summarize)
‡ a c
M10		 g h i l o t
U28		 u
U36		 v
Click to summarize M_AVERAGE_2X2

Specifies to use a 2x2 neighborhood kernel to perform the demosaicing. By using this algorithm, the zipper effect is minimized, but the resulting image is shifted upwards and to the left by a small amount.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Combination value for M_ADAPTIVE; M_ADAPTIVE_FAST.

You can add the following value to the above-mentioned values to set whether to perform a color correction on the image.

function map For M_ADAPTIVE
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_COLOR_CORRECTION

Specifies that a color correction is performed to further eliminate false colors.

 ‡ a c
M10		 g h i l o t
U28		 u
U36		 v
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
NONE NULL NONE DEFAULT FLOAT BAYER BG BAYER GB BAYER GR BAYER RG WHITE BALANCE CALCULATE ADAPTIVE ADAPTIVE FAST AVERAGE 2X2 COLOR CORRECTION