Merge pull request #49 from LimHyungTae/better_instructions

Better instructions

Makefile

@@ -0,0 +1,15 @@
+pyinstall:
+	@python3 -m pip install --upgrade pip
+	@pip install numpy
+	@pip install --verbose ./python/
+
+pyinstall_with_demo: pyinstall
+	@pip install open3d==0.18.0
+
+cppinstall:
+	@cmake -Bcpp/build cpp/
+	@cmake --build cpp/build -j$(nproc --all)
+
+cppinstall_with_demo:
+	@cmake -Bcpp/build cpp/ -DINCLUDE_CPP_EXAMPLES=ON
+	@cmake --build cpp/build -j$(nproc --all)

README.md

@@ -45,86 +45,66 @@
 [examplelink]: https://github.com/url-kaist/patchwork-plusplus/tree/master/examples
 
 ## :package: Prerequisite packages
-> You may need to install Eigen, numpy, and Open3D. Open3D is used for point cloud visualization.
+> What we need are just minimal dependencies.
 
-```bash
-# Install prerequisite packages including Open3D
-$ git clone https://github.com/url-kaist/patchwork-plusplus
-$ cd patchwork-plusplus
-$ bash scripts/install_open3d.bash
-```
-
-<details>
-<summary> Manual Installation line-by-line </summary>
-
-```bash
-# To install Eigen and numpy
-$ sudo apt-get install libeigen3-dev
-$ pip install numpy
-
-# To install Open3D Python packages
-$ pip install open3d
-
-# To install Open3D C++ packages
-$ git clone https://github.com/isl-org/Open3D
-$ cd Open3D
-$ util/install_deps_ubuntu.sh # Only needed for Ubuntu
-$ mkdir build && cd build
-$ cmake ..
-$ make # If it fails, try several times or try 'sudo make'
-$ sudo make install
+```commandline
+sudo apt-get install g++ build-essential libeigen3-dev python3-pip python3-dev cmake -y
 ```
 
 </details>
 
-## :gear: How to build
-> Please follow below codes to build Patchwork++.
+## :gear: How to build & Run
 
 ### Python
-```bash
-# in patchwork-plusplus directory
-$ cd python && pip install . 
-```
 
-### C++
-```bash
-# in patchwork-plusplus directory
-$ mkdir cpp/build && cd cpp/build
-$ cmake ..
-$ make
+**Pure installation**
+
+```commandline
+make pyinstall
 ```
 
-## :runner: To run the demo codes
-> There are some example codes for your convenience!
-> Please try using Patchwork++ to segment ground points in a 3D point cloud :smiley:
+Then, you can use Patchwork++ by `import pypatchworkpp`, which is super simple!
 
-### Python
-```bash
-# Run patchwork++ and visualize ground points(green) and nonground points(red)
-$ python examples/demo_visualize.py
+**Installation to run demo**
+
+Only Open3D (> 0.17.0) is additionally installed for visualization purposes.
 
-# Run patchwork++ with sequential point cloud inputs 
-$ python examples/demo_sequential.py
+```commandline
+make pyinstall_with_demo
 ```
 
+How to run Python demos is explained [here](https://github.com/url-kaist/patchwork-plusplus/tree/master/python/README.md#Demo).
+
 ### C++
-```bash
-# Run patchwork++ and visualize ground points(green) and nonground points(red)
-$ ./examples/demo_visualize
 
-# Run patchwork++ with sequential point cloud inputs 
-$ ./examples/demo_sequential
+**Pure installation**
+
+```commandline
+make cppinstall
+```
+
+**Installation with demo**
+
+Only Open3D (> 0.17.0) is additionally installed for visualization purposes.
 
-# Run patchwork++ with your point cloud file, example here
-$ ./examples/demo_visualize ./data/000000.bin # specify file path
+```commandline
+make cppinstall_with_demo
 ```
 
