Graphical Debugger VSIX Extension

C# Visual Studio Extension able to debug graphically geometrical items, such as object oriented boxes, points or 3D space objects. Those mysterious runtime and stack variables hiding in the shadows? Thanks to your breakpoint — they're BUSTED. Nothing escapes your graphical debugger now!

Getting Started guide

Welcome to GraphicalDebugger Extension! This guide will help you get started quickly with the features and usage of the extension inside Visual Studio.

Installation

1. Download and install the .vsix file from the official VS store.
2. Launch Visual Studio (version 17.0 or later).
3. Verify the extension is installed by navigating to Extensions > Manage Extensions > Installed.

Features

• Custom Tool Window: Provides a dockable window with a 3D space to debug variables and objects for enhanced productivity.
• Menu Commands: Adds variables during debug or creates objects, even without any running instance.
• Object Compatibility: Includes, as default, native OpenCascade object and WPF native too, with custom json any geometrical entity can be visualized.

Using the Extension

Opening the Tool Window

1. Go to View > Other Windows > GraphicalDebugger.
2. The tool window will appear docked or floating depending on your preference.
3. Interact with the controls and features provided.

Exploring Commands

On the top left, there is a command board:

• Add 🧩: You can add variables, from everywhere inside your running application, when they have a value.
• Objects 📦: You can add your freestanding objects outside your running application. Each object has a modern editor:
  • Box 📦 — defined by its dimensions and reference system. The definition mode (persistent) lets you build it either centered on its center or anchored on a corner (e.g. 0,0,0) and expanded along the X/Y/Z axes with signed sizes.
  • Point • — a single 3D coordinate.
  • Segment ╱ — a segment between a Start and an End point.
  • Vector ➜ — an arrow from an Origin towards a Direction.
  • Polyline 〰 — an ordered list of points; add or remove vertices on the fly.
  • Import 3D 📐 (last entry) — import a 3D model from file (STL today, STEP and more planned).
• Options ⚙️: You can customise the behaviour of the environment, including the viewport background color and grid color (both saved as persistent data), grid size/cell/thickness, the coordinate system and label visibility.

Custom Variables (Custom Wrappers)

GraphicalDebugger allows you to visualize any geometric data structure using wrappers and predefined JSON descriptors. This enables mapping complex objects, structures, or external libraries as long as they follow the correct JSON format.

How it Works

1. Each geometric type has a JSON descriptor defining:

   • Type: the original C# class.
   • WrapperType: the wrapper type used by the debugger to handle the object.
   • Structure: the properties of the object and how to navigate them.

2. Wrappers implement the logic for graphical representation in the 3D tool window:

   • PointWrapper → points in 3D space.
   • VectorWrapper → directional vectors.
   • PlaneWrapper → planes.
   • AxisWrapper → reference axes.
   • PolylineWrapper → composite curves or segments.
   • SegmentWrapper → individual segments.
   • AxisAlignedBoundingBoxWrapper / OrientedBoundingBoxWrapper → bounding boxes.

3. Each property in the structure uses a Navigate field to indicate how to access the runtime value.

   Example for gp_Pnt:

   {
       "Type": "gp_Pnt",
       "WrapperType": "PointWrapper",
       "Structure": {
           "X": { "Type": "double", "Navigate": ".X()" },
           "Y": { "Type": "double", "Navigate": ".Y()" },
           "Z": { "Type": "double", "Navigate": ".Z()" }
       }
   }
   

   Example for Geom_Plane:

    {
    	"Type": "Geom_Plane",
    	"WrapperType": "PlaneWrapper",
    	"Structure": {
    		"Origin":  { "Type": "gp_Pnt", "Navigate": ".Position().Location()" },
    		"XDirection": { "Type": "gp_Dir", "Navigate": ".Position().XDirection()" },
    		"ZDirection": { "Type": "gp_Dir", "Navigate": ".Position().Direction()" }
    	}
    }
   

   Example for Bnd_OBB:

    {
    	"Type": "Bnd_OBB",
    	"WrapperType": "OrientedBoundingBoxWrapper",
    	"Structure": {
    		"ReferenceSystem":  { "Type": "gp_Ax3", "Navigate": ".Position()" },
    		"Length": { "Type": "double", "Navigate": ".XHSize()" },
    		"Width":  { "Type": "double", "Navigate": ".XHSize()" },
    		"Height": { "Type": "double", "Navigate": ".XHSize()" }
    	}
    }
   

   Example for PolylineCustom:

    {
    	"Type": "MyPolyline.Geometry.GeomCompositeCurve",
    	"WrapperType": "PolylineWrapper",
    	"Structure": {
    		"Segments": { "Type": "OccExtension.Geom_CompositeCurveSegment", "Navigate": ".Segments", "Count": ".Count" }
    	}
    }
   

   Example for Geom_TrimmedCurve:

    {
    	"Type": "Geom_TrimmedCurve",
    	"WrapperType": "SegmentWrapper",
    	"Structure": {
    		"Start":  { "Type": "gp_Pnt", "Navigate": ".StartPoint()" },
    		"End": { "Type": "gp_Pnt", "Navigate": ".EndPoint()" }
    	}
    }
   

Supported Object Types

Some ready-to-use examples:

• Points and vectors: gp_Pnt, gp_Vec, System.Windows.Media.Media3D.Point3D, System.Numerics.Vector3
• Directions and axes: gp_Dir, gp_Ax1, gp_Ax3
• Planes: gp_Pln, Geom_Plane
• Curves and segments: Geom_TrimmedCurve, Geom_CompositeCurve
• Bounding boxes: Bnd_Box, Bnd_OBB

Creating Custom Variables

You can define complex custom objects by extending the JSON format and specifying the wrapper type. Using {0} in the Navigate expression allows runtime evaluation of dynamic values, enabling advanced calculations or property transformations directly within the debugger. Each custom object can have its own JSON descriptor, and you can link a specific folder containing these JSON files in the Options to manage them conveniently.

Error Log

The extension automatically saves errors to a local log file:

%LOCALAPPDATA%\GraphicalDebugger\gdLog.log

Open the file with any text editor to view error details.

Authors

• Edoardo Fratarcangeli LinkedIn
• Mirco Fabbri LinkedIn

Last Updates

3.1

• Minor fixes in style and design choices.

3.0

• New freestanding objects: Segment, Vector and Polyline, alongside Box and Point.
• Redesigned, modern editor dialogs built from reusable components.
• Box definition mode: centered on its center, or anchored on a corner and expanded along the X/Y/Z axes with signed sizes.
• Customizable, persistent background color and grid color.
• Import 3D that loads STL objects.
• Lazy loading to IEnumerables.
• Minor fixes.

Future Updates

3.2

• Extend Import 3D to STEP and more formats.
• Create a shared folder on GitHub to let everyone share their own custom json.