Create plugin template tutorial

README.md

@@ -11,3 +11,5 @@ Currently provided are:
 - [zstd_point_cloud_transport](https://github.com/ros-perception/point_cloud_transport_plugins/tree/master/zstd_point_cloud_transport) - A library using ZSTD to compress the pointclouds.
 
 More transports can be added. Pull requests are welcome!
+
+If it is not clear how to write a custom transport plugin, please see the `plugin_template` directory. This provides a template as well as written instructions for writing a custom transport plugin.

plugin_template/CMakeLists.txt

@@ -0,0 +1,58 @@
+# TODO (YourNameHere): This is not a working CMake Project! 
+# Some assembly required for your plugin. (-:
+
+cmake_minimum_required(VERSION 3.10.2)
+
+set(CMAKE_CXX_STANDARD 17)
+
+project(template_point_cloud_transport)
+
+find_package(ament_cmake REQUIRED)
+find_package(pluginlib REQUIRED)
+find_package(point_cloud_interfaces REQUIRED)
+find_package(point_cloud_transport REQUIRED)
+find_package(rclcpp REQUIRED)
+# TODO (YourNameHere): You might need more dependencies
+
+set(dependencies
+  pluginlib
+  point_cloud_interfaces
+  point_cloud_transport
+  rclcpp
+)
+
+
+include_directories(include)
+
+add_library(${PROJECT_NAME}
+  SHARED
+  # TODO (YourNameHere): You might need more source files
+  src/manifest.cpp
+  src/template_publisher.cpp
+  src/template_subscriber.cpp
+)
+
+ament_target_dependencies(${PROJECT_NAME} ${dependencies})
+
+install(TARGETS ${PROJECT_NAME}
+  ARCHIVE DESTINATION lib
+  LIBRARY DESTINATION lib
+  RUNTIME DESTINATION lib/${PROJECT_NAME}
+)
+
+install(
+  DIRECTORY include/${PROJECT_NAME}/
+  DESTINATION include/${PROJECT_NAME}
+)
+
+pluginlib_export_plugin_description_file(point_cloud_transport template_plugins.xml)
+
+if(BUILD_TESTING)
+  find_package(ament_lint_auto REQUIRED)
+  ament_lint_auto_find_test_dependencies()
+endif()
+
+ament_export_include_directories(include)
+ament_export_libraries(${PROJECT_NAME})
+ament_export_dependencies(${dependencies})
+ament_package()

plugin_template/README.md

@@ -0,0 +1,131 @@
+# \<TEMPLATE POINT CLOUD TRANSPORT>
+**ROS2 v0.1.**
+
+This repository serves as a tutorial on how to create a custom plugin for `point_cloud_transport`. It assumes that you already have a working `point_cloud_transport` installation.
+
+This is the spiritual successor to: https://github.com/paplhjak/templateplugin_point_cloud_transport and is heavily derived from it. In the ROS2 port, we opted to migrate the plugin tutorial but move it right next to the plugin code to avoid the instructions going stale. It is worth noting that there is nothing stopping the plugin you write from existing in a separate package or repo from `point_cloud_transport_plugins`.
+
+## 1) Plugin naming
+Each plugin needs its own name. It should be short and descriptive.
+
+For example: [draco_point_cloud_transport](https://github.com/ros-perception/point_cloud_transport_plugins/tree/rolling/draco_point_cloud_transport) is a plugin which uses Google [Draco](https://github.com/google/draco) compression, therefore the name **draco**.
+
+For demonstrative purposes, the plugin which we will be going through in this tutorial has used the name **template**. And we will be modifying the template to make our own plugin named **goblin**.
+
+## 2) Setup your plugin package
+
+Each transport plugin is its own ROS2 package. To create your own plugin package, let's clone the `point_cloud_transport_plugins` repo and make a copy of `plugin_template`:
+
+```bash
+$ cd /point_cloud_transport_ws/src
+$ git clone https://github.com/ros-perception/point_cloud_transport_plugins.git
+$ cp -r point_cloud_transport_plugins/plugin_template point_cloud_transport_plugins/goblin_point_cloud_transport
+```
+
+## 3) Time for Pattern Matching
+
+This template uses the plugin name **template**, which is referenced repeatedly in the source files. The files and classes implemented within the plugin follow a strict naming convention, inheriting from the name of the plugin. To follow the convention, we will replace each instance of **template** with the name of our new plugin. This can be done quickly using a case-sensitive find and replace tool. Most editors can invoke this tool. Once you make sure that the find is case-sensitive, go through the files in *ONLY* the `goblin_point_cloud_transport` folder, and make the following replacements:
+
+```
+1. TEMPLATE -> GOBLIN
+2. Template -> Goblin
+3. template_ -> goblin_
+4. "template" -> "goblin"
+```
+
+You can also rename the folders and files within the `goblin_point_cloud_transport` folder to match this convention. i.e.
+```
+1. *template_plugins.xml*
+2. *src/template_publisher.cpp*
+3. *src/template_subscriber.cpp*
+4. *include/template_point_cloud_transport/template_publisher.hpp*
+5. *include/template_point_cloud_transport/template_subscriber.hpp*
+```
+
+Be sure to double check that the `CMakeLists.txt` file points the expected files and that all the `#include`'s are still in order. Otherwise you will run into issues during the build phase.
+
+## 4) Custom Message (Optional)
+
+Although making your own compressed message type is an option, please check `point_cloud_interfaces` first to see if any existing compressed PointCloud2 message types already meet your needs. If they do, replace any instance of `CustomMessage` in the template package with that message's name, e.g. for `CompressedPointCloud2` (do not forget to check the #include's)
+
+```
+CustomMessage -> CompressedPointCloud2
+```
+
+If you do need a custom message, let's assume it is called **GobMessage**. See here if you are not familiar with defining a custom ROS2 message: https://docs.ros.org/en/rolling/index.html. 
+Once you have defined your **GobMessage**, go through the following files (do not forget to check the #include's):
+
+1. *goblin_publisher.h*
+2. *goblin_subscriber.h*
+3. *CMakeLists.txt*
+4. *goblin_publisher.cpp*
+5. *goblin_subscriber.cpp*
+6. *goblin_plugins.xml*
+
+and use the find and replace tool to replace the original name of **CustomMessage** with **GobMessage**.
+
+```
+CustomMessage -> GobMessage
+```
+
+## 5) Implementing Publisher Functionality
+
+Implementation of the publisher can be located in *src/goblin_publisher.cpp* within function *encodeTyped*.
+
+The encodeTyped function takes in a sensor_msgs::msg::PointCloud2 message, compresses it and converts the compressed data into our plugin's message format (see Step 4). You might have noticed that the plugin is only concerned with the compression / conversion process and does not call publish. This was done intentionally to separate concerns between plugin implementation and core point_cloud_transport functionality.
+
+## 6) Implementing Subscriber Functionality
+
+Implementation of the subscriber can be located in *src/goblin_subscriber.cpp* within function *decodeTyped*.
+
+The *decodeTyped* function takes in our plugin's message format, decompresses the data and converts it into a sensor_msgs::msg::PointCloud2. Once the point cloud message is ready, it is passed on to the subscriber callback. Just like in the publisher plugin, the subscriber plugin is only concerned with decoding and conversion. It does not actually call the subscriber callback.
+
+## 7) Description of Plugin
+
+Before we distribute our plugin, it is important that we fill in all the necessary information about it. 
+
+In goblin_plugins.xml, make sure to provide a brief description of both the publisher and the subscriber our plugin uses.
+
+Then fill out the package.xml. If you are unfamiliar with how to do this, see here please: https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Creating-Your-First-ROS2-Package.html#customize-package-xml.
+
+## 8) Build time!
+
+At this point your plugin should be able to succesfully compile, build, and be recognized by [point_cloud_transport](https://github.com/ros-perception/point_cloud_transport). 
+
+First, delete the COLCON_IGNORE file in `globlin_point_cloud_transport` (otherwise your package will be ignored).
+
+Build the plugin.
+
+```bash
+$ cd /point_cloud_transport_ws
+$ colcon build --merge-install --event-handlers console_direct+
+```
+
+Then check all plugins currently available on your system by running the command:
+
+``` bash
+source install/setup.bash
+ros2 run point_cloud_transport list_transports
+```
+
+The output should look something like this.
+
+```
+"point_cloud_transport/goblin"
+ - Provided by package: goblin_point_cloud_transport
+ - Publisher: 
+            This plugin publishes a CompressedPointCloud2 using the awesome power of turtles.
+
+ - Subscriber: 
+            This plugin decompresses a CompressedPointCloud2 topic, also using turtles.
+```
+
+Do you see your plugin? If not, please look back through these instructions and through the plugin code to verify you replaced all the instances of **template** with **goblin** and that the CMakeLists.txt and package.xml files are up to date w.r.t. file naming and any dependencies you have added.
+
+Support
+=======
+
+If you have found an error in these instructions, please file an issue at: [https://github.com/ros-perception/point_cloud_transport/issues]()
+
+Patches are encouraged, and may be submitted by forking this project and
+submitting a pull request through GitHub. Any help is further development of the project is much appreciated.

plugin_template/include/template_point_cloud_transport/template_publisher.hpp

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) <Current Year>, <Your Name Here> (if desired)
+ * Copyright (c) 2023, Open Source Robotics Foundation, Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ *    * Redistributions of source code must retain the above copyright
+ *      notice, this list of conditions and the following disclaimer.
+ *
+ *    * Redistributions in binary form must reproduce the above copyright
+ *      notice, this list of conditions and the following disclaimer in the
+ *      documentation and/or other materials provided with the distribution.
+ *
+ *    * Neither the name of the copyright holder nor the names of its
+ *      contributors may be used to endorse or promote products derived from
+ *      this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef TEMPLATE_POINT_CLOUD_TRANSPORT__TEMPLATE_PUBLISHER_HPP_
+#define TEMPLATE_POINT_CLOUD_TRANSPORT__TEMPLATE_PUBLISHER_HPP_
+
+#include <string>
+
+#include <sensor_msgs/msg/point_cloud2.hpp>
+
+#include <point_cloud_transport/point_cloud_transport.hpp>
+
+#include <point_cloud_transport/simple_publisher_plugin.hpp>
+#include <point_cloud_interfaces/msg/custom_message.hpp>
+
+
+namespace template_point_cloud_transport
+{
+
+// CustomMessage could be any ROS2 message.
+// e.g. point_cloud_interfaces::msg::CompressedPointCloud2, or you can make a new one. If you do, please
+// add the definiton to point_cloud_interfaces.
+class TemplatePublisher
+  : public point_cloud_transport::SimplePublisherPlugin<
+    point_cloud_interfaces::msg::CustomMessage>
+{
+public:
+  std::string getTransportName() const override;
+
+  void declareParameters(const std::string & base_topic) override;
+
+  std::string getDataType() const override
+  {
+    // return the name of whichever message you chose as a string
+    return "point_cloud_interfaces/msg/CustomMessage";
+  }
+
+  TypedEncodeResult encodeTyped(const sensor_msgs::msg::PointCloud2 & raw) const override;
+
+private:
+  // good place to put any internal variables (e.g. compression algo parameters)
+};
+}  // namespace template_point_cloud_transport
+
+#endif  // TEMPLATE_POINT_CLOUD_TRANSPORT__TEMPLATE_PUBLISHER_HPP_

plugin_template/include/template_point_cloud_transport/template_subscriber.hpp

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) <Current Year>, <Your Name Here> (if desired)
+ * Copyright (c) 2023, Open Source Robotics Foundation, Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ *    * Redistributions of source code must retain the above copyright
+ *      notice, this list of conditions and the following disclaimer.
+ *
+ *    * Redistributions in binary form must reproduce the above copyright
+ *      notice, this list of conditions and the following disclaimer in the
+ *      documentation and/or other materials provided with the distribution.
+ *
+ *    * Neither the name of the copyright holder nor the names of its
+ *      contributors may be used to endorse or promote products derived from
+ *      this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef TEMPLATE_POINT_CLOUD_TRANSPORT__TEMPLATE_SUBSCRIBER_HPP_
+#define TEMPLATE_POINT_CLOUD_TRANSPORT__TEMPLATE_SUBSCRIBER_HPP_
+
+#include <string>
+
+#include <point_cloud_interfaces/msg/custom_message.hpp>
+
+#include <point_cloud_transport/simple_subscriber_plugin.hpp>
+#include <point_cloud_transport/transport_hints.hpp>
+
+namespace template_point_cloud_transport
+{
+
+// CustomMessage could be any ROS2 message.
+// e.g. point_cloud_interfaces::msg::CompressedPointCloud2, or you can make a new one. If you do, please
+// add the definiton to point_cloud_interfaces.
+class TemplateSubscriber
+  : public point_cloud_transport::SimpleSubscriberPlugin<
+    point_cloud_interfaces::msg::CustomMessage>
+{
+public:
+  std::string getTransportName() const override;
+
+  void declareParameters() override;
+
+  std::string getDataType() const override
+  {
+    // return the name of whichever message you chose as a string
+    return "point_cloud_interfaces/msg/CustomMessage";
+  }
+
+  DecodeResult decodeTyped(const point_cloud_interfaces::msg::CustomMessage & compressed)
+  const override;
+private:
+  // good place to put any internal variables (e.g. decompression algo parameters)
+};
+}  // namespace template_point_cloud_transport
+
+#endif  // TEMPLATE_POINT_CLOUD_TRANSPORT__TEMPLATE_SUBSCRIBER_HPP_

plugin_template/package.xml

@@ -0,0 +1,31 @@
+<package format="3">
+  <name>template_point_cloud_transport</name>
+  <version>0.0.0</version>
+  <description>
+    template_point_cloud_transport is not a real transport plugin. It is just a template to reference when
+    making new point_cloud_transport plugins.
+  </description>
+  <author>YourNameHere</author>
+  <maintainer email="[email protected]">YourNameHere</maintainer>
+  <license>BSD</license>
+
+  <url type="repository">https://github.com/rolling/point_cloud_transport_plugins</url>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+
+  <build_depend>pluginlib</build_depend>
+
+  <exec_depend>pluginlib</exec_depend>
+
+  <!-- TODO (YourNameHere): You might need more dependencies-->
+  <depend>point_cloud_interfaces</depend>
+  <depend>point_cloud_transport</depend>
+  <depend>rclcpp</depend>
+
+  <test_depend>ament_lint_auto</test_depend>
+  <test_depend>ament_lint_common</test_depend>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>