Note

The published documentation is available at MIVisionX in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the docs folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see Contribute to ROCm documentation.

MIVisionX toolkit is a set of comprehensive computer vision and machine intelligence libraries, utilities, and applications bundled into a single toolkit. AMD MIVisionX delivers highly optimized conformant open-source implementation of the Khronos OpenVX™ and OpenVX™ Extensions along with Convolution Neural Net Model Compiler & Optimizer supporting ONNX, and Khronos NNEF™ exchange formats. The toolkit allows for rapid prototyping and deployment of optimized computer vision and machine learning inference workloads on a wide range of computer hardware, including small embedded x86 CPUs, APUs, discrete GPUs, and heterogeneous servers.

Latest release

AMD OpenVX™

AMD OpenVX™ is a highly optimized conformant open source implementation of the Khronos OpenVX™ 1.3 computer vision specification. It allows for rapid prototyping as well as fast execution on a wide range of computer hardware, including small embedded x86 CPUs and large workstation discrete GPUs.

Khronos OpenVX™ 1.0.1 conformant implementation is available in MIVisionX Lite

AMD OpenVX™ Extensions

The OpenVX framework provides a mechanism to add new vision functionality to OpenVX by vendors. This project has below listed OpenVX modules and utilities to extend amd_openvx, which contains the AMD OpenVX™ Core Engine.

• amd_loomsl: AMD Loom stitching library for live 360 degree video applications
• amd_media: AMD media extension module is for encode and decode applications
• amd_migraphx: AMD MIGraphX extension integrates the AMD's MIGraphx into an OpenVX graph. This extension allows developers to combine the vision funcions in OpenVX with the MIGraphX and build an end-to-end application for inference.
• amd_nn: OpenVX neural network module
• amd_opencv: OpenVX module that implements a mechanism to access OpenCV functionality as OpenVX kernels
• amd_rpp: OpenVX extension providing an interface to some of the ROCm Performance Primitives (RPP) functions. This extension enables rocAL to perform image augmentation.
• amd_winml: AMD WinML extension will allow developers to import a pre-trained ONNX model into an OpenVX graph and add hundreds of different pre & post processing vision / generic / user-defined functions, available in OpenVX and OpenCV interop, to the input and output of the neural net model. This extension aims to help developers to build an end to end application for inference.

Applications

MIVisionX has several applications built on top of OpenVX modules. These applications can serve as excellent prototypes and samples for developers to build upon.

Neural network model compiler and optimizer

Neural net model compiler and optimizer converts pre-trained neural net models to MIVisionX runtime code for optimized inference.

rocAL

The ROCm Augmentation Library - rocAL is designed to efficiently decode and process images and videos from a variety of storage formats and modify them through a processing graph programmable by the user.

rocAL is now available as an independent module at https://github.com/ROCm/rocAL. rocAL is deprecated in MIVisionX.

Toolkit

MIVisionX Toolkit is a comprehensive set of helpful tools for neural net creation, development, training, and deployment. The Toolkit provides useful tools to design, develop, quantize, prune, retrain, and infer your neural network work in any framework. The Toolkit has been designed to help you deploy your work on any AMD or 3rd party hardware, from embedded to servers.

MIVisionX toolkit provides tools for accomplishing your tasks throughout the whole neural net life-cycle, from creating a model to deploying them for your target platforms.

Utilities

• loom_shell: an interpreter to prototype 360 degree video stitching applications using a script
• mv_deploy: consists of a model-compiler and necessary header/.cpp files which are required to run inference for a specific NeuralNet model
• RunCL: command-line utility to build, execute, and debug OpenCL programs
• RunVX: command-line utility to execute OpenVX graph described in GDF text file

Prerequisites

Hardware

• CPU: AMD64
• GPU: AMD Radeon™ Graphics [optional]
• APU: AMD Radeon™ Mobile/Embedded [optional]

Important

Some modules in MIVisionX can be built for CPU ONLY. To take advantage of Advanced Features And Modules we recommend using AMD GPUs or AMD APUs.

Operating System

Linux

• Ubuntu - 20.04 / 22.04
• CentOS - 7
• RedHat - 8 / 9
• SLES - 15-SP5

Windows

• Windows 10 / 11

macOS

• macOS - Ventura 13 / Sonoma 14

Installation instructions

