Address review feedback: typed Python composite-option access, feature demo

Rework wrappers/python/examples/embedded_filters.py to use the typed
composite-option accessors (get_improved_close_range_control(),
get_temporal_filter_dpp_config()) registered per option id, reading
fields back by introspecting the returned typed object - no
struct.pack/unpack format string or hand-maintained byte offsets on the
Python side anymore. Fold composite_option_hello.py's demo into this
same file and remove it, so there's one Python composite-option example
instead of two.

Add an "Improved Close Range Depth" section to
examples/embedded-filters/rs-embedded-filters.cpp that demos the actual
feature rather than SDK plumbing: find the filter across all connected
devices (it's currently D500-USB-only, unlike the rest of this DDS-only
file), read its typed config, stream briefly with it off then on
(Downscale x2), report the minimum valid depth seen each way, and
restore the original configuration.

Author: Evgeni Raikhel

examples/embedded-filters/rs-embedded-filters.cpp

@@ -2,10 +2,12 @@
 // Copyright(c) 2025 RealSense, Inc. All Rights Reserved.
 
 #include <librealsense2/rs.hpp>
+#include <librealsense2/h/rs_hkr_improved_close_range_control.h>
 
 #include <iostream>
 #include <string>
 #include <thread>
+#include <vector>
 
 
 rs2::device get_dds_device()
@@ -138,6 +140,138 @@ try
     std::cout << "Setting toggle back to initial value: " << enabled << std::endl;
     dec_filter.set_option(RS2_OPTION_EMBEDDED_FILTER_ENABLED, enabled);
 
