aidge-model-explorer 0.9.0.post2
Aidge module for model explorer: https://github.com/google-ai-edge/model-explorer.
Requires Python: >=3.10

<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 Model Explorer

Plugin of the framework Google Model Explorer to visualize Aidge graphs.
For more information on how to use Model Explorer, you can refer yourself to the [official documentation](https://github.com/google-ai-edge/model-explorer/wiki/2.-User-Guide) of the framework.

## Quick start

**System Requirements**

- `python >= 3.10`
- `aidge_core`

```bash
pip install aidge-model-explorer
```


## 🛠 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 model_explorer -Clean -Tests -Python` |
| **Unix**    |  `./setup.sh -m model_explorer --clean --tests --python` |


> [!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_model_explorer/` directory:

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

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


#### Editable Install (Experimental)

Use this for real-time development without re-installing.

```bash
pip install --no-build-isolation -ve . --config-settings=editable.rebuild=true -Cbuild-dir=build
```


## 🚀 Features

### Visualize ONNX file

You can use directly the ``model-explorer`` CLI with the extension aidge_model_explorer to visualize an ONNX graph like so:

```bash
model-explorer aidge_mobilenetV2.onnx --extensions=aidge_model_explorer
```

This will allow you to see how Aidge will import your ONNX graph, looking at potential MetaOperator created. Also GenericOperator have a specific background allowing to easily see which operator is not supported natively by Aidge.

### Visualize wrapper method

This function wrap every call to the model explorer API, allowing to only call one line to visualize your graph.

**Note:** This function will automatically embed the visualization in a Jupyter Notebook cell if ran in a notebook, otherwise it will simply open a page in your browser.

```python
import aidge_core
import aidge_model_explorer

lstm = aidge_core.LSTM(in_channels=4, hidden_channels=8, seq_length=5)
model = aidge_core.get_connected_graph_view(lstm)

aidge_model_explorer.visualize(model, "LSTM")
```

:warning: When using model-explorer from a distant server, port forwarding is not always automatic. Make sure to open the right port. (You can force the port to use by providing the argument ``port``)

### Visualize from config

You can also use the model_explorer API by using a ``aidge_model_explorer.Config()`` which is an overridden class enabling full compatibility with the model_explorer API.

```python
import aidge_core
import aidge_model_explorer
import model_explorer


lstm = aidge_core.LSTM(in_channels=4, hidden_channels=8, seq_length=5)
lstm_model = aidge_core.get_connected_graph_view(lstm)

config = aidge_model_explorer.config()
config.add_graphview(lstm_model, "lstm")
model_explorer.visualize_from_config(config)
```

### Synchronize graphs with node ids

Model explorer support an option to synchronize two graphs using node id.
You can use this functionality to visualize a graph before and after graph modifications:

```python
import aidge_core
import aidge_model_explorer
import model_explorer


lstm = aidge_core.LSTM(in_channels=4, hidden_channels=8, seq_length=5)
lstm_model = aidge_core.get_connected_graph_view(lstm)


config = aidge_model_explorer.config()
# Note: need to add graphview before doing any manipulation to keep the ids
config.add_graphview(lstm_model, "lstm")

aidge_core.expand_metaops(lstm_model)
config.add_graphview(lstm_model, "lstm_expanded")

model_explorer.visualize_from_config(config)
```

Once the GUI is opened, you can then explorer the two models like this:

![Node styling](./static/sync.gif)

**Note:** Screen recording taken using ``v0.1.5`` of model explorer.

### Add attributes & metadata


```python
import aidge_core
import aidge_onnx
import aidge_model_explorer
import model_explorer


model = aidge_onnx.load_onnx("aidge_mobilenetV2.onnx")

conv_config = aidge_model_explorer.ConverterConfig()
conv_config.add_attribute("isConv",
                          lambda node: "" if (node.type() == "Conv2D" or node.type() == "ConvDepthWise2D") else None)

conv_config.add_output_metadata("mean",
                          lambda _, tensor: str(tensor.mean()))

config = aidge_model_explorer.config()
config.add_graphview(model, "model1", conv_config)

model_explorer.visualize_from_config(config)
```

Once the GUI is opened, you can then play with the node styler to easily see the nodes that are convolutions.

![Node styling](./static/coloring.gif)

**Note:** Screen recording taken using ``v0.1.5`` of model explorer.

### Update node style

If you want to apply a specific style, you can add the following attributes to your nodes:

- ``model_explorer:bg_color``: Changes the background color of the node. The value must be a string representing a valid color in hexadecimal format (e.g., "#ff0800" for red). The string should follow the standard 6-digit RGB hex code format, beginning with a `#`.
- ``model_explorer:border_color``: Changes the border color of the node. The value must be a string representing a valid color in hexadecimal format (e.g., "#ff0800" for red). The string should follow the standard 6-digit RGB hex code format, beginning with a `#`.
- ``model_explorer:h_border_color``: Changes the border color on hover of the node. The value must be a string representing a valid color in hexadecimal format (e.g., "#ff0800" for red). The string should follow the standard 6-digit RGB hex code format, beginning with a `#`.

Example:

```python
import aidge_core
import aidge_model_explorer
from aidge_model_explorer.visualize import visualize_from_config

node = aidge_core.ReLU(name="Colorized Node!")
node.attributes().set_attr(name="model_explorer:bg_color", value="#ff0800")
node.attributes().set_attr(name="model_explorer:border_color", value="#00ff4c")
node.attributes().set_attr(name="model_explorer:h_border_color", value="#1100ff")

g = aidge_core.sequential([node])
conf = aidge_model_explorer.config()

conf.add_graphview(g, "test_color")
visualize_from_config(conf)
```

## 📊 Default visualizations

Aidge model explorer propose some default visualization in order to let the user get started quickly.

### Has an implementation

Add an attribute to every node for which we cannot find an implementation to use (for example because input/output datatype does not match). This attribute is named `fail_best_match` and contains the description of the current node specs and the specs for which Aidge has a registered implementation.

To use this function use:

```python
my_graph: aidge_core.GraphView
aidge_model_explorer.has_best_match(my_graph, "cpu")
```