Sick-Perception

Don't be fooled, this is actually a mapping package!

⚠️ IMPORTANT ⚠️

Previous versions (branches) of this project were architected to be standalone "pure-C++" modules, however, this branch has been updated to target ROS[2], and offloads sensor interfacing and localization pipeline prerequisites to various external ROS packages, which are discuessed below. To view the old architecture, check out the perception-v1 and/or perception-v2 branches. These branches are not likely to be maintained, and as a result may not reflect the same functionality as this branch in the future.

Purpose

This project aims to provide an obstacle detection module utilizing SICK lidar hardware and PCL filtering algorithms for usage in autonomous robotics.

System Overview / [Functional] ROS Dependencies

TODO (make diagrams!)

Note that this list of dependencies is for the recommended "system" setup and does not include dependencies for building the project.

Dependency	Required Version/Ref	Description
sick_scan_xd	The latest release.	Lidar interfacing - provices point clouds and IMU measurements.
direct_lidar_inertial_odometry	The feature/ros2 branch, unless a ROS1->ROS2 bridge is utilized. Note that problems have been diagnosed with the current version of this repo, and CSM's fork may work better out of the box.	Localization - uses SLAM to produce a location and orientation estimate.

Initialization / Updating

The main obstacle detection 'perception' node does not require any submodules and can be built after using a normal git clone. If extra helper nodes (under extra/ directory) are needed, submodules may be required. Use the --recurse-submodules option when cloning fresh and git submodule update --init --recursive for an already cloned project or when changing/updating branches.

Build System

Since the project targets ROS2, it can be built using Colcon (which uses CMake). Dependencies are listed below:

Dependency	[Recommended] Sourcing Method	Required Version/Ref	Other Considerations
PCL (Point Cloud Library)	Must be manually installed. On linux, the easiest method is to use sudo apt-get install libpcl-dev. For windows, the PCL GitHub repository provides an installer for each release.	Versions 1.12.0 and up have been verified to work.	Make sure to add the relevant directories to PATH when installing on windows (see the PCL docs installation guide) so that CMake can properly find the libraries and headers.
Eigen	Eigen is a dependenciy of PCL and is thus almost gaurenteed to always be present by default. In any case, external versions can used as well, and can be sourced from the link provided.	Not super relevant. Any version compatible with PCL will suffice.	In almost every scenerio just use the bundled version with PCL since this dependency can then be ignored.
pcl_ros	Must Can be manually built and sourced as a ROS package, however rosdep can also manage this. Run rosdep install --from-path . while inside the project directory.	The correct branch for whatever ROS distro is in use.	If building manually: pcl_ros is a subproject in the perception_pcl repository.

Summary: PCL is effectively the only dependency granted that ROS[2] is installed and configured!

---

For the most part, the project is configured to use the optimal build variables by default, however, the provided options and some common CMake options are listed here (crossed out options have not been implemented and/or do not accomplish anything):

• sickperception_CXX_STANDARD -- C++ standard to use for building the project and dependencies. The project has not been verified on anything less than C++17.

• LDRP_ENABLE_LOGGING -- Enable/disable internal logging altogether.

• LDRP_ENABLE_DEBUG_LOGGING -- Enable/disable internal debug logging.

• LDRP_ENABLE_SAFETY_CHECKS -- Enable/disable "extra" safety checks.

• LDRP_ENABLE_TUNING -- Enable/disable live tuning via ROS topics and/or NetworkTables.

• LDRP_ENABLE_PROFILING -- Enable/disable pipeline profiling via ROS topics and/or NetworkTables.

• CMAKE_BUILD_TYPE -- Used on some build systems (non-MSVC) to define the build type (the project sets this to Release if not explicitly configured).

• CMAKE_INSTALL_PREFIX -- Where the installed files will be copied (CMake default variable).

  Note that 'sickperception_*' refers to a project-wide configuration, while 'LDRP_*' (stands for LiDaR Perception) refers to a code-specific [internal] configuration.

---

To build, use Colcon (when inside the top-level project directory):

colcon build (--event-handlers console_direct+)

Then source the package:

source ./install/setup.bash

Finally, the node can be run using:

ros2 run sick_perception ldrp_node

More detailed configurations and launch methods to come...

Usage

The ldrp_node ROS2 node has 2 inputs and 1 output in terms of topic subscriptions/publications:

• Inputs:
  • A sensor_msgs::msg::PointCloud2 topic providing raw LiDAR scans (that are timestamped) -- topic name is configurable based on setup.
  • A geometry_msgs::msg::PoseStamped topic providing timestamped pose updates (timestamps must correlate with scans!) -- topic name is configurable based on setup.
• Outputs:
  • A nav_msgs::msg::OccupancyGrid topic (/ldrp/obstacle_grid) representing a running map of the currently detected obstacles.

Helpful Docs

• ROS2 Docs
• ROS2 Tutorials
• ROS2 Message Types (make sure to select a relevant branch!)
• Colcon build reference