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

Adds an optional 2D viewport crosshair overlay to the realsense-viewer.

Feature summary
- Grid lines rendered over each 2D stream viewport using OpenGL
  (glBegin/GL_LINES) with glPushAttrib(GL_CURRENT_BIT) to prevent
  color-state bleed into PiP thumbnails
- Two new toggle buttons in each stream header:
  - Grid icon (fa-th ): show/hide the grid overlay
  - Info icon: show/hide viewport metadata overlay
  Both buttons start OFF at every launch (state is not persisted)
- Per-stream grid config: horizontal lines [1-5], vertical lines [1-5],
  line width (>=1), RGB color [0-255 each]; out-of-range values fall
  back to defaults (not clamped)

Configuration (realsense-config.json)
- Grid settings stored under viewer_model.grid.* using dot-path nested
  JSON API (get_nested / set_nested / set_nested_default)
- Defaults are written only in two cases:
  1. New file: config_file tracks _is_new_file (set in the
     file-based constructor when load_from_file returns nothing);
     ux_window writes defaults on startup when is_new_file() is true
  2. Restore Defaults button: viewer.cpp injects grid defaults into
     temp_cfg immediately after the reset, so they are saved on OK/Apply
- Existing configs without the grid section are left untouched

Files changed
- CMake/lrs_options.cmake: add BUILD_VIEWPORT_GRID_OVERLAY option (OFF)
- common/device-model.h: configurations::viewer::viewport_grid namespace
  with the six JSON key constants
- common/textual-icons.h: textual_icons::grid icon (, fa-th)
- common/rs-config.h / rs-config.cpp: is_new_file() accessor backed by
  _is_new_file member set in the filename constructor
- common/stream-model.h / stream-model.cpp: grid state members, toggle
  buttons, draw_2d_grid() helper; constructor reads grid config from JSON
- common/ux-window.cpp: write grid defaults on new-file startup
- common/viewer.cpp: write grid defaults when Restore Defaults is pressed
- tools/realsense-viewer/CMakeLists.txt: target_compile_definitions for
  BUILD_VIEWPORT_GRID_OVERLAY
- refactor(viewer): make viewport grid overlay a built-in capability
- Drop BUILD_VIEWPORT_GRID_OVERLAY cmake option and remove all #ifdef
  guards — the feature is now always compiled into realsense-viewer.
- Rename draw_2d_grid to draw_crosshair per review request.
- Update grid overlay button tooltips
- Align hover hint text with draw_crosshair rename.

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

Author: Evgeni Raikhel

common/device-model.h

@@ -150,6 +150,15 @@ namespace rs2
             static const char* lpc_point_size{ "viewer_model.lpc_point_size" };
             static const char* show_safety_zones_3d{ "viewer_model.show_safety_zones_3d" };
             static const char* show_safety_zones_2d{ "viewer_model.show_safety_zones_2d" };
+            namespace viewport_grid
+            {
+                static const char* horizontal_lines{ "viewer_model.grid.horizontal_lines" };
+                static const char* vertical_lines  { "viewer_model.grid.vertical_lines"   };
+                static const char* line_width      { "viewer_model.grid.line_width"        };
+                static const char* line_color_r    { "viewer_model.grid.line_color_r"      };
+                static const char* line_color_g    { "viewer_model.grid.line_color_g"      };
+                static const char* line_color_b    { "viewer_model.grid.line_color_b"      };
+            }
         }
         namespace window
         {

common/rs-config.cpp

@@ -111,7 +111,6 @@ config_file::config_file( std::string const & filename )
     }
     catch(...)
     {
-
     }
 }
 

common/rs-config.h

@@ -80,13 +80,15 @@ namespace rs2
         }
 
         bool contains(const char* key) const;
-        
+
         void save(const char* filename);
 
         void reset();
 
         void remove(const char* key);
 
+        bool is_empty() const { return _j.empty(); }
+
         static config_file& instance();
 
         // Retrieves a value from a nested JSON structure using dot notation

common/stream-model.cpp

@@ -7,6 +7,8 @@
 #include "os.h"
 #include <imgui_internal.h>
 #include <realsense_imgui.h>
