[!NOTE] The published documentation is available at rocAL 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.

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 page.

Supported Operations

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

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

Prerequisites

Operating Systems

Linux distribution
- Ubuntu - 22.04 / 24.04
- RedHat - 8 / 9
- SLES - 15 SP7

Hardware

CPU: AMD64
GPU: AMD Radeon™ Graphics / AMD Instinct™ Accelerators

[!IMPORTANT]

ROCm-supported hardware required for HIP backend

gfx908 or higher GPU required

Install ROCm 6.4.0 or later with amdgpu-install: Required usecase:rocm

[!IMPORTANT] sudo amdgpu-install --usecase=rocm

Compiler

AMD Clang++ Version 18.0.0 or later - installed with ROCm

Libraries

CMake Version 3.10 or later
```
sudo apt install cmake
```
HIP
```
sudo apt install hip-dev
```
MIVisionX Components: AMD OpenVX™ and AMD OpenVX™ Extensions: VX_RPP and AMD Media
```
sudo apt install mivisionx-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
```
TurboJPEG - Version 2.0 or higher
```
sudo apt install libturbojpeg0-dev
```
[!NOTE] If TurboJPEG >= 2.0 is not available to install via your distribution's repository, it must be manually installed. Source: libjpeg-turbo.

Python3 and Python3 PIP

sudo apt install python3-dev python3-pip

Python3 Wheel
```
sudo apt install python3-wheel
```
rocDecode - Optional for source install, but required for package install
```
sudo apt install rocdecode-dev
```
rocJPEG - Optional for source install, but required for package install
```
sudo apt install rocjpeg-dev
```

FFMPEG - Optional for source install, but required for package install

sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev

OpenCV - Optional for source install, but required for package install
```
sudo apt install libopencv-dev
```
PyBind11 - Manual install
- Source: https://github.com/pybind/pybind11
- Tag: v2.11.1
RapidJSON - Manual install
- Source: https://github.com/Tencent/rapidjson.git
- Tag: master

[!IMPORTANT]

Required compiler support

C++17

OpenMP

Threads

On Ubuntu 22.04 - Additional package required: libstdc++-12-dev
sudo apt install libstdc++-12-dev

[!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]]
                      --reinstall [Reinstall - optional (default:OFF)[options:ON/OFF]]

Installation instructions

The installation process uses the following steps:

ROCm-supported hardware install verification
Install ROCm 7.0.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

`Ubuntu`

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

`CentOS`/`RedHat`

sudo yum install rocal rocal-devel rocal-test

`SLES`

sudo zypper install rocal rocal-devel rocal-test

[!IMPORTANT]
SLES package install requires TurboJPEG manual install
git clone -b 3.0.2 https://github.com/libjpeg-turbo/libjpeg-turbo.git
mkdir tj-build && cd tj-build
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=RELEASE -DENABLE_STATIC=FALSE -DCMAKE_INSTALL_DEFAULT_LIBDIR=lib -DWITH_JPEG8=TRUE ../libjpeg-turbo/
make -j8 && sudo make 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

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 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

RocAL

Install / Use

README

Supported Operations

Prerequisites

Operating Systems

Hardware

Compiler

Libraries

Prerequisites setup script

Installation instructions

Package install

`Ubuntu`

`CentOS`/`RedHat`

`SLES`

Source install

HIP Backend

OpenCL Backend

Verify installation

Verify with rocal-test package

RocAL

Install / Use

README

Supported Operations

Prerequisites

Operating Systems

Hardware

Compiler

Libraries

Prerequisites setup script

Installation instructions

Package install

Ubuntu

CentOS/RedHat

SLES

Source install

HIP Backend

OpenCL Backend

Verify installation

Verify with rocal-test package

`Ubuntu`

`CentOS`/`RedHat`

`SLES`