feat(realsense-viewer): viewport grid and metadata overlay

Adds an optional 2-D grid line overlay and per-stream metadata overlay
to the realsense-viewer stream viewports, compiled on demand via the
BUILD_VIEWPORT_GRID_OVERLAY CMake flag (default OFF).

Grid configuration is read at startup from config-settings.xml
(placed next to the exe) under a <realsense-viewer>/<viewport-grid>
hierarchy, keeping the file extensible for future viewer-wide settings:

    <realsense-viewer>
        <viewport-grid>
            <horizontal_lines count="1"/>  <!-- range 1-5, default 1 -->
            <vertical_lines   count="1"/>  <!-- range 1-5, default 1 -->
            <line_width       pixels="1"/> <!-- >= 1, default 1 -->
            <line_color r="255" g="255" b="255"/> <!-- default white -->
        </viewport-grid>
    </realsense-viewer>

Out-of-range values fall back to their defaults (no clamping).
Missing file or invalid XML falls back to all defaults silently.

Two toggle buttons are added to each stream header bar:
  - Grid icon (fa-th, U+F00A): toggles the GL line grid over the viewport
  - Info icon: toggles metadata text overlay (stream type, format,
    resolution, frame#, timestamp, FPS)

Both buttons start in the off state on every launch.
GL color state is properly saved/restored (GL_CURRENT_BIT) to prevent
the grid color from bleeding into adjacent PiP thumbnails.

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

Author: Evgeni Raikhel

CMake/lrs_options.cmake

@@ -63,3 +63,4 @@ option(USE_EXTERNAL_LZ4 "Use externally build LZ4 library instead of building an
 option(BUILD_ASAN "Enable AddressSanitizer" OFF)
 option(BUILD_ROSBAG2 "Build and use rosbag2 recording system" ON) # temporary flag, should be removed when deprecated ROSBAG1 recording system is removed
 mark_as_advanced(BUILD_ASAN)
+option(BUILD_VIEWPORT_GRID_OVERLAY "Build 2D viewport grid overlay for realsense-viewer (configurable via config-settings.xml)" OFF)

common/device-model.h

@@ -141,6 +141,7 @@ namespace rs2
             static const char* show_map_ruler{ "viewer_model.show_map_ruler" };
             static const char* show_stream_details{ "viewer_model.show_stream_details" };
             static const char* metric_system{ "viewer_model.metric_system" };
+
             static const char* shading_mode{ "viewer_model.shading_mode" };
             static const char* commands_xml{ "viewer_model.commands_xml" };
             static const char* hwlogger_xml{ "viewer_model.hwlogger_xml" };

common/stream-model.cpp

@@ -7,6 +7,12 @@
 #include "os.h"
 #include <imgui_internal.h>
 #include <realsense_imgui.h>
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+#include "../third-party/rapidxml/rapidxml.hpp"
+#include <fstream>
+#include <iomanip>
+#include <sstream>
+#endif
 
 struct attribute
 {
@@ -28,6 +34,9 @@ namespace rs2
             configurations::viewer::show_stream_details, false);
         show_safety_zones_2d = config_file::instance().get_or_default(
             configurations::viewer::show_safety_zones_2d, true);
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+        load_grid_config();
+#endif
     }
 
     std::shared_ptr<texture_buffer> stream_model::upload_frame(frame&& f)
@@ -131,6 +140,84 @@ namespace rs2
         glPopAttrib();
     }
 
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+    static void draw_2d_grid(const rect& r, int h_lines, int v_lines, int line_width,
+                              int cr, int cg, int cb)
+    {
+        glPushAttrib(GL_ENABLE_BIT | GL_LINE_BIT | GL_COLOR_BUFFER_BIT | GL_CURRENT_BIT);
+        glLineWidth(static_cast<GLfloat>(line_width));
+        glEnable(GL_BLEND);
+        glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+        glColor4f(cr / 255.f, cg / 255.f, cb / 255.f, 0.7f);
+        glBegin(GL_LINES);
+        for (int c = 1; c <= v_lines; ++c)
+        {
+            float x = r.x + r.w * c / static_cast<float>(v_lines + 1);
+            glVertex2f(x, r.y);
+            glVertex2f(x, r.y + r.h);
+        }
+        for (int row = 1; row <= h_lines; ++row)
+        {
+            float y = r.y + r.h * row / static_cast<float>(h_lines + 1);
+            glVertex2f(r.x, y);
+            glVertex2f(r.x + r.w, y);
+        }
+        glEnd();
+        glPopAttrib();
+    }
+
+    void stream_model::load_grid_config()
+    {
+        std::ifstream fin("config-settings.xml");
+        if (!fin.is_open())
+            return;
+
+        std::stringstream ss;
+        ss << fin.rdbuf();
+        auto xml = ss.str();
+
+        try
+        {
+            rapidxml::xml_document<> doc;
+            doc.parse<0>(doc.allocate_string(xml.c_str()));
+
+            auto viewer_root = doc.first_node("realsense-viewer");
+            if (!viewer_root) return;
+            auto root = viewer_root->first_node("viewport-grid");
+            if (!root) return;
+
+            auto valid_lines = [](int v) { return (v >= 1 && v <= 5) ? v : 1; };
+
+            if (auto n = root->first_node("horizontal_lines"))
+                if (auto a = n->first_attribute("count"))
+                    grid_h_lines = valid_lines(std::atoi(a->value()));
+
+            if (auto n = root->first_node("vertical_lines"))
+                if (auto a = n->first_attribute("count"))
+                    grid_v_lines = valid_lines(std::atoi(a->value()));
+
+            if (auto n = root->first_node("line_width"))
+                if (auto a = n->first_attribute("pixels"))
+                {
+                    int w = std::atoi(a->value());
+                    if (w >= 1) grid_line_width = w;
+                }
+
+            if (auto n = root->first_node("line_color"))
+            {
+                auto valid_byte = [](int v) { return v >= 0 && v <= 255; };
+                int r = grid_color_r, g = grid_color_g, b = grid_color_b;
+                if (auto a = n->first_attribute("r")) r = std::atoi(a->value());
+                if (auto a = n->first_attribute("g")) g = std::atoi(a->value());
+                if (auto a = n->first_attribute("b")) b = std::atoi(a->value());
+                if (valid_byte(r) && valid_byte(g) && valid_byte(b))
+                { grid_color_r = r; grid_color_g = g; grid_color_b = b; }
+            }
+        }
+        catch (...) {}
+    }
+#endif
+
     bool stream_model::is_stream_visible() const
     {
         if (dev &&
@@ -413,6 +500,10 @@ namespace rs2
         if (RS2_STREAM_DEPTH == profile.stream_type()) ++num_of_buttons; // Color map ruler button
         if (RS2_FORMAT_MOTION_XYZ32F == profile.format()) ++num_of_buttons; // Motion graph button
         if (RS2_STREAM_OCCUPANCY == profile.stream_type() && _normalized_zoom.w == 1) ++num_of_buttons; // Safety zones button
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+        ++num_of_buttons; // Grid overlay button
+        ++num_of_buttons; // Viewport metadata overlay button
+#endif
 
         RsImGui_ScopePushFont(font);
         ImGui::PushStyleColor(ImGuiCol_Text, light_grey);
@@ -548,6 +639,56 @@ namespace rs2
         }
         ImGui::SameLine();
 
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+        label = rsutils::string::from() << textual_icons::grid << "##Grid " << profile.unique_id();
+        if (show_grid)
+        {
+            ImGui::PushStyleColor(ImGuiCol_Text, light_blue);
+            ImGui::PushStyleColor(ImGuiCol_TextSelectedBg, light_blue);
+            if (ImGui::Button(label.c_str(), { 24, top_bar_height }))
+            {
+                show_grid = false;
+            }
+            if (ImGui::IsItemHovered())
+                RsImGui::CustomTooltip("Hide grid overlay");
+            ImGui::PopStyleColor(2);
+        }
+        else
+        {
+            if (ImGui::Button(label.c_str(), { 24, top_bar_height }))
+            {
+                show_grid = true;
+            }
+            if (ImGui::IsItemHovered())
+                RsImGui::CustomTooltip("Show grid overlay");
+        }
+        ImGui::SameLine();
+
+        label = rsutils::string::from() << textual_icons::info_circle << "##VpMd " << profile.unique_id();
+        if (show_viewport_metadata)
+        {
+            ImGui::PushStyleColor(ImGuiCol_Text, light_blue);
+            ImGui::PushStyleColor(ImGuiCol_TextSelectedBg, light_blue);
+            if (ImGui::Button(label.c_str(), { 24, top_bar_height }))
+            {
+                show_viewport_metadata = false;
+            }
+            if (ImGui::IsItemHovered())
+                RsImGui::CustomTooltip("Hide metadata overlay");
+            ImGui::PopStyleColor(2);
+        }
+        else
+        {
+            if (ImGui::Button(label.c_str(), { 24, top_bar_height }))
+            {
+                show_viewport_metadata = true;
+            }
+            if (ImGui::IsItemHovered())
+                RsImGui::CustomTooltip("Show metadata overlay");
+        }
+        ImGui::SameLine();
+#endif
+
         if (RS2_STREAM_DEPTH == profile.stream_type())
         {
             label = rsutils::string::from() << textual_icons::bar_chart << "##Color map";
@@ -2036,6 +2177,60 @@ namespace rs2
             }
 
             update_ae_roi_rect(stream_rect, g, error_message);
+
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+            if (show_grid)
+                draw_2d_grid(stream_rect, grid_h_lines, grid_v_lines, grid_line_width,
+                             grid_color_r, grid_color_g, grid_color_b);
+
+            if (show_viewport_metadata)
+            {
+                auto* dl = ImGui::GetForegroundDrawList();
+                auto  fnt = ImGui::GetFont();
+                const float line_h   = ImGui::GetTextLineHeight();
+                const float pad      = 6.f;
+                const float bg_alpha = 0.55f;
+                const ImU32 bg_col   = IM_COL32(0, 0, 0, static_cast<int>(bg_alpha * 255));
+                const ImU32 txt_col  = IM_COL32(255, 255, 255, 230);
+
+                std::string stream_type_str = rs2_stream_to_string(profile.stream_type());
+                std::string format_str      = rs2_format_to_string(profile.format());
+                std::ostringstream oss;
+                oss << static_cast<int>(original_size.x) << "x" << static_cast<int>(original_size.y);
+                std::string res_str = oss.str();
+
+                oss.str(""); oss << "FPS: " << std::fixed << std::setprecision(1) << view_fps.get_fps();
+                std::string fps_str = oss.str();
+
+                oss.str(""); oss << "Frame#: " << frame_number;
+                std::string frame_str = oss.str();
+
+                oss.str(""); oss << "TS: " << std::fixed << std::setprecision(3) << timestamp << " ms";
+                std::string ts_str = oss.str();
+
+                std::string hdr_str = stream_type_str + "  " + format_str + "  " + res_str;
+
+                std::vector<std::string> lines = { hdr_str, frame_str, ts_str, fps_str };
+
+                float max_w = 0.f;
+                for (auto& s : lines)
+                    max_w = std::max(max_w, ImGui::CalcTextSize(s.c_str()).x);
+
+                float bg_x1 = stream_rect.x + pad;
+                float bg_y1 = stream_rect.y + pad;
+                float bg_x2 = bg_x1 + max_w + 2 * pad;
+                float bg_y2 = bg_y1 + lines.size() * (line_h + 2.f) + pad;
+
+                dl->AddRectFilled({ bg_x1, bg_y1 }, { bg_x2, bg_y2 }, bg_col, 3.f);
+
+                float ty = bg_y1 + pad * 0.5f;
+                for (auto& s : lines)
+                {
+                    dl->AddText(fnt, line_h, { bg_x1 + pad, ty }, txt_col, s.c_str());
+                    ty += line_h + 2.f;
+                }
+            }
+#endif
         }
         texture->show_preview(stream_rect, _normalized_zoom);
 

