rocAL

rocAL#

rocAL: Main Page
rocAL Documentation

MIT licensed

[!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](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

Operating Systems

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

Hardware

[!IMPORTANT]

  • 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
  • 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
  • Turbo JPEG
    sudo apt install libturbojpeg0-dev
  • 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
  • RapidJSON - Manual install

[!IMPORTANT]

  • Required compiler support
    • C++17
    • OpenMP
    • Threads
  • On Ubuntu 22.04 - Additional package required: libstdc++-12-dev
    sudo apt install libstdc++-12-dev
    `````
    </blockquote>
    >[!NOTE]
    <blockquote>* All package installs are shown with the `apt` package manager. Use the appropriate package manager for your operating system.
    </blockquote>
    ### Prerequisites setup script
    For your convenience, we provide the setup script,[rocAL-setup.py](https://github.com/ROCm/rocAL/blob/develop/rocAL-setup.py), which installs all required dependencies. Run this script only once.
    @code{shell}
    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:

>[!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`
</blockquote>
### Source install
To build rocAL from source and install, follow the steps below:
* Clone rocAL source code
@code{shell}
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

>[!NOTE]

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

#### OpenCL 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 ```shell 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

GitHub tag (latest SemVer)

Changelog

Review all notable changes with the latest release

Tested Configurations

  • Linux distribution
    • Ubuntu - 22.04 / 24.04
    • RedHat - 8 / 9
    • SLES - 15-SP5
  • ROCm: rocm-core - 7.0.0+
  • MIVisionX - mivisionx-dev/mivisionx-devel
  • rocDecode - rocdecode-dev/rocdecode-devel
  • rocJPEG - rocjpeg-dev/rocjpeg-devel
  • Protobuf - libprotobuf-dev/protobuf-devel
  • TurboJPEG - libturbojpeg0-dev/turbojpeg-devel
  • RapidJSON - https://github.com/Tencent/rapidjson
  • PyBind11 - v2.11.1
  • FFMPEG - ffmpeg dev package
  • OpenCV - libopencv-dev / 4.6.0
  • libsndfile - 1.0.31
  • Libtar - v1.2.20
  • rocAL Setup Script - V4.1.0
  • Dependencies for all the above packages