BRIDGE/ Run comparison

Master Thesis · University of Konstanz · 2025

Run the C++.
See the graph.

Connecting OGDF to GAV-VR via automated Lua bindings.

BRIDGE is a hybrid architecture that connects the Open Graph Drawing Framework (OGDF) to the GAV-VR viewer. It uses an automated binding generation pipeline (LibClang AST analysis → sol2/Lua bindings), a dual execution strategy (native P/Invoke for low latency, network mode for cloud offloading), and thread-local Lua state management for memory safety.

No headset required Dual execution: native + network Thread-local Lua state (TLS) Whitelist security policy

Comparison

Direct OGDF vs. OGDF through BRIDGE

A headset is optional for verifying the result. The VR renderer is one consumer of the bridge, not a requirement for checking it.

Orkhan Igidov — University of Konstanz

Live comparison

One case, two paths, side by side

Connect the Engine and pick a predefined C++/Lua pair, or paste your own. The graphs below appear only after the Engine returns graph data.

Both sources are sent to the Engine for execution via /api/execute_script. The Engine enforces a whitelist sandbox — only base, math, table, string libraries are loaded.

Engine status Connect the Engine to load available script pairs.

Direct OGDF · 2D reference

Engine output

OGDF via BRIDGE → GAV-VR

Engine output
What to compare

Layouts may differ between engines or runs; the claim to verify is that the same graph, algorithm, and settings produce a consistent result through both paths.

Run stages

Stages are reported by the runner while your job progresses. No timings are invented in the browser — published numbers come from the published experiments.

reproduce this run
Engine integration contract

Endpoint

POST /api/execute_script — the Engine's single documented route (mirroring the C++ ExecutionController). The request carries the Lua script name, the input graph, and script parameters.

Operational parameters per NetworkConfiguration.json: timeout: 30 seconds and retryCount: 3 for robustness against transient network instability.

Native mode bypasses HTTP entirely: the C# NativeBridge imports InitializeBindings, ExecuteScript, and FreeExecutionResponse via P/Invoke.

Request / response shape

Request: { "script", "input", "params" } — e.g. { "script": "hierarchical.lua", "input": "n100e100.graphml", "params": { "layerDistance": 3.0 } }.

Response: execution results with the output graph (nodes with x, y, z coordinates and edges). Large outputs are transmitted via a Base64 chunking protocol (MAX_CHUNK_DATA_SIZE = 1 MB).

On AWS, the API Gateway fronts the EC2-hosted Engine with HTTPS and IAM authorization; clients sign requests via SigV4. The Engine enforces a whitelist sandbox (only base, math, table, string libraries) and a 2000 ms execution timeout per script.

About this demo

Both panes render only the graph data the Engine returns; until the Engine is connected they stay empty — that is the correct state, and the page ships no sample graphs. Every output a reviewer sees was therefore produced by the published pipeline: the same Lua script executed through the BRIDGE Engine in Native (P/Invoke) or Network (REST) mode, with node coordinates and edges returned to this page unmodified. The Engine enforces a whitelist sandbox and a fresh Lua state per execution.

Architecture

What BRIDGE actually is

BRIDGE is a hybrid integration architecture, not a second implementation of OGDF. It uses a three-layered approach: (1) an Automatic Binding Generation Tool that parses OGDF headers via LibClang AST analysis and generates sol2/Lua bindings from YAML configuration, (2) a BRIDGE Engine with dual execution modes — Native Interface (P/Invoke for low-latency local execution) and Network Interface (cloud offloading for compute-intensive tasks), and (3) a C# Client in GAV-VR managing execution strategies and UI. Thread-local Lua state (TLS) ensures memory safety and concurrency; a strict whitelist policy enforces security.