common/stream-model.h

@@ -106,6 +106,17 @@ namespace rs2
         bool show_metadata = false;
         bool show_safety_zones_2d = true;
 
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+        bool show_grid              = false;
+        int  grid_h_lines           = 1;
+        int  grid_v_lines           = 1;
+        int  grid_line_width        = 1;
+        int  grid_color_r           = 255;
+        int  grid_color_g           = 255;
+        int  grid_color_b           = 255;
+        bool show_viewport_metadata = false;
+#endif
+
         std::shared_ptr<graph_model> graph;
         bool show_graph = false;
         bool graph_initialized = false;
@@ -128,6 +139,9 @@ namespace rs2
         void add_dds_metadata_descriptions(std::map<rs2_frame_metadata_value, std::string>& descriptions) const;
         void deal_d585S_metadata_md_values_special_cases(const frame& f);
         std::string get_meaning(const rs2_frame_metadata_value& md_val, const std::vector<std::string>& reasons, const std::string& reason_for_zero = "") const;
+#ifdef BUILD_VIEWPORT_GRID_OVERLAY
+        void load_grid_config();
+#endif
     };
 
 

common/textual-icons.h

@@ -34,6 +34,7 @@ namespace rs2
         // A note to a maintainer - preserve order when adding values to avoid duplicates
         static const textual_icon search{ u8"\uf002" };
         static const textual_icon file_movie{ u8"\uf008" };
