feat: adding code for release v0.9.0

Author: bhaefnerNV

.github/workflows/codeql.yml

@@ -48,7 +48,7 @@ jobs:
       run: |
         sudo apt update -y && sudo apt install -y --no-install-recommends \
         python3 python3-pip python3-dev python3-distutils doxygen && sudo rm -rf /var/lib/apt/lists/* \
-        && python3 -m pip install sphinx-rtd-theme sphinx breathe exhale recommonmark graphviz \
+        && python3 -m pip install sphinx-rtd-theme sphinx breathe recommonmark graphviz \
         && python3 -m pip install numpy==1.24.1 patchelf==0.17.2.1
 
     - if: matrix.language == 'c-cpp'
@@ -92,7 +92,7 @@ jobs:
     - if: matrix.language == 'c-cpp' && github.event_name == 'push'
       name: Build Docs and Clean up Sphinx Build Directory
       run: |
-        ./ci/build.sh debug build "-DBUILD_SAMPLES=OFF -DBUILD_TESTS=OFF -DBUILD_DOCS=ON -DBUILD_PYTHON=ON" $*
+        ./ci/build.sh debug build "-DBUILD_SAMPLES=OFF -DBUILD_TESTS=OFF -DBUILD_DOCS=ON -DBUILD_PYTHON=ON -DPYTHON_VERSIONS=3.8" $*
         find build/docs/sphinx -name '*.doctree' -delete
         find build/docs/sphinx -name '*.map' -delete
         find build/docs/sphinx -name '*.pickle' -delete

.gitignore

@@ -17,6 +17,7 @@
 # ----------------
 /build/
 /build-*/
+/build_*/
 /install/
 /cvcuda-installer*/
 
@@ -47,7 +48,8 @@ ipython_config.py
 
 # Documentation
 # -------------
-_exhale_api
+_c_cpp_api
+_cvcuda_api
 
 # Samples
 # -------------

CMakeLists.txt

@@ -23,7 +23,7 @@ endif()
 
 project(cvcuda
         LANGUAGES C CXX
-        VERSION 0.8.0
+        VERSION 0.9.0
         DESCRIPTION "CUDA-accelerated Computer Vision algorithms"
 )
 

README.md

