Metadata-Version: 2.4
Name: aidge-gui
Version: 0.1.0
Summary: Interactive graph and model visualizer for the Eclipse Aidge
Project-URL: Homepage, https://www.deepgreen.ai/en/platform
Project-URL: Documentation, https://eclipse.dev/aidge/
Project-URL: Repository, https://gitlab.eclipse.org/eclipse/aidge/aidge_gui
Project-URL: Issues, https://gitlab.eclipse.org/eclipse/aidge/issues/
Project-URL: Changelog, https://gitlab.eclipse.org/eclipse/aidge/releases
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: uvicorn[standard]
Requires-Dist: numpy
Requires-Dist: onnx
Requires-Dist: pydantic
Requires-Dist: python-multipart

<p align="center">
  <img src="https://gitlab.eclipse.org/eclipse/aidge/aidge/-/raw/main/docs/source/_static/Logotype-aidge.png" alt="Aidge logo" width="800"/>
</p>

[![EPL 2.0](https://img.shields.io/badge/license-EPL%202.0-blue.svg?style=for-the-badge)](https://www.eclipse.org/legal/epl-2.0/)
[![Examples](https://img.shields.io/badge/Gitlab-orange?&logo=gitlab&logoColor=white&style=for-the-badge)](https://gitlab.eclipse.org/eclipse/aidge/aidge)
[![PyPi](https://img.shields.io/badge/Pypi-blue?&logo=python&logoColor=white&style=for-the-badge)](https://pypi.org/project/aidge_learning/)
[![Examples](https://img.shields.io/badge/Tutorials-darkviolet?&logo=googlescholar&logoColor=white&style=for-the-badge)](https://eclipse.dev/aidge/source/Tutorial/index.html)
[![Documentation Status](https://readthedocs.org/projects/eclipse-aidge/badge/?version=latest&style=for-the-badge)](https://eclipse-aidge.readthedocs.io/en/latest/?badge=latest)
![GitLab Contributors](https://img.shields.io/gitlab/contributors/eclipse%2Faidge%2Faidge?gitlab_url=https%3A%2F%2Fgitlab.eclipse.org&style=for-the-badge)
![Open GitLab Issues](https://img.shields.io/gitlab/issues/open-raw/eclipse%2Faidge%2Faidge?gitlab_url=https%3A%2F%2Fgitlab.eclipse.org%2F&style=for-the-badge)
![Closed GitLab Issues](https://img.shields.io/gitlab/issues/closed-raw/eclipse%2Faidge%2Faidge?gitlab_url=https%3A%2F%2Fgitlab.eclipse.org%2F&style=for-the-badge&color=1591df)


# Aidge GUI

A lightweight interactive visualizer for `aidge_core` graphs. Call `visualize(graph)` anywhere in your Python script and inspect your graph live in the browser, no separate tool to launch.

If you want to experiment with Aidge or its GUI you can call `start_gui()` so start up the GUI with an empty graph.

## What it does

The visualizer spins up a local web server in the background and opens a browser tab automatically. The graph is rendered as an interactive canvas where you can:

- **Pan and zoom** across the graph
- **Inspect** operator types and attributes on each node
- **Edit** attribute values inline by clicking on them, the change is sent back to Python over WebSocket

The graph state lives entirely in Python. The browser is a thin rendering layer that displays what Python sends and forwards user interactions back.

## Quick start

**System Requirements**

- `python >= 3.10`
- `Node.js >= 18`
- `npm >= 9`
- `aidge_core`
- `aidge_backend_cpu`
- `aidge_onnx`


## 🛠 Build from Source

**Prerequisite** (in addition to previous one):
* Please review the [global installation instructions](https://gitlab.eclipse.org/eclipse/aidge/aidge/-/blob/main/README.md) before proceeding.
* If using a virtual environment, **use the same one** for all Aidge modules.


### 1. Python installation using setup scripts


| Environment | Python Development |
| --- | --- | 
| **Windows** | `.\setup.ps1 -Modules gui -Tests` |
| **Unix**    |  `./setup.sh -m gui --tests` |


> [!TIP]
> Use `Get-Help setup.ps1` (Windows) or `./setup.sh -h` (Unix) for full documentation.


### 2. Python Installation (pip)

Run these commands from the `aidge_gui/` directory:

```bash
# Standard install
pip install . -v

# Install with testing dependencies
pip install .[test] -v && pytest
```

## Example scripts

There are two ways of launching the GUI.

Visualizing a graph:

```python
import aidge_core
import aidge_onnx
import aidge_backend_cpu
from aidge_gui import visualize

graph = aidge_core.sequential([
    aidge_core.ReLU("node0"),
])

visualize(graph)
```

Or by starting it with an empty graph:

```python
import aidge_core
import aidge_onnx
import aidge_backend_cpu
from aidge_gui import start_gui

start_gui()
```

Using these functions will start the server at `http://localhost:8765` and open it in your default browser. The server runs in a background thread and shuts down automatically when your script exits.

The port and ip is configurable with the function arguments.


## API overview

### `visualize`

```python
visualize(
    graph: Union[aidge_core.GraphView, onnx.ModelProto],
    host: str = "127.0.0.1",
    port: int = 8765,
    open_browser: bool = True,
    block: bool = True,
) -> None
```

Launch the Aidge GUI and display an existing graph.

The input `graph` can be either an `aidge_core.GraphView` or an `onnx.ModelProto`. ONNX models are converted to Aidge before being displayed.

### `start_gui`

```python
start_gui(
    host: str = "127.0.0.1",
    port: int = 8765,
    open_browser: bool = True,
    block: bool = True,
) -> None
```

Launch the Aidge GUI with an empty graph.

This is useful when you want to experiment with the interface or create a graph directly from the GUI.

The `host`, `port`, `open_browser`, and `block` arguments behave the same way as in `visualize`.

## Common issues

### I replaced `aidge_model_explorer` with `aidge_gui` and it does not work anymore

Make sure that `visualize()` is used with the correct signature.

Unlike `aidge_model_explorer`, `aidge_gui.visualize()` does not take a graph name as second argument. For example:

```python
visualize(graph, "my_graph")
```

will interpret `"my_graph"` as the `host` argument, which will likely generate an error.

Use:

```python
visualize(graph)
```

or, if needed:

```python
visualize(graph, host="127.0.0.1", port=8765)
```

### It takes a long time to load or I cannot open multiple instances at once

This is often related to port availability. The default port may already be used by another process or by another Aidge GUI instance.

In that case, specify another available port:

```python
visualize(graph, port=8766)
```

### I updated Aidge GUI, but I do not see any difference in the browser

This is probably caused by the browser cache.

Try refreshing the page first. If the issue persists, clear the browser cache or force a hard refresh:

* `Ctrl + F5` or `Ctrl + Shift + R` on Windows/Linux
* `Cmd + Shift + R` on macOS
