System Information

System Information:

• OpenCV version: 4.x
• OS: Windows 10/11
• Language: Python (cv2)
• Video backend: cv2.CAP_DSHOW
• Affected properties: CAP_PROP_WHITE_BALANCE_BLUE_U, CAP_PROP_WB_TEMPERATURE, CAP_PROP_WHITE_BALANCE_RED_V

Detailed description

Issue Summary:

On Windows using the DirectShow backend (cv2.CAP_DSHOW), setting:

cap.set(cv2.CAP_PROP_WHITE_BALANCE_BLUE_U, 2700)

does not affect the blue channel gain as the property name suggests. Instead, it behaves identically to setting the white balance temperature to 2700K using AMCap or other DirectShow tools. This suggests OpenCV is incorrectly mapping this property to VideoProcAmp_WhiteBalance.

Additionally, CAP_PROP_WHITE_BALANCE_RED_V appears unsupported (either returns -1.0 or has no effect), and CAP_PROP_WB_TEMPERATURE is either non-functional or unimplemented in the DirectShow backend.

Expected Behavior:

• CAP_PROP_WB_TEMPERATURE should be properly mapped to VideoProcAmp_WhiteBalance and accept values in Kelvin.
• CAP_PROP_WHITE_BALANCE_BLUE_U and RED_V should control blue and red channel gains independently, if supported by the driver.
• At a minimum, this behavior should be documented to avoid confusion.

Proposed Fix:

1. Map CAP_PROP_WB_TEMPERATURE correctly to VideoProcAmp_WhiteBalance in the cap_dshow.cpp backend.
2. Optionally, decouple CAP_PROP_WHITE_BALANCE_BLUE_U from this behavior to preserve expected semantic meaning.
3. Update OpenCV documentation to reflect this platform-specific behavior.

Additional Notes:

This issue is specific to the Windows DirectShow backend. It causes confusion for users expecting to control RGB channel gains directly and breaks cross-platform expectations when moving between Linux (V4L2) and Windows. This is particularly problematic in scientific imaging applications that depend on precise and repeatable color balance settings.

Steps to reproduce

Steps to Reproduce:

1. Use cv2.VideoCapture(index, cv2.CAP_DSHOW)
2. Enable auto white balance: cap.set(cv2.CAP_PROP_AUTO_WB, 1)
3. Read a frame and confirm the white balance appearance (e.g., warm tones around 2700K)
4. Disable auto white balance: cap.set(cv2.CAP_PROP_AUTO_WB, 0)
5. Set cap.set(cv2.CAP_PROP_WHITE_BALANCE_BLUE_U, 2700)
6. Observe that the image matches the color temperature of auto WB at 2700K
7. Try reading or setting CAP_PROP_WHITE_BALANCE_RED_V — it returns -1.0 or does nothing

Issue submission checklist

• I report the issue, it's not a question
• I checked the problem with documentation, FAQ, open issues, forum.opencv.org, Stack Overflow, etc and have not found any solution
• I updated to the latest OpenCV version and the issue is still there
• There is reproducer code and related data files (videos, images, onnx, etc)