SCDS/FtcRobotControllerSDK
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add white balance control, new for SDK 7.1

Westside Robotics
2022-01-17 11:49:20 -08:00
parent f761c8270e
commit ae00365850
1 changed files with 66 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
FTC-Webcam-Controls.md

@ -1,28 +1,29 @@
## Introduction
This basic tutorial describes 7 webcam controls available in the FTC SDK. It includes an example, using 2 of these controls to potentially improve TensorFlow recognition in Freight Frenzy.
This basic tutorial describes 8 webcam controls available in the FTC SDK. It includes an example, using 2 of these controls to potentially improve TensorFlow recognition in Freight Frenzy.
Hats off to [**rgatkinson**](https://github.com/rgatkinson) and [**Windwoes**](https://github.com/Windwoes) who developed these FTC webcam controls.
## Software Overview
The FTC SDK contains a superinterface called CameraControl, which contains 4 interfaces:
The FTC SDK contains a superinterface called CameraControl, which contains 5 interfaces:
- ExposureControl
- GainControl
- WhiteBalanceControl <i>(new for SDK 7.1)</i>
- FocusControl
- PtzControl
Similar to Java classes, Java interfaces provide methods. A webcam can be controlled using methods of these 4 interfaces.
Similar to Java classes, Java interfaces provide methods. A webcam can be controlled using methods of these 5 interfaces.
PtzControl allows control of 3 related features: virtual pan, tilt and zoom. ExposureControl also contains a feature called auto-exposure priority, or AE Priority. Together there are **7 webcam controls** discussed in this tutorial.
PtzControl allows control of 3 related features: virtual pan, tilt and zoom. ExposureControl also contains a feature called auto-exposure priority, or AE Priority. Together there are **8 webcam controls** discussed in this tutorial.
The official documentation is found in the [FTC Javadocs](https://javadoc.io/doc/org.firstinspires.ftc). Click the link for **RobotCore**, then click the **CameraControl** link in the left column.
<p align="center">[[/images/FTC-Webcam-Controls/020-RobotCore.png|RobotCore]]
<br><i><b>FTC RobotCore Javadoc API</b></i><p>
That page provides links to the 4 interfaces listed above.
That page provides links to the 5 interfaces listed above.
The methods described here can be used in Android Studio or OnBot Java. They can also be provided to FTC Blocks programmers by creating myBlocks, covered in a separate [myBlocks tutorial](Custom-FTC-Blocks-(myBlocks)).
@ -50,7 +51,7 @@ The webcam may support minimum and maximum allowed values of exposure. These ca
There are no `set()` methods for min and max exposure; these are hard-coded in the webcam's firmware. Note that firmware settings may vary among different versions of the same webcam model.
These and other exposure methods are called on an ExposureControl object; an example follows after Exposure Control Mode.
These and other exposure methods are called on an ExposureControl object; sample code is shown below, after Exposure Control Mode.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
@ -78,7 +79,7 @@ Full details, and a few other methods, are described in the [ExposureControl Jav
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Exposure Control Example
## Exposure Control code samples
1. Import the interface. This line is automatically added by OnBot Java when the interface is used (coded).
- `import org.firstinspires.ftc.robotcore.external.hardware.camera.controls.ExposureControl;`
@ -188,9 +189,52 @@ The FTC implementations of TensorFlow Lite (and Vuforia) are good at **tracking*
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## White Balance Control
Continuing with other interfaces, the FTC SDK (new for version 7.1) provides methods for white balance control.
White balance is a digital camera setting that balances the **color temperature** in the image. Color temperature is measured in units of degrees Kelvin (K) and is a physical property of light.
For example, sunlight at noon measures between 5200-6000 K. An incandescent light bulb (warm/orange) has a color temperature of around 3000 K, while shade (cool/blue) measures around 8000 K.
When performed automatically, white balance adds the opposite color to the image in an attempt to bring the color temperature back to neutral. This interface WhiteBalanceControl allows the color temperature to be directly programmed by an FTC user.
A single value is used here to control white balance temperature, in units of degrees Kelvin, of Java type integer. Here are the methods:
- setWhiteBalanceTemperature(int temperature)
- getWhiteBalanceTemperature()
As with exposure and gain, the webcam may support minimum and maximum allowed values of white balance temperature. These can be retrieved with:
- getMinWhiteBalanceTemperature()
- getMaxWhiteBalanceTemperature()
There are no `set()` methods for min and max temperature values; these are hard-coded in the webcam's firmware. Note that firmware settings may vary among different versions of the same webcam model.
The Logitech C920 webcam has a min value of 2000 and a max value of 6500.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## White Balance Control Mode
This interface supports 3 values of WhiteBalanceControl.Mode:
- AUTO
- MANUAL
- UNKNOWN
To directly control the color balance temperature, set the webcam to Manual mode. Mode is managed with these WhiteBalanceControl methods:
- setMode(WhiteBalanceControl.Mode.MODE)
- getMode()
The Logitech C920 defaults to Auto mode for white balance control, and even reverts to Auto in a fresh session, after being set to Manual in a previous session. For other CameraControl settings, some webcams revert to a default value and some preserve their last commanded value.
[<p align="right"><i>Return to Top</i>](#introduction)<p>
## Focus Control
Continuing with other interfaces, the FTC SDK provides methods for webcam focus control. At a distance called "focus length", a subject's image (light rays) converge from the lens to form a clear image on the webcam sensor.
At a distance called "focus length", a subject's image (light rays) converge from the lens to form a clear image on the webcam sensor.
If supported by the webcam, focus can be managed with these FocusControl methods:
- setFocusLength(double focusLength)
@ -351,6 +395,15 @@ The method that sets the gain can also return a Boolean indicating whether the o
[<p align="right"><i>Return to Top</i>](#introduction)<p>
### White Balance Support
The methods that set temperature and mode can also return a Boolean, indicating whether the operation was successful or not. As optional examples:
- `wasTemperatureSet = setWhiteBalanceTemperature(3000);`
- `wasWhiteBalanceModeSet = setMode(WhiteBalanceControl.Mode.MANUAL);`
[<p align="right"><i>Return to Top</i>](#introduction)<p>
### Focus Support
Here are two methods to query focus and and a specific focus mode:
@ -386,11 +439,11 @@ For PTZ get() methods, some webcams simply **return zero** for unsupported value
- webcams may retain an assigned Exposure Mode or Focus Mode, even if unplugged
- always verify the current mode
- for a given exposure value, one mode's preview may look very different than another mode's preview
- some webcams accept (`set()`) and confirm (`get()`) a non-supported mode
- Logitech C270 preview becomes lighter up to exposure 655, then rolls over to dark at 656
- some webcams **accept** / `set()` and **confirm** / `get()` a **non-supported mode**
- Logitech C270 preview becomes **lighter** up to exposure 655, then rolls over to **dark** at 656
- this webcam's Min is 0, Max is 1000.
- Logitech V-UAX16 preview looks normal at exposure = 0, becomes **darker** up to 30-40
- Logitech C920 gain value (0-255) greatly influences preview quality, comparable to exposure (0-204)
- Logitech C920 **gain** value (0-255) greatly influences preview quality, comparable to **exposure** (0-204)
- restarting the RC app is sometimes needed after a webcam OpMode crashes
- firmware versions may vary among webcams of the same model number
@ -408,6 +461,8 @@ The following sample OpModes are linked here for reference only. These rudiment
- Adjust exposure and gain with TFOD (test OpMode for Examples 1, 2, 3): [W_TFOD_WebcamExpGain.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/FTC-Webcam-Controls/W_TFOD_WebcamExpGain.java)
- Adjust white balance temperature, if supported: [W_WebcamControls_WhiteBalance.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/FTC-Webcam-Controls/W_WebcamControls_WhiteBalance.java)
- Adjust focus, if supported: [W_WebcamControls_Focus.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/FTC-Webcam-Controls/W_WebcamControls_Focus.java)
- Adjust virtual pan, tilt and zoom, if supported: [W_WebcamControls_PTZ.java](https://github.com/FIRST-Tech-Challenge/WikiSupport/blob/master/SampleOpModes/FTC-Webcam-Controls/W_WebcamControls_PTZ.java)