+#include <iomanip>
+#include <sstream>
 
 struct attribute
 {
@@ -28,6 +30,21 @@ 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);
+        {
+            namespace cfg = configurations::viewer::viewport_grid;
+            auto& cf = config_file::instance();
+
+            auto valid_lines = []( int v ) { return ( v >= 1 && v <= 5 ) ? v : 1; };
+            grid_h_lines    = valid_lines( cf.get_nested<int>( cfg::horizontal_lines, 1   ) );
+            grid_v_lines    = valid_lines( cf.get_nested<int>( cfg::vertical_lines,   1   ) );
+            int w           = cf.get_nested<int>( cfg::line_width, 1 );
+            if ( w >= 1 ) grid_line_width = w;
+            int r = cf.get_nested<int>( cfg::line_color_r, 255 );
+            int g = cf.get_nested<int>( cfg::line_color_g, 255 );
+            int b = cf.get_nested<int>( cfg::line_color_b, 255 );
+            if ( r >= 0 && r <= 255 && g >= 0 && g <= 255 && b >= 0 && b <= 255 )
+            { grid_color_r = r; grid_color_g = g; grid_color_b = b; }
+        }
     }
 
     std::shared_ptr<texture_buffer> stream_model::upload_frame(frame&& f)
@@ -131,6 +148,31 @@ namespace rs2
         glPopAttrib();
     }
 
+    static void draw_crosshair(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();
+    }
+
     bool stream_model::is_stream_visible() const
     {
         if (dev &&
@@ -413,6 +455,7 @@ 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
+        ++num_of_buttons; // Grid overlay button
 
         RsImGui_ScopePushFont(font);
         ImGui::PushStyleColor(ImGuiCol_Text, light_grey);
@@ -548,6 +591,31 @@ namespace rs2
         }
         ImGui::SameLine();
 
+        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 crosshair/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 crosshair/grid overlay");
+        }
+        ImGui::SameLine();
+
+
         if (RS2_STREAM_DEPTH == profile.stream_type())
         {
             label = rsutils::string::from() << textual_icons::bar_chart << "##Color map";
@@ -2036,6 +2104,11 @@ namespace rs2
             }
 
             update_ae_roi_rect(stream_rect, g, error_message);
+
+            if (show_grid)
+                draw_crosshair(stream_rect, grid_h_lines, grid_v_lines, grid_line_width,
+                               grid_color_r, grid_color_g, grid_color_b);
+
         }
         texture->show_preview(stream_rect, _normalized_zoom);
 

common/stream-model.h

@@ -106,6 +106,14 @@ namespace rs2
         bool show_metadata = false;
         bool show_safety_zones_2d = true;
 
+        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;
+
         std::shared_ptr<graph_model> graph;
         bool show_graph = false;
         bool graph_initialized = false;

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" };

common/ux-window.cpp

@@ -87,6 +87,18 @@ namespace rs2
         config_file::instance().set_default(configurations::viewer::commands_xml, "./Commands.xml");
         config_file::instance().set_default(configurations::viewer::hwlogger_xml, "./HWLoggerEvents.xml");
 
+        if( config_file::instance().is_empty() )
+        {
+            namespace cfg = configurations::viewer::viewport_grid;
+            auto& cf = config_file::instance();
+            cf.set_nested_default( cfg::horizontal_lines, 1   );
+            cf.set_nested_default( cfg::vertical_lines,   1   );
+            cf.set_nested_default( cfg::line_width,       1   );
+            cf.set_nested_default( cfg::line_color_r,     255 );
+            cf.set_nested_default( cfg::line_color_g,     255 );
+            cf.set_nested_default( cfg::line_color_b,     255 );
+        }
+
         std::string path;
         try
         {

common/viewer.cpp

@@ -2983,6 +2983,15 @@ namespace rs2
                     {
                         reload_required = true;
                         temp_cfg = config_file();
+                        {
+                            namespace cfg = configurations::viewer::viewport_grid;
+                            temp_cfg.set_nested_default( cfg::horizontal_lines, 1   );
+                            temp_cfg.set_nested_default( cfg::vertical_lines,   1   );
+                            temp_cfg.set_nested_default( cfg::line_width,       1   );
+                            temp_cfg.set_nested_default( cfg::line_color_r,     255 );
+                            temp_cfg.set_nested_default( cfg::line_color_g,     255 );
+                            temp_cfg.set_nested_default( cfg::line_color_b,     255 );
+                        }
                     }
                     ImGui::SameLine();
                     if (ImGui::Button(" Export Settings "))