@@ -18,13 +18,13 @@
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-yellogreen.svg)](https://opensource.org/licenses/Apache-2.0)
 
-![Version](https://img.shields.io/badge/Version-v0.8.0--beta-blue)
+![Version](https://img.shields.io/badge/Version-v0.9.0--beta-blue)
 
 ![Platform](https://img.shields.io/badge/Platform-linux--64_%7C_win--64_wsl2%7C_aarch64-gray)
 
 [![CUDA](https://img.shields.io/badge/CUDA-v11.7-%2376B900?logo=nvidia)](https://developer.nvidia.com/cuda-toolkit-archive)
 [![GCC](https://img.shields.io/badge/GCC-v11.0-yellow)](https://gcc.gnu.org/gcc-11/changes.html)
-[![Python](https://img.shields.io/badge/python-v3.7_%7c_v3.8_%7c_v3.9_%7c_v3.10%7c_v3.11-blue?logo=python)](https://www.python.org/)
+[![Python](https://img.shields.io/badge/python-v3.8_%7c_v3.9_%7c_v3.10%7c_v3.11-blue?logo=python)](https://www.python.org/)
 [![CMake](https://img.shields.io/badge/CMake-v3.20-%23008FBA?logo=cmake)](https://cmake.org/)
 
 CV-CUDA is an open-source project that enables building efficient cloud-scale
@@ -53,13 +53,16 @@ To get a local copy up and running follow these steps.
 \** full build, including test module <br>
 \*** [samples][CV-CUDA Samples] require driver r535 or later to run and are only officially supported with CUDA 12.
 
-### Known limitations
+### Known limitations and issues
 
 - For GCC versions lower than 11.0, C++17 support needs to be enabled when compiling CV-CUDA.
 - The C++ test module cannot build with gcc<11 (requires specific C++-20 features).  With gcc-9 or gcc-10, please build with option `-DBUILD_TESTS=0`
 - [CV-CUDA Samples] require driver r535 or later to run and are only officially supported with CUDA 12.
 - Only one CUDA version (CUDA 11.x or CUDA 12.x) of CV-CUDA packages (Debian packages, tarballs, Python Wheels) can be installed at a time. Please uninstall all packages from a given CUDA version before installing packages from a different version.
-- Documentation built with older toolchains (doxygen, sphinx, breathe, exhale) may be incomplete. We recommend using Ubuntu 22.04 or later.
+- Documentation built on Ubuntu 20.04 needs an up-to-date version of sphinx (`pip install --upgrade sphinx`) as well as explicitly parsing the system's default python version ` ./ci/build_docs path/to/build -DPYTHON_VERSIONS="<py_ver>"`.
+- Python tests fail with numpy 2.0. We recommend using an older version (eg 1.26) until we have implemented a fix.
+- Python bindings installed via Debian packages fail with numpy 2.0. We recommend using an older version (eg 1.26) until we have implemented a fix.
+- The Resize and RandomResizedCrop operators incorrectly interpolate pixel values near the boundary of an image or tensor when using linear and cubic interpolation. This will be fixed in an upcoming release.
 
 ### Installation
 
@@ -87,12 +90,12 @@ Please note that the Python wheels are standalone, they include both the C++/CUD
 
 Install C++/CUDA libraries (cvcuda-lib*) and development headers (cvcuda-dev*) using `apt`:
 ```shell
-apt install -y ./cvcuda-lib-<x.x.x>-<cu_ver>-<arch>-linux.deb ./cvcuda-dev-<x.x.x>-<cu_ver>-<arch>-linux.deb
+sudo apt install -y ./cvcuda-lib-<x.x.x>-<cu_ver>-<arch>-linux.deb ./cvcuda-dev-<x.x.x>-<cu_ver>-<arch>-linux.deb
 ```
 
 Install Python bindings (cvcuda-python*) using `apt`:
 ```shell
-apt install -y ./cvcuda-python<py_ver>-<x.x.x>-<cu_ver>-<arch>-linux.deb
+sudo apt install -y ./cvcuda-python<py_ver>-<x.x.x>-<cu_ver>-<arch>-linux.deb
 ```
 where `<cu_ver>` is the desired CUDA version, `<py_ver>` is the desired Python version and `<arch>` is the desired architecture.
 
@@ -122,7 +125,7 @@ Install the dependencies needed to setup up the repository:
 
 On Ubuntu >= 20.04, install the following packages using `apt`:
 ```shell
-apt install -y git git-lfs
+sudo apt install -y git git-lfs
 ```
 
 Clone the repository
@@ -145,19 +148,20 @@ Install the dependencies required to build CV-CUDA:
 - python3-dev: for python bindings
 - libssl-dev: needed by the testsuite (MD5 hashing utilities)
 - CUDA toolkit
+- patchelf
 
 On Ubuntu >= 20.04, install the following packages using `apt`:
 ```shell
-apt install -y g++-11 cmake ninja-build python3-dev libssl-dev
+sudo apt install -y g++-11 cmake ninja-build python3-dev libssl-dev patchelf
 ```
 
 Any version of the 11.x or 12.x CUDA toolkit should work.
 CV-CUDA was tested with 11.7 and 12.2, these versions are thus recommended.
 
 ```shell
-apt install -y cuda-11-7
+sudo apt install -y cuda-11-7
 # or
-apt install -y cuda-12-2
+sudo apt install -y cuda-12-2
 ```
 
 Build the project:
@@ -175,18 +179,18 @@ ci/build.sh [release|debug] [output build tree path] [-DBUILD_TESTS=1|0] [-DPYTH
 
 #### 3. Build Documentation
 
-Known limitation: documentation built with older toolchains (doxygen, sphinx, breathe, exhale) may be incomplete. We recommend using Ubuntu 22.04 or later.
+Known limitation: Documentation built on Ubuntu 20.04 needs an up-to-date version of sphinx (`pip install --upgrade sphinx`) as well as explicitly parsing the system's default python version ` ./ci/build_docs path/to/build -DPYTHON_VERSIONS="<py_ver>"`.
 
 Install the dependencies required to  build the documentation:
 - doxygen: parse header files for reference documentation
 - python3, python3-pip: to install some python packages needed
-- sphinx, breathe, exhale, recommonmark, graphiviz: to render the documentation
+- sphinx, breathe, recommonmark, graphiviz: to render the documentation
 - sphinx-rtd-theme: documentation theme used
 
 On Ubuntu, install the following packages using `apt` and `pip`:
 ```shell
-apt install -y doxygen graphviz python3 python3-pip sphinx
-python3 -m pip install breathe exhale recommonmark graphviz sphinx-rtd-theme
+sudo apt install -y doxygen graphviz python3 python3-pip sphinx
+python3 -m pip install breathe recommonmark graphviz sphinx-rtd-theme
 ```
 
 Build the documentation:
@@ -204,11 +208,12 @@ For instructions on how to build samples from source and run them, see the [Samp
 Install the dependencies required for running the tests:
 - python3, python3-pip: to run python bindings tests
 - torch: dependencies needed by python bindings tests
+- numpy: known limitation: Python tests fail with numpy 2.0. We recommend using an older version (eg 1.26) until we have implemented a fix.
 
 On Ubuntu >= 20.04, install the following packages using `apt` and `pip`:
 ```shell
-apt install -y python3 python3-pip
-python3 -m pip install pytest torch
+sudo apt install -y python3 python3-pip
+python3 -m pip install pytest torch numpy==1.26
 ```
 
 The tests are in `<buildtree>/bin`. You can run the script below to run all tests at once. Here's an example when build tree is created in `build-rel`:

docs/CMakeLists.txt

@@ -38,39 +38,44 @@ file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
 list(GET PYTHON_VERSIONS -1 VER)
 
 add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
-                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
-                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
-                   COMMENT "Generating doxygen xml"
-	   	   DEPENDS cvcuda_python${VER})
+                    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                    MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+                    COMMENT "Generating doxygen xml"
+	   	    DEPENDS cvcuda_python${VER})
 
 add_custom_target(cvcuda_doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
 
 set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/sphinx)
-set(EXHALE_SOURCE ${SPHINX_SOURCE}/_exhale_api)
 set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
 set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
-set(SPHINX_GROUP_INDEX_FILE ${SPHINX_BUILD}/groupindex.html)
+set(C_CPP_API_RST ${SPHINX_SOURCE}/_c_cpp_api)
+set(PY_CVCUDA_API_RST ${SPHINX_SOURCE}/_python_api/_cvcuda_api)
+
+# Start from clean directory for rst files, otherwise build could be affected due to old files
+file(REMOVE_RECURSE ${C_CPP_API_RST}/*)
+file(REMOVE_RECURSE ${PY_CVCUDA_API_RST}/*)
 
 # Generate rst files for groups from doxygen index.xml
-add_custom_target(cvcuda_groups ALL
-	COMMAND python3 ${SPHINX_SOURCE}/generate_groups.py ${EXHALE_SOURCE} ${DOXYGEN_OUTPUT_DIR}/xml
-		  DEPENDS ${DOXYGEN_INDEX_FILE})
+add_custom_target(cvcuda_groups ALL python3 ${SPHINX_SOURCE}/generate_groups.py ${C_CPP_API_RST} ${DOXYGEN_OUTPUT_DIR}/xml
+		            DEPENDS cvcuda_doxygen)
+
+# Generate rst files for python documentation
+add_custom_target(cvcuda_python_docs ALL python3 ${SPHINX_SOURCE}/gen_py_doc_rsts.py ${PY_CVCUDA_API_RST} ${CMAKE_SOURCE_DIR}
+                        DEPENDS cvcuda_python${VER})
 
 # Generate Sphinx
 add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
-                   COMMAND
-		   ${CMAKE_COMMAND} -E env "SPHINX_PYTHON_SRC=${CMAKE_BINARY_DIR}/lib/python" "DOXYGEN_STRIP_PATH=${CMAKE_CURRENT_SOURCE_DIR}/../src"
-                   ${SPHINX_EXECUTABLE} -j auto -b html
-                   # Tell Breathe where to find the Doxygen output
-                   -Dbreathe_projects.cvcuda=${DOXYGEN_OUTPUT_DIR}/xml
-                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
-                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-                   DEPENDS
-		   ${SPHINX_SOURCE}/index.rst
-                   ${DOXYGEN_INDEX_FILE}
-		   cvcuda_groups
-                   MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
-                   COMMENT "Generating documentation with Sphinx")
+                    COMMAND ${CMAKE_COMMAND} -E env "SPHINX_PYTHON_SRC=${CMAKE_BINARY_DIR}/lib/python"
+                            ${SPHINX_EXECUTABLE} -j auto -b html
+                            # Tell Breathe where to find the Doxygen's xml output. Needed to have c/cpp documentation.
+                            -Dbreathe_projects.cvcuda=${DOXYGEN_OUTPUT_DIR}/xml
+                            ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                    DEPENDS ${SPHINX_SOURCE}/index.rst
+                            cvcuda_doxygen
+		            cvcuda_groups
+                    MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+                    COMMENT "Generating documentation with Sphinx")
 
 add_custom_target(cvcuda_sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
 

docs/Doxyfile.in

@@ -748,22 +748,22 @@ QUIET                  = NO
 # Tip: Turn warnings on while writing the documentation.
 # The default value is: YES.
 
-WARNINGS               = YES
+WARNINGS               = NO
 
 # If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
 # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters
 # in a documented function, or documenting parameters that don't exist or using
 # markup commands wrongly.
 # The default value is: YES.
 
-WARN_IF_DOC_ERROR      = YES
+WARN_IF_DOC_ERROR      = NO
 
 # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
 # are documented, but have no documentation for their parameters or return
@@ -2419,7 +2419,7 @@ PLANTUML_INCLUDE_PATH  =
 # Minimum value: 0, maximum value: 10000, default value: 50.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_GRAPH_MAX_NODES    = 50
+DOT_GRAPH_MAX_NODES    = 128
 
 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
 # generated by dot. A depth value of 3 means that only nodes reachable from the

docs/sphinx/_python_api/nvcv/cache.rst

@@ -0,0 +1,22 @@
+..
+  # SPDX-FileCopyrightText: Copyright (c) 2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  # SPDX-License-Identifier: Apache-2.0
+  #
+  # Licensed under the Apache License, Version 2.0 (the "License");
+  # you may not use this file except in compliance with the License.
+  # You may obtain a copy of the License at
+  #
+  # http://www.apache.org/licenses/LICENSE-2.0
+  #
+  # Unless required by applicable law or agreed to in writing, software
+  # distributed under the License is distributed on an "AS IS" BASIS,
+  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  # See the License for the specific language governing permissions and
+  # limitations under the License.
+
+Cache
+=====
+
+.. automodule:: nvcv
+  :noindex:
+  :members: cache_size, clear_cache

docs/sphinx/_python_api/nvcv/colorspec.rst

@@ -0,0 +1,22 @@
+..
+  # SPDX-FileCopyrightText: Copyright (c) 2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  # SPDX-License-Identifier: Apache-2.0
+  #
+  # Licensed under the Apache License, Version 2.0 (the "License");
+  # you may not use this file except in compliance with the License.
+  # You may obtain a copy of the License at
+  #
+  # http://www.apache.org/licenses/LICENSE-2.0
+  #
+  # Unless required by applicable law or agreed to in writing, software
+  # distributed under the License is distributed on an "AS IS" BASIS,
+  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  # See the License for the specific language governing permissions and
+  # limitations under the License.
+
+Color Models
+============
+
+.. automodule:: nvcv
+  :noindex:
+  :members: ColorSpec

docs/sphinx/_python_api/nvcv/format.rst

@@ -0,0 +1,22 @@
+..
+  # SPDX-FileCopyrightText: Copyright (c) 2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  # SPDX-License-Identifier: Apache-2.0
+  #
+  # Licensed under the Apache License, Version 2.0 (the "License");
+  # you may not use this file except in compliance with the License.
+  # You may obtain a copy of the License at
+  #
+  # http://www.apache.org/licenses/LICENSE-2.0
+  #
+  # Unless required by applicable law or agreed to in writing, software
+  # distributed under the License is distributed on an "AS IS" BASIS,
+  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  # See the License for the specific language governing permissions and
+  # limitations under the License.
+
+Image Formats
+=============
+
+.. automodule:: nvcv
+  :noindex:
+  :members: Format

docs/sphinx/_python_api/nvcv/image.rst

@@ -0,0 +1,22 @@
+..
+  # SPDX-FileCopyrightText: Copyright (c) 2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  # SPDX-License-Identifier: Apache-2.0
+  #
+  # Licensed under the Apache License, Version 2.0 (the "License");
+  # you may not use this file except in compliance with the License.
+  # You may obtain a copy of the License at
+  #
+  # http://www.apache.org/licenses/LICENSE-2.0
+  #
+  # Unless required by applicable law or agreed to in writing, software
+  # distributed under the License is distributed on an "AS IS" BASIS,
+  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  # See the License for the specific language governing permissions and
+  # limitations under the License.
+
+Image
+=====
+
+.. automodule:: nvcv
+  :noindex:
+  :members: Image, as_image

docs/sphinx/_python_api/nvcv/imagebatch.rst

@@ -0,0 +1,22 @@
+..
+  # SPDX-FileCopyrightText: Copyright (c) 2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  # SPDX-License-Identifier: Apache-2.0
+  #
+  # Licensed under the Apache License, Version 2.0 (the "License");
+  # you may not use this file except in compliance with the License.
+  # You may obtain a copy of the License at
+  #
+  # http://www.apache.org/licenses/LICENSE-2.0
+  #
+  # Unless required by applicable law or agreed to in writing, software
+  # distributed under the License is distributed on an "AS IS" BASIS,
+  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  # See the License for the specific language governing permissions and
+  # limitations under the License.
+
+ImageBatchVarShape
+==================
+
+.. automodule:: nvcv
+  :noindex:
+  :members: ImageBatchVarShape, as_images