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-SP4
ROCm supported hardware
Install ROCm with amdgpu-install with --usecase=graphics,rocm --no-32
RPP
AMD OpenVX™ and AMD OpenVX™ Extensions: VX_RPP and AMD Media - MIVisionX Components
Turbo JPEG - Version 2.0.6.2 from https://github.com/rrawther/libjpeg-turbo.git
Half-precision floating-point library - Version 1.12.0 or higher
Google Protobuf - Version 3.12.4 or higher
LMBD Library
RapidJSON
PyBind11
HIP
OpenMP
C++17

Build and install instructions

ROCm supported hardware
Install ROCm with amdgpu-install with --usecase=graphics,rocm --no-32

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

On `Ubuntu`

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

On `CentOS`/`RedHat`

sudo yum install rocal rocal-devel rocal-test

On `SLES`

sudo zypper install rocal rocal-devel rocal-test

Note:

Package install requires Turbo JPEG, PyBind 11 v2.10.4 and Protobuf V3.12.4 manual install
CentOS/RedHat/SLES requires FFMPEG Dev package manual install

Source build and install

Prerequisites setup script for Linux - rocAL-setup.py

For the convenience of the developer, we here provide the setup script which will install all the dependencies required by this project.

NOTE: This script only needs to be executed once.

Prerequisites for running the script

Linux distribution
- Ubuntu - 20.04 / 22.04
- CentOS - 7
- RedHat - 8 / 9
- SLES - 15-SP4
ROCm supported hardware
Install ROCm with amdgpu-install with --usecase=graphics,rocm --no-32

usage:

python rocAL-setup.py       --directory [setup directory - optional (default:~/)]
                            --opencv    [OpenCV Version - optional (default:4.6.0)]
                            --protobuf  [ProtoBuf Version - optional (default:3.12.4)]
                            --pybind11  [PyBind11 Version - optional (default:v2.10.4)]
                            --reinstall [Remove previous setup and reinstall (default:OFF)[options:ON/OFF]]
                            --backend   [rocAL Dependency Backend - optional (default:HIP) [options:OCL/HIP]]
                            --rocm_path [ROCm Installation Path - optional (default:/opt/rocm) - ROCm Installation Required]

Note:

ROCm upgrade requires the setup script rerun.

Using rocAL-setup.py

Clone rocAL source code

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

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

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
- run tests - test option instructions
  make test
Note:
- PyPackageInstall used for rocal_pybind installation
- sudo required for pybind installation
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
- 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 packge install

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

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 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-SP4
ROCm: rocm-core - 5.7.0.50700-6
RPP - rpp & rpp-dev/rpp-devel
MIVisionX - mivisionx & mivisionx-dev/mivisionx-devel
Protobuf - V3.12.4
OpenCV - 4.6.0
FFMPEG - n4.4.2
RapidJSON- master
PyBind11 - v2.10.4
rocAL Setup Script - V1.1.0
Dependencies for all the above packages