diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..ee76499 --- /dev/null +++ b/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 all ROS 2-related Python code. All 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. diff --git a/README.md b/README.md index 2531d72..0769b85 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # YOLOv8 ROS Integration This repository contains Python modules and a dependency specification to use -Ultralytics YOLOv8 with ROS. +Ultralytics YOLOv8 with ROS. Additional documentation about how this repository is +organized can be found in [`ARCHITECTURE.md`](/ARCHITECTURE.md). ## Getting Started