Getting Started#

Installation#

We strongly recommend using a virtual environment. If you’re not sure where to start, we offer a tutorial here.

Installing Ikomia API#

Install Ikomia API

pip install ikomia

Warning

We only support Python 3.7, 3.8, 3.9 and 3.10 on Windows 10 and Linux.

Pre-requisites#

Open your favorite IDE (PyCharm, VS Code…) and create a new project in your virtual environment.
Then, you can just copy/paste the different examples below.

Important

If you use a notebook (Jupyter, Jupyter Lab or Google Colab), please copy/paste this code snippet for a better display of images.

from PIL import ImageShow
ImageShow.register(ImageShow.IPythonViewer(), 0)

Basic usage : workflow with 1 algorithm#

In this example, we simply use the Canny Edge Detector from OpenCV.

Workflow Structure#

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#CC5A20', 'lineColor': '#CC5A20' } } }%% graph LR A[(Input images)] -.-> B(ocv_canny) B -.-> C[(Output images)]

Code#

Create and run your 1st workflow.

from ikomia.dataprocess.workflow import Workflow
from ikomia.utils.displayIO import display

# Init your workflow
wf = Workflow()

# Add the Canny Edge Detector
canny = wf.add_task(name="ocv_canny", auto_connect=True)

# Run on your image    
# wf.run_on(path="path/to/your/image.png")
wf.run_on(url="https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg")


# Inspect your results
display(canny.get_input(0).get_image())
display(canny.get_output(0).get_image())

For a step by step explanation, see here.

Results#

Source image	Canny Edge Detector

Basic usage : workflow with 1 algorithm from Ikomia HUB#

In this example, we use an algorithm from Ikomia HUB.
Just run your workflow and at runtime, it will automagically download and install all algorithms (if not already installed) on your machine.

Workflow Structure#

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#CC5A20', 'lineColor': '#CC5A20' } } }%% graph LR A[(Input images)] -.-> B(infer_yolo_v7) B -.-> C[(Output images)]

Code#

Create and run your workflow.

from ikomia.dataprocess.workflow import Workflow
from ikomia.utils.displayIO import display

# Init your workflow
wf = Workflow()    

# Add the YOLO v7 Object Detector
yolov7 = wf.add_task(name="infer_yolo_v7", auto_connect=True)

# Run on your image  
# wf.run_on(path="path/to/your/image.png")
wf.run_on(url="https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg")

# Inspect your results
display(yolov7.get_input(0).get_image())
display(yolov7.get_image_with_graphics())

For a step by step explanation, see here.

Results#

Source image	YOLO v7 Object Detector

Advanced usage : workflow with 1 algorithm + custom settings#

Workflow Structure#

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#CC5A20', 'lineColor': '#CC5A20' } } }%% graph LR A[(Input images)] -.-> B(ocv_canny) B -.-> C[(Output images)]

Code#

Adjust the algorithm parameters with our ik auto-completion mechanism …

from ikomia.dataprocess.workflow import Workflow
from ikomia.utils.displayIO import display
from ikomia.utils import ik

# Init your workflow
wf = Workflow()

# Add the Canny Edge Detector with specific parameters
canny = wf.add_task(ik.ocv_canny(threshold1="100", threshold2="200"), auto_connect=True)

# Run on your image  
# wf.run_on(path="path/to/your/image.png")
wf.run_on(url="https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg")

# Inspect your results
display(canny.get_input(0).get_image())
display(canny.get_output(0).get_image())

… or use a classic Dict approach

from ikomia.dataprocess.workflow import Workflow
from ikomia.utils.displayIO import display

# Init your workflow
wf = Workflow()

# Add the Canny Edge Detector
canny = wf.add_task(name="ocv_canny", auto_connect=True)

# Change Canny parameters
canny.set_parameters({ 
    "threshold1": "100",
    "threshold2": "200"
}) 

