Contents¶

Contents
- Develop Python User Defined Functions using Jupyter Notebook

Develop Python User Defined Functions using Jupyter Notebook¶

Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations, and narrative text. Jupyter Notebook supports the latest versions of the browsers such as Chrome, Firefox, Safari, Opera, and Edge. Some of the uses of Jupyter Notebook include:

Data cleaning and transformation
Numerical simulation
Statistical modeling
Data visualization
Machine learning, and so on.

The web-based IDE of Jupyter Notebook allows you to develop User Defined Functions (UDFs) in Python. This tool provides an interface for you to interact with the Jupyter Notebook to write, edit, experiment, and create python UDFs. It works along with the jupyter_connector([WORK_DIR]/IEdgeInsights/common/video/tree/master/udfs/python/jupyter_connector.py) UDF for enabling the IDE for UDF development. You can use a web browser or Visual Studio Code (VS Code) to use Jupyter Notebook for UDF development.

For more information on how to write and modify an OpenCV UDF, refer to the opencv_udf_template.ipynb([WORK_DIR]/IEdgeInsights/tools/JupyterNotebook/opencv_udf_template.ipynb) (sample OpenCV UDF template). This sample UDF uses the OpenCV APIs to write a sample text on the frames, which can be visualized in the Visualizer display. While using this UDF, ensure that the encoding is disabled. Enabling the encoding will automatically remove the text that is added to the frames.

Note

Custom UDFs like the GVASafetyGearIngestion are specific to certain use cases only. Do not use Jupyter Notebook with these custom UDFs. Instead, modify the VideoIngestion pipeline to use the GVA ingestor pipeline and modify the config to use the jupyter_connector UDF.
In this document, you will find labels of ‘Edge Insights for Industrial (EII)’ for filenames, paths, code snippets, and so on. Consider the references of EII as Open Edge Insights for Industrial (Open EII). This is due to the product name change of EII as Open EII.

Prerequisites for using Jupyter Notebooks¶

The following are the prerequisites for using Jupyter Notebook to develop UDFs:

Jupyter Notebook requires a set of configs, interfaces, and the public and private keys to be present in etcd. To meet this prerequisite, ensure that an entry for Jupyter Notebook with its relative path from the IEdgeInsights([WORK_DIR]/IEdgeInsights/) directory is set in any of the .yml files present in the build/usecases([WORK_DIR]/IEdgeInsights/tree/master/build/usecases) directory.
- Refer the following example to add the entry in the video-streaming.yml([WORK_DIR]/IEdgeInsights/tree/master/build/usecases/video-streaming.yml) file.
```
AppContexts:
---snip---
- tools/JupyterNotebook
```

Ensure that in the config of either VideoIngestion or VideoAnalytics the jupyter_connector([WORK_DIR]/IEdgeInsights/common/video/tree/master/udfs/python/jupyter_connector.py) UDF is enabled to connect to Jupyter Notebook. Refer the following example to connect VideoIngestion to JupyterNotebook. Change the config in the config.json([WORK_DIR]/IEdgeInsights/VideoIngestion/config.json):

{
    "config": {
        "encoding": {
            "type": "jpeg",
            "level": 95
        },
        "ingestor": {
            "type": "opencv",
            "pipeline": "./test_videos/pcb_d2000.avi",
            "loop_video": true,
            "queue_size": 10,
            "poll_interval": 0.2
        },
        "sw_trigger": {
            "init_state": "running"
        },
        "max_workers":4,
        "udfs": [{
            "name": "jupyter_connector",
            "type": "python",
            "param1": 1,
            "param2": 2.0,
            "param3": "str"
        }]
    }
}

Run Jupyter Notebook from web browsers¶

Perform the following steps to develop UDF using the Jupyter Notebook from a web browser:

In the terminal, run the following command:

python3 builder.py -f usecases/video-streaming.yml

Refer the IEdgeInsights/README.md to provision, build and run the tool along with the Open EII recipe or stack.
To see the logs, run the following command:
```
docker logs -f ia_jupyter_notebook
```
In the browser, from the logs, copy and paste the URL along with the token. Refer to the following sample URL:
```
http://127.0.0.1:8888/?token=5839f4d1425ecf4f4d0dd5971d1d61b7019ff2700804b973
```
Note:

If you are accessing the server remotely, replace the IP address ‘127.0.0.1’ with the host IP.
After launching the Jupyter Notebook service in a browser, from the list of available files, run the main.ipynb([WORK_DIR]/IEdgeInsights/tools/JupyterNotebook/main.ipynb) file. Ensure that the Python3.8 kernel is selected.
If required, to experiment and test the UDF, you can modify and rerun the process method of the udf_template.ipynb([WORK_DIR]/IEdgeInsights/tools/JupyterNotebook/udf_template.ipynb) file.
To send parameters to the custom UDF, add them in the jupyter_connector UDF config provided to either VideoIngestion or VideoAnalytics. You can access the parameters in the udf_template.ipynb([WORK_DIR]/IEdgeInsights/tools/JupyterNotebook/udf_template.ipynb) constructor in the udf_config parameter.

Note:

The udf_config parameter is a dictionary (dict) that contains all these parameters. For more information, refer to the sample UDF from the pcb_filter.py([WORK_DIR]/IEdgeInsights/common/video/udfs/python/pcb/pcb_filter.py) file. After modifying or creating a new UDF, run main.ipynb and then, restart VideoIngestion or VideoAnalytics with which you have enabled the Jupyter Notebook service.
To save or export the UDF, click Download as and then, select (.py).

Note:

To use the downloaded UDF, place it in the ../../common/video/udfs/python([WORK_DIR]/IEdgeInsights/common/video/udfs/python) directory or integrate it with the Custom UDFs.

Run Jupyter Notebook using Visual Studio Code¶

Perform the following steps to use Visual Studio Code (VS Code) to develop a UDF:

In the terminal, run the following command:

python3 builder.py -f usecases/video-streaming.yml

Refer the IEdgeInsights/README.md to provision, build and run the tool along with the Open EII recipe or stack.
To see the logs, run the following command:
```
docker logs -f ia_jupyter_notebook
```
In the consolidated build/docker-compose.yml file, for the ia_jupyter_notebook service, change read_only: true to read_only: false.
Run the docker-compose up -d ia_jupyter_notebook command.
In VS Code, install the Remote - Containers extension.
Using the shortcut key combination (Ctrl+Shift+P) access the Command Palette.
In the Command Palette, run the Remote-Containers: Attach to Running Container command.
Select the ia_jupyter_notebook container.
In the ia_jupyter_notebook container, install the Python and Jupyter extensions.
In the Command Palette, run the Jupyter: Specify Jupyter server for connections command.

Note: If the Jupyter: Specify Jupyter server for connections command is not available, then run the Jupyter: Specify local or remote Jupyter server for connections command.
Choose Existing: Specify the URI of an existing server when prompted to select how to connect to Jupyter Notebook.
Enter the server’s URI (hostname) with the authentication token (included with a ?token= URL parameter), when prompted to enter the URI of a Jupyter server. Refer to the sample URL mentioned in the previous procedure.
Open the /home/eiiuser folder to update the respective udf_template and the main notebooks and rerun.
To create a Jupyter notebook, run the Jupyter: Create New Jupyter Notebook command in the Command Palette.
To save the UDF, go to More Actions (…), and then, select Export.
When prompted Export As, select Python Script.
From the File menu, click Save As.
Select Show Local.
Enter the name and save the file.

Note

You cannot upload files to the workspace in VS Code due to the limitation with the Jupyter Notebook plugin. To use this functionality, access the Jupyter notebook through a web browser.