The automatic white balance algorithm of Raspberry Pi

 The automatic white balance (AWB) algorithm on the Raspberry Pi (used in its camera modules) is part of the Picamera software stack and the libcamera framework (used in newer Raspberry Pi OS versions). Below is a detailed breakdown of how it works, its limitations, and ways to customize it.

---

1. How AWB Works on Raspberry Pi

AWB in Picamera (Legacy)

• Algorithm: Uses a simple gray-world assumption (averages colors to neutral gray).

• Control: Adjusted via awb_mode in Python ('auto', 'sunlight', 'tungsten', etc.).

• Limitations:

  • Prone to errors in scenes with dominant colors (e.g., green grass skews balance).

  • Less accurate than modern smartphone AWB.

AWB in libcamera (New Default)

• Algorithm: More advanced, leveraging machine learning (trained on diverse scenes).

• Control: Configured via libcamera commands or rpicam-apps (e.g., --awb auto).

• Modes:

  • auto (default, adaptive).

  • incandescent, fluorescent, daylight, etc. (presets).

  • manual (user-defined RGB gains).

---

2. Key AWB Algorithms Used

a) Gray-World Algorithm

• Assumes the average scene reflectance is gray.

• Adjusts R, G, B gains to equalize channels.

• Problem: Fails with monochromatic scenes.

b) Retinex-Based AWB

• Mimics human vision by analyzing local contrasts.

• Used in advanced implementations (e.g., libcamera).

c) Machine Learning (ML) AWB

• Trained on thousands of images to predict optimal white balance.

• Used in Raspberry Pi’s newer firmware.

---

3. How to Adjust AWB on Raspberry Pi

Option 1: Using libcamera (Recommended)

bash

# Set AWB to auto (default)
libcamera-still --awb auto -o image.jpg

# Use a preset (e.g., daylight)
libcamera-still --awb daylight -o image.jpg

# Manual white balance (set red/blue gains)
libcamera-still --awb off --awbgains 1.5,2.0 -o image.jpg

Option 2: Using Python (Legacy Picamera)

python

from picamera import PiCamera

camera = PiCamera()
camera.awb_mode = 'auto'  # Options: 'sunlight', 'cloudy', 'shade', etc.
camera.capture('image.jpg')

Option 3: Disabling AWB (Manual Control)

bash

# Disable AWB and set fixed gains (e.g., R=1.5, B=1.8)
libcamera-still --awb off --awbgains 1.5,1.8 -o image.jpg

---

4. Improving AWB Accuracy

a) Use a Gray/White Reference Card

• Place a neutral gray card in the scene for calibration.

• Set manual white balance based on it.

b) Tune AWB Gains

• Experiment with --awbgains in libcamera.

• Example:

  bash

  libcamera-still --awb off --awbgains 1.2,1.5 -o calibrated.jpg

c) Post-Processing (OpenCV)

• Use OpenCV for better AWB in code:

  python

  import cv2
  img = cv2.imread('image.jpg')
  gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
  result = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)  # Simple WB correction
  cv2.imwrite('corrected.jpg', result)

---

5. Limitations of Raspberry Pi AWB

• Low-light performance: Struggles in dim conditions.

• Dominant colors: Can fail if one color dominates (e.g., green grass).

• No custom ML models: Unlike smartphones, Pi lacks dedicated AI hardware for AWB.

---

6. Comparison: Picamera vs. libcamera AWB

Feature	Picamera (Legacy)	libcamera (New)
Algorithm	Gray-world	ML-enhanced
Accuracy	Moderate	Better
Control	Basic presets	Manual RGB gains
Low-Light	Poor	Improved
Speed	Fast	Slightly slower

---

Final Recommendations

• For best results: Use libcamera with --awb auto or manual gains.

• For critical applications: Use a reference card and manual WB.

• For advanced users: Post-process with OpenCV for finer control.