opencv_apps

opencv_apps provides the ROS nodes that run the functions of OpenCV: image processing, features, contours, optical flows, tracking, detection and recognition, and the deep learning models of cv::dnn. Each node subscribes an image topic, and publishes its results as messages and as an image, so you can use the functions of OpenCV just by running a launch file. The same source supports both ROS 1 and ROS 2.

sudo apt install ros-$ROS_DISTRO-opencv-apps ros-$ROS_DISTRO-image-publisher
# ROS 2, terminal 1: publish the USB camera as image (0: the number of the camera, /dev/video0)
ros2 run image_publisher image_publisher_node 0 --ros-args -r image_raw:=image
# ROS 2, terminal 2: the face detection on it
ros2 launch opencv_apps face_detection.launch.xml image:=image
# ROS 1 (ROS One), terminal 1: publish the USB camera as camera/image_raw (0: /dev/video0)
rosrun image_publisher image_publisher 0 __name:=camera
# ROS 1 (ROS One), terminal 2: the face detection on it
roslaunch opencv_apps face_detection.launch image:=camera/image_raw use_opencv4:=true

Documentation: https://ros-perception.github.io/opencv_apps/ (the topics, the parameters and the usage of the nodes)

What opencv_apps can do

Image processing

Filter and transform the images: edges, histogram equalization, morphology, image pyramids, smoothing, thresholds and the Fourier transform.

adding_images	discrete_fourier_transform	edge_detection	equalize_histogram
morphology	pyramids	smoothing	threshold

Color

Extract the pixels in a range of colors in HSV, HLS, Lab* or RGB, and compare the color histograms.

hsv_color_filter	hls_color_filter	lab_color_filter	rgb_color_filter
compare_histogram

Features, lines and contours

Find the corners, lines, line segments, circles, blobs and contours, with their moments and convex hulls.

corner_harris	goodfeature_track	hough_lines	hough_circles
line_segment_detector	find_contours	general_contours	contour_moments
convex_hull	blob_detection

Segmentation

Separate the foreground and the objects: background subtraction, connected components and watershed.

segment_objects

Contributing to opencv_apps

opencv_apps wraps OpenCV samples (from opencv/samples/cpp, samples/tapi, tutorials, or elsewhere) as ROS nodes. One source file builds on both ROS1 (catkin) and ROS2 (colcon/ament). Please keep each node small and focused on one OpenCV feature, and follow the layout below so the repository stays consistent.

Checklist for a new node <name> (class <Name>Nodelet)

Use threshold as the template; see also camshift (trackbars/mouse) and face_recognition (services).

1. Nodelet src/nodelet/<name>_nodelet.cpp, written in the ROS2 API on opencv_apps::Nodelet (include/opencv_apps/nodelet.h):
   • parameters: declare_parameter(name, default, paramDescriptor(desc, min, max)), updated in a parametersCallback registered with add_on_set_parameters_callback;
   • I/O: subscribeImage / subscribeCamera in subscribe(), advertiseImage / advertise for outputs;
   • end with RCLCPP_COMPONENTS_REGISTER_NODE(opencv_apps::<Name>Nodelet).
   • On ROS1 the same file compiles through ros1/include/opencv_apps/ros1_compat.h, which also serves the declared parameters as dynamic_reconfigure (startReconfigureServer, ~set_parameters). A cfg/*.cfg is therefore not needed for new nodes; existing nodes keep theirs only for compatibility (if you add one, its defaults/ranges must match the paramDescriptor).
   • Guard OpenCV API differences with CV_MAJOR_VERSION / CV_MINOR_VERSION (OpenCV 3.x/4.x are in CI).
2. CMakeLists.txt, both sections (keep changes scoped to the new node; do not restructure other targets):
   • ROS2: <name>:<Name>Nodelet in _nodelets and src/nodelet/<name>_nodelet.cpp in _nodelet_cppfiles;
   • ROS1: opencv_apps_add_nodelet(<name> src/nodelet/<name>_nodelet.cpp).
   • opencv_contrib modules: gate both with if(TARGET opencv_xxx) (see opencv_optflow / simple_flow), and the tests too.
3. nodelet_plugins.xml: <class name="opencv_apps/<name>" type="opencv_apps::<Name>Nodelet" ...>.
4. New messages: msg/<Type>.msg (globbed on ROS2; add it to ROS1 add_message_files) and a shim ros1/include/opencv_apps/msg/<snake_type>.hpp like msg/circle.hpp.
5. Launch: launch/<name>.launch (ROS1) and launch/<name>.launch.xml (ROS2) with the same arguments.
6. Tests (required):
   • ROS1: test/test-<name>.test (rostest + hztest), registered in test/CMakeLists.txt with add_rostest(test-<name>.test ARGS gui:=false);
   • ROS2: test/ros2/test_<name>.py (launch_testing, globbed automatically) using camera(), include(), description() and TopicsTest from test/ros2/opencv_apps_test.py.
7. README.md: add the node to the list.

Build and test

# ROS1
catkin_make
catkin_make run_tests   # all tests; results in build/test_results/opencv_apps/
# one test (catkin-generated target name, list them with `make -C build help | grep run_tests`):
catkin_make run_tests_opencv_apps_rostest_test-<name>__gui_false.test

# ROS2
colcon build --packages-select opencv_apps --cmake-args -DBUILD_TESTING=ON
colcon test --packages-select opencv_apps --ctest-args -R <name>
colcon test-result --verbose

CI (.github/workflows/ci.yml, .travis.sh) also runs clang-format, catkin_lint and clang-tidy; to check locally:

clang-format -i -style=file src/nodelet/<name>_nodelet.cpp   # repository .clang-format
ROS_DISTRO=melodic ROS_VERSION=1 catkin_lint --resolve-env --strict .   # use the catkin_lint version pinned in ci.yml
# clang-tidy (repository .clang-tidy): build with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON, then
run-clang-tidy -p <build dir containing compile_commands.json>

Pull requests

Each PR must include:

• the test(s) above, passing on ROS1 and ROS2;
• a demo video (GIF or mp4) of the node output (e.g. /<name>/image) in the PR description.