OGDF - Unity Bridge

A C# integration layer and Virtual Reality client connecting Unity environments to the BRIDGE engine for dynamic execution of Open Graph Drawing Framework (OGDF) algorithms.

📖 About

OGDF - Unity Bridge is the client-side component of a master thesis project designed to solve the interoperability challenges between managed VR environments (C#/.NET) and high-performance native graph libraries (C++).

Visualizing complex networks in Virtual Reality often leads to unintelligible "hairball" structures. This Unity client provides an intuitive, immersive interface for users to dynamically apply complex OGDF layout algorithms to their graphs without leaving VR, utilizing the BRIDGE middleware.

Key Features

• Dynamic VR User Interface: Automatically generates in-game VR menus, sliders, and toggles based on external JSON configurations (ParameterDefinitions.json).
• Dual Execution Strategy:
  • Native Mode: Communicates with the local BRIDGE C++ engine via P/Invoke (NativeBridge.cs) for zero-latency execution.
  • Network Mode: Offloads heavy graph computations to a standalone server or AWS Cloud via REST APIs (NetworkExecutor.cs).
• Asynchronous Graph Updates: Utilizes Unity's Job System (GraphUpdateJob) and Coroutines to apply massive graph layout changes smoothly, preventing frame drops and VR motion sickness.
• On-the-fly Script Building: The ScriptBuilder dynamically constructs Lua scripts injected with user-selected parameters via the MRTK-Keyboard before sending them to the execution engine.

🚀 Installation

Prerequisites

• Game Engine: Unity 2021.3 LTS or higher.
• VR SDK: SteamVR Plugin (included).
• Dependencies: MRTK-Keyboard (included in Plugins), Newtonsoft.Json, AWSSDK.Core.
• Backend: The compiled Engine.dll and lua54.dll from the BRIDGE repository.

Setup Steps

1. Clone the Repository

   git clone https://github.com/orkhanigidov/ogdf-unity-bridge.git

2. Open in Unity Open the cloned folder via the Unity Hub.
3. Install Native Plugins (For Native Mode) Copy the compiled Engine.dll and lua54.dll from your BRIDGE C++ build into the Unity project:

   Assets/Plugins/x86_64/

4. Configure SteamVR Ensure your VR headset is connected. Accept the recommended SteamVR settings prompt when Unity opens.

💻 Usage

The client allows you to seamlessly switch between local execution and cloud execution based on your hardware capabilities.

1. Configuration (Resources)

All parameters and network settings are managed via JSON files located in Assets/Resources/Ogdf/Configurations/.

• ParameterDefinitions.json: Defines the UI elements (sliders, inputs, dropdowns) for each OGDF algorithm. The Unity ModalController reads this to spawn VR interfaces.
• NetworkConfiguration.json: Defines the endpoint for Network Execution mode:

  {
    "protocol": "https",
    "host": "xxxxxx.execute-api.eu-north-1.amazonaws.com",
    "port": 443,
    "endpoint": "api/execute_script",
    "provider": "Aws",
    "region": "eu-north-1"
  }

2. Adding Layout Scripts

To add a new OGDF algorithm to the VR menu, simply place the corresponding .lua script into Assets/Resources/Ogdf/Scripts/ (e.g., hierarchical.lua, orthogonal.lua). The ScriptListController will automatically detect it and populate the VR menu.

3. Execution Modes

In the Unity Scene, locate the IntegrationController component attached to the main management GameObject.

• Set Execution Mode to Native to use the local Engine.dll via P/Invoke.
• Set Execution Mode to Network to send requests to the configured AWS or local Oat++ server.

Once in VR, point your laser at the menu, select an algorithm, adjust the layout parameters using the generated UI and MRTK keyboard, and pull the trigger to execute. The GraphUpdateJob will smoothly morph the graph into its new layout.

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

• Copyright: © 2025 Orkhan Igidov
• Thesis Context: Connecting OGDF to GAV-VR - Design Concept and Realisation (Universität Konstanz).