+    std::cout << std::endl;
+    std::cout << "Improved Close Range Depth (composite option)" << std::endl;
+    std::cout << "=========================================" << std::endl;
+
+    // Unlike Decimation above, this filter has no RS2_OPTION_EMBEDDED_FILTER_ENABLED scalar
+    // option at all - its whole configuration, enable included, is one atomically-exchanged
+    // struct (see rs_hkr_improved_close_range_control.h). It's currently registered on the D500
+    // USB path only (see improved_close_range_filter_feature in
+    // src/ds/features/improved-close-range-filter-feature.cpp), not over DDS, so - unlike the
+    // rest of this file - it's looked up across every connected device rather than the one DDS
+    // device selected above.
+    // rs2::embedded_filter/rs2::depth_sensor have no default constructor - a 0-or-1-element
+    // vector stands in for "found or not" instead of a nullable local.
+    std::vector<rs2::embedded_filter> found_filter;
+    std::vector<rs2::depth_sensor> found_sensor;
+    for (auto&& d : rs2::context().query_devices())
+    {
+        auto ds = d.first<rs2::depth_sensor>();
+        if (!ds)
+            continue;
+        for (auto&& f : ds.query_embedded_filters())
+        {
+            if (f.supports_composite_option(RS2_COMPOSITE_OPTION_HKR_IMPROVED_CLOSE_RANGE_CONTROL))
+            {
+                found_filter.push_back(f);
+                found_sensor.push_back(ds);
+                break;
+            }
+        }
+        if (!found_filter.empty())
+            break;
+    }
+
+    if (found_filter.empty())
+    {
+        std::cout << "No connected device exposes HKR Improved Close Range Control - skipping." << std::endl;
+    }
+    else
+    {
+        rs2::embedded_filter& close_range_filter = found_filter.front();
+        rs2::depth_sensor& close_range_depth_sensor = found_sensor.front();
+        const auto id = RS2_COMPOSITE_OPTION_HKR_IMPROVED_CLOSE_RANGE_CONTROL;
+
+        // Typed get - the SDK's own bound struct (get_composite_option_as<T>()), not raw bytes;
+        // the same struct set_composite_option_from() below takes to write it back atomically.
+        rs2_improved_close_range_control original{};
+        try
+        {
+            original = close_range_filter.get_composite_option_as<rs2_improved_close_range_control>(id);
+        }
+        catch (const rs2::error& e)
+        {
+            // Registered but not actually functional on this device/FW is a real, expected
+            // outcome - supports_composite_option() only reflects static registration, never a
+            // live capability check.
+            std::cout << "Registered but not functional on this device/FW: " << e.what() << std::endl;
+            original.header.version = 0;
+        }
+
+        if (original.header.version == 0)
+        {
+            // get_composite_option_as() failed above - nothing more to demo.
+        }
+        else
+        {
+            auto close_range_profile = get_depth_profile(close_range_depth_sensor, nominal_width, nominal_height);
+            if (!close_range_profile)
+            {
+                std::cout << "No " << nominal_width << "x" << nominal_height
+                          << " depth profile available on this device for the demo - skipping." << std::endl;
+            }
+            else
+            {
+                // Streams a short burst on close_range_depth_sensor's own current configuration
+                // and returns the minimum non-zero (i.e. valid) depth value seen - a simple,
+                // honest way to show the effect without asserting anything about what's actually
+                // in front of the camera right now.
+                auto capture_min_valid_depth = [&](int frames_to_skip, int frames_to_measure) -> uint16_t
+                {
+                    rs2::frame_queue queue(1);
+                    close_range_depth_sensor.open(close_range_profile);
+                    close_range_depth_sensor.start(queue);
+
+                    for (int i = 0; i < frames_to_skip; ++i)
+                        queue.wait_for_frame();
+
+                    uint16_t min_depth = 0;
+                    for (int i = 0; i < frames_to_measure; ++i)
+                    {
+                        auto depth = queue.wait_for_frame().as<rs2::depth_frame>();
+                        auto data = reinterpret_cast<const uint16_t*>(depth.get_data());
+                        size_t pixel_count = (size_t)depth.get_width() * depth.get_height();
+                        for (size_t p = 0; p < pixel_count; ++p)
+                        {
+                            if (data[p] != 0 && (min_depth == 0 || data[p] < min_depth))
+                                min_depth = data[p];
+                        }
+                    }
+
+                    close_range_depth_sensor.stop();
+                    close_range_depth_sensor.close();
+                    return min_depth;
+                };
+
+                std::cout << "Streaming with Improved Close Range Depth OFF..." << std::endl;
+                auto cfg = original;
+                cfg.enable = 0;
+                close_range_filter.set_composite_option_from(id, cfg);
+                auto min_depth_off = capture_min_valid_depth(5, 10);
+                std::cout << "  Minimum valid depth (filter off): " << min_depth_off << " (depth units)" << std::endl;
+
+                std::cout << "Streaming with Improved Close Range Depth ON (Downscale x2)..." << std::endl;
+                cfg = original;
+                cfg.enable = 1;
+                cfg.filter_type = 0;      // Downscale
+                cfg.downscale_ratio = 1;  // x2
+                close_range_filter.set_composite_option_from(id, cfg);
+                auto min_depth_on = capture_min_valid_depth(5, 10);
+                std::cout << "  Minimum valid depth (filter on):  " << min_depth_on << " (depth units)" << std::endl;
+
+                if (min_depth_on > 0 && (min_depth_off == 0 || min_depth_on < min_depth_off))
+                    std::cout << "Improved Close Range Depth reported a closer minimum valid depth, as expected." << std::endl;
+                else
+                    std::cout << "No closer minimum valid depth observed this run - depends on what's actually "
+                                 "in front of the camera." << std::endl;
+
+                std::cout << "Restoring original configuration." << std::endl;
+                close_range_filter.set_composite_option_from(id, original);
+            }
+        }
+    }
+
     return EXIT_SUCCESS;
 }
 catch( const rs2::error & e )

wrappers/python/examples/composite_option_hello.py

@@ -6,7 +6,6 @@
 #####################################################
 
 
-import struct
 import sys
 import pyrealsense2 as rs
 
@@ -21,10 +20,13 @@
 5. For each embedded filter: show supported COMPOSITE options and print current values too -
    these are a completely separate identity space from the ordinary (scalar) options above (see
    rs2_composite_option_id in rs_composite_option.h): a single multi-field control exchanged
