Copy examples for building user projects with Open3D to Open3D repo (#…

…6884)

Earlier example location:

https://github.com/intel-isl/open3d-cmake-find-package
https://github.com/isl-org/open3d-cmake-external-project

Copying them into the main repo to reduce maintenance overhead and ensure they are up to date.

docker/docker_test.sh

@@ -170,8 +170,7 @@ cpp_python_linking_uninstall_test() {
     fi
 
     ${docker_run} -i --rm "${DOCKER_TAG}" /bin/bash -c "\
-        git clone https://github.com/isl-org/open3d-cmake-find-package.git \
-     && cd open3d-cmake-find-package \
+        cd examples/cmake/open3d-cmake-find-package \
      && mkdir build \
      && pushd build \
      && echo Testing build with cmake \
@@ -182,8 +181,7 @@ cpp_python_linking_uninstall_test() {
 
     if [ "${BUILD_SHARED_LIBS}" == "ON" ] && [ "${BUILD_SYCL_MODULE}" == "OFF" ]; then
         ${docker_run} -i --rm "${DOCKER_TAG}" /bin/bash -c "\
-            git clone https://github.com/isl-org/open3d-cmake-find-package.git \
-         && cd open3d-cmake-find-package \
+            cd examples/cmake/open3d-cmake-find-package \
          && mkdir build \
          && pushd build \
          && echo Testing build with pkg-config \

docs/cpp_project.rst

@@ -9,10 +9,10 @@ CMake
 We provide two example CMake projects to demonstrate how to use Open3D in your
 CMake projects.
 
-* `Find Pre-Installed Open3D Package in CMake <https://github.com/isl-org/open3d-cmake-find-package>`_
+* `Find Pre-Installed Open3D Package in CMake <https://github.com/isl-org/tree/main/examples/cmake/open3d-cmake-find-package>`_
   This option can be used if you'd like to build and install Open3D first,
   then link your project to Open3D.
-* `Use Open3D as a CMake External Project <https://github.com/isl-org/open3d-cmake-external-project>`_
+* `Use Open3D as a CMake External Project <https://github.com/isl-org/tree/main/open3d-cmake-external-project>`_
   This option can be used if you'd like Open3D to build alongside with your
   project.
 

examples/cmake/open3d-cmake-external-project/CMakeLists.txt

@@ -0,0 +1,52 @@
+# On Ubuntu 18.04, get the latest CMake from https://apt.kitware.com/.
+cmake_minimum_required(VERSION 3.18)
+
+project(Open3DCMakeExternalProject LANGUAGES C CXX)
+
+option(GLIBCXX_USE_CXX11_ABI   "Set -D_GLIBCXX_USE_CXX11_ABI=1"       OFF)
+option(STATIC_WINDOWS_RUNTIME  "Use static (MT/MTd) Windows runtime"  ON )
+
+if(NOT CMAKE_BUILD_TYPE)
+    message(STATUS "No CMAKE_BUILD_TYPE specified, default to Release.")
+    set(CMAKE_BUILD_TYPE "Release")
+endif()
+
+# Option 1: Use ExternalProject_Add, as shown in this CMake example.
+# Option 2: Install Open3D first and use find_package, see
+#           http://www.open3d.org/docs/release/cpp_project.html for details.
+include(ExternalProject)
+ExternalProject_Add(
+    external_open3d
+    PREFIX open3d
+    GIT_REPOSITORY https://github.com/isl-org/Open3D.git
+    GIT_TAG main   # Use a specific tag, e.g. v0.18.0 to pin Open3D version.
+    GIT_SHALLOW ON
+    UPDATE_COMMAND ""
+    # Check out https://github.com/intel-isl/Open3D/blob/master/CMakeLists.txt
+    # For the full list of available options.
+    CMAKE_ARGS
+        -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
+        -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
+        -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
+        -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
+        -DGLIBCXX_USE_CXX11_ABI=${GLIBCXX_USE_CXX11_ABI}
+        -DSTATIC_WINDOWS_RUNTIME=${STATIC_WINDOWS_RUNTIME}
+        -DBUILD_SHARED_LIBS=ON
+        -DBUILD_PYTHON_MODULE=OFF
+        -DBUILD_EXAMPLES=OFF
+)
+
+# Simulate importing Open3D::Open3D
+ExternalProject_Get_Property(external_open3d INSTALL_DIR)
+add_library(Open3DHelper INTERFACE)
+add_dependencies(Open3DHelper external_open3d)
+target_compile_features(Open3DHelper INTERFACE cxx_std_14)
+target_compile_definitions(Open3DHelper INTERFACE _GLIBCXX_USE_CXX11_ABI=$<BOOL:${GLIBCXX_USE_CXX11_ABI}>)
+target_include_directories(Open3DHelper INTERFACE "${INSTALL_DIR}/include" "${INSTALL_DIR}/include/open3d/3rdparty")
+target_link_directories(Open3DHelper INTERFACE "${INSTALL_DIR}/lib")
+target_link_libraries(Open3DHelper INTERFACE Open3D)
+add_library(Open3D::Open3D ALIAS Open3DHelper)
+
+add_executable(Draw)
+target_sources(Draw PRIVATE Draw.cpp)
+target_link_libraries(Draw PRIVATE Open3D::Open3D)

examples/cmake/open3d-cmake-external-project/Draw.cpp

@@ -0,0 +1,26 @@
+// ----------------------------------------------------------------------------
+// -                        Open3D: www.open3d.org                            -
+// ----------------------------------------------------------------------------
+// Copyright (c) 2018-2023 www.open3d.org
+// SPDX-License-Identifier: MIT
+// ----------------------------------------------------------------------------
+
+#include <string>
+
+#include "open3d/Open3D.h"
+
+int main(int argc, char *argv[]) {
+    if (argc == 2) {
+        std::string option(argv[1]);
+        if (option == "--skip-for-unit-test") {
+            open3d::utility::LogInfo("Skiped for unit test.");
+            return 0;
+        }
+    }
+
+    auto sphere = open3d::geometry::TriangleMesh::CreateSphere(1.0);
+    sphere->ComputeVertexNormals();
+    sphere->PaintUniformColor({0.0, 1.0, 0.0});
+    open3d::visualization::DrawGeometries({sphere});
+    return 0;
+}

examples/cmake/open3d-cmake-external-project/README.md

@@ -0,0 +1,56 @@
+# Use Open3D as a CMake External Project
+
+This is one of the two CMake examples showing how to use Open3D in your CMake
+project:
+
+-   [Find Pre-Installed Open3D Package in CMake](../open3d-cmake-find-package)
+-   [Use Open3D as a CMake External Project](../open3d-cmake-external-project)
+
+For more details, check out the [Open3D repo](https://github.com/isl-org/Open3D) and
+[Open3D docs](http://www.open3d.org/docs/release/cpp_project.html).
+
+## Step 1: Install Open3D dependencies
+
+On Ubuntu:
+
+```bash
+# Install minimal Open3D compilation dependencies. For the full list, checkout:
+# https://github.com/isl-org/Open3D/blob/master/util/install_deps_ubuntu.sh
+sudo apt-get --yes install xorg-dev libglu1-mesa-dev
+```
+
+On macOS/Windows:
+
+```bash
+# Skip this step
+```
+
+## Step 2: Use Open3D in this example project
+
+You can specify the number of parallel jobs to speed up compilation.
+
+On Ubuntu/macOS:
+
+```bash
+wget https://github.com/isl-org/Open3D/archive/refs/heads/main.zip -o Open3D-main.zip
+unzip Open3D-main.zip 'Open3D-main/cmake/ispc_isas/*' -d example-project
+cd example-project/Open3D-main/examples/cmake/open3d-cmake-external-project
+mkdir build
+cd build
+cmake ..
+make -j 12
+./Draw
+```
+
+On Windows:
+
+```batch
+wget https://github.com/isl-org/Open3D/archive/refs/heads/main.zip -o Open3D-main.zip
+unzip Open3D-main.zip 'Open3D-main/cmake/ispc_isas/*' -d example-project
+cd example-project/Open3D-main/examples/cmake/open3d-cmake-external-project
+mkdir build
+cd build
+cmake ..
+cmake --build . --config Release --parallel 12
+Release\Draw
+```

examples/cmake/open3d-cmake-find-package/CMakeLists.txt

@@ -0,0 +1,33 @@
+# On Ubuntu 18.04, get the latest CMake from https://apt.kitware.com/.
+cmake_minimum_required(VERSION 3.18)
+
+project(Open3DCMakeFindPackage LANGUAGES C CXX)
+
+# The options need to be the same as Open3D's default
+# If Open3D is configured and built with custom options, you'll also need to
+# specify the same custom options.
+option(STATIC_WINDOWS_RUNTIME "Use static (MT/MTd) Windows runtime" ON)
+if(STATIC_WINDOWS_RUNTIME)
+    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+else()
+    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
+endif()
+
+# Find installed Open3D, which exports Open3D::Open3D
+find_package(Open3D REQUIRED)
+
+add_executable(Draw)
+target_sources(Draw PRIVATE Draw.cpp)
+target_link_libraries(Draw PRIVATE Open3D::Open3D)
+
+# On Windows if BUILD_SHARED_LIBS is enabled, copy .dll files to the executable directory
+if(WIN32)
+    get_target_property(open3d_type Open3D::Open3D TYPE)
+    if(open3d_type STREQUAL "SHARED_LIBRARY")
+        message(STATUS "Copying Open3D.dll to ${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>")
+        add_custom_command(TARGET Draw POST_BUILD
+                           COMMAND ${CMAKE_COMMAND} -E copy
+                                   ${CMAKE_INSTALL_PREFIX}/bin/Open3D.dll
+                                   ${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>)
+    endif()
+endif()

examples/cmake/open3d-cmake-find-package/Draw.cpp

@@ -0,0 +1,26 @@
+// ----------------------------------------------------------------------------
+// -                        Open3D: www.open3d.org                            -
+// ----------------------------------------------------------------------------
+// Copyright (c) 2018-2023 www.open3d.org
+// SPDX-License-Identifier: MIT
+// ----------------------------------------------------------------------------
+
+#include <string>
+
+#include "open3d/Open3D.h"
+
+int main(int argc, char *argv[]) {
+    if (argc == 2) {
+        std::string option(argv[1]);
+        if (option == "--skip-for-unit-test") {
+            open3d::utility::LogInfo("Skiped for unit test.");
+            return 0;
+        }
+    }
+
+    auto sphere = open3d::geometry::TriangleMesh::CreateSphere(1.0);
+    sphere->ComputeVertexNormals();
+    sphere->PaintUniformColor({0.0, 1.0, 0.0});
+    open3d::visualization::DrawGeometries({sphere});
+    return 0;
+}

examples/cmake/open3d-cmake-find-package/README.md

@@ -0,0 +1,75 @@
+# Find Pre-Installed Open3D Package in CMake
+
+This is one of the two CMake examples showing how to use Open3D in your CMake
+project:
+
+-   [Find Pre-Installed Open3D Package in CMake](../open3d-cmake-find-package)
+-   [Use Open3D as a CMake External Project](../open3d-cmake-external-project)
+
+For more details, check out the [Open3D repo](https://github.com/isl-org/Open3D) and
+[Open3D docs](http://www.open3d.org/docs/release/cpp_project.html).
+
+You may download a precompiled binary package (recommended), or compile your
+own.
+
+## Step 1a: Download pre-compiled Open3D binary package
+
+Download the pre-compiled Open3D binary package from the [Open3D release page](https://github.com/isl-org/Open3D/releases). The binary package is available for Ubuntu (with and without CUDA), macOS (Inel and Apple Si), and Windows. You may download a stable release or a development build (devel-main).
+
+## Step 1b: Compile and install Open3D
+
+Follow the [Open3D compilation guide](http://www.open3d.org/docs/release/compilation.html),
+compile and install Open3D in your preferred location. You can specify the
+installation path with `CMAKE_INSTALL_PREFIX` and the number of parallel jobs
+to speed up compilation.
+
+On Ubuntu/macOS:
+
+```bash
+git clone https://github.com/isl-org/Open3D.git
+cd Open3D
+mkdir build
+cd build
+cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=${HOME}/open3d_install ..
+make install -j 12
+cd ../..
+```
+
+On Windows:
+
+```batch
+git clone https://github.com/isl-org/Open3D.git
+cd Open3D
+mkdir build
+cd build
+cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=C:\open3d_install ..
+cmake --build . --config Release --parallel 12 --target install
+cd ..\..
+```
+
+Note: `-DBUILD_SHARED_LIBS=ON` is recommended if `-DBUILD_CUDA_MODULE=ON`.
+
+## Step 2: Use Open3D in this example project
+
+On Ubuntu/macOS:
+
+```bash
+cp -ar Open3D/examples/cmake/open3d-cmake-find-package .
+cd open3d-cmake-find-package
+mkdir build
+cd build
+cmake -DOpen3D_ROOT=${HOME}/open3d_install ..
+make -j 12
+./Draw
+```
+
+On Windows:
+
+```batch
+cp -ar Open3D/examples/cmake/open3d-cmake-find-package .
+cd open3d-cmake-find-package
+mkdir build
+cmake -DOpen3D_ROOT=C:\open3d_install ..
+cmake --build . --config Release --parallel 12
+Release\Draw
+```

util/ci_utils.sh

@@ -316,11 +316,9 @@ run_cpp_unit_tests() {
 # Need variable OPEN3D_INSTALL_DIR
 test_cpp_example() {
     # Now I am in Open3D/build/
-    cd ..
-    git clone https://github.com/isl-org/open3d-cmake-find-package.git
-    cd open3d-cmake-find-package
+    pushd ../examples/cmake/open3d-cmake-find-package
     mkdir build
-    cd build
+    pushd build
     echo Testing build with cmake
     cmake -DCMAKE_INSTALL_PREFIX=${OPEN3D_INSTALL_DIR} ..
     make -j"$NPROC" VERBOSE=1
@@ -338,8 +336,9 @@ test_cpp_example() {
             ./Draw --skip-for-unit-test
         fi
     fi
-    # Now I am in Open3D/open3d-cmake-find-package/build/
-    cd ../../build
+    popd
+    popd
+    # Now I am in Open3D/build/
 }
 
 # Install dependencies needed for building documentation (on Ubuntu 18.04)