/ariitk_best_practices

Guidelines to writing a good package.

Primary LanguageC++

ariitk_best_practices

This repository contains a ROS node system that generates 3D pointclouds using PCL and fits them to either a plane or a sphere via RANSAC, visualizing the results in RViz.

Fig: Visualization of the plane and sphere models.

However, the main aim of this package is to outline the practices to be used while writing a ROS package.

The directory and file system is outlined below:-

  • install
    This folder contains the .rosinstall files whose primary role is to automatically clone all the package dependencies of your ROS package. For more information on the syntax and usage of rosinstall, please refer to this link.
    • install_https.rosinstall
      This is the sample rosinstall file for cloning the repository catkin_simple using https. More repositories can be added as required.
    • install_ssh.rosinstall This is the sample rosinstall file for cloning the same repository as above, but using ssh keys.
  • pcl_ransac
    This folder contains the code for the custom libraries that you have written for use in your ROS package. this should not contain any ROS code, and should be modular so that it can be used in other packages as well.
    • include
      • pcl_ransac
        • pcl_ransac.hpp
          These file(s) contains all the includes for the library, and the declarations for all the variables+functions in the library. All of this is put in a class/classes under the common namespace ariitk::pcl_ransac. If the function definitions are one-liners, they may be defined here. Otherwise only declarations are to be written here.
    • src
      • pcl_ransac.cpp
        These cpp file(s) contain the actual definitions for all the functions declared in the header files inside pcl_ransac/include/pcl_ransac/, in serial order.
    • test
      This folder contains the code for testing individual functions using googletest. Instead of running the entire code, you can check particular functions, whether they are producing the correct output or not.
      • src
        • pcl_ransac_test.cpp
          These file(s) contain the code for the test. For each function that you want to test, you need to write a seperate TEST() function. More details on how to write this code can be found here.
    • CMakeLists.txt
      Self explanatory. Note:We will use catkin_simple as it makes writing our CMakeLists.txt a lot easier. For more information please refer the above link.
    • package.xml
      Self explanatory. Link for reference.
  • pcl_ransac_msgs
    This package contains all the custom actions, messages and services that your main ROS package needs. Refer to the links to learn how to write these.
    • msg
      • CloudModel.msg / ModelCoefficients.msg These file(s) contain the definitions of custom messages required by your ROS package.
    • srv
      • ToggleModel.srv
        These file(s) contain the definitions of custom services required by your ROS package.
    • CMakeLists.txt
      Self explanatory.
    • package.xml
      Self explanatory.
  • pcl_ransac_ros
    This contains the main ROS package. All your package-specific code goes here.
    • cfg
      • pc_gen_params.yaml
        These file(s) have the parameters that you want to load everytime you run your ROS nodes. It is always a good idea to put as many constants/values here as possible, so you don't have to recompile everytime you change a value.
    • include
      • pcl_ransac_ros
        • point_cloud_pub.hpp, cloud_model_fit.hpp
          These file(s) contains all the includes for the ROS package, and the declarations for all the variables+functions in the ROS package. All of this is put in a class/classes under the common namespace ariitk::pcl_ransac_ros. If the function definitions are one-liners, they may be defined here. Otherwise only declarations are to be done here.
    • launch
      • default.launch
        Launch file(s) for launching your nodes, loading parameters, etc.
    • rviz
      • visualizer.rviz
        Configuration file(s) generated by rviz.
    • src
      • point_cloud_pub.cpp, cloud_model_fit.cpp
        These cpp file(s) contain the actual definitions for all the functions declared in the header files inside pcl_ransac_ros/include/pcl_ransac_ros/, in serial order.
      • pcl_ransac_ros_node.cpp These are the actual node(s) that your machine will run. This should be kept as de-cluttered as possible.
    • test
      As mentioned earlier, this folder contains the code for testing individual functions using googletest. More details on how to write this code can be found here.
    • CMakeLists.txt
      Self explanatory
    • package.xml Self explanatory
  • .clang-format
    This file contains the formatting settings to be used with clang-format. To use clang-format, please install it by running sudo apt-get install clang-format and running it with clang-format -style=file -i /path/to/file. Make sure that this file is present on your workspace or home directory. It is also recommended that you install the clang-format extension for whatever editor you are using, to avoid running this command for each file. Also please note that clang doesn't currently support indentation after access modifiers (like public: and private:) so you have to indent the code after these yourself. Also doesn't support newline after : while using initialization lists in constructor.
  • .gitignore
    This file contains the list of all the files that you don't want to push with your repositories, like configuration files (like .vscode in this example), images, videos, certain folders, etc. Follows linux standard file/directory naming scheme. Each new entry must be written on a new line. More information can be found here.
  • README.md
    This file contains the description of your ROS package. Concisely write about the purpose of your package, requirements and steps to run it. Describe any other details as necessary. Follows markdown syntax.