-   atomically, in ONE UVC transaction. get/set_composite_option() hand back/take raw bytes rather
-   than a typed value - Python has no templates, so (mirroring the C++/C99 samples under
-   examples/composite-option and examples/C/composite-ctl) the caller unpacks/packs those bytes
-   against the option's documented wire layout with the `struct` module.
+   atomically, in ONE UVC transaction. Each id known to this example is registered below against
+   its typed accessor method (e.g. get_improved_close_range_control()) - the Python equivalent of
+   the C++ wrapper's get_composite_option_as<T>() template call (see
+   wrappers/python/pyrs_options.cpp) - so what comes back is a real object bound field-for-field
+   against the actual C struct, not raw bytes. Fields are then read off that object by
+   introspection, so this example carries no hand-maintained wire layout of its own: no struct
+   format string, no byte offsets, no field list to keep in sync by hand.
 '''
 
 def list_embedded_filter_options(embedded_filter):
@@ -35,25 +37,27 @@ def list_embedded_filter_options(embedded_filter):
     print("\n")
 
 
-# Known wire layouts for composite options this example knows how to interpret - there is no
-# generic "any composite option" cast (the SDK ships no per-id dispatch), so a new composite
-# option needs its layout added here too, same as every other composite-option sample's typed
-# dispatch. See rs_hkr_improved_close_range_control.h / rs_hkr_temporal_filter_dpp.h for the documented layouts.
-_COMPOSITE_OPTION_LAYOUTS = {
-    rs.composite_option_id.hkr_improved_close_range_control: (
-        # dppc_header (version, flags, ctl_id, param_count, param_type) shared by the whole HKR
-        # DPP control family, then Improved Close Range's 7 logical fields, then 1 reserved (always 0) slot.
-        '<BBHBBiiiiiiii',
-        ['version', 'flags', 'ctl_id', 'param_count', 'param_type',
-         'enable', 'filter_type', 'downscale_ratio', 'shift_mode', 'shift_pixels',
-         'threshold_mode', 'threshold_mm', 'reserved0']),
-    rs.composite_option_id.hkr_temporal_filter_dpp: (
-        # No shared header on this one - just its own 4 fields, tightly packed.
-        '<ifii',
-        ['enabled', 'smooth_alpha', 'smooth_delta', 'persistency_index']),
+# Typed accessor method registered per known composite-option id - the SDK ships no generic "any
+# composite option" cast (there is no per-id dispatch table, in C++ or Python), so a new composite
+# option still needs an entry here, same as every other composite-option sample in this repo
+# dispatches by known id. Unlike a raw wire-layout table though, nothing here names a byte offset
+# or format string: the registered method returns a real typed object (see
+# rs.improved_close_range_control / rs.temporal_filter_dpp_config in pyrs_options.cpp), and
+# _typed_fields() below reads its fields back by introspection.
+_COMPOSITE_OPTION_ACCESSORS = {
+    rs.composite_option_id.hkr_improved_close_range_control: 'get_improved_close_range_control',
+    rs.composite_option_id.hkr_temporal_filter_dpp: 'get_temporal_filter_dpp_config',
 }
 
 
+def _typed_fields(value):
+    '''The real, public fields on a typed composite-option object, discovered from the object
+    itself rather than a hand-maintained name list. `header` is skipped - it's wire-transport
+    framing (version/ctl_id/param_count/...), not one of the control's own logical fields.'''
+    return [name for name in dir(value)
+            if not name.startswith('_') and name != 'header' and not callable(getattr(value, name))]
+
+
 def list_embedded_filter_composite_options(embedded_filter):
     composite_ids = embedded_filter.get_supported_composite_options()
     if not composite_ids:
@@ -65,8 +69,14 @@ def list_embedded_filter_composite_options(embedded_filter):
         print("  {}:".format(repr(id)))
         print("    read-only: {}".format(embedded_filter.is_composite_option_read_only(id)))
         print("    description: \"{}\"".format(embedded_filter.get_composite_option_description(id)))
+
+        accessor_name = _COMPOSITE_OPTION_ACCESSORS.get(id)
+        if accessor_name is None:
+            print("    (no typed accessor registered for this id in this example - see "
+                  "get_composite_option()/get_composite_option_range() for the untyped, raw-bytes API)")
+            continue
         try:
-            raw = embedded_filter.get_composite_option(id)
+            value = getattr(embedded_filter, accessor_name)(id)
         except RuntimeError as e:
             # Registered but not actually functional on this device/FW is a real, expected
             # outcome (supports_composite_option()/get_supported_composite_options() only
@@ -75,15 +85,8 @@ def list_embedded_filter_composite_options(embedded_filter):
             print("    SKIPPED (registered but not functional on this device/FW): {}".format(e))
             continue
 
-        layout = _COMPOSITE_OPTION_LAYOUTS.get(id)
-        if layout is None:
-            print("    raw bytes ({}): {}".format(len(raw), raw.hex()))
-            continue
-
-        fmt, field_names = layout
-        values = struct.unpack(fmt, raw)
-        for name, value in zip(field_names, values):
-            print("    {} = {}".format(name, value))
+        for name in _typed_fields(value):
+            print("    {} = {}".format(name, getattr(value, name)))
     print("\n")