Cleanup C++ model example and cmake CI job (#8411)

Author: NicolasHug

.github/scripts/cmake.sh

@@ -46,16 +46,10 @@ fi
 echo '::group::Prepare CMake builds'
 mkdir -p cpp_build
 
-pushd test/tracing/frcnn
-python trace_model.py
+pushd examples/cpp
+python script_model.py
 mkdir -p build
-mv fasterrcnn_resnet50_fpn.pt build
-popd
-
-pushd examples/cpp/hello_world
-python trace_model.py
-mkdir -p build
-mv resnet18.pt build
+mv resnet18.pt fasterrcnn_resnet50_fpn.pt build
 popd
 
 # This was only needed for the tracing above
@@ -65,6 +59,7 @@ echo '::endgroup::'
 echo '::group::Build and install libtorchvision'
 pushd cpp_build
 
+
 # On macOS, CMake is looking for the library (*.dylib) and the header (*.h) separately. By default, it prefers to load
 # the header from other packages that install the library. This easily leads to a mismatch if the library installed
 # from conda doesn't have the exact same version. Thus, we need to explicitly set CMAKE_FIND_FRAMEWORK=NEVER to force
@@ -85,40 +80,24 @@ fi
 popd
 echo '::endgroup::'
 
-echo '::group::Build and run project that uses Faster-RCNN'
-pushd test/tracing/frcnn/build
-
-cmake .. -DTorch_DIR="${Torch_DIR}" -DWITH_CUDA="${WITH_CUDA}" \
-  -DCMAKE_PREFIX_PATH="${CONDA_PREFIX}" \
-  -DCMAKE_FIND_FRAMEWORK=NEVER
-if [[ $OS_TYPE == windows ]]; then
-  "${PACKAGING_DIR}/windows/internal/vc_env_helper.bat" "${PACKAGING_DIR}/windows/internal/build_frcnn.bat" $JOBS
-  cd Release
-  cp ../fasterrcnn_resnet50_fpn.pt .
-else
-  make -j$JOBS
-fi
-
-./test_frcnn_tracing
-
-popd
-echo '::endgroup::'
-
 echo '::group::Build and run C++ example'
-pushd examples/cpp/hello_world/build
+pushd examples/cpp/build
 
 cmake .. -DTorch_DIR="${Torch_DIR}" \
   -DCMAKE_PREFIX_PATH="${CONDA_PREFIX}" \
-  -DCMAKE_FIND_FRAMEWORK=NEVER
+  -DCMAKE_FIND_FRAMEWORK=NEVER \
+  -DUSE_TORCHVISION=ON  # Needed for faster-rcnn since it's using torchvision ops like NMS.
 if [[ $OS_TYPE == windows ]]; then
   "${PACKAGING_DIR}/windows/internal/vc_env_helper.bat" "${PACKAGING_DIR}/windows/internal/build_cpp_example.bat" $JOBS
   cd Release
   cp ../resnet18.pt .
+  cp ../fasterrcnn_resnet50_fpn.pt .
 else
   make -j$JOBS
 fi
 
-./hello-world
+./run_model resnet18.pt
+./run_model fasterrcnn_resnet50_fpn.pt
 
 popd
 echo '::endgroup::'

README.md

@@ -74,40 +74,14 @@ python setup.py install
 
 # Using the models on C++
 
-TorchVision provides an example project for how to use the models on C++ using JIT Script.
-
-Installation From source:
-
-```
-mkdir build
-cd build
-# Add -DWITH_CUDA=on support for the CUDA if needed
-cmake ..
-make
-make install
-```
-
-Once installed, the library can be accessed in cmake (after properly configuring `CMAKE_PREFIX_PATH`) via the
-`TorchVision::TorchVision` target:
-
-```
-find_package(TorchVision REQUIRED)
-target_link_libraries(my-target PUBLIC TorchVision::TorchVision)
-```
-
-The `TorchVision` package will also automatically look for the `Torch` package and add it as a dependency to
-`my-target`, so make sure that it is also available to cmake via the `CMAKE_PREFIX_PATH`.
-
-For an example setup, take a look at `examples/cpp/hello_world`.
-
-Python linking is disabled by default when compiling TorchVision with CMake, this allows you to run models without any
-Python dependency. In some special cases where TorchVision's operators are used from Python code, you may need to link
-to Python. This can be done by passing `-DUSE_PYTHON=on` to CMake.
-
-### TorchVision Operators
-
-In order to get the torchvision operators registered with torch (eg. for the JIT), all you need to do is to ensure that
-you `#include <torchvision/vision.h>` in your project.
+Refer to [example/cpp](https://github.com/pytorch/vision/tree/main/examples/cpp).
+
+**DISCLAIMER**: the `libtorchvision` library includes the torchvision
+custom ops as well as most of the C++ torchvision APIs. Those APIs do not come
+with any backward-compatibility guarantees and may change from one version to
+the next. Only the Python APIs are stable and with backward-compatibility
+guarantees. So, if you need stability within a C++ environment, your best bet is
+to export the Python APIs via torchscript.
 
 ## Documentation
 

examples/cpp/CMakeLists.txt

@@ -0,0 +1,18 @@
+cmake_minimum_required(VERSION 3.10)
+project(run_model)
+
+option(USE_TORCHVISION "Whether to link to torchvision" OFF)
+
+find_package(Torch REQUIRED)
+if(USE_TORCHVISION)
+  find_package(TorchVision REQUIRED)
+endif()
+
+add_executable(run_model run_model.cpp)
+
+target_link_libraries(run_model "${TORCH_LIBRARIES}")
+if(USE_TORCHVISION)
+  target_link_libraries(run_model TorchVision::TorchVision)
+endif()
+
+set_property(TARGET run_model PROPERTY CXX_STANDARD 17)

examples/cpp/README.rst

@@ -0,0 +1,104 @@
+Using torchvision models in C++
+===============================
+
+This is a minimal example of getting TorchVision models to work in C++ with
+Torchscript. The model is first scripted in Python and exported to a file, and
+then loaded in C++. For a similar tutorial, see [this
+tutorial](https://pytorch.org/tutorials/advanced/cpp_export.html).
+
+In order to successfully compile this example, make sure you have ``LibTorch``
+installed. You can either:
+
+- Install PyTorch normally
+- Or download the LibTorch C++ distribution.
+
+In both cases refer [here](https://pytorch.org/get-started/locally/) the
+corresponding install or download instructions.
+
+Some torchvision models only depend on PyTorch operators, and can be used in C++
+without depending on the torchvision lib. Other models rely on torchvision's C++
+operators like NMS, RoiAlign (typically the detection models) and those need to
+be linked against the torchvision lib.
+
+We'll first see the simpler case of running a model without the torchvision lib
+dependency.
+
+Running a model that doesn't need torchvision lib
+-------------------------------------------------
+
+Create a ``build`` directory inside the current one.
+
+```bash
+mkdir build
+cd build
+```
+
+Then run `python ../trace_model.py` which should create a `resnet18.pt` file in
+the build directory. This is the scripted model that will be used in the C++
+code.
+
+We can now start building with CMake. We have to tell CMake where it can find
+the necessary PyTorch resources. If you installed PyTorch normally, you can do:
+
+```bash
+TORCH_PATH=$(python -c "import pathlib, torch; print(pathlib.Path(torch.__path__[0]))")
+Torch_DIR="${TORCH_PATH}/share/cmake/Torch"   # there should be .cmake files in there
+
+cmake .. -DTorch_DIR=$Torch_DIR
+```
+
+If instead you downloaded the LibTorch somewhere, you can do:
+
+```bash
+cmake .. -DCMAKE_PREFIX_PATH=/path/to/libtorch
+```
+
+Then `cmake --build .` and you should now be able to run
+
+```bash
+./run_model resnet18.pt
+```
+
+If you try to run the model with a model that depends on the torchvision lib, like
+`./run_model fasterrcnn_resnet50_fpn.pt`, you should get a runtime error. This is
+because the executable wasn't linked against the torchvision lib.
+
+
+Running a model that needs torchvision lib
+------------------------------------------
+
+First, we need to build the torchvision lib. To build the torchvision lib go to
+the root of the torchvision project and run:
+
+```bash
+mkdir build
+cd build
+cmake .. -DCMAKE_PREFIX_PATH=/path/to/libtorch  # or -DTorch_DIR= if you installed PyTorch normally, see above
+cmake --build .
+cmake --install .
+```
+
+You may want to pass `-DCMAKE_INSTALL_PREFIX=/path/to/libtorchvision` for
+cmake to copy/install the files to a specific location (e.g. `$CONDA_PREFIX`).
+
+On Windows, you may also need to pass `-DUSE_PYTHON`. Refer to the corresponding
+`CMakeLists.txt` for additional options.
+
+**DISCLAIMER**: the `libtorchvision` library includes the torchvision
+custom ops as well as most of the C++ torchvision APIs. Those APIs do not come
+with any backward-compatibility guarantees and may change from one version to
+the next. Only the Python APIs are stable and with backward-compatibility
+guarantees. So, if you need stability within a C++ environment, your best bet is
+to export the Python APIs via torchscript.
+
+Now that libtorchvision is built and installed we can tell our project to use
+and link to it via the `-DUSE_TORCHVISION` flag. We also need to tell CMake
+where to find it, just like we did with LibTorch, e.g.:
+
+```bash
+cmake .. -DTorch_DIR=$Torch_DIR -DTorchVision_DIR=path/to/libtorchvision -DUSE_TORCHVISION=ON
+cmake --build .
+```
+
+Now the `run_model` executable should be able to run the
+`fasterrcnn_resnet50_fpn.pt` file.