Introduction and sample apps to showcase oneML functionalities and possible use cases.

• oneML-bootcamp
  • Overview
    • Supported platforms
    • What is oneML?
    • What can you do with this repository?
  • Features
    • Face applications
    • Vehicle applications
  • Getting Started
    • For Linux users
      • Step 1: Build a docker image
      • Step 2: Build sample applications
      • Step 3: Run sample applications
    • For Windows users
      • Step 0: Install required tools
      • Step 1: Build sample applications
      • Step 2: Run sample applications
  • Setup and Build
    • Linux
      • Docker build
      • Apps build
    • Windows
      • Requirements
      • Dependencies
      • Apps build
    • CUDA
  • API Reference
  • Usage
  • Roadmap

oneML is a fully-fledged C SDK providing APIs for a number of different AI/ML applications. Potentially, it can be deployed on any target (CPU, GPU, CUDA) and platform (Android, iOS, embedded Linux, Linux, Windows). Morveover, oneML library provides API bindings in other programming languages such as Java, Python, C# and Golang.

This repository provides oneML library (community edition) and its example applications in 4 programming languages: C , Java, Python, C# and Golang (for Linux only). In case of Android development, you can use oneML's Java bindings. Please feel free to open an issue on GitHub if you found any issue.

In this community edition, oneML library provides APIs for 2 main applications: face and vehicle AI applications.

• Face detector
• Face embedding
• EKYC
• Face 1-1 verification
• Face identification

• Vehicle detector

This section describes steps for quickly testing oneML library. We will download oneML library and models. Then, we build and run sample C applications on x86_64 architecture. There are 2 separated guidelines for Linux and Windows users.

NOTE: For other languages and architectures, please refer to Setup and Build section.

We recommend to set up an environment for oneML with a docker container. A docker image can be built from Dockerfile in docker folder. Here, we are going to build a base image and another image for CPU runtime. Run the below command to build the image.

docker build -t oneml-bootcamp:cpu-base -f docker/Dockerfile --build-arg base_image=ubuntu:20.04 .
docker build -t oneml-bootcamp:cpu -f docker/Dockerfile.cpu --build-arg base_image=oneml-bootcamp:cpu-base .

We will run a docker container with oneml-bootcamp:cpu image that we built in the previous step, and mount this repository folder to the container at /workspace path. We execute bash inside the container to run the next following steps.

docker run -it --name oneml-bootcamp -v $PWD:/workspace oneml-bootcamp:cpu /bin/bash -c "cd /workspace && /bin/bash"   

Then, inside the container, we download oneML library and models, and build sample C applications with build.sh script.

./build.sh -t x86_64 -cc --clean

The oneML library and models are downloaded to assets/binaries/x86_64.

assets/binaries/x86_64
├── bindings
├── config.yaml
├── include
├── lib
├── oneml-bootcamp-x86_64.tar.gz
├── README.md
└── share

The compiled C applications are in bin folder.

bin
├── ekyc
├── face_detector
├── face_embedder
├── face_id
├── face_verification
└── vehicle_detector

We will run face detector and vehicle detector application. Our sample applications run oneML models with images in assets/images folder. Change the directory to bin folder.

cd bin

To run the face detector application, simply run this command.

$ ./face_detector 
Faces: 1
Face 0
Score: 0.997635
Pose: Front
BBox: [(43.740112, 85.169624), (170.153168, 173.094971)]
Landmark 0: (109.936066, 95.690453)
Landmark 1: (149.844360, 94.360649)
Landmark 2: (130.055618, 117.397400)
Landmark 3: (112.128708, 137.498520)
Landmark 4: (146.398651, 136.513870)

To run the vehicle detector application, simply run this command.

