Migrate repository to ROS 2

.github/workflows/colcon-build.yml

@@ -0,0 +1,25 @@
+name: colcon build
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    container:
+      image: osrf/ros:humble-desktop
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: "src/${{ github.repository_id }}"
+      - name: Inspect directory contents
+        run: apt-get update && apt-get install --yes tree && pwd && tree
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+      - name: Run colcon build
+        run: . /opt/ros/humble/setup.sh && colcon build --symlink-install
+      - name: Run yolo checks
+        run: |
+          .venv/bin/yolo check | tee check.log
+          ! grep -q "❌" check.log
+        working-directory: "${{ github.workspace }}/src/${{ github.repository_id }}"

ARCHITECTURE.md

@@ -0,0 +1,41 @@
+# Package Organization
+
+This repository is a ROS 2 wrapper around the Ultralytics YOLOv8 library. As is
+standard with learning-based Python packages, a virtual environment is used to
+avoid Python dependency conflicts with other packages on the system. Virtual
+environments appear to be incompatible with the standard ROS 2 Python package
+architecture, thus `ament_cmake` is used instead of `ament_python`.
+
+## Virtual Environment Specification
+
+`pyproject.toml`, `poetry.lock`, and `poetry.toml` are used by the Poetry
+dependency manager to set up a virtual environment. `pyproject.toml` contains
+the editable list of Python dependencies used by the package. In general,
+`poetry.lock` and `poetry.toml` do not need to be manually edited.
+
+## `yolov8_ros/`
+
+This folder contains this package's ROS 2 nodes. ROS 2 nodes are implemented as
+modules with the suffix `_node` and must contain a `main()` function that can
+accept zero arguments. Nodes are not meant to be imported by other Python
+modules. `parameters.py` contains the sets of ROS 2 parameters declared by each
+node and their accompanying documentation.
+
+## ROS 2 Files
+
+### Package and Build System Files
+
+`package.xml` is a required ROS 2 package specification file.
+
+`CMakeLists.txt` defines where files and folders in this repository are copied
+or linked during the ROS 2 workspace build and install process.
+
+### Runtime Files
+
+`launch/` contains ROS 2 launch files.
+
+`scripts/python_entrypoint.py` is an internal script used to run Python modules
+within the virtual environment from launch files. See additional documentation
+at the top of this file.
+
+`rviz2/` contains saved configuration files for the `rviz2` tool.

CMakeLists.txt

@@ -1,208 +1,58 @@
 cmake_minimum_required(VERSION 3.16)
-project(yolov8-ros)
+project(yolov8_ros)
 
-## Compile as C++11, supported in ROS Kinetic and newer
-# add_compile_options(-std=c++11)
+# Find CMake dependencies
+find_package(ament_cmake REQUIRED)
 
-## Find catkin macros and libraries
-## if COMPONENTS list like find_package(catkin REQUIRED COMPONENTS xyz)
-## is used, also find other catkin packages
-find_package(catkin REQUIRED)
-
-## System dependencies are found with CMake's conventions
-# find_package(Boost REQUIRED COMPONENTS system)
-
-
-## Uncomment this if the package has a setup.py. This macro ensures
-## modules and global scripts declared therein get installed
-## See http://ros.org/doc/api/catkin/html/user_guide/setup_dot_py.html
-# catkin_python_setup()
+# Build Python virtual environment
 add_custom_target(
     poetry_virtualenv ALL
-    COMMAND ${CMAKE_SOURCE_DIR}/scripts/cmake_virtualenv_setup.py
+    COMMAND poetry install --no-root --no-ansi --no-interaction
     WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-    COMMENT "Building ${CMAKE_PROJECT_NAME} virtualenv... may take some time"
+    COMMENT "Building ${CMAKE_PROJECT_NAME} virtualenv... this may take some time"
 )
 
