rocAL

rocAL#

rocAL: Main Page

The AMD 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 currently provides C API. For more details, go to [rocAL user guide](docs) page.

Supported Operations

rocAL can be currently used to perform the following operations either with randomized or fixed parameters:

Blend	Blur (Gaussian 3x3)	Brightness	Color Temperature
ColorTwist	Contrast	Crop	Crop Mirror Normalization
CropResize	Exposure Modification	Fisheye Lens	Flip (Horizontal, Vertical and Both)
Fog	Gamma	Hue	Jitter
Lens Correction	Pixelization	Raindrops	Random Crop
Resize	Resize Crop Mirror	Rotation	Salt And Pepper Noise
Saturation	Snowflakes	Vignette	Warp Affine

Prerequisites

Linux distribution
- Ubuntu - 20.04 / 22.04
- CentOS - 7
- RedHat - 8 / 9
- SLES - 15-SP5
ROCm-supported hardware

[!IMPORTANT] gfx908 or higher GPU required
Install ROCm 6.1.0 or later with amdgpu-install: Required usecase - rocm

[!IMPORTANT] sudo amdgpu-install --usecase=rocm
HIP
sudo apt install rocm-hip-runtime-dev
RPP
sudo apt install rpp-dev
MIVisionX Components: AMD OpenVX™ and AMD OpenVX™ Extensions: VX_RPP and AMD Media
sudo apt install mivisionx-dev
rocDecode
sudo apt install rocdecode-dev
Half-precision floating-point library - Version 1.12.0 or higher
sudo apt install half
Google Protobuf - Version 3.12.4 or higher
sudo apt install libprotobuf-dev
LMBD Library
sudo apt install liblmdb-dev
Python3 and Python3 PIP
sudo apt install python3-dev python3-pip
Python Wheel
pip3 install wheel
PyBind11
- Source: https://github.com/pybind/pybind11
- Tag: v2.11.1
Turbo JPEG
- Source: https://github.com/libjpeg-turbo/libjpeg-turbo.git
- Tag: 3.0.2
RapidJSON
- Source: https://github.com/Tencent/rapidjson.git
- Tag: master
Optional: FFMPEG
sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
Optional: OpenCV
sudo apt install libopencv-dev

[!IMPORTANT]

Compiler features required

OpenMP

C++17

>[!NOTE]

* All package installs are shown with the apt package manager. Use the appropriate package manager for your operating system.

Prerequisites setup script

For your convenience, we provide the setup script,rocAL-setup.py, which installs all required dependencies. Run this script only once.

python rocAL-setup.py --directory [setup directory - optional (default:~/)]
                      --rocm_path [ROCm Installation Path - optional (default:/opt/rocm)]
                      --backend   [rocAL Dependency Backend - optional (default:HIP) [options:OCL/HIP]]
                      --ffmpeg    [FFMPEG Installation - optional (default:OFF)[options:ON/OFF]]
                      --reinstall [Reinstall - optional (default:OFF)[options:ON/OFF]]

Installation instructions

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

>[!IMPORTANT]

Use either package install or source install as described below.

Package install

Install rocAL runtime, development, and test packages.

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

<tt>Ubuntu</tt>

sudo apt-get install rocal rocal-dev rocal-test

<tt>CentOS</tt>/<tt>RedHat</tt>

sudo yum install rocal rocal-devel rocal-test

<tt>SLES</tt>

sudo zypper install rocal rocal-devel rocal-test

>[!IMPORTANT]

* Package install requires TurboJPEG, and RapidJSON manual install

CentOS/RedHat/SLES requires additional FFMPEG Dev package manual install

rocAL Python module: To use python module, you can set PYTHONPATH:

export PYTHONPATH=/opt/rocm/lib:$PYTHONPATH

Source install

To build rocAL from source and install, follow the steps below:

Clone rocAL source code

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

>[!NOTE]

rocAL has support for two GPU backends: OPENCL and HIP:

HIP Backend

Instructions for building rocAL with the HIP GPU backend (default GPU backend):
- run the setup script to install all the dependencies required by the HIP GPU backend:
  cd rocAL
  
  python rocAL-setup.py
- run the below commands to build rocAL with the HIP GPU backend:
  mkdir build-hip
  
  cd build-hip
  
  cmake ../
  
  make -j8
  
  sudo cmake --build . --target PyPackageInstall
  
  sudo make install
  
  >[!NOTE]
  
  * PyPackageInstall used for rocal_pybind installation

>[!IMPORTANT]

* Use -D PYTHON_VERSION_SUGGESTED=3.x with cmake for using a specific Python3 version if required.

Use -D AUDIO_SUPPORT=ON to enable Audio features, Audio support will be enabled by default with ROCm versions > 6.2

run tests - test option instructions
make test

>[!NOTE]

To run tests with verbose option, use make test ARGS="-VV".

OpenCL Backend

Instructions for building rocAL with OPENCL GPU backend

>[!NOTE]

+ rocAL_pybind is not supported on OPENCL backend

rocAL cannot be installed for both GPU backends in the same default folder (i.e., /opt/rocm/)

if an app interested in installing rocAL with both GPU backends, then add -DCMAKE_INSTALL_PREFIX in the cmake commands to install rocAL with OPENCL and HIP backends into two separate custom folders.

Verify installation

The installer will copy
- Executables into /opt/rocm/bin
- Libraries into /opt/rocm/lib
- rocal_pybind into /opt/rocm/lib
- Header files into /opt/rocm/include/rocal
- Apps, & Samples folder into /opt/rocm/share/rocal
- Documents folder into /opt/rocm/share/doc/rocal

Verify with rocal-test package

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

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

>[!NOTE]

* Make sure all rocAL required libraries are in your PATH

RHEL/SLES - Export FFMPEG libraries into your PATH

export LD_LIBRARY_PATH=/usr/local/lib:/usr/local/lib64/:/usr/local/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
export PATH=$PATH:/opt/rocm/bin

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib

Verify rocAL PyBind with rocal-test package

Test package will install ctest module to test rocAL PyBindings. Follow below steps to test package install

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

>[!NOTE]

* Make sure all rocAL required libraries are in your PATH
export PATH=$PATH:/opt/rocm/bin

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib

export PYTHONPATH=/opt/rocm/lib:$PYTHONPATH

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 [email protected] for questions, and feedback on rocAL.

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

Linux distribution
- Ubuntu - 20.04 / 22.04
- CentOS - 7
- RedHat - 8 / 9
- SLES - 15-SP5
ROCm: rocm-core - 6.1.0.60100-64
RPP - rpp & rpp-dev/rpp-devel
MIVisionX - mivisionx & mivisionx-dev/mivisionx-devel
Protobuf - libprotobuf-dev/protobuf-devel
RapidJSON - https://github.com/Tencent/rapidjson
Turbo JPEG - Version 3.0.2
PyBind11 - v2.11.1
FFMPEG - ffmpeg dev package
OpenCV - libopencv-dev / 4.6.0
libsndfile - 1.0.31
rocAL Setup Script - V2.6.0
Dependencies for all the above packages