$ ./vehicle_detector 
Vehicles: 8
Vehicle 0
Score: 0.907127
BBox[top=302.584076,left=404.385437,bottom=486.317841,right=599.864502]
Vehicle 1
Score: 0.899688
BBox[top=301.987000,left=651.770996,bottom=432.352997,right=920.848637]
Vehicle 2
Score: 0.875428
BBox[top=314.573608,left=143.590546,bottom=445.937286,right=367.556488]
Vehicle 3
Score: 0.873904
BBox[top=237.489685,left=100.689484,bottom=303.421906,right=279.191864]
Vehicle 4
Score: 0.842179
BBox[top=243.125473,left=328.062103,bottom=307.927338,right=473.017853]
Vehicle 5
Score: 0.822146
BBox[top=238.680069,left=563.760925,bottom=308.430756,right=705.746033]
Vehicle 6
Score: 0.653955
BBox[top=215.012100,left=477.994904,bottom=252.589249,right=547.705505]
Vehicle 7
Score: 0.620528
BBox[top=213.333237,left=641.528503,bottom=249.301697,right=742.615601]

To build oneML C applications on Windows, we need to install these tools as follows:

• Microsoft Visual Studio 16 2019 or newer
• CMake 3.17 or newer

We will download oneML library and models, and build sample C applications with build.bat script.

.\build.bat -t msvc-x64 -cc --clean

The oneML library and models are downloaded to assets\binaries\msvc-x64.

assets\binaries\msvc-x64
├── bindings
├── config.yaml
├── include
├── lib
├── oneml-bootcamp-msvc-x64.tar.gz
├── README.md
└── share

The compiled C applications are in bin\Release folder.

bin\Release
├── ekyc.exe
├── face_detector.exe
├── face_embedder.exe
├── face_id.exe
├── face_verification.exe
└── vehicle_detector.exe

We will run face detector and vehicle detector application. Our sample applications run oneML models with images in assets\images folder. Change the directory to bin\Release folder.

cd bin\Release

To run the face detector application, simply run this command.

.\face_detector.exe 

Result

Faces: 1
Face 0
Score: 0.997635
Pose: Front
BBox: [(43.740120, 85.169617), (170.153168, 173.094971)]
Landmark 0: (109.936081, 95.690453)
Landmark 1: (149.844376, 94.360649)
Landmark 2: (130.055634, 117.397392)
Landmark 3: (112.128716, 137.498520)
Landmark 4: (146.398636, 136.513870)

To run the vehicle detector application, simply run this command.

.\vehicle_detector.exe

Output

Vehicles: 8
Vehicle 0
Score: 0.907128
BBox[top=302.583893,left=404.385590,bottom=486.317871,right=599.864380]
Vehicle 1
Score: 0.899688
BBox[top=301.986755,left=651.771118,bottom=432.352966,right=920.846069]
Vehicle 2
Score: 0.875427
BBox[top=314.573425,left=143.590775,bottom=445.937408,right=367.556946]
Vehicle 3
Score: 0.873901
BBox[top=237.489792,left=100.689354,bottom=303.421936,right=279.191772]
Vehicle 4
Score: 0.842178
BBox[top=243.125641,left=328.062012,bottom=307.927002,right=473.017883]
Vehicle 5
Score: 0.822146
BBox[top=238.680267,left=563.760864,bottom=308.430756,right=705.746338]
Vehicle 6
Score: 0.653957
BBox[top=215.012009,left=477.994873,bottom=252.589355,right=547.705811]
Vehicle 7
Score: 0.620529
BBox[top=213.333160,left=641.528442,bottom=249.301712,right=742.615662]

Depending on your OS and on which programming language you would like to use, the setup and build process is going to be slightly different. Please refer to the respective section below.

On Linux machines, it is always advised to used docker to create a reproducible workspace and not have to worry about dependencies. If you don't want to use docker, feel free to setup your local environment to match the one provided in our Dockerfiles.

There are multiple Dockerfiles available based on the HW to be targeted for the deployment as well as if the device requires specific build tools or dependencies.

There are two different types of docker images:

• base docker images are supposed to provide all the common tools and libraries shared by all the other, more specific, images built on top of them
• device/OS-specific, e.g. cpu, gpu, android

For a normal CPU environment:

docker build -t oneml-bootcamp:cpu-base -f docker/Dockerfile --build-arg base_image=ubuntu:20.04 .
docker build -t oneml-bootcamp:cpu -f docker/Dockerfile.cpu --build-arg base_image=oneml-bootcamp:cpu-base .

For a GPU environment:

