Register HKR MinZ Control as a composite option, consolidating off the scalar path

Registers RS2_COMPOSITE_OPTION_HKR_MINZ_CONTROL via composite_xu_option (ds::depth_xu,
ds::DS5_HKR_MINZ_CONTROL = 0x14, sizeof(rs2_minz_control)) across every device
constructor that used to register the scalar "Improved Close Range Depth" option:
D555 (FW-gated), rs5x5_device and rs5x5_dedicated_color_device (unconditional), and
left disabled on D585 GMSL for the same pre-existing MIPI/V4L2 backend limitation.

Retires close_range_xu_option/d500_close_range_embedded_filter/close_range_filter_feature
entirely (POC/demo PR - full consolidation onto the composite-option mechanism rather
than keeping two independent accessors on one physical XU control). Known consequence:
common/embedded-filter-model.cpp's generic RS2_OPTION_EMBEDDED_FILTER_ENABLED toggle no
longer applies to this filter - not fixed, out of scope here.

Also corrects rs_hkr_minz_control.h's ctl_id (0x0004 -> 0x0008) and flags (-> 0x01),
sourced from the former close_range_xu_option implementation and a real-hardware FW
validation tool rather than the Confluence page's stale wire-layout table.

Adds examples/composite-option-walkthrough/rs-minz-control-walkthrough.cpp - enumerate/
get_range/get/set/get one at a time against a real connected device.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Evgeni Raikhel

examples/composite-option-walkthrough/CMakeLists.txt

