NI-IMAQ White Balancing Utility

NI-IMAQ White Balancing Utility Help

June 2004 Edition, Part Number 370712B-01

NI-IMAQ White Balancing Utility Help provides conceptual information about Bayer cameras and step-by-step information about using the NI-IMAQ White Balancing Utility with a Bayer camera. This help file is designed for users who are new to using Bayer cameras for image acquisition applications as well as those who have experience with the cameras.

To navigate this help file, use the Contents, Index, and Search tabs to the left of this window.

For more information about this help file, refer to the following topics:

Conventions—formatting and typographical conventions in this help file

Related Documentation

Important Information

Technical Support and Professional Services

To comment on the documentation, email techpubs@ni.com.

© 2003–2004 National Instruments Corporation. All rights reserved.


Conventions

This help file uses the following conventions:

» | The » symbol leads you through nested menu items and dialog box options to a final action. The sequence File»Page Setup»Options directs you to pull down the File menu, select the Page Setup item, and select Options from the last dialog box.
 | This icon denotes a tip, which alerts you to advisory information.
 | This icon denotes a note, which alerts you to important information.
bold | Bold text denotes items that you must select or click on in the software, such as menu items and dialog box options. Bold text also denotes parameter names, emphasis, or an introduction to a key concept.
green | Underlined text in this color denotes a link to a help topic, help file, or Web address.
green | Text in this color with a dashed underline denotes a pop-up link to a definition or special term.
italic | Italic text denotes variables or cross references. This font also denotes text that is a placeholder for a word or value that you must supply.
monospace | Text in this font denotes text or characters that you should enter from the keyboard, sections of code, programming examples, and syntax examples. This font is also used for the proper names of disk drives, paths, directories, programs, subprograms, subroutines, device names, functions, operations, variables, filenames and extensions, and code excerpts.


Related Documentation

The following documents contain information that you might find helpful as you use this help file:

  • NI-IMAQ User Manual
  • NI-IMAQ Function Reference Help
  • NI-IMAQ VI Reference Help
  • Measurement & Automation Explorer Help for IMAQ


About Bayer Cameras

Refer to the following sections for information about various aspects of Bayer cameras.

Bayer Encoding

Bayer encoding is a method you can use to produce color images with a single imaging sensor, as opposed to three individual sensors for the red, green, and blue components of light. This technology greatly reduces the cost of cameras.

The Bayer color filter array (CFA) is a primary color, mosaic pattern of 50% green, 25% red, and 25% blue pixels. Green pixels comprise half of the total pixels because the human eye gets most of its sharpness information from green light.

The following illustration describes how the Bayer CFA is used in the image acquisition process.

Light travels through the camera lens onto an image sensor that provides one value for each sensor cell. The sensor is an array of tiny, light-sensitive diodes called photosites. The sensor converts light into electrical charges. The sensor is covered by the Bayer CFA so that only one color value reaches any given pixel. The raw output is a mosaic of red, green, and blue pixels of different intensity.

When the image is captured, the accumulated charge for each cell is read, and analog values are converted to digital pixel values using an analog-to-digital (A/D) converter.

Color Interpolation

Color interpolation, sometimes referred to as demosaicing, fills in the missing colors. A decoding algorithm determines a value for the RGB components for each pixel in the array by averaging the color values of selected neighboring pixels and producing an estimate of color and intensity.

After the interpolation process is complete, the white balancing process further enhances the image by adjusting the red and blue signals to match the green signal in white areas of the image.

Example

Several decoding algorithms perform color decoding, including nearest neighbor, linear, cubic, and cubic spline interpolations. The following example provides a simple explanation of the interpolation process:

Determine the value of the pixel in the center of the following group:

RGR
GBG
RGR

These pixels have the following values:

200 050 220
060 100 062
196 058 198

Neighboring pixels are used to determine the RGB values for the center pixel. The blue component is taken directly from the pixel value, and the green and red components are the average of the surrounding green and red pixels, respectively.

R = (200 + 220 + 196 + 198)/4 = 203.5 ~ 204
G = (50 + 60 + 62 + 58)/4 = 57.5 ~ 58
B = 100

The final RGB value for the pixel is (204,58,100). This process is repeated for each pixel in the image.

White Balance

White balance is a method you can use to adjust for different lighting conditions and optical properties of the filter. While the human eye compensates for light with a color bias based on its memory of white, a camera captures the real state of light. Optical properties of the Bayer filter may result in mismatched intensities between the red, green, and blue components of the image.

To adjust image colors more closely to the human perception of light, white balancing assumes that if a white area can be made to look white, the remaining colors will be accurate as well. White balancing involves identifying the portion of an image that is closest to white, adjusting this area to white, and correcting the balance of colors in the remainder of the image based on the white area.