-################################################
-## Declare ROS messages, services and actions ##
-################################################
-
-## To declare and build messages, services or actions from within this
-## package, follow these steps:
-## * Let MSG_DEP_SET be the set of packages whose message types you use in
-##   your messages/services/actions (e.g. std_msgs, actionlib_msgs, ...).
-## * In the file package.xml:
-##   * add a build_depend tag for "message_generation"
-##   * add a build_depend and a exec_depend tag for each package in MSG_DEP_SET
-##   * If MSG_DEP_SET isn't empty the following dependency has been pulled in
-##     but can be declared for certainty nonetheless:
-##     * add a exec_depend tag for "message_runtime"
-## * In this file (CMakeLists.txt):
-##   * add "message_generation" and every package in MSG_DEP_SET to
-##     find_package(catkin REQUIRED COMPONENTS ...)
-##   * add "message_runtime" and every package in MSG_DEP_SET to
-##     catkin_package(CATKIN_DEPENDS ...)
-##   * uncomment the add_*_files sections below as needed
-##     and list every .msg/.srv/.action file to be processed
-##   * uncomment the generate_messages entry below
-##   * add every package in MSG_DEP_SET to generate_messages(DEPENDENCIES ...)
-
-## Generate messages in the 'msg' folder
-# add_message_files(
-#   FILES
-#   Message1.msg
-#   Message2.msg
-# )
-
-## Generate services in the 'srv' folder
-# add_service_files(
-#   FILES
-#   Service1.srv
-#   Service2.srv
-# )
-
-## Generate actions in the 'action' folder
-# add_action_files(
-#   FILES
-#   Action1.action
-#   Action2.action
-# )
-
-## Generate added messages and services with any dependencies listed here
-# generate_messages(
-#   DEPENDENCIES
-#   std_msgs  # Or other packages containing msgs
-# )
-
-################################################
-## Declare ROS dynamic reconfigure parameters ##
-################################################
-
-## To declare and build dynamic reconfigure parameters within this
-## package, follow these steps:
-## * In the file package.xml:
-##   * add a build_depend and a exec_depend tag for "dynamic_reconfigure"
-## * In this file (CMakeLists.txt):
-##   * add "dynamic_reconfigure" to
-##     find_package(catkin REQUIRED COMPONENTS ...)
-##   * uncomment the "generate_dynamic_reconfigure_options" section below
-##     and list every .cfg file to be processed
-
-## Generate dynamic reconfigure parameters in the 'cfg' folder
-# generate_dynamic_reconfigure_options(
-#   cfg/DynReconf1.cfg
-#   cfg/DynReconf2.cfg
-# )
-
-###################################
-## catkin specific configuration ##
-###################################
-## The catkin_package macro generates cmake config files for your package
-## Declare things to be passed to dependent projects
-## INCLUDE_DIRS: uncomment this if your package contains header files
-## LIBRARIES: libraries you create in this project that dependent projects also need
-## CATKIN_DEPENDS: catkin_packages dependent projects also need
-## DEPENDS: system dependencies of this project that dependent projects also need
-catkin_package(
-#  INCLUDE_DIRS include
-#  LIBRARIES yolov8-ros
-#  CATKIN_DEPENDS other_catkin_pkg
-#  DEPENDS system_lib
+# Install launch files.
+# https://docs.ros.org/en/humble/Tutorials/Intermediate/Launch/Launch-system.html
+install(
+    DIRECTORY
+    launch
+    DESTINATION share/${PROJECT_NAME}/
 )
 
-###########
-## Build ##
-###########
-
-## Specify additional locations of header files
-## Your package locations should be listed before other locations
-include_directories(
-# include
-# ${catkin_INCLUDE_DIRS}
+# ROS 1 provided a mechanism in XML launch files to find the corresponding
+# source directory of a package. ROS 2 removed this mechanism but instead allows
+# users to reference the "install" path of a package within a workspace. Thus,
+# the virtual environment in this source directory must be discoverable inside
+# the workspace's install directory. We manually symlink the virtual environment
+# directory for two reasons:
+# 1) "colcon build" would otherwise copy gigabytes worth of libraries
+# 2) "colcon build --symlink-install" creates a symlink for each file in the
+#    directory, rather than a single symlink for the directory itself.
+#
+# ROS 2 looks for executables in ${CMAKE_INSTALL_PREFIX}/lib.
+file(
+    # "file" commands are executed at build time. The install directory won't
+    # exist yet during a fresh build, which will cause the next CREATE_LINK to
+    # fail.
+    MAKE_DIRECTORY
+    ${CMAKE_INSTALL_PREFIX}
+)
+file(
+    CREATE_LINK
+    ${CMAKE_SOURCE_DIR}/.venv
+    ${CMAKE_INSTALL_PREFIX}/.venv
+    SYMBOLIC
+)
+install(
+    DIRECTORY
+    yolov8_ros
+    DESTINATION lib/${PROJECT_NAME}
+)
+install(
+    PROGRAMS
+    scripts/python_entrypoint.py
+    DESTINATION lib/${PROJECT_NAME}
 )
 
-## Declare a C++ library
-# add_library(${PROJECT_NAME}
-#   src/${PROJECT_NAME}/yolov8-ros.cpp
-# )
-
-## Add cmake target dependencies of the library
-## as an example, code may need to be generated before libraries
-## either from message generation or dynamic reconfigure
-# add_dependencies(${PROJECT_NAME} ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})
-
-## Declare a C++ executable
-## With catkin_make all packages are built within a single CMake context
-## The recommended prefix ensures that target names across packages don't collide
-# add_executable(${PROJECT_NAME}_node src/yolov8-ros_node.cpp)
-
-## Rename C++ executable without prefix
-## The above recommended prefix causes long target names, the following renames the
-## target back to the shorter version for ease of user use
-## e.g. "rosrun someones_pkg node" instead of "rosrun someones_pkg someones_pkg_node"
-# set_target_properties(${PROJECT_NAME}_node PROPERTIES OUTPUT_NAME node PREFIX "")
-
-## Add cmake target dependencies of the executable
-## same as for the library above
-# add_dependencies(${PROJECT_NAME}_node ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})
-
-## Specify libraries to link a library or executable target against
-# target_link_libraries(${PROJECT_NAME}_node
-#   ${catkin_LIBRARIES}
-# )
-
-#############
-## Install ##
-#############
-
-# all install targets should use catkin DESTINATION variables
-# See http://ros.org/doc/api/catkin/html/adv_user_guide/variables.html
-
-## Mark executable scripts (Python etc.) for installation
-## in contrast to setup.py, you can choose the destination
-# catkin_install_python(PROGRAMS
-#   scripts/my_python_script
-#   DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
-# )
-
-## Mark executables for installation
-## See http://docs.ros.org/melodic/api/catkin/html/howto/format1/building_executables.html
-# install(TARGETS ${PROJECT_NAME}_node
-#   RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
-# )
-
-## Mark libraries for installation
-## See http://docs.ros.org/melodic/api/catkin/html/howto/format1/building_libraries.html
-# install(TARGETS ${PROJECT_NAME}
-#   ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
-#   LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
-#   RUNTIME DESTINATION ${CATKIN_GLOBAL_BIN_DESTINATION}
-# )
-
-## Mark cpp header files for installation
-# install(DIRECTORY include/${PROJECT_NAME}/
-#   DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION}
-#   FILES_MATCHING PATTERN "*.h"
-#   PATTERN ".svn" EXCLUDE
-# )
-
-## Mark other files for installation (e.g. launch and bag files, etc.)
-# install(FILES
-#   # myfile1
-#   # myfile2
-#   DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION}
-# )
-
-#############
-## Testing ##
-#############
-
-## Add gtest based cpp test target and link libraries
-# catkin_add_gtest(${PROJECT_NAME}-test test/test_yolov8-ros.cpp)
-# if(TARGET ${PROJECT_NAME}-test)
-#   target_link_libraries(${PROJECT_NAME}-test ${PROJECT_NAME})
-# endif()
-
-## Add folders to be run by python nosetests
-# catkin_add_nosetests(test)
+ament_package()