# Run on your image  
# wf.run_on(path="path/to/your/image.png")
wf.run_on(url="https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg")

# Inspect your results
display(canny.get_input(0).get_image())
display(canny.get_output(0).get_image())

For a step by step explanation, see here.

Results#

Source image	Canny Edge Detector

Advanced usage : workflow with 2 algorithms + custom settings#

Workflow Structure#

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#CC5A20', 'lineColor': '#CC5A20' } } }%% graph LR A[(Input images)] -.-> B(infer_face_detection_kornia) B --> C(ocv_blur) C -.-> D[(Output images)]

Code#

from ikomia.dataprocess.workflow import Workflow
from ikomia.utils.displayIO import display
from ikomia.utils import ik

# Init your workflow
wf = Workflow()

# Add the Kornia Face Detector
face = wf.add_task(ik.infer_face_detection_kornia(), auto_connect=True) 

# Add a blur effect
blur = wf.add_task(ik.ocv_blur(kSizeWidth="61", kSizeHeight="61"), auto_connect=True)

# Run on your image  
# wf.run_on(path="path/to/your/image.png")
wf.run_on(url="https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_people.jpg")

# Inspect your results
display(face.get_image_with_graphics())
display(blur.get_output(0).get_image())

Results#

Kornia Face Detector	Blurred faces

Advanced usage : export results to JSON#

Code#

Create and run your workflow.

from ikomia.dataprocess.workflow import Workflow
from ikomia.utils import ik

# Init your workflow
wf = Workflow()    

# Add the YOLO v7 Object Detector
yolov7 = wf.add_task(ik.infer_yolo_v7(), auto_connect=True)

# Run on your image
# wf.run_on(path="path/to/your/image.png")
wf.run_on(url="https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg")

# Get results as JSON
results_json = yolov7.get_results().to_json(["json_format", "indented"])
print(results_json)

For a step by step explanation, see here.

Results#

{
    "detections": [
        {
            "box": {
                "height": 235.06271362304688,
                "width": 286.51531982421875,
                "x": 853.1284790039062,
                "y": 374.7386779785156
            },
            "color": {
                "a": 9,
                "b": 50,
                "g": 99,
                "r": 232
            },
            "confidence": 0.9322412014007568,
            "id": 0,
            "label": "laptop"
        }
    ]
}

Advanced usage : export workflow to JSON#

Code#

Create and export your workflow as JSON.

from ikomia.dataprocess.workflow import Workflow
from ikomia.utils import ik

# Init your workflow
wf = Workflow("My workflow")        

# Add the YOLO v7 Object Detector
yolov7 = wf.add_task(ik.infer_yolo_v7(), auto_connect=True)

# Save your workflow as JSON in the current folder or specify a path
# wf.save("/path/to/my_workflow.json")
wf.save("./my_workflow.json")

Then just load and run your workflow.

from ikomia.dataprocess import workflow
from ikomia.utils import ik
from ikomia.utils.displayIO import display

# Load your workflow from the current folder or specify a path
# wf = workflow.load("/path/to/my_workflow.json")
wf = workflow.load("./my_workflow.json")

# Run on your image
# wf.run_on(path="path/to/your/image.png")
wf.run_on(url="https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg")

# Find all tasks with the name 'infer_yolo_v7' in the workflow
# and store them in a list
# yolov7_list = wf.find_task("infer_yolo_v7")
yolov7_list = wf.find_task(ik.infer_yolo_v7.name())
yolov7 = yolov7_list[0]

# Inspect your results
display(yolov7.get_input(0).get_image())
display(yolov7.get_image_with_graphics())

For a step by step explanation, see here.

Results#

Source image	YOLO v7 Object Detector

Conclusion#

Congratulations! You’ve reached the end of the quickstart guide. You should now have a good understanding of how to use Ikomia API to create, customize and run workflows with various algorithms. Feel free to explore more features and create your own amazing workflows!