You should perform a white balance every time lighting conditions change. Setting the white balance incorrectly may cause color inconsistencies in the image.

White Level

The white level defines the brightness of an image after white balancing. The values for the red, green, and blue gains are determined by dividing the white level by the mean value of each component color. The maximum white level is 255.

If the white level is too high or too low, the image will appear too light or too dark. You can adjust the white level to fine-tune the image brightness.

When using the White Balancing Utility, start with the default white level value of 220. Select a region of interest and click Auto Calculate Gains. If the image appears incorrect, increase or decrease the white level, select a region of interest, and click Auto Calculate Gains. Repeat this procedure until the image appears correct.


Using the NI-IMAQ White Balancing Utility

Understanding the Interface

Using the Utility with an Acquired Image

Using the Utility with an Existing Image

Saving an Image

Closing the Utility


Understanding the Interface

Use the NI-IMAQ White Balancing Utility interface to interactively determine the correct gain settings and sensor pattern for your imaging setup. The proper settings are dependent upon the camera and lighting for a particular system.

You use the gain settings as parameters for the IMAQ Create Bayer LUT and IMAQ Bayer Color Decode VIs in LabVIEW, or for the imgCalculate BayerColorLut() and imgBayerColorDecode() functions in LabWindows/CVI. For information about these VIs and functions, refer to NI-IMAQ VI Reference Help or NI-IMAQ Function Reference Help.

  1. Image window—Displays the image being processed, allows you to zoom or select a region of interest, and displays cursor location and pixel RGB values.
  2. Utility tabs—Displays the Bayer Pattern, Gains, and Parameters tabs.
  3. Controls—Displays controls to acquire images, open an existing image, set the image bit depth, save an image, close the utility, and open this help file.

Bayer Pattern Tab

The Bayer Pattern tab displays the four possible variations of the Bayer encoding pattern. Use the radio buttons to select the correct pattern for your image. The correct settings may change if the top or left offset is modified.

Gains Tab

The Gains tab displays controls to adjust the image RGB gains and white level. Select a region of interest, set the white level, and click Auto Calculate Gains to calculate the gain values.

Parameters Tab

The Parameters tab displays the calculated RGB gain, bit depth values, and the Bayer encoding pattern for an image. Record the displayed values to use in your application with the imgBayerColorDecode and imgCalculateBayerColorLUT functions or IMAQ Create Bayer LUT and IMAQ Bayer Color Decode VIs.


Using the Utility with an Acquired Image

Complete the following steps to acquire an image and find the correct gain settings for an image:

  1. Verify that your image acquisition device and camera are correctly configured using Measurement and Automation Explorer (MAX). Refer to Measurement & Automation Explorer Help for IMAQ for information about configuring your image acquisition device and camera.
  2. Launch the NI-IMAQ White Balancing Utility from Programs»National Instruments»Vision»Bayer White Balancing Utility.
  3. Click the Snap button [image] to acquire a single image, or click the Grab button [image] to capture images in continuous mode.

    Tip Use an image with distinct areas of red, green, blue, and white to determine the correct settings. If you have a color printer, you can print and use the RGB Image Example.
  4. Select the Bayer Pattern tab and select the appropriate Bayer Encoding Pattern for the image.

    Note The Bayer CFA pattern can appear in one of the following four variations, depending on the current left and top offsets of the acquisition window:
    GBGB
    RGRG
    GRGR
    BGBG
    BGBG
    GRGR
    RGRG
    GBGB
  5. Select the Gains tab.
  6. Set the desired white level. The default white level value is 220.
  7. Click the ROI button [image] and select a white region of interest on the image.
  8. Click Auto Calculate Gains to calculate the RGB gain settings.

    Note You also can use the individual Gain controls to manually adjust the white balance.
  9. Select the Parameters tab and record the displayed values to use in your application.

    Use these calculated parameters with the imgBayerColorDecode and imgCalculateBayerColorLUT functions or IMAQ Create Bayer LUT and IMAQ Bayer Color Decode VIs.

For more information about finding the correct gain settings, refer to About Bayer Cameras and NI-IMAQ White Balancing Utility FAQs.


Using the Utility with an Existing Image

