godoplot 0.1.3

A high-performance 3D visualization library using Godot

godoplot

Godoplot is a high-performance, GPU-accelerated 3D visualization library for Python (3.11 and above), built on top of the Godot 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 radiusxradius 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 (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