From 0a8992d261e8e220a2b6f388476b6851f5937592 Mon Sep 17 00:00:00 2001 From: Kiriti Gowda Date: Tue, 22 Aug 2023 14:40:53 -0700 Subject: [PATCH] Documentation - Sphinx DoxyFile Updates (#56) * DoxyFile Updates * Sphinx - Updates * Sphinx - Fix * Sphinx - Updates * Cleanup * rocAL - User Guide Updates * Fix - Readme * Sphinx - Build fix * Chapter 3 - Updates * Update docs/sphinx/_toc.yml.in * Documentation - updates * Fix Chapters * Readme - Updates * Fix --------- Co-authored-by: Sam Wu --- README.md | 109 +++------------ docs/README.md | 50 ++++--- docs/doxygen/.DoxygenLayout.xml | 238 ++++++++++++++++++++++++++++++++ docs/sphinx/_toc.yml.in | 26 ++-- docs/user_guide/ch1.md | 56 ++++---- docs/user_guide/ch2.md | 2 +- docs/user_guide/ch3.md | 21 +-- docs/user_guide/ch4.md | 2 +- docs/user_guide/ch5.md | 2 +- docs/user_guide/ch6.md | 2 +- docs/user_guide/index.md | 1 - 11 files changed, 345 insertions(+), 164 deletions(-) create mode 100644 docs/doxygen/.DoxygenLayout.xml delete mode 100644 docs/user_guide/index.md diff --git a/README.md b/README.md index 4550b729b..d8a208451 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

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 [docs](docs) page. +For more details, go to [rocAL user guide](docs) page. ## Documentation @@ -66,10 +66,10 @@ rocAL can be currently used to perform the following operations either with rand ## Prerequisites - * Linux distribution + Ubuntu - `20.04` / `22.04` + CentOS - `7` / `8` + + RedHat - `8` / `9` + SLES - `15-SP4` * [AMD RPP](https://github.com/GPUOpen-ProfessionalCompute-Libraries/rpp) * [AMD OpenVX™](https://github.com/GPUOpen-ProfessionalCompute-Libraries/MIVisionX/tree/master/amd_openvx) and AMD OpenVX™ Extensions: `VX_RPP` and `AMD Media` @@ -93,6 +93,9 @@ For the convenience of the developer, we here provide the setup script which wil * Linux distribution + Ubuntu - `20.04` / `22.04` + + CentOS - `7` / `8` + + RedHat - `8` / `9` + + SLES - `15-SP4` * [ROCm supported hardware](https://docs.amd.com) * [ROCm](https://docs.amd.com) @@ -114,24 +117,26 @@ For the convenience of the developer, we here provide the setup script which wil ### Using `rocAL-setup.py` -* Install [ROCm](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html) +* Install [ROCm](https://rocmdocs.amd.com/en/latest/deploy/linux/installer/install.html) + * Use the below commands to set up and build rocAL + + + Clone rocAL source code ``` git clone https://github.com/ROCmSoftwarePlatform/rocAL.git cd rocAL ``` + **Note:** rocAL supports **CPU** and two **GPU** backends: **OPENCL**/**HIP**: - **Note:** rocAL has support for two GPU backends: **OPENCL** and **HIP**: + + Building rocAL with default **HIP** backend: - + Instructions for building rocAL with the **HIP** GPU backend (i.e., default GPU backend): - - + run the setup script to install all the dependencies required by the **HIP** GPU backend: + + run the setup script to install all the dependencies required ``` python rocAL-setup.py ``` - + run the below commands to build rocAL with the **HIP** GPU backend: + + run the below commands to build rocAL ``` mkdir build-hip cd build-hip @@ -140,97 +145,27 @@ For the convenience of the developer, we here provide the setup script which wil sudo cmake --build . --target PyPackageInstall sudo make install ``` -**Note:** sudo is required to build rocAL_pybind package (only supported on HIP backend) - - + Instructions for building rocAL with **OPENCL** GPU backend: - - + run the setup script to install all the dependencies required by the **OPENCL** GPU backend: - ``` - python rocAL-setup.py --reinstall yes --backend OCL - ``` - - + run the below commands to build rocAL with the **OPENCL** GPU backend: - ``` - mkdir build-ocl - cd build-ocl - cmake -DBACKEND=OPENCL ../ - make -j8 - sudo make install - ``` + **Note:** sudo is required to build rocAL_pybind package (only supported on HIP 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 + + 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. -### Prerequisites - Manual Install - -* [AMD RPP](https://github.com/GPUOpen-ProfessionalCompute-Libraries/rpp) -* [AMD OpenVX™](https://github.com/GPUOpen-ProfessionalCompute-Libraries/MIVisionX/tree/master/amd_openvx) and AMD OpenVX™ Extensions: `VX_RPP` and `AMD Media` -* [Boost library](https://www.boost.org) - Version `1.66` or higher -* [Turbo JPEG](https://libjpeg-turbo.org/) - Version `2.0` or higher -* [Half-precision floating-point](https://half.sourceforge.net) library - Version `1.12.0` or higher -* [Google Protobuf](https://developers.google.com/protocol-buffers) - Version `3.11.1` or higher -* [LMBD Library](http://www.lmdb.tech/doc/) -* [RapidJSON](https://github.com/Tencent/rapidjson) -* [PyBind11](https://github.com/pybind/pybind11) - -#### Turbo JPEG installation - -Turbo JPEG library is a SIMD optimized library which currently rocAL uses to decode input JPEG images. It needs to be built from the source and installed in the default path for libraries and include headers. You can follow the instruction below to download the source, build and install it. -**Note:** install nasm package - -``` -sudo apt-get install nasm -``` - -**Note:** You need wget package to download the tar file. -``` - sudo apt-get install wget -``` - -``` -git clone -b 2.0.6.2 https://github.com/rrawther/libjpeg-turbo.git -cd libjpeg-turbo && mkdir build && cd build -cmake -DCMAKE_INSTALL_PREFIX=/usr \ - -DCMAKE_BUILD_TYPE=RELEASE \ - -DENABLE_STATIC=FALSE \ - -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libjpeg-turbo-2.0.3 \ - -DCMAKE_INSTALL_DEFAULT_LIBDIR=lib \ - .. -make -j$nproc && sudo make install -``` - -#### LMDB installation -``` -sudo apt-get install libgflags-dev libgoogle-glog-dev liblmdb-dev -``` - -#### RapidJSON installation -``` -git clone https://github.com/Tencent/rapidjson.git -cd rapidjson && mkdir build && cd build -cmake ../ && make -j$nproc && sudo make install -``` - -#### PyBind11 installation -``` -pip install pytest==7.3.1 -git clone -b https://github.com/pybind/pybind11 -cd pybind11 && mkdir build && cd build -cmake -DDOWNLOAD_CATCH=ON -DDOWNLOAD_EIGEN=ON ../ && make -j4 && sudo make install -``` - ## Tested Configurations * Linux distribution + Ubuntu - `20.04` / `22.04` * ROCm: rocm-core - `5.4.0.50400-72` +* RPP - [1.2.0](https://github.com/GPUOpen-ProfessionalCompute-Libraries/rpp/releases/tag/1.2.0) +* MIVisionX - [master](https://github.com/GPUOpen-ProfessionalCompute-Libraries/MIVisionX) +* Boost - [1.72.0](https://www.boost.org/users/history/version_1_72_0.html) * Protobuf - [V3.12.4](https://github.com/protocolbuffers/protobuf/releases/tag/v3.12.4) * OpenCV - [4.6.0](https://github.com/opencv/opencv/releases/tag/4.6.0) -* RPP - [1.2.0](https://github.com/GPUOpen-ProfessionalCompute-Libraries/rpp/releases/tag/1.2.0) * FFMPEG - [n4.4.2](https://github.com/FFmpeg/FFmpeg/releases/tag/n4.4.2) -* MIVisionX - [master](https://github.com/GPUOpen-ProfessionalCompute-Libraries/MIVisionX) -* Dependencies for all the above packages +* RapidJSON- [master](https://github.com/Tencent/rapidjson) +* PyBind11 - [v2.10.4](https://github.com/pybind/pybind11) +* CuPy - [master](https://github.com/ROCmSoftwarePlatform/cupy.git) * rocAL Setup Script - `V1.0.2` +* Dependencies for all the above packages diff --git a/docs/README.md b/docs/README.md index 7eb40a738..4a00c6c93 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,6 @@ -# rocAL Introduction +

+ +# rocAL User Guide Today’s deep learning applications require loading and pre-processing data efficiently to achieve high processing throughput. This requires creating efficient processing pipelines fully utilizing the underlying hardware capabilities. Some examples are load and decode data, do a variety of augmentations, color-format conversions, etc. Deep learning frameworks require supporting multiple data formats and augmentations to adapt to a variety of data-sets and models. @@ -6,6 +8,14 @@ Deep learning frameworks require supporting multiple data formats and augmentati AMD ROCm Augmentation Library (rocAL) is designed to efficiently do such processing pipelines from both images and video as well as from a variety of storage formats. These pipelines are programmable by the user using both C++ and Python APIs. +## User Guide Chapters +- [Chapter 1 - Overview](user_guide/ch1.md) +- [Chapter 2 - Architecture Components](user_guide/ch2.md) +- [Chapter 3 - Installation](user_guide/ch3.md) +- [Chapter 4 - Using with Python API](user_guide/ch4.md) +- [Chapter 5 - Framework Integration](user_guide/ch5.md) +- [Chapter 6 - Using with C++ API](user_guide/ch6.md) + ## Key Components of rocAL * Full processing pipeline support for data_loading, meta-data loading, augmentations, and data-format conversions for training and inference. @@ -16,11 +26,11 @@ These pipelines are programmable by the user using both C++ and Python APIs. ## Prerequisites -Refer to [rocAL](https://github.com/ROCmSoftwarePlatform/rocAL) to follow and install pre-requisites. +Refer [rocAL Prerequisites](https://github.com/ROCmSoftwarePlatform/rocAL#prerequisites) ## Build instructions -Follow the build instructions in [rocAL](https://github.com/ROCmSoftwarePlatform/rocAL) +Refer [rocAL build instructions](https://github.com/ROCmSoftwarePlatform/rocAL#build-instructions) ## rocAL Python @@ -38,23 +48,23 @@ Follow the build instructions in [rocAL](https://github.com/ROCmSoftwarePlatform * Contains the image augmentations & file read and decode operations which are linked to rocAL C++ API * All ops (listed below) are supported for the single input image and batched inputs. -|Image Augmentation | Reader and Decoder | Geometric Ops | -| :------------------: |:--------------------:| :-------------:| -| ColorTwist | File Reader | CropMirrorNormalize | -| Brightness | ImageDecoder | Resize | -| Gamma Correction | ImageDecoderRandomCrop | ResizeCrop | -| Snow | COCOReader | WarpAffine | -| Rain | TFRecordReader | FishEye | -| Blur | | LensCorrection | -| Jitter | | Rotate | -| Hue | | | -| Saturation | | | -| Fog | | | -| Contrast | | | -| Vignette | | | -| SNPNoise | | | -| Pixelate | | | -| Blend | | | +| Image Augmentation | Reader and Decoder | Geometric Ops | +| :----------------: | :--------------------: | :-----------------: | +| ColorTwist | File Reader | CropMirrorNormalize | +| Brightness | ImageDecoder | Resize | +| Gamma Correction | ImageDecoderRandomCrop | ResizeCrop | +| Snow | COCOReader | WarpAffine | +| Rain | TFRecordReader | FishEye | +| Blur | | LensCorrection | +| Jitter | | Rotate | +| Hue | | | +| Saturation | | | +| Fog | | | +| Contrast | | | +| Vignette | | | +| SNPNoise | | | +| Pixelate | | | +| Blend | | | ### amd.rocal.pipeline diff --git a/docs/doxygen/.DoxygenLayout.xml b/docs/doxygen/.DoxygenLayout.xml new file mode 100644 index 000000000..23af4cdc8 --- /dev/null +++ b/docs/doxygen/.DoxygenLayout.xml @@ -0,0 +1,238 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 59960be40..cbfa51912 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -2,24 +2,22 @@ # These comments will also be removed. defaults: numbered: False -root: README +root: doxygen/html/index subtrees: - caption: User Guide entries: - - file: user_guide/ch1 - subtrees: - - entries: - - file: user_guide/ch2 - - file: user_guide/ch3 - - file: user_guide/ch4 - - file: user_guide/ch5 - - file: user_guide/ch6 -- caption: API - entries: - - file: doxygen/html/index + - file: README + subtrees: + - entries: + - file: user_guide/ch1 + - file: user_guide/ch2 + - file: user_guide/ch3 + - file: user_guide/ch4 + - file: user_guide/ch5 + - file: user_guide/ch6 - caption: Examples entries: - - file: examples + - file: examples - caption: About entries: - - file: license + - file: license diff --git a/docs/user_guide/ch1.md b/docs/user_guide/ch1.md index 9bfbca831..97f08d2c7 100644 --- a/docs/user_guide/ch1.md +++ b/docs/user_guide/ch1.md @@ -1,4 +1,4 @@ -# rocAL User Guide +# Chapter 1: Overview ## 1.1 Overview @@ -41,43 +41,43 @@ rocAL operators offer the flexibility to run on CPU or GPU for building hybrid p ### Table 1. Augmentations Available through rocAL -| Color Augmentations | Effects Augmentations | Geometry Augmentations | -| ------------------- | --------------------- | ---------------------- | -| Blend | Fog | Crop | -| Blur | Jitter | Crop Mirror Normalization | -| Brightness | Pixelization | Crop Resize | -| Color Temperature | Raindrops | Fisheye Lens | -| Color Twist | Snowflakes | Flip (Horizontal, Vertical, and Both) | -| Contrast | Salt and Pepper Noise | Lens Correction | -| Exposure | | Random Crop | -| Gamma | | Resize | -| Hue | | Resize Crop Mirror | -| Saturation | | Rotation | -| Vignette | | Warp Affine | +| Color Augmentations | Effects Augmentations | Geometry Augmentations | +| ------------------- | --------------------- | ------------------------------------- | +| Blend | Fog | Crop | +| Blur | Jitter | Crop Mirror Normalization | +| Brightness | Pixelization | Crop Resize | +| Color Temperature | Raindrops | Fisheye Lens | +| Color Twist | Snowflakes | Flip (Horizontal, Vertical, and Both) | +| Contrast | Salt and Pepper Noise | Lens Correction | +| Exposure | | Random Crop | +| Gamma | | Resize | +| Hue | | Resize Crop Mirror | +| Saturation | | Rotation | +| Vignette | | Warp Affine | - Readers: These are used to read and understand the different types of datasets and their metadata. Some examples of readers are list of files with folders, LMDB, TFRecord, and JSON file for metadata. To use the readers, import the instance of amd.rocal.readers into the Python script. ### Table 2. Readers Available through rocAL -| Readers | Description | -| ------- | ----------- | -| File Reader | Reads images from a list of files in a folder(s) | -| Video Reader | Reads videos from a list of files in a folder(s) | -| Caffe LMDB Reader | Reads (key, value) pairs from Caffe LMDB | -| Caffe2 LMDB Reader | Reads (key, value) pairs from Caffe2 LMDB | -| COCO Reader – file source and keypoints | Reads images and JSON annotations from COCO dataset | -| TFRecord Reader | Reads from a TFRecord dataset | -| MXNet Reader | Reads from a RecordIO dataset | +| Readers | Description | +| --------------------------------------- | --------------------------------------------------- | +| File Reader | Reads images from a list of files in a folder(s) | +| Video Reader | Reads videos from a list of files in a folder(s) | +| Caffe LMDB Reader | Reads (key, value) pairs from Caffe LMDB | +| Caffe2 LMDB Reader | Reads (key, value) pairs from Caffe2 LMDB | +| COCO Reader – file source and keypoints | Reads images and JSON annotations from COCO dataset | +| TFRecord Reader | Reads from a TFRecord dataset | +| MXNet Reader | Reads from a RecordIO dataset | - Decoders: These are used to support different input formats of images and videos. Decoders extract data from the datasets that are in compressed formats such as JPEG, MP4, etc. To use the decoders, import the instance of amd.rocal.decoders into the Python script. ### Table 3. Decoders Available through rocAL -| Decoders | Description | -| -------- | ----------- | -| Image | Decodes JPEG images | -| Image_raw | Decodes images in raw format | +| Decoders | Description | +| ----------------- | -------------------------------------- | +| Image | Decodes JPEG images | +| Image_raw | Decodes images in raw format | | Image_random_crop | Decodes and randomly crops JPEG images | -| Image_slice | Decodes and slices JPEG images | +| Image_slice | Decodes and slices JPEG images | To see examples demonstrating the usage of decoders and readers, [click here](https://github.com/GPUOpen-ProfessionalCompute-Libraries/MIVisionX/tree/master/rocAL/rocAL_pybind/examples) diff --git a/docs/user_guide/ch2.md b/docs/user_guide/ch2.md index a92329635..e4aa6367e 100644 --- a/docs/user_guide/ch2.md +++ b/docs/user_guide/ch2.md @@ -1,4 +1,4 @@ -# rocAL Architecture Components +# Chapter 2: Architecture Components The rocAL architecture comprises rocAL Master-Graph and RPP as major components. diff --git a/docs/user_guide/ch3.md b/docs/user_guide/ch3.md index 63480a6ea..912dec236 100644 --- a/docs/user_guide/ch3.md +++ b/docs/user_guide/ch3.md @@ -1,18 +1,19 @@ -# rocAL Installation +# Chapter 3: Installation This chapter provides information about the installation of rocAL and related packages. ## 3.1 Prerequisites -- Linux Distribution -- [AMD RPP library](https://github.com/GPUOpen-ProfessionalCompute-Libraries/rpp) -- MIvisionX (AMD RPP OpenVX extension) -- Boost lib 1.66 or higher -- [Turbo JPEG](https://github.com/rrawther/libjpeg-turbo) with Partial Decoder support -- Half float library -- jsoncpp library -- Google protobuf 3.11.1 or higher -- LMDB +* Linux distribution +* [AMD RPP](https://github.com/GPUOpen-ProfessionalCompute-Libraries/rpp) +* [AMD OpenVX™](https://github.com/GPUOpen-ProfessionalCompute-Libraries/MIVisionX/tree/master/amd_openvx) and AMD OpenVX™ Extensions: `VX_RPP` and `AMD Media` +* [Boost library](https://www.boost.org) - Version `1.72` or higher +* [Turbo JPEG](https://libjpeg-turbo.org/) - Version `2.0` or higher +* [Half-precision floating-point](https://half.sourceforge.net) library - Version `1.12.0` or higher +* [Google Protobuf](https://developers.google.com/protocol-buffers) - Version `3.12.4` or higher +* [LMBD Library](http://www.lmdb.tech/doc/) +* [RapidJSON](https://github.com/Tencent/rapidjson) +* [PyBind11](https://github.com/pybind/pybind11) ## 3.2 Platform Support diff --git a/docs/user_guide/ch4.md b/docs/user_guide/ch4.md index 3b0706fcd..8aa5cdeab 100644 --- a/docs/user_guide/ch4.md +++ b/docs/user_guide/ch4.md @@ -1,4 +1,4 @@ -# Using rocAL with Python API +# Chapter 4: Using with Python API rocAL uses simple Python operators to provide high performance and flexibility by utilizing the underlying hardware capabilities in a very efficient manner. diff --git a/docs/user_guide/ch5.md b/docs/user_guide/ch5.md index a8df571ff..ebdf3845a 100644 --- a/docs/user_guide/ch5.md +++ b/docs/user_guide/ch5.md @@ -1,4 +1,4 @@ -# Framework Integration +# Chapter 5: Framework Integration rocAL improves the pipeline efficiency by preprocessing the data and parallelizing the data loading on the CPU and running trainings on the GPU. To separate the data loading from the training, rocAL provides TensorFlow and PyTorch iterators and readers as a plugin. The integration process with PyTorch and TensorFlow is described in the sections below. diff --git a/docs/user_guide/ch6.md b/docs/user_guide/ch6.md index fbf84618a..f3f481945 100644 --- a/docs/user_guide/ch6.md +++ b/docs/user_guide/ch6.md @@ -1,4 +1,4 @@ -# Using rocAL with C++ API +# Chapter 6: Using with C++ API This chapter explains how to create a pipeline and add augmentations using C++ APIs directly. The Python APIs also call these C++ APIs internally using the Python pybind utility as explained in the section Installing rocAL Python Package. diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md deleted file mode 100644 index cd3d45227..000000000 --- a/docs/user_guide/index.md +++ /dev/null @@ -1 +0,0 @@ -# User Guide