Metadata-Version: 2.4
Name: godoplot
Version: 0.1.3
Summary: A high-performance 3D visualization library using Godot
Author: Mugilan Baskaran
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/mugilan-b/godoplot
Project-URL: Bug Tracker, https://github.com/mugilan-b/godoplot/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
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: Operating System :: OS Independent
Classifier: Environment :: GPU
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Natural Language :: English
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: websocket-client>=1.6.0
Dynamic: license-file

# godoplot
Godoplot is a high-performance, GPU-accelerated 3D visualization library for Python (3.11 and above), built on top of the [Godot](https://godotengine.org/) Engine.

This is an early Alpha release.

***
## Quickstart:
You can generate a 3D scatter plot in just a few lines of code:
```
import numpy as np
import godoplot.api as gp

x = np.random.rand(100)
y = np.random.rand(100)
z = np.random.rand(100)

gp.point_scatter3d(x, y, z, name="Test Scatter")
gp.show()
```

To view built-in examples:
```
from godoplot import show examples

# The clear=True parameter clears any previous plots in the same window.
examples.scatter_lorenz_butterfly(clear=True)
# examples.surface_interference(clear=True)
# examples.surface_terrain(clear=True)
show()
```

***
## API Reference:

Plots:

1. Scatter plot:
    ```
        godoplot.point_scatter3d(
            x: list[float] | np.ndarray, 
            y: list[float] | np.ndarray, 
            z: list[float] | np.ndarray, 
            radius: int | None = 2, 
            color: str | None = "#0099FF81", 
            name: str | None = "defaultplot"
        )
    ```
        To ensure maximum GPU performance, each point is rendered as a square of `radius`x`radius` pixels with a constant angular size, bypassing complex sphere geometry.

2. Surface/Mesh/Wireframe plot:
    ```
        godoplot.surface3d(
            vertices, 
            faces, 
            vertex_colors=None, 
            color: str | None = "#FF5500", 
            wireframe: bool | None = False, 
            name: str | None = "defaultplot"
        )
    ```
    Plots a 3D mesh or surface. To plot a surface, you must provide points in space, and instructions on how to connect those points to form triangles.

    `vertices`: Array-like of shape (N, 3) for X, Y, Z coordinates.

    `faces`: Array-like of shape (M, 3). Each entry contains three integers corresponding to indices in your vertices array. For example, a face of [0, 1, 2] tells the engine to draw a solid triangle connecting the 0th, 1st, and 2nd vertices.

    `vertex_colors`: Optional array-like of shape (N, 3) or (N, 4) for RGB/RGBA floats - useful for heatmaps.

Lifecycle Management:

3. `godoplot.clear()`: Clears the screen of active plots.

4. `godoplot.show()`: Launches the Godot visualizer window and renders queued data. Only needs to be called once; further calls will reuse the same instance.

5. `godoplot.GodoClient`: Advanced class for direct Inter-Process Communication (IPC). **WIP**

***
## Visualizer controls:
Movement:

`W/A/S/D` to move around.

`Shift/Ctrl` to raise/descend.

Hold `Right mouse button` to look around.

Tap `Left mouse button` to identify coordinates of the object pointed at.

`Scroll wheel`: In 2D view mode and in orbit mode, this zooms in and zooms out.

Hotkeys:

Press `G` to toggle between grid modes.

Press `R` to reset.

Press `Space` or the UI button to "orbit" your plot.

UI Elements:
| Location | Description |
| ----------- | ----------- |
| Bottom left | Coordinate teleportation inputs (X, Y, Z). |
| Top left | Orbit toggle button |
| Top right | 2D Orthogonal view toggles (XY, XZ, YZ). Tap again to return to 3D. |


***
## Technical Architecture:
Under the hood, there are two components:

1. The Python Library: Handles data abstraction, packaging, and Inter-Process Communication (IPC) via WebSockets.
2. The Godot Visualizer: A pre-compiled Godot scene containing the plotting logic and a WebSocket server. Since Godot is inherently optimized for GPU pipelines, it handles the heavy lifting of rendering.

Execution Flow:
Upon the first call to gp.show(), the library automatically downloads the appropriate Godot engine binary from the [official Godot repository](https://github.com/godotengine/godot) (verifies via SHA checksums) and caches it in your local AppData directory. The visualizer scene data (.pck) is bundled directly with the pip installation. The Python client then launches the engine as a subprocess and streams the data over a local port.

Note: The raw Godot project files are available in this repository under godot_source/godoplot/ if you wish to modify the scene setup directly.

***
## Platform support:

As of v0.1.3, the Godot sub-launching logic is verified on: `Windows AMD64 (x86_64)`. 
However, the codebase is platform-agnostic and is designed to support:

- `Windows AMD64 (x86_64)`
- `Linux AMD64 (x86_64)`
- `Linux ARM64 (aarch64)`
- `macOS Universal (aarch64)`

It should support virtually all modern dedicated GPUs and integrated GPUs.

***
## Roadmap:
- Dedicated documentation website and interactive demo.
- CI/CD setup
- Live Simulation Support (Streaming data arrays frame-by-frame).

***
## Contact & bug reports:
If you encounter bugs, please open an Issue on the GitHub repository. For direct contact, reach out on my **discord**: `daredevil121`
