Contents ======== * `Contents <#contents>`__ * `Develop Python User Defined Functions using Jupyter Notebook <#develop-python-user-defined-functions-using-jupyter-notebook>`__ * `Prerequisites for using Jupyter Notebook <#prerequisites-for-using-jupyter-notebooks>`__ * `Run Jupyter Notebook from Web Browser <#run-jupyter-notebook-from-web-browsers>`__ * `Run Jupyter Notebook using Visual Studio Code <#run-jupyter-notebook-using-visual-studio-code>`__ 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. .. code-block:: yml 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``\ ): .. code-block:: javascript { "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: .. code-block:: sh 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: .. code-block:: sh 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: .. code-block:: sh 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: .. code-block:: sh 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: .. code-block:: sh 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 #. In the Command Palette, run the ``Jupyter: Specify 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 limitations of the Jupyter Notebook plugin. To use this functionality, access the Jupyter notebook through a web browser.