05 Auto White Balance Tutorial

Learn how to build a C++ application that runs a closed-loop auto white balance (AWB) controller against a live Sol3 camera.

Prerequisites

Completed Getting Started
Completed SSH Setup
Completed Deployment Workflow

Overview

This tutorial shows how to build and deploy an application that estimates white balance gains from the camera’s YUV stream and feeds them back into the camera-side ISP each iteration.

Important

This application runs on the Sol3 device, not on your development machine. It owns the camera’s CameraControl stream, so it cannot run alongside another control client (the GUI or tutorial 01). The x64 mock camera server serves only a RAW10 stream and cannot exercise this YUV-based flow.

Tutorial Code

The SDK includes a complete auto white balance tutorial at:

sol3-sdk/apps/tutorials/05_auto_white_balance.cpp

How It Works

The application binds to the camera control endpoint and runs a control loop. Each iteration:

Reads the latest YUV frame and converts NV12 to BGR.
Estimates residual white balance gains over a centered ROI.
Multiplies the residual into the gains the camera reports it applied to that frame (synchronized via control_debayer_params, avoiding multi-frame lag).
Publishes a fresh CameraControl with the requested schedule/exposure and the updated debayer_params.

Build and Deploy

Step 1: Build Application Image

Build the ARM64 container image for Sol3:

sol3_build_app_image tutorial_05_auto_white_balance arm64 --cmake-preset arm64 --tag latest

Step 2: Deploy to Sol3 Device

Deploy the image to your Sol3 device:

sol3_deploy_app_image tutorial-05-auto-white-balance-arm64:latest <USER@HDK_IP>

Step 3: Run on Sol3 Device

SSH to the Sol3 device and run the application.

# SSH to device
ssh <USER@HDK_IP>

# Run the auto white balance controller
docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  --privileged \
  localhost:5000/tutorial-05-auto-white-balance-arm64:latest <ARGS>

Usage Examples

All commands below run on the Sol3 device after SSH connection.

For brevity, the commands below use <AWB-CMD> to represent:

docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  --privileged \
  localhost:5000/tutorial-05-auto-white-balance-arm64:latest <ARGS>

Default AWB Loop

5 fps, 1 ms exposure, centered 0.5 ROI, 1 Hz cadence:

<AWB-CMD> --camid 1

Tighter ROI and Faster Cadence

<AWB-CMD> --camid 1 --roi-fraction 0.25 --period-ms 250

Custom Exposure and Gain Ceiling

<AWB-CMD> --camid 1 --fps 10 --exposure_ns 5000000 --iso 400 --max-gain 4

Options

Flag	Default	Description
`--camid`	`1`	Camera id, range `[1, 12]`
`--fps`	`5`	Capture rate, range `[1, 30]`
`--iso`	`100`	Sensor ISO
`--exposure_ns`	`1000000`	Exposure time in nanoseconds
`--roi-fraction`	`0.5`	Fraction of the frame used for the centered ROI, range `[0.05, 1.0]`
`--max-gain`	`8.0`	Per-channel gain ceiling (positive)
`--period-ms`	`1000`	Iteration cadence in milliseconds (positive)