Linux

The installation process uses the following steps:

• ROCm-supported hardware install verification

• Install ROCm 6.1.0 or later with amdgpu-install with --usecase=rocm

• Use either Package install or Source install as described below.

Package install

Install MIVisionX runtime, development, and test packages.

• Runtime package - mivisionx only provides the dynamic libraries and executables
• Development package - mivisionx-dev/mivisionx-devel provides the libraries, executables, header files, and samples
• Test package - mivisionx-test provides ctest to verify installation

Ubuntu

sudo apt-get install mivisionx mivisionx-dev mivisionx-test

CentOS / RedHat

sudo yum install mivisionx mivisionx-devel mivisionx-test

SLES

sudo zypper install mivisionx mivisionx-devel mivisionx-test

Important

• Package install supports HIP backend
• Package install requires OpenCV V4.6 manual install
• CentOS/RedHat/SLES requires FFMPEG Dev package manual install

Source install

Prerequisites setup script

For your convenience, we provide the setup script, MIVisionX-setup.py, which installs all required dependencies.

python MIVisionX-setup.py --directory [setup directory - optional (default:~/)]
                          --opencv    [OpenCV Version - optional (default:4.6.0)]
                          --ffmpeg    [FFMPEG Installation - optional (default:ON) [options:ON/OFF]]
                          --amd_rpp   [MIVisionX VX RPP Dependency Install - optional (default:ON) [options:ON/OFF]]
                          --neural_net[MIVisionX Neural Net Dependency Install - optional (default:ON) [options:ON/OFF]]
                          --inference [MIVisionX Inference Dependency Install - optional (default:ON) [options:ON/OFF]]
                          --developer [Setup Developer Options - optional (default:OFF) [options:ON/OFF]]
                          --reinstall [Remove previous setup and reinstall (default:OFF)[options:ON/OFF]]
                          --backend   [MIVisionX Dependency Backend - optional (default:HIP) [options:HIP/OCL/CPU]]
                          --rocm_path [ROCm Installation Path - optional (default:/opt/rocm ROCm Installation Required)]

Note

• Install ROCm before running the setup script
• This script only needs to be executed once
• ROCm upgrade requires the setup script rerun

Using MIVisionX-setup.py

• Clone MIVisionX git repository

  git clone https://github.com/ROCm/MIVisionX.git

Important

MIVisionX has support for two GPU backends: OPENCL and HIP

• Instructions for building MIVisionX with the HIP GPU backend (default backend):

  • run the setup script to install all the dependencies required by the HIP GPU backend:

  cd MIVisionX
  python MIVisionX-setup.py

  • run the below commands to build MIVisionX with the HIP GPU backend:

  mkdir build-hip
  cd build-hip
  cmake ../
  make -j8
  sudo make install

  • run tests - test option instructions

  make test

• Instructions for building MIVisionX with OPENCL GPU backend

Windows

• Windows SDK
• Visual Studio 2019 or later
• Install the latest AMD drivers
• Install OpenCL SDK
• Install OpenCV 4.6.0
  • Set OpenCV_DIR environment variable to OpenCV/build folder
  • Add %OpenCV_DIR%\x64\vc14\bin or %OpenCV_DIR%\x64\vc15\bin to your PATH

Using Visual Studio

• Use MIVisionX.sln to build for x64 platform

Important

Some modules in MIVisionX are only supported on Linux

macOS

macOS build instructions

Important

macOS only supports MIVisionX CPU backend

Verify installation

Linux / macOS

• The installer will copy
  • Executables into /opt/rocm/bin
  • Libraries into /opt/rocm/lib
  • Header files into /opt/rocm/include/mivisionx
  • Apps, & Samples folder into /opt/rocm/share/mivisionx
  • Documents folder into /opt/rocm/share/doc/mivisionx
  • Model Compiler, and Toolkit folder into /opt/rocm/libexec/mivisionx

Verify with sample application

Canny Edge Detection

export PATH=$PATH:/opt/rocm/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib
runvx /opt/rocm/share/mivisionx/samples/gdf/canny.gdf

Note

• More samples are available here
• For macOS use export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/opt/rocm/lib

Verify with mivisionx-test package

Test package will install ctest module to test MIVisionX. Follow below steps to test packge install

