diff --git a/examples/google_colab/pysdk_deepx_hello_world.ipynb b/examples/google_colab/pysdk_deepx_hello_world.ipynb new file mode 100644 index 0000000..67ccc0a --- /dev/null +++ b/examples/google_colab/pysdk_deepx_hello_world.ipynb @@ -0,0 +1,253 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Get Started with DeGirum PySDK in Google Colab! \n", + "Welcome to the DeGirum PySDK Quickstart Colab! This notebook is designed to help you get started with PySDK right away, without the need to set up tools or dependencies on your local machine. While the Colab environment may not provide the full range of PySDK’s functionality, the included examples will give you a solid understanding of its capabilities. If you’d like to explore the complete features and unlock the full potential of PySDK, we encourage you to install it on your own machine. Let’s get started by installing the `degirum` and `degirum_tools` packages!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%pip install degirum\n", + "%pip install degirum_tools" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Setting the token\n", + "Since we’ll be using hardware hosted in the cloud by DeGirum, you’ll need to set a token to access these resources. This token serves as your secure key to connect to DeGirum’s cloud infrastructure and enables you to run the examples provided in this notebook seamlessly.\n", + "\n", + "To guide you through the process of obtaining your token and adding it as a new secret in Google Colab, refer to the videos below: \n", + "\n", + "[![Generating a Token for the DeGirum AI Hub](https://img.youtube.com/vi/iyii0RzyFm8/0.jpg)](https://youtu.be/iyii0RzyFm8)\n", + "[![How to Add a New Secret in Google Colab](https://img.youtube.com/vi/GmevDVlT0OQ/0.jpg)](https://youtu.be/GmevDVlT0OQ) \n", + "\n", + "*Click on the thumbnail to watch the tutorial video.* \n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You may verify your token with this code:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import degirum_tools\n", + "# print cloud token\n", + "degirum_tools.get_token()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Running Your First Inference\n", + "\n", + "In this section, we’ll demonstrate how to use PySDK to perform object detection on an example image using a cloud-hosted AI model. Here’s what the code does:\n", + "\n", + "1. **Import Required Libraries**: The `degirum` package is used for loading and using AI models, and `degirum_tools` provides utility functions such as obtaining a token and displaying results.\n", + "\n", + "2. **Load the Object Detection Model**: The `degirum.load_model()` method loads a pre-trained YOLOv8 object detection model hosted in the DeGirum cloud. The key parameters here are:\n", + " - `model_name`: Specifies the AI model to use.\n", + " - `inference_host_address`: Indicates where inference will be performed. Setting it to `\"@cloud\"` connects the request to DeGirum’s cloud-hosted hardware, leveraging powerful compute resources without requiring local setup. For on-premise or local deployments, this value can be replaced with the IP address or hostname of the target device.\n", + " - `zoo_url`: Defines the location of the model zoo, a repository of pre-trained AI models. In this example, it is set to `'degirum/deepx'`, specifying a cloud-hosted model zoo managed by DeGirum. The `zoo_url` format typically follows `/` and can be customized for private repositories.\n", + " - `token`: Authenticates your access to the cloud-hosted resources, retrieved here using `degirum_tools.get_token()`.\n", + "\n", + "3. **Run Inference on an Image**: The model processes an example image (a URL pointing to an example image) and generates detection results.\n", + "\n", + "4. **Display the Results**: The numeric results of the inference, including detected bounding boxes and class IDs, are printed to the console. Additionally, using `degirum_tools.Display`, the inference results are visualized with object overlays on the input image.\n", + "\n", + "When you run this code, you should see hardware hosted on the cloud run an object classification model, identify detected objects, and show bounding boxes for those detected objects with only a few lines of code." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import degirum as dg, degirum_tools\n", + "\n", + "# load object detection AI model\n", + "model = dg.load_model(\n", + " model_name=\"yolov8n_coco--640x640_quant_deepx_m1a_1\",\n", + " inference_host_address=\"@cloud\",\n", + " zoo_url='degirum/deepx',\n", + " token=degirum_tools.get_token(),\n", + ")\n", + "\n", + "# perform AI model inference on given image source\n", + "inference_result = model(\"https://raw.githubusercontent.com/DeGirum/PySDKExamples/main/images/bikes.jpg\")\n", + "\n", + "# show results of inference\n", + "print(inference_result) # numeric results\n", + "with degirum_tools.Display() as display:\n", + " display.show_image(inference_result)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Unified AI Inference with DeGirum PySDK\n", + "We will now highlight the core capabilities of PySDK, showcasing its flexibility and simplicity in deploying AI models across multiple hardware platforms. By specifying the appropriate model name and model zoo, you can seamlessly run different types of models, such as classification, detection, and keypoint detection, using the same unified interface. The JSON configuration provided in the code below enables you to select the hardware you want to use for the AI task you want to perform. We assign a model zoo URL as well as the model names from the DeGirum AI Hub for each AI task. Our approach abstracts hardware-specific complexities, driving a consistent experience for diverse AI tasks. from the DeGirum AI Hub for each AI task. Our approach abstracts hardware-specific complexities, driving a consistent experience for diverse AI tasks. \n", + "\n", + "In the code below, `degirum_tools.Display`, overlays an intuitive visualization of the model's inference results on the input image. This example underscores PySDK’s design philosophy: different models, same code, unified visualization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import ipywidgets as widgets\n", + "from IPython.display import display\n", + "import degirum as dg, degirum_tools\n", + "\n", + "# Define configurations\n", + "model_configurations = {\n", + " \"DEEPX\": {\n", + " \"zoo_url\": \"degirum/deepx\",\n", + " \"model_names\": {\n", + " \"classification\": [\"mobilenetv2--224x224_quant_deepx_m1a_1\"],\n", + " \"detection\": [\"yolov8n_coco--640x640_quant_deepx_m1a_1\"],\n", + " \"keypoint_detection\": [\"yolov8n_relu6_widerface_kpts--640x640_quant_deepx_m1a_1\"]\n", + " },\n", + " },\n", + "}\n", + "\n", + "source_images = {\n", + " \"classification\": \"https://raw.githubusercontent.com/DeGirum/PySDKExamples/main/images/Cat.jpg\",\n", + " \"detection\": \"https://raw.githubusercontent.com/DeGirum/PySDKExamples/main/images/bikes.jpg\",\n", + " \"keypoint_detection\": \"https://raw.githubusercontent.com/DeGirum/PySDKExamples/main/images/Mask1.jpg\"\n", + "}\n", + "# Create widgets\n", + "\n", + "model_type_dropdown = widgets.Dropdown(\n", + " options=list(source_images.keys()),\n", + " value=\"classification\",\n", + " description=\"Model Type:\",\n", + ")\n", + "\n", + "run_button = widgets.Button(\n", + " description=\"Run Inference\",\n", + " button_style=\"success\", # Optional: 'success', 'info', 'warning', 'danger'\n", + ")\n", + "\n", + "output = widgets.Output()\n", + "\n", + "# Define the inference function\n", + "def run_inference(button_click):\n", + " with output:\n", + " output.clear_output() # Clear previous output\n", + " hardware_option = \"DEEPX\"\n", + " model_type = model_type_dropdown.value\n", + "\n", + " inference_host_address = \"@cloud\"\n", + " zoo_url = model_configurations[hardware_option][\"zoo_url\"]\n", + " model_name = model_configurations[hardware_option][\"model_names\"][model_type][0]\n", + " source_image = source_images[model_type]\n", + "\n", + " print(f\"Running inference on hardware: {hardware_option}\")\n", + " print(f\"Model type: {model_type}\")\n", + " print(f\"Model name: {model_name}\")\n", + "\n", + " # Load and run inference\n", + " model = dg.load_model(\n", + " model_name=model_name,\n", + " inference_host_address=inference_host_address,\n", + " zoo_url=zoo_url,\n", + " token=degirum_tools.get_token()\n", + " )\n", + " inference_result = model(source_image)\n", + "\n", + " print(\"Inference result:\")\n", + " print(inference_result)\n", + " with degirum_tools.Display() as display:\n", + " display.show_image(inference_result)\n", + "\n", + "# Link the Run button to the inference function\n", + "run_button.on_click(run_inference)\n", + "\n", + "# Display widgets and output\n", + "display(model_type_dropdown, run_button, output)\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Explore and Experiment with DeGirum PySDK\n", + "\n", + "This example demonstrates how to perform AI inference using PySDK with a pre-trained model hosted in the cloud. We encourage you to experiment further by trying out different **model zoos**, **model names**, and **image sources**. For instance, you can explore various AI tasks such as object detection, classification, and keypoint detection by selecting models from different model zoos (e.g., `degirum/degirum`, `degirum/google`, `degirum/intel`, etc.) and providing images of your choice. This flexibility showcases PySDK's unified API, allowing you to customize and test AI inference across multiple hardware platforms and tasks effortlessly. Dive in and discover the possibilities!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import degirum as dg, degirum_tools\n", + "\n", + "hw_location = \"@cloud\" # \"@cloud\" for cloud inference, \"@local\" for local inference, or IP address for AI server inference\n", + "model_zoo_url = \"degirum/deepx\"\n", + "model_name = \"yolov8n_coco--640x640_quant_deepx_m1a_1\"\n", + "image_source = \"https://raw.githubusercontent.com/DeGirum/PySDKExamples/main/images/Mask1.jpg\"\n", + "\n", + "# load object detection AI model\n", + "model = dg.load_model(\n", + " model_name=model_name,\n", + " inference_host_address=hw_location,\n", + " zoo_url=model_zoo_url,\n", + " token=degirum_tools.get_token()\n", + ")\n", + "\n", + "# perform AI model inference on given image source\n", + "inference_result = model(image_source)\n", + "\n", + "# show results of inference\n", + "print(inference_result) # numeric results\n", + "with degirum_tools.Display() as display:\n", + " display.show_image(inference_result)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.11" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +}