cras_cpp_common

A Czech-army knife for ROS code written in C++.

The aim of this package is to provide some missing utility functions to roscpp. Using libraries from this package, you should be able to write more efficient, safer and less error-prone code without much boilerplate. As this package is intended to handle a lot of the boring code for you “behind the scenes”, ubiquitous effort was put into unit-testing everything, so that you can rely on the provided code without the usual fear whether it works or not.

This readme shortly introduces the provided libraries. Detailed documentation can be found in the comments in code and in the API docs. Examples of usage can be found in the dependent packages from ros-utils, and in the unit tests.

Parts of this package were used by team CTU-CRAS-Norlab in DARPA Subterranean Challenge.

Support and Build Status

This package is supported on Melodic and Noetic until their End of Life (and maybe later). It is occasionally tested with non-default GCC versions like Melodic+GCC8 or Noetic+GCC11.

Development versions:

Release jobs Melodic : Buildfarm no longer builds Melodic, but compatibility is still kept.

Release jobs Noetic :

List of provided libraries

• any: Provides forward compatibility for std::any.
• c_api: Utilities for writing a C API for your packages.
• cloud, tf2_sensor_msgs: Utilities for working with pointclouds (iterators, copying, extracting channels, transforming the clouds).
• diag_utils: Helpers for easy setup of a diagnosed publisher/subscriber that checks message rate or delay. Configuration of the expected rates/delays is via ROS parameters.
• expected: Provides forward compatibility for std::expected.
• filter_utils:
  • FilterBase eases access to filter parameters via param_utils.
  • FilterChain class and nodelet improve upon filters::FilterChain by adding support for dynamic disabling/enabling of individual filters, diagnostics of the individual filters and possibility to publish the intermediate filtering results.
• functional: Provides forward compatibility for std::apply(), std::invoke() and std::bind_front(). Especially cras::bind_front() is super useful for specifying ROS subscriber callbacks, where you just bind this to the callback, and the rest of the parameters is automatically handled.
• log_utils: Unified access to the ROS_* and NODELET_* logging macros. This is more an internal utility of this package.
• math_utils: sgn() signum function, and RunningStats (computes mean and variance on a stream of data in O(1) time per sample).
• message_utils: BaseMessage<M> and IsMessageParam<M> template helpers for working with ROS message classes.
• node_utils: Integration of diag_utils and param_utils for ROS nodes.
• nodelet_utils:
  • cras::Nodelet base class provides integration of diag_utils and param_utils for nodelets, adds the ability to update name of the current thread with name of the nodelet, adds support for sharing a single TF buffer between multiple nodelets, and provides an ok() method that is similar to ros::ok(), but starts returning false when the nodelet is being unloaded.
  • nodelet_manager_sharing_tf_buffer is a customized nodelet manager that is able to share its own (single) TF buffer to multiple nodelets (based on cras::Nodelet).
• optional: Provides forward compatibility for std::optional.
• param_utils: Utilities for type-safe, easy, unified and configurable access to ROS parameters. See below for examples and more details.
• pool_allocator: Provides a memory-pool-based allocator for ROS messages. It comes handy if you want to publish shared pointer messages on a high rate - it should decrease the time needed for object allocation via new.
• rate_limiter: Library for intelligent rate-limiting of events (mainly messages). So far it implements the algorithm from topic_tools throttle (not very good), and token bucket algorithm (pretty good for most cases).
• set_utils: Provides isSetIntersectionEmpty() working on a pair of std::sets.
• small_map: Provides SmallMap and SmallSet, variants of std::map implemented using std::list which are append-only and lock-free for reading.
• span: Provides forward compatibility for std::span.
• string_utils: Provides many string manipulation helpers you’ve always dreamed of. Universal to_string() that converts almost anything to a sensible string. startsWith()/endsWith(), replace(), contains(), split()/join(), format() (like sprintf() but without hassle and on std::string), stripLeading()/stripTrailing(), removePrefix()/removeSuffix(), parseFloat()/parseDouble() (convert string to double independent of locale!), parseInt32() and friends (parse many textual representations to an integer, or with specified radix). parseTime() and parseDuration() to parse textual date/time strings to ros::Time and ros::Duration. toValidRosName() to convert any input string to a valid ROS graph resource name.
• suppress_warnings: Unified macros that suppress various compiler warnings for a piece of code.
• test_utils: Provide a hack that allows loading a locally-defined nodelet without the need to register it via package.xml.
• tf2_utils: getRoll(), getPitch(), getYaw(), getRPY() from a tf2::Quaternion or geometry_msgs::Quaternion!
  • Also provides InterruptibleTFBuffer that can cooperate with cras::Nodelet and stop a TF lookup if the nodelet is being unloaded (normally, the lookup freezes when you pause simulation time).
• thread_utils: getThreadName() and setThreadName().
  • Also provides ReverseSemaphore synchronization primitive that counts towards zero and notifies when empty.
• time_utils: remainingTime() tells you how much of a timeout remains if you started waiting at some specified time. Conversions between ros::Rate() and frequency. Multiplication and division operators for ROS duration types. Seamless conversions between WallTime, Time and SteadyTime using convertTime(). Similarly, convertDuration().
• type_utils: Provides compile-time and run-time getTypeName() helper that converts a C++ type to a string containing its name.
• urdf_utils: Conversions between urdf and Eigen types.
• xmlrpc_value_traits: Type traits for XmlRpc::XmlRpcValue.
• xmlrpc_value_utils: Conversions between XmlRpc::XmlRpcValue and C++ and STL types.

List of provided CMake helpers

• node_from_nodelet: Easily convert a nodelet into a standalone node executable. See cras_topic_tools package for an example.

param_utils: Parameter Reading Helpers

param_utils, node_utils, nodelet_utils and filter_utils provide a type-safe, unified and highly configurable interface for reading ROS parameters. Use the same syntax to read parameters of a node, nodelet, filter, or a custom XmlRpcValue struct. Read an Eigen matrix, vector of unsigned ints, ros::Duration or geometry_msgs::Vector3 directly without the need to write a single line of conversion code or value checking. Type of the value to read is automatically determined either from the provided default value, or from template parameter of the getParam<>() function.

Example usage:

// Usage in a nodelet based on `cras::Nodelet`:
// read a parameter of size_t type defaulting to 10 if not set.
// The _sz suffix is a helper to convert a numeric literal to size_t type.
const auto params = this->privateParams();
const size_t queueSize = params->getParam("queue_size", 10_sz, "messages");

// Usage in a node:
// read array of 3 doubles from parameter server into a tf2::Vector3, defaulting to the specified vector if not set.
cras::NodeParamHelper params("~");
const tf2::Vector3 gravity = params->getParam("gravity", tf2::Vector3(0, 0, -9.81), "m.s^-2");

// Usage in a filter based on cras::FilterBase:
// read a required ros::Duration parameter from a float
// the nullopt specifies instead of the default value specifies it is required.
const ros::Duration timeout = this->getParam<ros::Duration>("timeout", cras::nullopt);

// Usage directly from a XmlRpcValue dict
// read an Eigen::Vector3d from a XmlRpcValue array
XmlRpc::XmlRpcValue values;
values["offset"][0] = 1; values["offset"][1] = 2; values["offset"][2] = 3; 
auto logger = std::make_shared<cras::NodeLogHelper>();
auto paramHelper = std::make_shared<cras::XmlRpcValueGetParamAdapter>(values, "");
BoundParamHelper params(logger, paramHelper);
const Eigen::Vector3d offset = params->getParam("offset", Eigen::Vector3d::UnitX());

File truncated at 100 lines see the full file

Changelog for package cras_cpp_common

2.5.1 (2025-02-18)

2.5.0 (2025-02-13)

2.4.8 (2025-01-07)

• Added GetParamConvertingOptions() to ease defining converting getParam() that works with GCC 7.
• Added NodeWithOptionalMaster.
• Improved compatibility with newer compilers. Resolves https://github.com/RoboStack/ros-noetic/pull/501#issuecomment-2567224502 .
• Contributors: Martin Pecka

2.4.7 (2024-12-12)

• Fixed installation of nodelet_manager_sharing_tf_buffer.
• Contributors: Martin Pecka

2.4.6 (2024-12-12)

• nodelet_utils: Allowed accessing the shared_ptr of the shared TF buffer.
• node_from_nodelet: Worked around the bug where remapping private topics was impossible for anonymous nodes.
• tf2_utils: Added TfMessageFilter compatible with log_utils.
• time_utils: Added converters between ros::Time and struct tm.
• Fixed a few printf format issues.
• string_utils: Handle possible error in vsnprintf. Added printf-format attributes to cras::format() to enable compile-time checks of format strings.
• string_utils: Added iconvConvert(), transliterateToAscii() and toValidRosName() functions.
• Contributors: Martin Pecka

2.4.5 (2024-11-02)

• string_utils: Added date/time parsing methods.
• string_utils: Added methods for parsing integers with known radix.
• diag_utils: Added tests for offline diag updater.
• diag_utils: Added offline diag updater.
• node_from_nodelet: Added support for stopping the node when requestStop() has been called in the nodelet code.
• Contributors: Martin Pecka

2.4.4 (2024-09-14)

• Fixed roslint.
• Contributors: Martin Pecka

2.4.3 (2024-09-14)

• Fixed build with ros_comm 1.17.0 .
• Contributors: Martin Pecka

2.4.2 (2024-09-05)

2.4.1 (2024-09-04)

• Fixed roslint
• Contributors: Martin Pecka

2.4.0 (2024-09-04)

• Added small_map and fixed concurrency problems in log_utils.
• Updated fast_float to 6.1.5.
• node_from_nodelet: Fixed error message
• Contributors: Martin Pecka

2.3.9 (2024-02-27)

• Removed catkin_lint buildfarm hacks.
• Updated to fast_float 6.1.0 .
• Contributors: Martin Pecka

2.3.8 (2024-01-12)

• Fixed FindFilesystem CMake module usage of try_compile
• Contributors: Martin Pecka

2.3.7 (2024-01-09)

• node_from_nodelet: Fix syntax for Melodic.
• Contributors: Martin Pecka

2.3.6 (2024-01-09)

• node_from_nodelet: Implemented a simplified version that doesn't need the nodelet header file.
• node_from_nodelet: Fixed a bug with missing return 0 at the end of main.
• Contributors: Martin Pecka

2.3.5 (2023-11-21)

• param_utils: Added getParam() specialization for geometry_msgs/Pose messages.
• nodelet_utils: Added Resettable interface to

File truncated at 100 lines see the full file