-### Demo Result
-If you execute Patchwork++ with given demo codes well, you can get the following result!
+How to run the C++ demos is explained [here](https://github.com/url-kaist/patchwork-plusplus/tree/master/cpp).
+
+### ROS2
+
+You should not need any extra dependency, just clone and build:
+
+```commandline
+cd colcon_ws/src && git clone 
+cd ../../
+colcon build --packages-select patchworkpp
+```
 
-It is a ground segmentation result of data/000000.bin file using Open3D visualization. (Ground : Green, Nonground : Red)
+How to launch ROS2 nodes is explained [here](https://github.com/url-kaist/patchwork-plusplus/tree/master/cpp).
 
-![Open3D Visualization of "data/000000.bin"](pictures/demo_000000.png)
 
 ## :pencil: Citation
 If you use our codes, please cite our paper ([arXiv][arXivLink], [IEEE *Xplore*][patchworkppIEEElink])
@@ -168,3 +148,12 @@ If you have any questions, please do not hesitate to contact us
 
 [sjlink]: https://github.com/seungjae24
 [htlink]: https://github.com/LimHyungTae
+
+
+---
+
+## Todo List
+- [ ] Support intensity for RNR in `master` branch
+- [ ] Support `Patchwork` mode for users who use this repository for baseline comparison purposes
+- [ ] Integrate TBB and optimize the performance
+

cpp/CMakeLists.txt

@@ -1,11 +1,10 @@
 cmake_minimum_required(VERSION 3.11)
-project(PATCHWORK VERSION 1.0.0)
+project(patchworkpp VERSION 1.0.0)
 
 set(CMAKE_CXX_STANDARD 20)
 set(PYTHON_EXECUTABLE python3)
 set(CMAKE_BUILD_TYPE Release)
 
-
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${Open3D_C_FLAGS}")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${Open3D_CXX_FLAGS}")
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${Open3D_EXE_LINKER_FLAGS}")
@@ -17,30 +16,47 @@ else()
   list(PREPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
 endif()
 
+option(INCLUDE_CPP_EXAMPLES "Include C++ example codes, which require Open3D for visualization" OFF)
 
-list(APPEND Open3D_LIBRARIES dl)
+# Parameters in `patchworkpp` subdirectory.
+# Thus, link should be `patchworkpp::ground_seg_cores`
+set(PARENT_PROJECT_NAME ${PROJECT_NAME})
+set(TARGET_NAME ground_seg_cores)
 
 add_subdirectory(patchworkpp)
 
-set(INCLUDE_EXAMPLES ON CACHE BOOL "Build examples")
+if (INCLUDE_CPP_EXAMPLES)
+  if(CMAKE_VERSION VERSION_LESS "3.15")
+    # Just automatically update cmake version
+    execute_process(COMMAND bash ../scripts/install_latest.cmake.bash
+                    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+  endif()
 
-if (INCLUDE_EXAMPLES)
+  list(APPEND Open3D_LIBRARIES dl)
 
   message(STATUS "Building examples for c++")
-  find_package(Open3D REQUIRED HINTS ${CMAKE_INSTALL_PREFIX}/lib/CMake)
+  find_package(Open3D QUIET)
+  if (NOT Open3D_FOUND)
+    message(STATUS "Open3D not found, installing Open3D...")
+    execute_process(COMMAND bash ../scripts/install_open3d.bash
+                    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+    find_package(Open3D REQUIRED HINTS ${CMAKE_INSTALL_PREFIX}/lib/CMake)
+  else()
+    message(STATUS "Found Open3D ${Open3D_VERSION}")
+  endif()
 
   list(APPEND Open3D_LIBRARIES dl)
   link_directories(${Open3D_LIBRARY_DIRS})
   message(STATUS "Found Open3D ${Open3D_VERSION}")
 
   add_executable(demo_visualize ${CMAKE_CURRENT_SOURCE_DIR}/patchworkpp/examples/demo_visualize.cpp)
-  target_link_libraries(demo_visualize PRIVATE PATCHWORK::patchworkpp ${Open3D_LIBRARIES} "stdc++fs")
+  target_link_libraries(demo_visualize PRIVATE ${PARENT_PROJECT_NAME}::${TARGET_NAME} ${Open3D_LIBRARIES} "stdc++fs")
   target_include_directories(demo_visualize PUBLIC ${Open3D_INCLUDE_DIRS})
   set_target_properties(demo_visualize PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/examples")
 
   add_executable(demo_sequential ${CMAKE_CURRENT_SOURCE_DIR}/patchworkpp/examples/demo_sequential.cpp)
-  target_link_libraries(demo_sequential PRIVATE PATCHWORK::patchworkpp ${Open3D_LIBRARIES} "stdc++fs")
+  target_link_libraries(demo_sequential PRIVATE ${PARENT_PROJECT_NAME}::${TARGET_NAME} ${Open3D_LIBRARIES} "stdc++fs")
   target_include_directories(demo_sequential PUBLIC ${Open3D_INCLUDE_DIRS})
   set_target_properties(demo_sequential PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/examples")
 
-endif()
+endif()

cpp/README.md

@@ -0,0 +1,87 @@
+<div align="center">
+    <h1>Patchwork++</h1>
+    <a href="https://github.com/url-kaist/patchwork-plusplus/tree/master/patchworkpp"><img src="https://img.shields.io/badge/-C++-blue?logo=cplusplus" /></a>
+    <a href="https://github.com/url-kaist/patchwork-plusplus/tree/master"><img src="https://img.shields.io/badge/Python-3670A0?logo=python&logoColor=ffdd54" /></a>
+    <a href="https://github.com/url-kaist/patchwork-plusplus/tree/master/ros"><img src="https://img.shields.io/badge/ROS2-Humble-blue" /></a>
+    <a href="https://github.com/url-kaist/patchwork-plusplus/tree/master"><img src="https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black" /></a>
+    <a href="https://ieeexplore.ieee.org/document/9981561"><img src="https://img.shields.io/badge/DOI-10.1109/IROS47612.2022.9981561-004088.svg"/>
+    <br />
+    <br />
+    <a href=https://www.youtube.com/watch?v=fogCM159GRk>Video</a>
+    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+    <a href="https://github.com/url-kaist/patchwork-plusplus/tree/master/README.md###Python">Install</a>
+    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+    <a href="https://github.com/url-kaist/patchwork-plusplus/tree/master/ros">ROS2</a>
+    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+    <a href=https://www.youtube.com/watch?v=fogCM159GRk>Paper</a>
+    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+    <a href=https://github.com/url-kaist/patchwork-plusplus/issues>Contact Us</a>
+  <br />
+  <br />
+  <p align="center"><img src=../pictures/patchwork++.gif alt="animated" /></p>
+
+  [Patchwork++][arXivlink], an extension of [Patchwork][patchworklink], is **a fast, robust, and self-adaptive ground segmentation algorithm** on 3D point cloud.
+</div>
+
+[arXivlink]: https://arxiv.org/abs/2207.11919
+[patchworklink]: https://github.com/LimHyungTae/patchwork
+
+---
+
+# Patchwork++ in C++
+
+## Manual Installation Just in Case
+
+```commandline
+# in patchwork-plusplus directory
+$ cd cpp && mkdir build && cd build
+$ cmake -DCMAKE_BUILD_TYPE=Release ..
+$ make -j 16
+```
+
+If you want to run demo, just run
+
+```commandline
+make cppinstall_with_demo
+```
+
+in the top-level directory, or 
+
+```commandline
+# in patchwork-plusplus directory
+$ cd cpp && mkdir build && cd build
+$ cmake -DCMAKE_BUILD_TYPE=Release -DINCLUDE_CPP_EXAMPLES=ON ..
+$ make -j 16
+```
+
+> [!WARNING]  
+> Please check your cmake version via `cmake --version`.
+> If it is lower than 3.20, it is automatically updated by `scripts/install_latest_cmake.bash` (see [here](https://github.com/url-kaist/patchwork-plusplus/blob/master/cpp/CMakeLists.txt#L31)).
+
+## :runner: To run the demo codes
+> There are some example codes for your convenience!
+> Please try using Patchwork++ to segment ground points in a 3D point cloud :smiley:
+
+
+* Example 1. Run patchwork++ and visualize ground points (green) and non-ground points (red)
+```commandline
+./cpp/build/examples/demo_visualize
+```
+
+* Example 2. Run patchwork++ with sequential point cloud inputs 
+```commandline
+./cpp/build/examples/demo_sequential
+```
+
+* Example 3. Run patchwork++ with your point cloud file, example here
+```commandline
+./examples/demo_visualize ./data/000000.bin # specify file path
+```
+
+### Demo Result
+If you execute Patchwork++ with given demo codes well, you can get the following result!
+
+It is a ground segmentation result of data/000000.bin file using Open3D visualization. (Ground : Green, Nonground : Red)
+
+![Open3D Visualization of "data/000000.bin"](../pictures/demo_000000.png)
+

cpp/patchworkpp/CMakeLists.txt

@@ -2,32 +2,34 @@ project(patchworkpp_src)
 
 include(GNUInstallDirs)
 
+message("Parent project name: " ${PARENT_PROJECT_NAME})
+
 find_package(Eigen3 REQUIRED QUIET)
 
-add_library(patchworkpp STATIC src/patchworkpp.cpp)
-set_target_properties(patchworkpp PROPERTIES POSITION_INDEPENDENT_CODE ON)
+add_library(${TARGET_NAME} STATIC src/patchworkpp.cpp)
+set_target_properties(${TARGET_NAME} PROPERTIES POSITION_INDEPENDENT_CODE ON)
 
-target_include_directories(patchworkpp PUBLIC
+target_include_directories(${TARGET_NAME} PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
   $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
-target_link_libraries(patchworkpp Eigen3::Eigen)
-add_library(PATCHWORK::patchworkpp ALIAS patchworkpp)
+target_link_libraries(${TARGET_NAME} Eigen3::Eigen)
+add_library(${PARENT_PROJECT_NAME}::${TARGET_NAME} ALIAS ${TARGET_NAME})
 
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/
   DESTINATION include
 )
-install(TARGETS patchworkpp
-  EXPORT PATCHWORKConfig
+install(TARGETS ${TARGET_NAME}
+  EXPORT ${PARENT_PROJECT_NAME}Config
   LIBRARY DESTINATION lib
 )
 
-export(TARGETS patchworkpp
-  NAMESPACE PATCHWORK::
-  FILE "${CMAKE_CURRENT_BINARY_DIR}/PATCHWORKConfig.cmake"
+export(TARGETS ${TARGET_NAME}
+  NAMESPACE ${PARENT_PROJECT_NAME}::
+  FILE "${CMAKE_CURRENT_BINARY_DIR}/${PARENT_PROJECT_NAME}Config.cmake"
 )
-install(EXPORT PATCHWORKConfig
-  DESTINATION "${CMAKE_INSTALL_DATADIR}/PATCHWORK/cmake"
-  NAMESPACE PATCHWORK::
+install(EXPORT ${PARENT_PROJECT_NAME}Config
+  DESTINATION "${CMAKE_INSTALL_DATADIR}/${PARENT_PROJECT_NAME}/cmake"
+  NAMESPACE ${PARENT_PROJECT_NAME}::
 )

python/CMakeLists.txt

@@ -6,6 +6,12 @@ set(CMAKE_BUILD_TYPE Release)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
+# Parameters used in `patchworkpp` subdirectory.
+# Thus, link should be `patchworkpp::ground_seg_cores`
+# See https://github.com/url-kaist/patchwork-plusplus/tree/master/cpp/CMakeLists.txt#L21
+set(PARENT_PROJECT_NAME patchworkpp)
+set(TARGET_NAME ground_seg_cores)
+
 find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
 find_package(pybind11 CONFIG REQUIRED)
 
@@ -21,7 +27,7 @@ endif()
 
 pybind11_add_module(pypatchworkpp patchworkpp/pybinding.cpp)
 
-target_link_libraries(pypatchworkpp PUBLIC PATCHWORK::patchworkpp)
+target_link_libraries(pypatchworkpp PUBLIC ${PARENT_PROJECT_NAME}::${TARGET_NAME})
 
 if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
   target_compile_options(pypatchworkpp PUBLIC -fsized-deallocation)