Complete the following steps to open an existing image and find the correct gain settings for an image:

  1. Launch the NI-IMAQ White Balancing Utility from Programs»National Instruments»Vision»Bayer White Balancing Utility.
  2. Click the Browse button [image].
  3. Select the image you want to open.
  4. Click OK to open the selected image.
  5. Set the appropriate Bit Depth value for the image.

    Note Images that are eight bits are automatically detected and the Bit Depth is grayed out. Until the correct bit depth is set, images that are greater than eight bits may appear very light or very dark. An incorrect bit depth causes incorrect gain settings.
  6. Select the Bayer Pattern tab and click the appropriate Bayer Encoding Pattern radio button for the image.

    Note The Bayer CFA pattern can appear in one of the following four variations, depending on the current left and top offsets of the acquisition window:
    GBGB
    RGRG
    GRGR
    BGBG
    BGBG
    GRGR
    RGRG
    GBGB
  7. Select the Gains tab.
  8. Set the desired white level. The default white level value is 220.
  9. Click the ROI button [image] and select a white region of interest on the image.
  10. Click Auto Calculate Gains to calculate the RGB gain settings.

    Note You also can use the individual Gain controls to manually adjust the white balance.
  11. Select the Parameters tab and record the displayed values to use in your application.

    Use these calculated parameters with the imgBayerColorDecode and imgCalculateBayerColorLUT functions or IMAQ Create Bayer LUT and IMAQ Bayer Color Decode VIs.

For more information on finding the correct gain settings, refer to About Bayer Cameras and NI-IMAQ White Balancing Utility FAQs.


Saving an Image

Complete the steps below to save a color BMP image file for the first time or to make a copy of an existing image:

Note BMP color images use 8 bits per color plane.
  1. Click the Save Image button.
  2. Enter a new File name.
  3. Click Save.


Closing the NI-IMAQ White Balancing Utility

Complete these steps to close the NI-IMAQ White Balancing Utility interface:

  1. Save the images you want to keep.
  2. Click Quit.


Reference

FAQs

RGB Image Example


NI-IMAQ White Balancing Utility FAQs

Why do the colors in my image look incorrect after auto white balancing?

The most common cause of incorrect color decoding is an incorrect Bayer pattern selection. The correct Bayer pattern depends on the camera sensor, but also can be affected by the left and top offsets of the current acquisition window. Click the Bayer Pattern tab, choose a different pattern, and perform the white balance again.

Which Bayer encoding pattern should I use?

Because the correct pattern is dependent on the left and top offsets of the current acquisition window, use the following trial and error procedure to find the correct Bayer pattern:

  1. Click the Bayer Pattern tab and select a Bayer Encoding Pattern.
  2. Click the Gains tab.
  3. Click the ROI button [image] and select a white region of interest on the image.
  4. Click Auto Calculate Gains.

Repeat this procedure until the colors appear correct.

Why does my image still look incorrect or appear to be dominated by one color after I have tried all of the Bayer patterns?

Make sure the Bit Depth value matches the bit depth of the camera. Try changing the gain and exposure of the camera. Images that are too dark or too light may adversely affect the gain calculations.

Why does my image appear all white?

Make sure the Bit Depth value matches the bit depth of the camera.

Why does my image appear washed out?

The maximum value for the individual color gains is 3.99. If any of the gains reached the maximum value after white balancing, the image may have been too dark to begin with and the gain was not able to compensate. Increase the gain or exposure on the camera, take a new image, and perform the white balance again.

I have a 10-bit Bayer sensor, but BMP saves only 8 bits per color plane. What happens to the other 2 bits?

Currently, the Bayer decoding algorithm supports only 8 bits per color plane. The Bayer decoding algorithm uses all bits to appropriately scale the data to 8 bits per color plane.


RGB Image Example


Important Information

Warranty

Copyright

Trademarks

Patents

Warning Regarding Use of NI Products


Warranty

The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives notice of such defects during the warranty period. National Instruments does not warrant that the operation of the software shall be uninterrupted or error free.

A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before any equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are covered by warranty.

National Instruments believes that the information in this document is accurate. The document has been carefully reviewed for technical accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected. In no event shall National Instruments be liable for any damages arising out of or related to this document or the information contained in it.

Except as specified herein, National Instruments makes no warranties, express or implied, and specifically disclaims any warranty of merchantability or fitness for a particular purpose. Customer's right to recover damages caused by fault or negligence on the part of National Instruments shall be limited to the amount theretofore paid by the customer. National Instruments will not be liable for damages resulting from loss of data, profits, use of products, or incidental or consequential damages, even if advised of the possibility thereof. This limitation of the liability of National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against National Instruments must be brought within one year after the cause of action accrues. National Instruments shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein does not cover damages, defects, malfunctions, or service failures caused by owner's failure to follow the National Instruments installation, operation, or maintenance instructions; owner's modification of the product; owner's abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outside reasonable control.


Copyright

Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National Instruments Corporation.


Trademarks