+        static const textual_icon grid{ u8"\uf00a" };  // fa-th: 3x3 grid of squares (viewport grid overlay)
         static const textual_icon check{ u8"\uf00c" };
         static const textual_icon times{ u8"\uf00d" };
         static const textual_icon power_off{ u8"\uf011" };

tools/realsense-viewer/CMakeLists.txt

@@ -256,6 +256,17 @@ if(OPENVINO_NGRAPH)
     target_compile_definitions(realsense-viewer PRIVATE OPENVINO_NGRAPH)
 endif()
 
+if(BUILD_VIEWPORT_GRID_OVERLAY)
+    message(STATUS "Viewport grid overlay enabled for realsense-viewer")
+    target_compile_definitions(realsense-viewer PRIVATE BUILD_VIEWPORT_GRID_OVERLAY)
+    add_custom_command(TARGET realsense-viewer POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            ${CMAKE_CURRENT_SOURCE_DIR}/config-settings.xml
+            $<TARGET_FILE_DIR:realsense-viewer>/config-settings.xml
+        COMMENT "Copying grid config-settings.xml to output directory"
+    )
+endif()
+
 source_group("SW-Update" FILES ${SW_UPDATE_FILES})
 
 include_directories(

tools/realsense-viewer/config-settings.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    realsense-viewer configuration file.
+
+    viewport-grid section (requires BUILD_VIEWPORT_GRID_OVERLAY=ON):
+        horizontal_lines : number of horizontal interior lines (range 1-5, default 1)
+        vertical_lines   : number of vertical interior lines   (range 1-5, default 1)
+        line_width       : line thickness in pixels (integer >= 1, default 1)
+        line_color       : RGB color, each channel in the range 0-255 (default White 255,255,255)
+
+        Values outside the valid range are clamped to the nearest bound.
+        Missing or invalid values fall back to the defaults listed above.
+-->
+<realsense-viewer>
+    <viewport-grid>
+        <horizontal_lines count="1"/>
+        <vertical_lines   count="1"/>
+        <line_width       pixels="1"/>
+        <line_color r="255" g="255" b="255"/>
+    </viewport-grid>
+</realsense-viewer>