Color Mode

The Color Mode setting controls how the color image is computed. Color Mode setting has the following possible values:

• ToneMapping

• UseFirstAcquisition

• Automatic

ToneMapping uses all the acquisitions to create one merged and normalized color image. For HDR captures the dynamic range of the captured images is usually higher than the 8-bit color image range. Tone mapping will map the HDR color data to the 8-bit color output range by applying a scaling factor. Tone mapping can also be used for single-acquisition captures to normalize the captured color image to the full 8-bit output. When using ToneMapping the color values can be inconsistent over repeated captures if you move, add or remove objects in the scene. For the most control of the colors, use the UseFirstAcquisition mode.

UseFirstAcquisition uses the color data acquired from the first acquisition provided. If the capture consists of more than one acquisition, then the remaining acquisitions are not used for the color image. No tone mapping is performed. This option provides the most control of the color image, and the color values will be consistent over repeated captures with the same settings.

• Automatic is the default option.

• Automatic is identical to UseFirstAcquisition for single-acquisition captures and multi-acquisition captures where all the acquisitions have identical (duplicated) acquisition settings.

• Automatic is identical to ToneMapping for multi-acquisition HDR captures with differing acquisition settings.

Note

Since SDK 2.7 it is possible to disable tone mapping for HDR captures by setting UseFirstAcquisition for Color Mode.

For single acquisition captures tone mapping can be used to brighten dark images.

Single capture with Color Mode set to UseFirstAcquisition or Automatic (no tone mapping)	Single capture with Color Mode set to ToneMapping

For multi-acquisition HDR tone mapping can be used to map high-dynamic-range colors to the more limited dynamic range output.

Single capture of the first of three HDR acquisitions with Color Mode set to UseFirstAcquisition or Automatic (no tone mapping)	Single capture of the second of three HDR acquisitions with Color Mode set to UseFirstAcquisition or Automatic (no tone mapping)	Single capture of the third of three HDR acquisitions with Color Mode set to UseFirstAcquisition or Automatic (no tone mapping)
HDR with three acquisitions with Color Mode set to ToneMapping or Automatic

HDR capture with UseFirstAcquisition

If you do not want to use tone mapping for your multi-acquisition HDR, but instead use the color image of one of the acquisitions, that is possible. Identify which of the acquisitions you want to use the color from. Then, make sure that acquisition is the first in the sequence of acquisition settings for your HDR capture, and set the Color Mode to UseFirstAcquisition. For the above example, the resulting color image will look like the color image of the single capture using the first of the three HDR acquisitions.

Hint

Make acquisition first in the sequence by clicking … → Move to top in Zivid Studio.

If you want to change the acquisition from which the HDR capture gets the color image, just rearrange the acquisition settings. UseFirstAcquisition Color Mode is recommended for keeping color consistent over repeated captures, useful for e.g, object classification based on color or texture in 2D image. For detailed explanation with implementation example, check out How to deal with Color Inconsistency from HDR.

Check out how to set processing settings with Zivid SDK, including Color Mode:

C++

source

std::cout << "Configuring processing settings for capture:" << std::endl;
Zivid::Settings settings{
    Zivid::Settings::Experimental::Engine::phase,
    Zivid::Settings::Processing::Filters::Smoothing::Gaussian::Enabled::yes,
    Zivid::Settings::Processing::Filters::Smoothing::Gaussian::Sigma{ 1.5 },
    Zivid::Settings::Processing::Filters::Noise::Removal::Enabled::yes,
    Zivid::Settings::Processing::Filters::Noise::Removal::Threshold{ 7.0 },
    Zivid::Settings::Processing::Filters::Outlier::Removal::Enabled::yes,
    Zivid::Settings::Processing::Filters::Outlier::Removal::Threshold{ 5.0 },
    Zivid::Settings::Processing::Filters::Reflection::Removal::Enabled::yes,
    Zivid::Settings::Processing::Filters::Reflection::Removal::Experimental::Mode::global,
    Zivid::Settings::Processing::Filters::Experimental::ContrastDistortion::Correction::Enabled::yes,
    Zivid::Settings::Processing::Filters::Experimental::ContrastDistortion::Correction::Strength{ 0.4 },
    Zivid::Settings::Processing::Filters::Experimental::ContrastDistortion::Removal::Enabled::no,
    Zivid::Settings::Processing::Filters::Experimental::ContrastDistortion::Removal::Threshold{ 0.5 },
    Zivid::Settings::Processing::Color::Balance::Red{ 1.0 },
    Zivid::Settings::Processing::Color::Balance::Green{ 1.0 },
    Zivid::Settings::Processing::Color::Balance::Blue{ 1.0 },
    Zivid::Settings::Processing::Color::Gamma{ 1.0 },
    Zivid::Settings::Processing::Color::Experimental::Mode::automatic
};
std::cout << settings.processing() << std::endl;

C#

source

Console.WriteLine("Configuring processing settings for capture:");
var settings = new Zivid.NET.Settings() {
    Experimental = { Engine = Zivid.NET.Settings.ExperimentalGroup.EngineOption.Phase },
    Processing = { Filters = { Smoothing = { Gaussian = { Enabled = true, Sigma = 1.5 } },
                               Noise = { Removal = { Enabled = true, Threshold = 7.0 } },
                               Outlier = { Removal = { Enabled = true, Threshold = 5.0 } },
                               Reflection = { Removal = { Enabled = true, Experimental = { Mode = ReflectionFilterModeOption.Global} } },
                               Experimental = { ContrastDistortion = { Correction = { Enabled = true,
                                                                                      Strength = 0.4 },
                                                                       Removal = { Enabled = true,
                                                                                   Threshold = 0.5 } } } },
                   Color = { Balance = { Red = 1.0, Green = 1.0, Blue = 1.0 },
                             Gamma = 1.0,
                             Experimental = { Mode = ColorModeOption.Automatic } } }
};
Console.WriteLine(settings.Processing);

Python

source

print("Configuring processing settings for capture:")
settings = zivid.Settings()
settings.experimental.engine = "phase"
filters = settings.processing.filters
filters.smoothing.gaussian.enabled = True
filters.smoothing.gaussian.sigma = 1.5
filters.noise.removal.enabled = True
filters.noise.removal.threshold = 7.0
filters.outlier.removal.enabled = True
filters.outlier.removal.threshold = 5.0
filters.reflection.removal.enabled = True
filters.reflection.removal.experimental.mode = "global"
filters.experimental.contrast_distortion.correction.enabled = True
filters.experimental.contrast_distortion.correction.strength = 0.4
filters.experimental.contrast_distortion.removal.enabled = False
filters.experimental.contrast_distortion.removal.threshold = 0.5
color = settings.processing.color
color.balance.red = 1.0
color.balance.blue = 1.0
color.balance.green = 1.0
color.gamma = 1.0
settings.processing.color.experimental.mode = "automatic"
print(settings.processing)

Version History

SDK	Changes
2.7.0	Tone mapping API is replaced by Color Mode API.
2.3.0	Tone mapping API is added.