Torizon 4.0.0

Introduction

Through Torizon, Toradex provides Debian Docker images with support for packages that greatly ease the development process for several embedded computing applications, including computer vision.

In this article, we will show how you can quickly build an application with OpenCV using Python for NXP's i.MX SoC, such as i.MX8, i.MX8X or i.MX8MM. For those who don't know, OpenCV is the most popular open-source computer vision library.

This article complies to the Typographic Conventions for Torizon Documentation.

Prerequisites

• A arm64v8 based Toradex's SoM (Apalis iMX8, Apalis iMX8X, Colibri iMX8X or Verdin iMX8M Mini)

• TorizonCore installed on the SoM (To get instructions about how to install TorizonCore, see Quickstart Guide selecting Torizon as your Target Device OS)

• Basic knowledge of Docker containers. To learn more about Docker, visit the Docker Overview. To understand the first steps with Docker usage and TorizonCore, follow the Toradex Quickstart Guide for Torizon as Target Device OS.

• Having a monitor or display connected to the SoM.

• A Dockerhub Account

Note: Apalis iMX8X is phased out, and it is not available for purchase anymore. The latest supported BSP and TorizonCore version is 5.4.0.

About this Sample Project

This example uses the cv2 to access OpenCV libraries using Python3. It runs a slightly modified version of the sample extracted from the official OpenCV-Python tutorial.

In this project, we implemented the code in the main.py file. Keep this code in mind, we'll come back to it later. It loads the image from this file, which is locally stored and then exhibits it in a window in grayscale mode for 20 seconds:

 main.py
import numpy as np
import cv2
 
# Load an color image in grayscale
img = cv2.imread('106926-verdin-imx8mm-front-view.jpg',cv2.IMREAD_GRAYSCALE)
cv2.imshow('image',img)
cv2.waitKey(20000) # Time in miliseconds
cv2.destroyAllWindows()

• 

  The OpenCV example loading an image in grayscale mode

You can modify the example for other color modes (like cv2.IMREAD_COLOR or cv2.IMREAD_UNCHANGED)

For the Impatient: Running the Sample Project in Torizon Without Building It

If you only want to see the sample project in action, in your board terminal, download the specific docker-compose file and run the containers:

# wget https://github.com/toradex/torizon-samples/raw/master/opencv/docker-compose.yaml
# docker-compose -f docker-compose.yaml up

Modifying and Building the Project from Source

Getting the Source Code of the Torizon Samples

Now, going down into the details, we will explore the demonstration example available on the Toradex samples repository.

To obtain the files, clone the torizon-samples repository to your computer:

$ cd ~
$ git clone https://github.com/toradex/torizon-samples.git

Build the Sample Project

First, in your PC terminal, build the sample project:

Note: Use your Dockerhub credentials

$ cd torizon-samples/opencv
$ docker build -t <your-dockerhub-username>/opencv-example .

After the build, push the image to your Dockerhub account:

$ docker push <your-dockerhub-username>/opencv-example

Modify the Docker-compose

After building the Dockerfile image above and pushing it to your Dockerhub, you need to edit the docker-compose file.

Edit the image field of the example with your image repository (replace the torizonextras username):

Note: Use your Dockerhub credentials

 docker-compose.yaml
  depends_on:
      - weston
    image: your-dockerhub-username/opencv-example
    volumes:

After editing, save and send this file to your module using scp:

$ scp docker-compose.yaml torizon@<your-ip>:/home/torizon

Run the Sample Project

Now enter your module's terminal using SSH:

$ ssh torizon@<target-ip>

Note: For more information about SSH, please refer to SSH on Linux.

Now you can launch the sample application by using the command:

# docker-compose -f docker-compose.yaml up

Implementation Details

The Docker Compose (yaml) file

This file configures the application's services. It informs the Docker runtime which containers the system will run, set privileges, among other options.

This example will run a Python3 script that uses the imshow method from OpenCV to display a picture. This method uses Wayland and Weston as a backend.

Therefore, this docker-compose file will start two containers:

• One with the Weston image (Wayland compositor).
• One with the application image (Wayland client). This container is the one that will execute our Python Script with the OpenCV library.

Both containers will communicate through shared folders by bind mounting.

Toradex supports Wayland protocol through its Debian Containers for Torizon.

The Dockerfile

In this section, you will go through some relevant snippets containing information about the Dockerfile, which describes the container itself.

Toradex Debian image - Wayland

Toradex provides a basic Wayland image in its Dockerhub page. To use with an arm64v8 computer-on-module (COM), add torizon/arm64v8-debian-wayland-base-vivante to your image.

FROM torizon/arm64v8-debian-wayland-base-vivante

OpenCV libraries

The following Dockerfile command lines shows an example on how to setup the required packages to install the OpenCV library:

##### INSTALL OPENCV #####
RUN apt-get update && apt-get install -y libopencv4.2-java libopencv4.2-jni \
    libopencv-calib3d4.2 libopencv-calib3d-dev libopencv-contrib4.2 \
    libopencv-contrib-dev libopencv-core4.2 libopencv-core-dev libopencv-dev \
    libopencv-dnn4.2 libopencv-dnn-dev libopencv-features2d4.2 \
    libopencv-features2d-dev libopencv-flann4.2 libopencv-flann-dev \
    libopencv-gapi4.2 libopencv-gapi-dev \
    libopencv-highgui4.2 libopencv-highgui-dev libopencv-imgcodecs4.2 \
    libopencv-imgcodecs-dev libopencv-imgproc4.2 libopencv-imgproc-dev \
    libopencv-ml4.2 libopencv-ml-dev libopencv-objdetect4.2 \
    libopencv-objdetect-dev libopencv-photo4.2 libopencv-photo-dev \
    libopencv-shape4.2 libopencv-shape-dev libopencv-stitching4.2 \
    libopencv-stitching-dev libopencv-superres4.2 libopencv-superres-dev \
    libopencv-video4.2 libopencv-video-dev libopencv-videoio4.2 \
    libopencv-videoio-dev libopencv-videostab4.2 libopencv-videostab-dev \
    libopencv-viz4.2 libopencv-viz-dev opencv-data opencv-doc python3-opencv \
    && apt-get clean && apt-get autoremove

If there are dependencies no longer needed, the last Dockerfile command lines will clear them.

The last line of the dockerfile execute the Python3 script as entrypoint:

ENTRYPOINT python3 opencv-example.py

Additional Considerations

• You can use the cv2.VideoCapture function from cv2 to capture frames from video inputs, such as an external camera connected to the MIPI interface or even USB.
• OpenCV provides modules for Machine Learning and Neural Networks. These modules target Arm Cortex-A cores and utilize Arm Neon to process models. However, until this moment, these modules are not accelerated by GPU. You can use other inference engines in conjunction with OpenCV to increase AI processing performance. See other AI solutions that Toradex offers through it network of partners.
• if you need OpenCV for Armv7 (32-bit), please contact us.