pytrace3d: 3D Code Execution Visualizer, Stack VM & Serverless IDE Visual Bridge

Overview

pytrace3d is a decoupled, high-velocity developer telemetry library, Stack Virtual Machine, and visual programming SDK for Python. It captures runtime execution states, call stack elevations, and variable mutations, translating them into a continuous 3D spatial vector coordinate environment paired with bidirectional visual node flows.

The library operates completely serverless with zero web dependencies, zero HTTP servers, and zero websockets. It bridges code open in any IDE directly to interactive visual node cards and close-up 3D execution memory nodes.

The embedded 3D spatial mathematics and kinematics core is powered by Pyton3D.

+-------------------------------------------------------------------------------+
|                       Target Python Script / IDE Buffer                       |
+-------------------------------------------------------------------------------+
                                        |
                                        v
+-------------------------------------------------------------------------------+
|             PyTrace3DTracer (sys.settrace Runtime Kernel Engine)              |
|  - Frame Event Interception ("call", "line", "return", "exception")           |
|  - Source Code Line Resolution (inspect.getsourcelines)                       |
|  - Stack Altitude Normalization (current_depth - base_frame_depth)            |
|  - Variable State & Mutation Delta Tracking (ALLOCATE_VAR, MUTATE_VAR)        |
+-------------------------------------------------------------------------------+
                                        |
                                        v  (Chronological Action Tokens)
+-------------------------------------------------------------------------------+
|                   Fast 3D Spatial Vector Coordinate Pass                      |
|  - X-Axis: Step Index (Time Progression)                                      |
|  - Y-Axis: Stack Altitude (Recursion & Call Depth Towers)                     |
|  - Z-Axis: Variable Lane Index Slots (Dedicated Data Channels)                |
+-------------------------------------------------------------------------------+
                                        |
                  +---------------------+---------------------+
                  |                                           |
                  v                                           v
+------------------------------------+    +------------------------------------+
| Headless CLI / JSON Export / CI-CD |    | Native Desktop CAD Studio Viewport |
| (pytrace3d trace / export_json)    |    | (Close-up Step Nodes & Scrubber)   |
+------------------------------------+    +------------------------------------+

Architectural Blueprint

graph TD
    subgraph Developer IDE & Source Code Layer
        A[IDE Source File .py] <-->|In-Process File Watcher| B[LiveSyncBridge]
        C[@visual_trace / @visual_node] --> D[PyTrace3DTracer Kernel]
    end

    subgraph Telemetry & Spatial Vector Engine
        A --> D
        D -->|Frame Events| E[Chronological Action Tokens]
        E -->|Fast Vector Pass| F[3D Spatial Coordinates: X=Time, Y=Altitude, Z=Lane]
        A -->|AST Compiler| G[Stack Assembly Bytecode Opcodes]
    end

    subgraph Native Desktop CAD Studio GUI
        F --> H[3D Close-up Step Memory Nodes]
        B <-->|Two-Way AST Sync| I[Visual Block Flow Builder]
        I -->|Code Synthesis| A
        G --> J[Stack VM Operand Tower]
        K[(SQLite Persistence Store)] <--> H
    end

Studio Interface Showcase

1. Live Two-Way IDE-to-Visual-Node Synchronization

Modifying code in your IDE editor automatically updates the visual flow blocks in the Studio:

2. Close-Up 3D Execution Viewport & Labeled Memory Nodes

Real-time step-by-step 3D memory nodes labeled with step numbers, statements, and variable values:

3. High-Velocity Terminal Telemetry Execution

Fast runtime tracing, variable tracking, and stack depth capture directly in the terminal:

4. Stack Virtual Machine Disassembly & Operand Tower

Compiled Stack Assembly bytecode opcodes mapped against the active 3D trajectory:

5. SQLite Relational Persistence & Historical Trace Recording

Built-in SQLite persistence for time-travel replay and historical session analysis:

Core Capabilities

1. High-Velocity Telemetry Tracing (pytrace3d.core)