mkdir mivisionx-test && cd mivisionx-test
cmake /opt/rocm/share/mivisionx/test/
ctest -VV

Windows

• MIVisionX.sln builds the libraries & executables in the folder MIVisionX/x64

• Use RunVX to test the build

  ./runvx.exe ADD_PATH_TO/MIVisionX/samples/gdf/skintonedetect.gdf

Docker

MIVisionX provides developers with docker images for Ubuntu 20.04 / 22.04. Using docker images developers can quickly prototype and build applications without having to be locked into a single system setup or lose valuable time figuring out the dependencies of the underlying software.

Docker files to build MIVisionX containers and suggested workflow are available

MIVisionX docker

• Ubuntu 20.04
• Ubuntu 22.04

Documentation

Run the steps below to build documentation locally.

• sphinx documentation

cd docs
pip3 install -r sphinx/requirements.txt
python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

• Doxygen

doxygen .Doxyfile

Technical support

Please email mivisionx.support@amd.com for questions, and feedback on MIVisionX.

Please submit your feature requests, and bug reports on the GitHub issues page.

Release notes

Latest release version

Changelog

Review all notable changes with the latest release

Tested configurations

• Windows 10 / 11
• Linux distribution
  • Ubuntu - 20.04 / 22.04
  • CentOS - 7
  • RHEL - 8 / 9
  • SLES - 15-SP5
• ROCm: rocm-core - 6.3.0.60300
• RPP - 1.9.0.60300
• miopen-hip - 3.2.0.60300
• migraphx - 2.11.0.60300
• OpenCV - 4.6.0
• FFMPEG - n4.4.2
• Dependencies for all the above packages
• MIVisionX Setup Script - V3.7.0

Known issues

• Package install OpenCV manual install
• Package install in RHEL/SLES/CentOS requires manual FFMPEG Dev install

MIVisionX dependency map

HIP Backend

Docker Image: sudo docker build -f docker/ubuntu20/{DOCKER_LEVEL_FILE_NAME}.dockerfile -t {mivisionx-level-NUMBER} .

• new component added to the level
• existing component from the previous level

Build Level	MIVisionX Dependencies	Modules	Libraries and Executables	Docker Tag
Level_1	cmake gcc g++	amd_openvx utilities	libopenvx.so - OpenVX™ Lib - CPU libvxu.so - OpenVX™ immediate node Lib - CPU runvx - OpenVX™ Graph Executor - CPU with Display OFF
Level_2	ROCm HIP +Level 1	amd_openvx amd_openvx_extensions utilities	libopenvx.so - OpenVX™ Lib - CPU/GPU libvxu.so - OpenVX™ immediate node Lib - CPU/GPU runvx - OpenVX™ Graph Executor - Display OFF
Level_3	OpenCV FFMPEG +Level 2	amd_openvx amd_openvx_extensions utilities	libopenvx.so - OpenVX™ Lib libvxu.so - OpenVX™ immediate node Lib libvx_amd_media.so - OpenVX™ Media Extension libvx_opencv.so - OpenVX™ OpenCV InterOp Extension mv_compile - Neural Net Model Compile runvx - OpenVX™ Graph Executor - Display ON
Level_4	MIOpen MIGraphX ProtoBuf +Level 3	amd_openvx amd_openvx_extensions apps utilities	libopenvx.so - OpenVX™ Lib libvxu.so - OpenVX™ immediate node Lib libvx_amd_media.so - OpenVX™ Media Extension libvx_opencv.so - OpenVX™ OpenCV InterOp Extension mv_compile - Neural Net Model Compile runvx - OpenVX™ Graph Executor - Display ON libvx_nn.so - OpenVX™ Neural Net Extension
Level_5	AMD_RPP RPP deps +Level 4	amd_openvx amd_openvx_extensions apps AMD VX RPP utilities	libopenvx.so - OpenVX™ Lib libvxu.so - OpenVX™ immediate node Lib libvx_amd_media.so - OpenVX™ Media Extension libvx_opencv.so - OpenVX™ OpenCV InterOp Extension mv_compile - Neural Net Model Compile runvx - OpenVX™ Graph Executor - Display ON libvx_nn.so - OpenVX™ Neural Net Extension libvx_rpp.so - OpenVX™ RPP Extension

Important

OpenVX and the OpenVX logo are trademarks of the Khronos Group Inc.