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 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/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, such as GVASafetyGearIngestion, are only applicable to specific use cases. 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.

Prerequisites for using Jupyter Notebook¶

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/build/usecases) directory.
- Refer the following example to add the entry in the video-streaming.yml([WORK_DIR]/IEdgeInsights/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/udfs/python/jupyter_connector.py) UDF is enabled to connect to the 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 Browser¶

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

In the terminal, execute 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 EII recipe or stack.
To see the logs, execute 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, select the main.ipynb([WORK_DIR]/IEdgeInsights/tools/JupyterNotebook/main.ipynb) file. Ensure that the Python3.8 kernel is selected.
Due to some security measures, JupyterNotebook sometimes doesn’t allow what it considers to be untrusted code to be run by shutting down the kernel. Ensure you mark your notebooks as Trusted to avoid this issue by selecting the Trust option in the dialog box that appears after clicking on Not Trusted button.
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 for either VideoIngestion or VideoAnalytics services. 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 for which the Jupyter Notebook service has been enabled.
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, execute the following command:

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

Refer to the IEdgeInsights/README.md to provision, build and run the tool along with the EII recipe or stack.
To see the logs, execute 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 Dev Containers extension.
Using the shortcut key combination (Ctrl+Shift+P) access the Command Palette.
In the Command Palette, run the Dev 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 Notebook: Select Notebook Kernel command.
Choose Select Another Kernel when prompted to select the kernel.
Select the Existing Jupyter Server option to connect to an existing Jupyter server when prompted to choose a kernel source.
Choose Enter the URL of the running server when prompted to select a Jupyter server.
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.
Select Python 3(ipykernel) kernel when prompted to choose the kernel from remote.
Note:

If Notebook: Select Notebook Kernel option is not available, use the following steps to run Jupyter Notebook
1. In the Command Palette, run the Jupyter: Specify Jupyter server for connections command.
2. Choose Existing: Specify the URI of an existing server when prompted to select how to connect to Jupyter Notebook.
3. 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 limitations of the Jupyter Notebook plugin. To use this functionality, access the Jupyter notebook through a web browser.