• Low-overhead sys.settrace() runtime kernel with relativized stack_altitude = current_depth - base_frame_depth.
• Deep local variable diffing (ALLOCATE_VAR, MUTATE_VAR) and loop cycle iteration tracking (LOOP_ITER).
• Source statement resolution via inspect.getsourcelines(frame.f_code).
• Fast JSON telemetry export (export_trace_json).

2. Serverless In-Process IDE Live Bridge (pytrace3d.bridge)

• IDE → Studio: Saving code in your IDE editor triggers in-process AST decompilation to update visual blocks in real time.
• Studio → IDE: Modifying visual blocks or parameters in the Studio synthesizes clean Python code and writes it directly back to your file.

3. Pythonic Developer SDK & Decorators (pytrace3d.decorators)

• @visual_trace(auto_launch=True): Decorator for auto-launching the 3D execution studio when a function is called.
• @visual_node(name=..., category=...): Decorator to register functions as reusable visual blocks.
• with trace_scope("Scope Name"):: Context manager to trace isolated algorithms or loops.

4. Stack Virtual Machine & Assembly Compiler (pytrace3d.vm)

• Compiles Python expressions to simplified Stack Assembly opcodes (PUSH_CONST, LOAD_VAR, STORE_VAR, ADD, COMPARE_LT, JUMP_IF_FALSE, PRINT).
• Simulates operand push/pop operations with a physical stack tower representation.

5. SQLite Relational Store (pytrace3d.database)

• Embedded SQLite engine for storing project flows, visual graphs, and execution telemetry recordings.

System Requirements & Dependencies

Prerequisites

• Python: Python 3.9 or higher (tested on Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14)
• Operating System: Cross-platform (Windows 10/11, macOS, Linux)

Core Dependencies

• numpy >= 1.20.0: High-performance vector transformations and coordinate buffer mathematics.
• matplotlib >= 3.5.0: Hardware-accelerated 3D Cartesian viewport and interactive projections.
• sqlite3 (Python Standard Library): Embedded relational database for telemetry time-travel querying.
• tkinter (Python Standard Library): Native CAD Studio windowing and interactive flow canvas.

Optional / Development Dependencies

• pytest >= 7.0.0: Automated test execution suite.
• build, twine: For building and publishing distribution packages to PyPI.

Installation

# 1. Clone repository
git clone https://github.com/adityarajIITj/pytrace3d.git
cd pytrace3d_package

# 2. Install dependencies via requirements.txt
pip install -r requirements.txt

# 3. Install pytrace3d package in development/editable mode
pip install -e .

Quickstart & Usage

1. Watch an IDE File with Live Two-Way Visual Sync

pytrace3d watch examples/hello_world_live.py

Open examples/hello_world_live.py in your IDE, edit values, and save (Ctrl+S) to see the visual blocks update automatically.

2. Trace Functions with Decorators

from pytrace3d import visual_trace, trace_scope

# Option A: Trace function and auto-launch 3D Viewport
@visual_trace(auto_launch=True)
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

result = fibonacci(4)

# Option B: Trace isolated block
with trace_scope("Array Math") as t:
    arr = [x * 2 for x in range(5)]

3. Headless Telemetry Tracing

# Trace script and print telemetry in terminal
pytrace3d trace examples/hello_world_live.py

# Trace and persist to SQLite
pytrace3d trace examples/hello_world_live.py --save-db -o trace.json

4. Stack Assembly Disassembly

pytrace3d dis examples/hello_world_live.py

5. Launch Native Desktop Studio

pytrace3d studio

Documentation Links

• Technical Documentation (DOCUMENTATION.md): Deep-dive specifications, mathematical derivations, AST event schemas, and compiler pipelines.
• User Guide (USER_GUIDE.md): Practical tutorials, feature-by-feature walk-throughs, and PyPI publishing instructions.
• Upstream Pyton3D Engine: Core 3D physics and mathematics repository.

License

Distributed under the MIT License. See LICENSE for details.

Author

Aditya Raj
Indian Institute of Technology Jodhpur (IIT Jodhpur)
Email: b25bs1020@iitj.ac.in
GitHub: @adityarajIITj