Offline Codegen LibClang AST Analysis YAML Config → sol2/Lua Bindings Automated — no manual wrappers BRIDGE Engine Native Interface P/Invoke (C# ↔ C++) Low-latency local execution Thread-local Lua state (TLS) Network Interface REST API Cloud offloading Whitelist security policy GAV-VR C# Client Execution Strategy Selection · UI Control · Graph Rendering 🔒 Whitelist policy · 🧵 Thread-local Lua state (TLS)
Figure 1 · The BRIDGE architecture: offline binding generation, dual execution engine (native P/Invoke + network REST), and GAV-VR client. Thread-local Lua state and whitelist security span both execution paths.

sol2 is the C++/Lua binding library the generated module is built on — it is the mechanism, not the research claim. The claim is that selected OGDF functionality becomes callable from GAV-VR's Lua runtime with its parameters passed through unchanged, and that the resulting layouts are identical to what OGDF produces directly. BRIDGE uses thread-local Lua state (TLS) for memory safety, and enforces a whitelist security policy. Dual execution modes (Native P/Invoke + Network REST) share the same automated binding layer.

Reproduce

Four commands from clone to render

Everything a reviewer needs is in the repository: pinned dependencies, the example graphs, and the exact commands below. No headset is required for any verification step.

Step 1

Build BRIDGE

Clone the repository and compile the BRIDGE components with the bootstrap script.

terminal 
$ git clone <repository-url> && cd bridge
$ cp .env.example .env
# edit .env: LIBRARY_INCLUDE_PATH, WRAPPER_DIR, UNITY_PROJECT_PATH
# Windows (PowerShell):
$ ./bootstrap.ps1 -BuildType Release -InstallDeps
# Linux:
$ sudo ./bootstrap.sh --build-type Release --install-deps
Step 2

Verify the Engine build

Confirm the build artifacts exist: Engine.dll (native mode) or Engine.exe (network server).

terminal 
# Native mode artifact (DLL, deployed to Unity Plugins):
$ ls build/Engine.dll
# Network mode artifact (standalone server):
$ ls build/Engine.exe
Step 3

Run it through BRIDGE → GAV-VR

Native mode: the Engine.dll is loaded by GAV-VR via P/Invoke (no CLI needed). Network mode: start the Engine server, then point GAV-VR at it. A headset is optional — GAV-VR also renders in a normal desktop window.

terminal 
# Native mode: Engine.dll is auto-deployed to the Unity project
# and loaded via P/Invoke by the NativeExecutor — no CLI command needed.

# Network mode: start the Engine server:
$ ./Engine.exe --host 0.0.0.0 --port 8000

# In GAV-VR: Options Panel → Execution Mode → Native/Network
# NetworkConfiguration.json: { "host": "localhost", "port": 8000, "endpoint": "/api/execute_script" }

# Optional Docker (exposes port 8000):
$ docker run --rm -p 8000:8000 -v $PWD/data:/data bridge-engine:latest
Step 4

Or verify against the hosted runner

The Engine's Network mode exposes a REST API. Send a script-execution request with curl On AWS, the API Gateway endpoint requires IAM/SigV4-signed requests.

terminal 
$ curl -X POST <engine-host>:8000/api/execute_script \
     -H 'Content-Type: application/json' \
     -d '{"script": "hierarchical.lua", "input": "n100e100.graphml", "params": {"layerDistance": 3.0, "nodeDistance": 3.0}}'
# AWS API Gateway (IAM SigV4 signing required):
$ curl -X POST <gateway-host>/api/execute_script \
     -H 'Authorization: AWS4-HMAC-SHA256 ...' -d '...'
Native modeLocal P/Invoke execution for low-latency layout.
Network modeCloud offloading via REST for compute-intensive tasks.
OutputGraph nodes and edges are the primary result. Large payloads are transmitted via Base64 chunking (1 MB chunks). Failure details surfaced on error.
SafetyWhitelist sandbox loads only base, math, table, string libraries; thread-local Lua state (TLS) isolates concurrent executions; 2000 ms execution timeout.

Resources

Links and code

Cite

BibTeX

igidov2025bridge.bib