tutorial.md

# ⏯ [interactive pipe website](https://balthazarneveu.github.io/interactive_pipe/)

![](https://balthazarneveu.github.io/interactive_pipe/static/interact-pipe-logo-horizontal-rgb.svg)


# Full tutorial

**Note** : The same tutorial is also available on [Google Colab](https://colab.research.google.com/github/livalgo/interactive-pipe-examples/blob/main/interactive_pipe_tutorial.ipynb) to learn about the Jupyter notebook backend.

# Analyzing the headless pipeline

```python
headless_tutorial_pipeline = interactive_pipeline(gui=None)(tutorial_pipeline)
# gui=None allows retuning a HeadlessPipeline instance.
headless_tutorial_pipeline.graph_representation("__tuto_pipeline")
```
Let's now call the pipeline several times with varying parameters.

🎁 We provide a basic code sample to generate the gif animation.

```python
from PIL import Image as PILImage
img_list = []
for freq in np.linspace(1, 100, 10):
    # Let's first override some of the default parameters.
    headless_tutorial_pipeline.parameters = {
        "gen_color": {"frequency": freq, 'isotropy': freq/100.},
        "compare_by_splitting": {"ratio": freq/100.}}
    # Let's execute
    headless_tutorial_pipeline()
    img = (255.*headless_tutorial_pipeline.results[1][1]).astype(np.uint8)
    img_list.append(PILImage.fromarray(img))

img_list[0].save("animation.gif", save_all=True, append_images=img_list[1:], duration=1, loop=1000)
```

![animation](https://huggingface.co/spaces/balthou/interactive-pipe-tutorial/resolve/main/animation.gif)

# Advice


## Keep separation between "production code" (library / not interactive) & interactivity
- 💡 One of the strength of interactive pipe is to avoid adding hundreds of lines of code dedicated to GUI (graphical user interfaces). 
- With interactive pipe, you have the choice to keep this design choice. Each processing block can be defined as a regular function, without even importing the `interactive` decorator. In a separate file, you'll add sliders.

### Several ways to decorate building blocks


#### 1.Decorate afterward   🏆 *= Recommended approach*
- ➖ Less elegant to read (`add_interactivity` may be in a different file)
- ➕ The decorated function can be re-used somewhere else (before being decorated).
- ➕ Possibility to add conditions (`debug` flag)
 
```python
def gen_color(frequency=0, isotropy=0.):
    ...


def add_interactivity(debug=True):
    interactive(
        frequency=(80, [1, 100]),
        isotropy=(0.8, [0.1, 1.]) if debug else 0.8
    )(gen_color)
```


#### 2.Decorate using `@`


```python
@interactive(
    frequency=(80, [1, 100]),
    isotropy=(0.8, [0.1, 1.])
)
def gen_color(frequency=0, isotropy=0.):
    ...
```
- ➕ Easy to read
- ➖ The decorated function can't be re-used somewhere else.
- ➖ No possibility to add condition to hide/show slider. To hide the slider, you need to comment!


#### 3. Shorter code using `@`

```python
@interactive()
def gen_color(
    frequency=(80, [1, 100]),
    isotropy=(0.8, [0.1, 1.])
):
```

- ➕ Shortest code
- ➖ The decorated function can't be re-used somewhere else

## Pipeline visualization

Internally, `interactive_pipe` builds an execution graph of the pipeline. 
- If you're using  the `qt` backend, press `G` to build the graph. 
- If you're in a notebook, it's possible to easily plot the graph.
```python
headless_tutorial_pipeline = interactive_pipeline(gui=None)(tutorial_pipeline)
headless_tutorial_pipeline.graph_representation()
```

| pipeline's execution graph |
| :--:| 
| ![Pipeline](https://huggingface.co/spaces/balthou/interactive-pipe-tutorial/resolve/main/pipeline.png) |


## Backend choice



|Backend | 🚀  `Qt` | 🐢 `Gradio` |
|:---|:---|:---|
| Responsiveness | ➕ Very fast | ➖ Slower  |
| Shareable | ➖ No, only 1 local Qt Window | ➕ Share a link with others,  (➕ Optional: standalone hosting on  HF spaces 🤗 ) |
| Keyboard controls |  ➕ Yes | ➖ No |
| Full screen |  ➕ Yes | ➖ No |


| 🚀  `Qt` | 🐢 `Gradio` |
|:---:|:---:|
| ![QT](https://huggingface.co/spaces/balthou/interactive-pipe-tutorial/resolve/main/pyqt.gif) | ![Gradio](https://huggingface.co/spaces/balthou/interactive-pipe-tutorial/resolve/main/gradio.gif) |


### Matplotlib backend

Please note that there's also a matplotlib `gui="mpl"` backend in case of environments where you really don't have access to Qt or Jupyter notebooks.