PR #7563 from Nir: L515 - Replace ambient light with digital gain

common/model-views.cpp

@@ -5539,7 +5539,7 @@ namespace rs2
                                     //Known preset was chosen
                                     auto new_val = opt_model.range.min + opt_model.range.step * selected;
                                     model.add_log(to_string() << "Setting " << opt_model.opt << " to "
-                                        << opt_model.value << " (" << labels[selected] << ")");
+                                        << new_val << " (" << labels[selected] << ")");
 
                                     opt_model.endpoint->set_option(opt_model.opt, new_val);
 

include/librealsense2/h/rs_option.h

@@ -90,7 +90,8 @@ extern "C" {
         RS2_OPTION_PRE_PROCESSING_SHARPENING, /**< Changes the amount of sharpening in the pre-processed image */
         RS2_OPTION_NOISE_FILTERING, /**< Control edges and background noise */
         RS2_OPTION_INVALIDATION_BYPASS, /**< Enable\disable pixel invalidation */
-        RS2_OPTION_AMBIENT_LIGHT, /**< Change the depth ambient light see rs2_ambient_light for values */
+        RS2_OPTION_AMBIENT_LIGHT, /**< DEPRECATED! - Use RS2_OPTION_DIGITAL_GAIN instead. */
+        RS2_OPTION_DIGITAL_GAIN = RS2_OPTION_AMBIENT_LIGHT, /**< Change the depth digital gain see rs2_digital_gain for values */
         RS2_OPTION_SENSOR_MODE, /**< The resolution mode: see rs2_sensor_mode for values */
         RS2_OPTION_EMITTER_ALWAYS_ON, /**< Enable Laser On constantly (GS SKU Only) */
         RS2_OPTION_THERMAL_COMPENSATION, /**< Depth Thermal Compensation for selected D400 SKUs */
@@ -100,7 +101,7 @@ extern "C" {
         RS2_OPTION_HDR_ENABLED,  /**< Enable / disable HDR */
         RS2_OPTION_SEQUENCE_NAME, /**< HDR Sequence name */
         RS2_OPTION_SEQUENCE_SIZE, /**< HDR Sequence size */
-        RS2_OPTION_SEQUENCE_ID, /**< HDR Sequence ID - 0 is not HDR; sequence ID for HDR configuartion starts from 1 */
+        RS2_OPTION_SEQUENCE_ID, /**< HDR Sequence ID - 0 is not HDR; sequence ID for HDR configuration starts from 1 */
         RS2_OPTION_HUMIDITY_TEMPERATURE, /**< Humidity temperature [Deg Celsius]*/
         RS2_OPTION_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
     } rs2_option;
@@ -163,14 +164,22 @@ extern "C" {
     } rs2_sensor_mode;
     const char* rs2_sensor_mode_to_string(rs2_sensor_mode preset);
 
-    /** \brief ambient light for RS2_OPTION_AMBIENT_LIGHT option. */
+    /** \brief  DEPRECATED! - Use RS2_OPTION_DIGITAL_GAIN instead. */
     typedef enum rs2_ambient_light
     {
         RS2_AMBIENT_LIGHT_NO_AMBIENT = 1,
         RS2_AMBIENT_LIGHT_LOW_AMBIENT = 2,
     } rs2_ambient_light;
     const char* rs2_ambient_light_to_string(rs2_ambient_light preset);
 
+    /** \brief digital gain for RS2_OPTION_DIGITAL_GAIN option. */
+    typedef enum rs2_digital_gain
+    {
+        RS2_DIGITAL_GAIN_HIGH = 1,
+        RS2_DIGITAL_GAIN_LOW = 2,
+    } rs2_digital_gain;
+    const char* rs2_digital_gain_to_string(rs2_digital_gain preset);
+
     /** \brief values for RS2_OPTION_TRIGGER_CAMERA_ACCURACY_HEALTH option. */
     typedef enum rs2_cah_trigger
     {

src/algo/depth-to-rgb-calibration/optimizer.cpp

@@ -121,11 +121,11 @@ std::string optimizer::settings::to_string() const
 {
     return librealsense::to_string()
         << '[' << ( is_manual_trigger ? "MANUAL" : "AUTO" ) << ' ' << hum_temp << "degC"
-        << " ambience="
-        << ( ambient == RS2_AMBIENT_LIGHT_NO_AMBIENT    ? "none/long"
-             : ambient == RS2_AMBIENT_LIGHT_LOW_AMBIENT ? "low/short"
+        << " digital gain="
+        << (digital_gain == RS2_DIGITAL_GAIN_HIGH ? "high/long"
+            : digital_gain == RS2_DIGITAL_GAIN_LOW ? "low/short"
                                                         : "??" )
-        << " gain=" << receiver_gain << ']';
+        << " receiver gain=" << receiver_gain << ']';
 }
 
 
@@ -464,7 +464,7 @@ void optimizer::set_z_data( std::vector< z_t > && depth_data,
     /*[zEdge,Zx,Zy] = OnlineCalibration.aux.edgeSobelXY(uint16(frame.z),2); % Added the second input - margin to zero out
     [iEdge,Ix,Iy] = OnlineCalibration.aux.edgeSobelXY(uint16(frame.i),2); % Added the second input - margin to zero out
     validEdgePixelsByIR = iEdge>params.gradITh; */
-    _params.set_depth_resolution(depth_intrinsics.width, depth_intrinsics.height, _settings.ambient);
+    _params.set_depth_resolution(depth_intrinsics.width, depth_intrinsics.height, _settings.digital_gain);
     _z.width = depth_intrinsics.width;
     _z.height = depth_intrinsics.height;
     _z.orig_intrinsics = depth_intrinsics;
@@ -1553,7 +1553,7 @@ svm_model_linear::svm_model_linear()
 svm_model_gaussian::svm_model_gaussian()
 {
 }
-void params::set_depth_resolution( size_t width, size_t height, rs2_ambient_light ambient)
+void params::set_depth_resolution( size_t width, size_t height, rs2_digital_gain digital_gain)
 {
     AC_LOG( DEBUG, "    depth resolution= " << width << "x" << height );
     // Some parameters are resolution-dependent
@@ -1573,7 +1573,7 @@ void params::set_depth_resolution( size_t width, size_t height, rs2_ambient_ligh
     }
     if (use_enhanced_preprocessing)
     {
-        if (ambient == RS2_AMBIENT_LIGHT_NO_AMBIENT)
+        if (digital_gain == RS2_DIGITAL_GAIN_HIGH)
         {
             if (VGA)
             {
@@ -1849,12 +1849,12 @@ void optimizer::set_cycle_data(const std::vector<double3>& vertices,
 
 void optimizer::adjust_params_to_apd_gain()
 {
-    if(_settings.ambient == RS2_AMBIENT_LIGHT_NO_AMBIENT) // long preset
+    if(_settings.digital_gain == RS2_DIGITAL_GAIN_HIGH) // long preset
         _params.saturation_value = 230;
-    else if(_settings.ambient == RS2_AMBIENT_LIGHT_LOW_AMBIENT) // short preset
+    else if(_settings.digital_gain == RS2_DIGITAL_GAIN_LOW) // short preset
         _params.saturation_value = 250;
     else
-        throw std::runtime_error( to_string() <<_settings.ambient <<" invalid ambient value");
+        throw std::runtime_error(to_string() << _settings.digital_gain << " invalid digital gain value");
 }
 
 void optimizer::adjust_params_to_manual_mode()

src/algo/depth-to-rgb-calibration/optimizer.h

@@ -30,8 +30,7 @@ namespace depth_to_rgb_calibration {
     struct params
     {
         params();
-
-        void set_depth_resolution(size_t width, size_t height, rs2_ambient_light ambient);
+        void set_depth_resolution(size_t width, size_t height, rs2_digital_gain digital_gain);
         void set_rgb_resolution(size_t width, size_t height);
 
         double gamma = 0.9;
@@ -284,7 +283,7 @@ namespace depth_to_rgb_calibration {
         {
             bool is_manual_trigger = false;
             double hum_temp = 0.;
-            rs2_ambient_light ambient = RS2_AMBIENT_LIGHT_NO_AMBIENT;
+            rs2_digital_gain digital_gain = RS2_DIGITAL_GAIN_HIGH;
             int receiver_gain = 0;  // aka APD
 
             std::string to_string() const;

src/l500/ac-trigger.cpp

@@ -1012,7 +1012,7 @@ namespace ivcam2 {
                     algo::depth_to_rgb_calibration::optimizer::settings settings;
                     settings.is_manual_trigger = _calibration_type == calibration_type::MANUAL;
                     settings.hum_temp = _temp;
-                    settings.ambient = _ambient;
+                    settings.digital_gain = _digital_gain;
                     settings.receiver_gain = _receiver_gain;
                     depth_to_rgb_calibration algo(
                         settings,
@@ -1300,38 +1300,38 @@ namespace ivcam2 {
         // Algo was written with specific receiver gain (APD) in mind, depending on
         // the FW preset (ambient light)
         auto & depth_sensor = _dev.get_depth_sensor();
-        auto & ambient_light = depth_sensor.get_option( RS2_OPTION_AMBIENT_LIGHT );
-        float raw_ambient = ambient_light.query();
+        auto & digital_gain = depth_sensor.get_option(RS2_OPTION_DIGITAL_GAIN);
+        float raw_digital_gain = digital_gain.query();
         auto & apd = depth_sensor.get_option( RS2_OPTION_AVALANCHE_PHOTO_DIODE );
         float raw_apd = apd.query();
         _receiver_gain = int( raw_apd );
-        _ambient = ( rs2_ambient_light ) int( raw_ambient );
-        switch( _ambient )
+        _digital_gain = ( rs2_digital_gain ) int(raw_digital_gain);
+        switch(_digital_gain)
         {
-        case RS2_AMBIENT_LIGHT_LOW_AMBIENT:  // SHORT
+        case RS2_DIGITAL_GAIN_LOW:
             if( _receiver_gain != 18 )
             {
                 if( ! invalid_reason.empty() )
                     invalid_reason += ", ";
                 invalid_reason += to_string()
-                               << "low-ambient (SHORT) receiver gain (" << raw_apd << ") != 18";
+                               << "receiver gain(" << raw_apd << ") of 18 is expected with low digital gain(SHORT)";
             }
             break;
 
-        case RS2_AMBIENT_LIGHT_NO_AMBIENT:  // LONG
+        case RS2_DIGITAL_GAIN_HIGH:  
             if( _receiver_gain != 9 )
             {
                 if( ! invalid_reason.empty() )
                     invalid_reason += ", ";
                 invalid_reason += to_string()
-                               << "no-ambient (LONG) receiver gain (" << raw_apd << ") != 9";
+                               << "receiver gain(" << raw_apd << ") of 9 is expected with high digital gain(LONG)";
             }
             break;
 
         default:
             if( ! invalid_reason.empty() )
                 invalid_reason += ", ";
-            invalid_reason += to_string() << "invalid (" << raw_ambient << ") ambient preset";
+            invalid_reason += to_string() << "invalid (" << raw_digital_gain << ") digital gain preset";
             break;
         }
 

src/l500/ac-trigger.h

@@ -24,7 +24,7 @@ namespace ivcam2 {
         rs2::frameset _sf;
         rs2::frame _cf, _pcf;  // Keep the last and previous frame!
 
-        rs2_ambient_light _ambient;
+        rs2_digital_gain _digital_gain;
         int _receiver_gain;
         double _temp;
 

src/l500/l500-options.cpp

@@ -84,10 +84,10 @@ namespace librealsense
         if (_fw_version < firmware_version(MIN_CONTROLS_FW_VERSION))
         {
             depth_sensor.register_option
-            (RS2_OPTION_VISUAL_PRESET, std::make_shared<uvc_xu_option<int >>(raw_depth_sensor, ivcam2::depth_xu, ivcam2::L500_AMBIENT,
-                "Change the depth ambient light to ambient: 1 for no ambient and 2 for low ambient",
-                std::map<float, std::string>{ { float(RS2_AMBIENT_LIGHT_NO_AMBIENT), "No Ambient"},
-                { float(RS2_AMBIENT_LIGHT_LOW_AMBIENT), "Low Ambient" }}));
+            (RS2_OPTION_VISUAL_PRESET, std::make_shared<uvc_xu_option<int >>(raw_depth_sensor, ivcam2::depth_xu, ivcam2::L500_DIGITAL_GAIN,
+                "Change the depth digital gain to: 1 for high gain and 2 for low gain",
+                std::map<float, std::string>{ { float(RS2_DIGITAL_GAIN_HIGH), "High Gain"},
+                { float(RS2_DIGITAL_GAIN_LOW), "Low Gain" }}));
         }
         else
         {
@@ -188,16 +188,16 @@ namespace librealsense
                                                   resolution_option.get(),
                                                   "Enable/disable pixel invalidation" );
 
-            _ambient_light = register_option<uvc_xu_option<int>, uvc_sensor&, platform::extension_unit, uint8_t, std::string, const std::map<float, std::string>& >
-                (RS2_OPTION_AMBIENT_LIGHT, raw_depth_sensor, ivcam2::depth_xu, ivcam2::L500_AMBIENT,
-                    "Change the depth ambient light to ambient: 1 for no ambient and 2 for low ambient",
-                    std::map<float, std::string>{ { RS2_AMBIENT_LIGHT_NO_AMBIENT, "No Ambient"},
-                    { RS2_AMBIENT_LIGHT_LOW_AMBIENT, "Low Ambient" }});
+            _digital_gain = register_option<uvc_xu_option<int>, uvc_sensor&, platform::extension_unit, uint8_t, std::string, const std::map<float, std::string>& >
+                (RS2_OPTION_DIGITAL_GAIN, raw_depth_sensor, ivcam2::depth_xu, ivcam2::L500_DIGITAL_GAIN,
+                    "Change the depth digital gain to: 1 for high gain and 2 for low gain",
+                    std::map<float, std::string>{ { RS2_DIGITAL_GAIN_HIGH, "High Gain"},
+                    { RS2_DIGITAL_GAIN_LOW, "Low Gain" }});
 
 
             _preset = register_option <float_option_with_description<rs2_l500_visual_preset>, option_range>
                 (RS2_OPTION_VISUAL_PRESET, option_range{ RS2_L500_VISUAL_PRESET_CUSTOM , RS2_L500_VISUAL_PRESET_SHORT_RANGE, 1, RS2_L500_VISUAL_PRESET_DEFAULT },
-                    "Preset to calibrate the camera to environment ambient, no ambient or low ambient. 1 is no ambient and 2 is low ambient");
+                    "Preset to calibrate the camera to environment ambient, no ambient or low ambient.");
 
             _advanced_options = get_advanced_controls();
         }
@@ -207,7 +207,7 @@ namespace librealsense
     {
         std::vector<rs2_option> res;
 
-        res.push_back(RS2_OPTION_AMBIENT_LIGHT);
+        res.push_back(RS2_OPTION_DIGITAL_GAIN);
         for (auto&& o : _hw_options)
             res.push_back(o.first);
 
@@ -239,18 +239,18 @@ namespace librealsense
         switch (preset)
         {
         case RS2_L500_VISUAL_PRESET_NO_AMBIENT:
-            _ambient_light->set_with_no_signal(RS2_AMBIENT_LIGHT_NO_AMBIENT);
+            _digital_gain->set_with_no_signal(RS2_DIGITAL_GAIN_HIGH);
             break;
         case RS2_L500_VISUAL_PRESET_LOW_AMBIENT:
-            _ambient_light->set_with_no_signal(RS2_AMBIENT_LIGHT_LOW_AMBIENT);
+            _digital_gain->set_with_no_signal(RS2_DIGITAL_GAIN_LOW);
             set_max_laser();
             break;
         case RS2_L500_VISUAL_PRESET_MAX_RANGE:
-            _ambient_light->set_with_no_signal(RS2_AMBIENT_LIGHT_NO_AMBIENT);
+            _digital_gain->set_with_no_signal(RS2_DIGITAL_GAIN_HIGH);
             set_max_laser();
             break;
         case RS2_L500_VISUAL_PRESET_SHORT_RANGE:
-            _ambient_light->set_with_no_signal(RS2_AMBIENT_LIGHT_LOW_AMBIENT);
+            _digital_gain->set_with_no_signal(RS2_DIGITAL_GAIN_LOW);
             break;
         case RS2_L500_VISUAL_PRESET_CUSTOM:
             move_to_custom();

src/l500/l500-options.h

@@ -77,7 +77,7 @@ namespace librealsense
         void set_max_laser();
 
         std::map<rs2_option, std::shared_ptr<cascade_option<l500_hw_options>>> _hw_options;
-        std::shared_ptr< cascade_option<uvc_xu_option<int>>> _ambient_light;
+        std::shared_ptr< cascade_option<uvc_xu_option<int>>> _digital_gain;
         std::shared_ptr< cascade_option<float_option_with_description<rs2_l500_visual_preset>>> _preset;
 
         template<typename T, class ... Args>

src/l500/l500-private.h

@@ -26,7 +26,7 @@ namespace librealsense
     {
         // L500 depth XU identifiers
         const uint8_t L500_HWMONITOR = 1;
-        const uint8_t L500_AMBIENT = 2;
+        const uint8_t L500_DIGITAL_GAIN = 2; // Renamed from L500_AMBIENT
         const uint8_t L500_ERROR_REPORTING = 3;
 
         const uint32_t FLASH_SIZE = 0x00200000;

src/rs.cpp

@@ -1267,6 +1267,7 @@ const char* rs2_frame_metadata_value_to_string(rs2_frame_metadata_value metadata
 const char* rs2_l500_visual_preset_to_string(rs2_l500_visual_preset preset)               { return get_string(preset); }
 const char* rs2_sensor_mode_to_string(rs2_sensor_mode mode)                               { return get_string(mode); }
 const char* rs2_ambient_light_to_string( rs2_ambient_light ambient )                      { return get_string(ambient); }
+const char* rs2_digital_gain_to_string(rs2_digital_gain gain)                             { return get_string(gain); }
 const char* rs2_cah_trigger_to_string( rs2_cah_trigger mode )                             { return get_string(mode); }
 const char* rs2_calibration_type_to_string(rs2_calibration_type type)                     { return get_string(type); }
 const char* rs2_calibration_status_to_string(rs2_calibration_status status)               { return get_string(status); }

src/types.cpp

@@ -227,6 +227,18 @@ namespace librealsense
 #undef CASE
     }
 
+    const char* get_string(rs2_digital_gain value)
+    {
+#define CASE(X) STRCASE(DIGITAL_GAIN, X)
+        switch (value)
+        {
+            CASE(HIGH)
+            CASE(LOW)
+        default: assert(!is_valid(value)); return UNKNOWN_VALUE;
+        }
+#undef CASE
+    }
+
     const char* get_string( rs2_cah_trigger value )
     {
 #define CASE(X) STRCASE(CAH_TRIGGER, X)
@@ -420,7 +432,8 @@ namespace librealsense
             CASE(PRE_PROCESSING_SHARPENING)
             CASE(NOISE_FILTERING)
             CASE(INVALIDATION_BYPASS)
-            CASE(AMBIENT_LIGHT)
+            //CASE(AMBIENT_LIGHT) // Deprecated - replaced by "DIGITAL_GAIN" option
+            CASE(DIGITAL_GAIN)
             CASE(SENSOR_MODE)
             CASE(EMITTER_ALWAYS_ON)
             CASE(THERMAL_COMPENSATION)

src/types.h

@@ -556,6 +556,7 @@ namespace librealsense
     RS2_ENUM_HELPERS(rs2_calibration_type, CALIBRATION_TYPE)
     RS2_ENUM_HELPERS_CUSTOMIZED(rs2_calibration_status, RS2_CALIBRATION_STATUS_FIRST, RS2_CALIBRATION_STATUS_LAST )
     RS2_ENUM_HELPERS_CUSTOMIZED(rs2_ambient_light, RS2_AMBIENT_LIGHT_NO_AMBIENT, RS2_AMBIENT_LIGHT_LOW_AMBIENT)
+    RS2_ENUM_HELPERS_CUSTOMIZED(rs2_digital_gain, RS2_DIGITAL_GAIN_HIGH, RS2_DIGITAL_GAIN_LOW)
     RS2_ENUM_HELPERS(rs2_cah_trigger, CAH_TRIGGER)
     RS2_ENUM_HELPERS(rs2_host_perf_mode, HOST_PERF)
 

unit-tests/algo/d2rgb/test-reproduction.cpp

@@ -198,7 +198,7 @@ int main( int argc, char * argv[] )
             catch( std::exception const & e )
             {
                 std::cout << "!! failed: " << e.what() << " -> assuming [MANUAL LONG 9 @40degC]" << std::endl;
-                settings.ambient = RS2_AMBIENT_LIGHT_NO_AMBIENT;
+                settings.digital_gain = RS2_DIGITAL_GAIN_HIGH;
                 settings.hum_temp = 40;
                 settings.is_manual_trigger = true;
                 settings.receiver_gain = 9;

unit-tests/unit-tests-live.cpp

@@ -5871,10 +5871,10 @@ TEST_CASE("l500_presets_set_preset", "[live]")
 
         std::map<int, int> expected_ambient_per_preset =
         {
-            {RS2_L500_VISUAL_PRESET_NO_AMBIENT, RS2_AMBIENT_LIGHT_NO_AMBIENT},
-            {RS2_L500_VISUAL_PRESET_LOW_AMBIENT, RS2_AMBIENT_LIGHT_LOW_AMBIENT},
-            {RS2_L500_VISUAL_PRESET_MAX_RANGE, RS2_AMBIENT_LIGHT_NO_AMBIENT},
-            {RS2_L500_VISUAL_PRESET_SHORT_RANGE, RS2_AMBIENT_LIGHT_LOW_AMBIENT}
+            {RS2_L500_VISUAL_PRESET_NO_AMBIENT, RS2_DIGITAL_GAIN_HIGH},
+            {RS2_L500_VISUAL_PRESET_LOW_AMBIENT, RS2_DIGITAL_GAIN_LOW},
+            {RS2_L500_VISUAL_PRESET_MAX_RANGE, RS2_DIGITAL_GAIN_HIGH},
+            {RS2_L500_VISUAL_PRESET_SHORT_RANGE, RS2_DIGITAL_GAIN_LOW}
         };
 
         std::map<int, int> expected_laser_power_per_preset =
@@ -5891,9 +5891,9 @@ TEST_CASE("l500_presets_set_preset", "[live]")
             {
                 ds.set_option(RS2_OPTION_SENSOR_MODE, (float)res);
                 ds.set_option(RS2_OPTION_VISUAL_PRESET, (float)i.first);
-                CAPTURE(ds.get_option(RS2_OPTION_AMBIENT_LIGHT));
-                REQUIRE(ds.get_option(RS2_OPTION_AMBIENT_LIGHT) == i.second);
-                apd_per_ambient[ds.get_option(RS2_OPTION_AMBIENT_LIGHT)] = ds.get_option(RS2_OPTION_AVALANCHE_PHOTO_DIODE);
+                CAPTURE(ds.get_option(RS2_OPTION_DIGITAL_GAIN));
+                REQUIRE(ds.get_option(RS2_OPTION_DIGITAL_GAIN) == i.second);
+                apd_per_ambient[ds.get_option(RS2_OPTION_DIGITAL_GAIN)] = ds.get_option(RS2_OPTION_AVALANCHE_PHOTO_DIODE);
                 auto expected_laser_power = expected_laser_power_per_preset.find(i.first);
                 if (expected_laser_power != expected_laser_power_per_preset.end())
                 {

wrappers/android/librealsense/src/main/java/com/intel/realsense/librealsense/Option.java

@@ -70,7 +70,8 @@ public enum Option {
     PRE_PROCESSING_SHARPENING(66),
     NOISE_FILTERING(67),
     INVALIDATION_BYPASS(68),
-    AMBIENT_LIGHT(69),
+    AMBIENT_LIGHT(69), // Deprecated - Use DIGITAL_GAIN instead
+    DIGITAL_GAIN(69),
     SENSOR_MODE(70),
     EMITTER_ALWAYS_ON(71),
     THERMAL_COMPENSATION(72),