@@ -21,3 +21,13 @@ set_property(TARGET rs-composite-option-walkthrough PROPERTY CXX_STANDARD 14)
 target_link_libraries(rs-composite-option-walkthrough PRIVATE ${LRS_TARGET})
 set_target_properties (rs-composite-option-walkthrough PROPERTIES FOLDER Examples)
 install(TARGETS rs-composite-option-walkthrough RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+# PROTOTYPE / DEMO: HKR MinZ Control, one call at a time, against a REAL connected device (no
+# fake transport) - see rs-minz-control-walkthrough.cpp.
+add_executable(rs-minz-control-walkthrough
+    rs-minz-control-walkthrough.cpp
+)
+set_property(TARGET rs-minz-control-walkthrough PROPERTY CXX_STANDARD 14)
+target_link_libraries(rs-minz-control-walkthrough PRIVATE ${LRS_TARGET})
+set_target_properties (rs-minz-control-walkthrough PROPERTIES FOLDER Examples)
+install(TARGETS rs-minz-control-walkthrough RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

examples/composite-option-walkthrough/rs-minz-control-walkthrough.cpp

@@ -0,0 +1,83 @@
+// License: Apache 2.0. See LICENSE file in root directory.
+// Copyright(c) 2026 RealSense, Inc. All Rights Reserved.
+
+// PROTOTYPE / DEMO - HKR MinZ Control, one call at a time, against a real connected device.
+// Requires a D555/D5xx with FW >= 7.58.39807.10573 (see minz_filter_feature's registration gate
+// in d500-factory.cpp). No fake transport here - this is the real depth sensor's real XU control.
+
+#include <librealsense2/rs.hpp>
+
+#include <algorithm>
+#include <cstring>
+#include <iostream>
+#include <stdexcept>
+
+int main()
+try
+{
+    rs2::context ctx;
+    auto devices = ctx.query_devices();
+    if( devices.size() == 0 )
+        throw std::runtime_error( "no RealSense device connected" );
+
+    rs2::depth_sensor sensor = devices[0].first< rs2::depth_sensor >();
+    const auto id = RS2_COMPOSITE_OPTION_HKR_MINZ_CONTROL;
+
+    // 1) Enumeration
+    auto supported = sensor.get_supported_composite_options();
+    bool has_minz = std::find( supported.begin(), supported.end(), id ) != supported.end();
+    std::cout << "[1] MinZ control supported: " << ( has_minz ? "yes" : "no" ) << '\n';
+    if( ! has_minz )
+        return 0;
+
+    // 2) Get range (min/max/step/def), typed
+    auto range = sensor.get_composite_option_range_as< rs2_minz_control_range >( id );
+    std::cout << "[2] Range (version=" << range.version << "):\n"
+              << "    enable:          min=" << range.min.enable          << " max=" << range.max.enable
+              << " step=" << range.step.enable          << " def=" << range.def.enable          << '\n'
+              << "    downscale_ratio: min=" << range.min.downscale_ratio << " max=" << range.max.downscale_ratio
+              << " step=" << range.step.downscale_ratio << " def=" << range.def.downscale_ratio << '\n'
+              << "    disparity_shift: min=" << range.min.disparity_shift << " max=" << range.max.disparity_shift
+              << " step=" << range.step.disparity_shift << " def=" << range.def.disparity_shift << '\n'
+              << "    threshold:       min=" << range.min.threshold      << " max=" << range.max.threshold
+              << " step=" << range.step.threshold      << " def=" << range.def.threshold      << '\n'
+              << "    threshold_mode:  min=" << range.min.threshold_mode << " max=" << range.max.threshold_mode
+              << " step=" << range.step.threshold_mode << " def=" << range.def.threshold_mode << '\n';
+
+    // 3) Get current value, typed
+    auto current = sensor.get_composite_option_as< rs2_minz_control >( id );
+    std::cout << "[3] Current: enable=" << current.enable
+              << " downscale_ratio=" << current.downscale_ratio
+              << " disparity_shift=" << current.disparity_shift
+              << " threshold=" << current.threshold
+              << " threshold_mode=" << current.threshold_mode << '\n';
+
+    // 4) Set - read-modify-write so the wire header (version/flags/ctl_id/param_count/
+    //    param_type) is preserved exactly as the device reported it, not zero-initialized.
+    rs2_minz_control cfg = current;
+    cfg.enable          = 1;
+    cfg.downscale_ratio = 2;
+    cfg.threshold        = 500;
+    cfg.threshold_mode   = 1;   // Manual
+    sensor.set_composite_option_from( id, cfg );
+    std::cout << "[4] Set: enable=1 downscale_ratio=2 threshold=500 threshold_mode=1 (Manual)\n";
+
+    // 5) Get again to confirm
+    auto after = sensor.get_composite_option_as< rs2_minz_control >( id );
+    std::cout << "[5] Readback: enable=" << after.enable
+              << " downscale_ratio=" << after.downscale_ratio
+              << " threshold=" << after.threshold
+              << " threshold_mode=" << after.threshold_mode << '\n';
+
+    return 0;
+}
+catch( const rs2::error & e )
+{
+    std::cerr << "FAIL: librealsense error: " << e.what() << std::endl;
+    return 1;
+}
+catch( const std::exception & e )
+{
+    std::cerr << "FAIL: " << e.what() << std::endl;
+    return 1;
+}

include/librealsense2/h/rs_hkr_minz_control.h

@@ -17,6 +17,17 @@
 * Wire is little-endian; #pragma pack(1) is required because the header's odd 6-byte size would
 * otherwise leave the compiler inserting 2 bytes of padding before params[0].
 *
+* Header field values (version=0x01, flags=0x01, ctl_id=0x0008) were taken from the former
+* close_range_xu_option implementation (since removed - see below) and independently confirmed
+* against a real-hardware FW validation tool - NOT from the Confluence page's own wire-layout
+* table, which states ctl_id=0x0004 and is stale on that point.
+*
+* This control replaces what used to be exposed as the scalar, enable-only "Improved Close Range
+* Depth" option (RS2_OPTION_EMBEDDED_FILTER_ENABLED via close_range_xu_option) - both addressed
+* the SAME physical XU control (unit 3, selector 0x14). PROTOTYPE/DEMO PR: that scalar option has
+* been removed and consolidated onto this composite option, which exposes full read/write access
+* to all 5 fields instead of just enable.
+*
 * These structs exist purely so callers do not need to hand-roll and keep in sync their own copy
 * of the documented wire layout; the SDK does not expose any function named after them - cast the
 * raw bytes returned by rs2_get_composite_option/rs2_get_composite_option_range to/from these
@@ -43,7 +54,10 @@ typedef struct rs2_minz_control
     /* --- dppc_header: shared by the whole HKR DPP control family, not MinZ-specific --- */
     uint8_t  version;             /**< Wire struct version, per dppc_header. Currently 0x01 */
     uint8_t  flags;                /**< Bitwise control-status mask (active/read-only), per dppc_header */
-    uint16_t ctl_id;               /**< dpp_ctrl_list entry identifying this control. dpp_minz_filter = 0x0004 */
+    uint16_t ctl_id;               /**< dpp_ctrl_list entry identifying this control. dpp_minz_filter = 0x0008 -
+                                    * confirmed against the FW validation tool and the existing
+                                    * close_range_xu_option implementation; an earlier doc pass on this
+                                    * file incorrectly said 0x0004. */
 
     /* --- dppc_ctl parameter block header --- */
     uint8_t  param_count;          /**< Populated param slots below. 5 for MinZ */

src/ds/CMakeLists.txt

@@ -47,8 +47,8 @@ target_sources(${LRS_TARGET}
         "${CMAKE_CURRENT_LIST_DIR}/features/gain-limit-feature.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/features/gyro-sensitivity-feature.h"
         "${CMAKE_CURRENT_LIST_DIR}/features/gyro-sensitivity-feature.cpp"
-        "${CMAKE_CURRENT_LIST_DIR}/features/close-range-filter-feature.h"
-        "${CMAKE_CURRENT_LIST_DIR}/features/close-range-filter-feature.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/features/temporal-filter-feature.h"
         "${CMAKE_CURRENT_LIST_DIR}/features/temporal-filter-feature.cpp"
+        "${CMAKE_CURRENT_LIST_DIR}/features/minz-filter-feature.h"
+        "${CMAKE_CURRENT_LIST_DIR}/features/minz-filter-feature.cpp"
 )

src/ds/d500/CMakeLists.txt

@@ -18,8 +18,8 @@ target_sources(${LRS_TARGET}
         "${CMAKE_CURRENT_LIST_DIR}/d500-object-detection.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/hw_monitor_extended_buffers.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/d500-options.cpp"
-        "${CMAKE_CURRENT_LIST_DIR}/d500-close-range-embedded-filter.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/d500-temporal-embedded-filter.cpp"
+        "${CMAKE_CURRENT_LIST_DIR}/d500-minz-embedded-filter.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/d500-fw-update-device.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/d500-auto-calibration.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/d500-debug-protocol-calibration-engine.cpp"
@@ -34,8 +34,8 @@ target_sources(${LRS_TARGET}
         "${CMAKE_CURRENT_LIST_DIR}/d500-object-detection.h"
         "${CMAKE_CURRENT_LIST_DIR}/hw_monitor_extended_buffers.h"
         "${CMAKE_CURRENT_LIST_DIR}/d500-options.h"
-        "${CMAKE_CURRENT_LIST_DIR}/d500-close-range-embedded-filter.h"
         "${CMAKE_CURRENT_LIST_DIR}/d500-temporal-embedded-filter.h"
+        "${CMAKE_CURRENT_LIST_DIR}/d500-minz-embedded-filter.h"
         "${CMAKE_CURRENT_LIST_DIR}/d500-info.h"
         "${CMAKE_CURRENT_LIST_DIR}/d500-fw-update-device.h"
         "${CMAKE_CURRENT_LIST_DIR}/d500-auto-calibration.h"