NI-IMAQ™, National Instruments™, and ni.com™ are trademarks of National Instruments Corporation.

Product and company names mentioned herein are trademarks or trade names of their respective companies.


Patents

For patents covering National Instruments products, refer to the appropriate location: Help»Patents in your software, the patents.txt file on your CD, or ni.com/patents.


WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS

(1) National Instruments products are not designed with components and testing for a level of reliability suitable for use in or in connection with surgical implants or as critical components in any life support systems whose failure to perform can reasonably be expected to cause significant injury to a human.

(2) In any application, including the above, reliability of operation of the software products can be impaired by adverse factors, including but not limited to fluctuations in electrical power supply, computer hardware malfunctions, computer operating system software fitness, fitness of compilers and development software used to develop an application, installation errors, software and hardware compatibility problems, malfunctions or failures of electronic monitoring or control devices, transient failures of electronic systems (hardware and/or software), unanticipated uses or misuses, or errors on the part of the user or applications designer (adverse factors such as these are hereafter collectively termed "system failures"). Any application where a system failure would create a risk of harm to property or persons (including the risk of bodily injury and death) should not be reliant solely upon one form of electronic system due to the risk of system failure. To avoid damage, injury, or death, the user or application designer must take reasonably prudent steps to protect against system failures, including but not limited to back-up or shut down mechanisms. Because each end-user system is customized and differs from National Instruments' testing platforms and because a user or application designer may use National Instruments products in combination with other products in a manner not evaluated or contemplated by National Instruments, the user or application designer is ultimately responsible for verifying and validating the suitability of National Instruments products whenever National Instruments products are incorporated in a system or application, including, without limitation, the appropriate design, process and safety level of such system or application.


Technical Support and Professional Services

Visit the following sections of the National Instruments Web site at ni.com for technical support and professional services:

  • Support—Online technical support resources include the following:
    • Self-Help Resources—For immediate answers and solutions, visit our extensive library of technical support resources available in English, Japanese, and Spanish at ni.com/support. These resources are available for most products at no cost to registered users and include software drivers and updates, a KnowledgeBase, product manuals, step-by-step troubleshooting wizards, conformity documentation, example code, tutorials and application notes, instrument drivers, discussion forums, a measurement glossary, and so on.
    • Assisted Support Options—Contact NI engineers and other measurement and automation professionals by visiting ni.com/support. Our online system helps you define your question and connects you to the experts by phone, discussion forum, or email.
  • Training—Visit ni.com/training for self-paced tutorials, videos, and interactive CDs. You can also register for instructor-led, hands-on courses at locations around the world.
  • System Integration—If you have time constraints, limited in-house technical resources, or other project challenges, NI Alliance Program members can help. To learn more, call your local NI office or visit ni.com/alliance.

If you searched ni.com and could not find the answers you need, contact your local office or NI corporate headquarters. You also can visit the Worldwide Offices section of ni.com/niglobal to access the branch office Web sites, which provide up-to-date contact information, support phone numbers, email addresses, and current events.


Branch Offices

Office | Telephone Number
Australia | 1800 300 800
Austria | 43 0 662 45 79 90 0
Belgium | 32 0 2 757 00 20
Brazil | 55 11 3262 3599
Canada (Calgary) | 403 274 9391
Canada (Montreal) | 514 288 5722
Canada (Ottawa) | 613 233 5949
Canada (Québec) | 514 694 8521
Canada (Toronto) | 905 785 0085
Canada (Vancouver) | 514 685 7530
China | 86 21 6555 7838
Czech Republic | 420 2 2423 5774
Denmark | 45 45 76 26 00
Finland | 385 0 9 725 725 11
France | 33 0 1 48 14 24 24
Germany | 49 0 89 741 31 30
Greece | 30 2 10 42 96 427
India | 91 80 51190000
Israel | 972 0 3 6393737
Italy | 39 02 413091
Japan | 81 3 5472 2970
Korea | 82 02 3451 3400
Malaysia | 603 9131 0918
Mexico | 001 800 010 0793
Netherlands | 31 0 348 433 466
New Zealand | 1800 300 800
Norway | 47 0 66 90 76 60
Poland | 48 0 22 3390 150
Portugal | 351 210 311 210
Russia | 7 095 238 7139
Singapore | 65 6226 5886
Slovenia | 386 3 425 4200
South Africa | 27 0 11 805 8197
Spain | 34 91 640 0085
Sweden | 46 0 8 587 895 00
Switzerland | 41 56 200 51 51
Taiwan | 886 2 2528 7227
Thailand | 662 992 7519
United Kingdom | 44 0 1635 523545
United States (Corporate) | 512 683 0100