docker build -t oneml-bootcamp:gpu-base -f docker/Dockerfile --build-arg base_image=nvidia/cuda:11.5.1-cudnn8-runtime-ubuntu20.04 .
docker build -t oneml-bootcamp:gpu -f docker/Dockerfile.gpu --build-arg base_image=oneml-bootcamp:gpu-base .

For an Android environment:

docker build -t oneml-bootcamp:cpu-base -f docker/Dockerfile --build-arg base_image=ubuntu:20.04 .
docker build -t oneml-bootcamp:android -f docker/Dockerfile.android --build-arg base_image=oneml-bootcamp:cpu-base .

We provide a bash script that will setup the project, prepare the environment and build all the artifacts necessary to run the sample applications.

./build.sh --help

will provide with the description of the build script. Here are some examples:

To build C apps for x86_64 target:

./build.sh -t x86_64 -cc --clean

To build Python apps for aarch64-linux-gnu target:

./build.sh -t aarch64-linux-gnu -py --clean

To build C# apps for x86_64 target:

./build.sh -t x86_64 -cs --clean

To build Java apps for x86_64 target:

./build.sh -t x86_64 -jni --clean

To build Android apps for aarch64-linux-android target:

./build.sh -t aarch64-linux-android -jni --clean

On x86_64, CUDA-capable GPU is also supported. To build C apps for x86-64-cuda target:

./build.sh -t x86_64-cuda -cc --clean

If --clean is not specified, the existing oneML artifacts will be used and the old build files will not be deleted.

We provide support for our library and sample applications for Windows OS as well.

Unfortunately, there is no easy way to use our Dockerfiles in this environment, thus the user has to rely on their own local environment and make sure all the dependencies are installed before proceeding with the build process and run the applications.

• Only Windows 10 64 bit is currently supported.
• Windows users are required to set an environment variable to configure the trust store for SSL certificates. More here.

@powershell -NoProfile -ExecutionPolicy unrestricted -Command ^
    (new-object System.Net.WebClient).Downloadfile( ^
        'https://pki.google.com/roots.pem', 'roots.pem')
set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=�%\roots.pem

The following dependencies must be installed in order for the project to build and run successfully:

• Microsoft Visual Studio 16 2019 or newer
• curl to pull some data from the internet
• tar to unpack some archives
• CMake 3.17 or newer (for C build only)
• Python 3.6 or newer and pip (for Python build only)
• .NET6 (for C# build only)
• JDK 1.8 (for Java build only)
• Android Studio xxx (for Android build only)
• Golang 1.15 (for Golang build only)
• Powershell, a recent version (for any build, but C )

We provide a batch script that will setup the project, prepare the environment and build all the artifacts necessary to run the sample applications.

build.bat --help

will provide with the description of the build script. Here are some examples:

To build C apps for msvc-x64 target:

build.bat -t msvc-x64 -cc --clean

To build Python apps for msvc-x64 target:

build.bat -t msvc-x64 -py --clean

To build C# apps for msvc-x64 target:

build.bat -t msvc-x64 -cs --clean

To build Java apps for msvc-x64 target:

build.bat -t msvc-x64 -jni --clean

If --clean is not specified, the existing oneML artifacts will be used and the old build files will not be deleted.

Currently x86-64-cuda target supports only CUDA 11.x runtime on Linux only. We also plan to support CUDA 10.2 in the future. Moreover, it is built with backward compatibility in mind. x86-64-cuda supports the following CUDA compute capabilities

• 7.5
• 7.0
• 6.1
• 6.0
• 5.2
• 5.0

For compute capabilities later than 7.5, it might not work.

• C /Java/Python/C# APIs
• Golang APIs

It is possible to find more details about the usage in each programming language specific folder in apps folder. You can click on the following links:

• C apps
• Python apps
• C# apps
• Java apps
• Golang apps

For all the applications, it is possible to set the LOG level of oneML by settings ONEML_CPP_MIN_LOG_LEVEL environment variable to one of the following values:

• INFO, to log all the information
• WARNING, to log only warnings and more critical information
• ERROR, to log only errors and fatal crashes
• FATAL, to only log fatal crashes

• Support iOS
• Support CUDA 10.2
• Support Golang on Windows