Metadata-Version: 2.4
Name: pytrace3d
Version: 0.2.0
Summary: High-Velocity 3D Code Execution Visualizer, Stack Virtual Machine & Visual Flow IDE
Home-page: https://github.com/adityarajIITj/pytrace3d_package
Author: Aditya Raj
Author-email: Aditya Raj <b25bs1020@iitj.ac.in>
License: MIT
Project-URL: Homepage, https://github.com/adityarajIITj/pytrace3d_package
Project-URL: Repository, https://github.com/adityarajIITj/pytrace3d_package.git
Project-URL: Bug Tracker, https://github.com/adityarajIITj/pytrace3d_package/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Interpreters
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: matplotlib>=3.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file

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

<p align="left">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-007EC6.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.9+-44CC11.svg" alt="Python 3.9+"></a>
  <a href="https://github.com/adityarajIITj/pyton3d"><img src="https://img.shields.io/badge/3D%20Engine-Built%20From%20Scratch-brightgreen.svg" alt="3D Engine: Built From Scratch"></a>
  <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg" alt="Platform: Windows | macOS | Linux">
  <img src="https://img.shields.io/badge/Tests-18%20Passed-success.svg" alt="Tests">
</p>

## 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](https://github.com/adityarajIITj/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

```mermaid
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:

![Live Visual Block Builder](docs/images/hello_world_visual_blocks.png)

### 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:

![3D Execution Viewport](docs/images/hello_world_3d_viewport.png)

### 3. High-Velocity Terminal Telemetry Execution
Fast runtime tracing, variable tracking, and stack depth capture directly in the terminal:

![Terminal Execution Output](docs/images/hello_world_terminal.png)

### 4. Stack Virtual Machine Disassembly & Operand Tower
Compiled Stack Assembly bytecode opcodes mapped against the active 3D trajectory:

![Stack Virtual Machine View](docs/images/studio_stack_vm.png)

### 5. SQLite Relational Persistence & Historical Trace Recording
Built-in SQLite persistence for time-travel replay and historical session analysis:

![SQLite Persistence](docs/images/studio_sqlite_save.png)

---

## 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 &rarr; Studio**: Saving code in your IDE editor triggers in-process AST decompilation to update visual blocks in real time.
- **Studio &rarr; 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

```bash
# 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
```bash
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
```python
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
```bash
# 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
```bash
pytrace3d dis examples/hello_world_live.py
```

### 5. Launch Native Desktop Studio
```bash
pytrace3d studio
```

---

## Documentation Links

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

---

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for details.

---

## Author

**Aditya Raj**  
Indian Institute of Technology Jodhpur (IIT Jodhpur)  
Email: [b25bs1020@iitj.ac.in](mailto:b25bs1020@iitj.ac.in)  
GitHub: [@adityarajIITj](https://github.com/adityarajIITj)
