cras_py_common package from cras_ros_utils repocamera_throttle cras_bag_tools cras_cpp_common cras_docs_common cras_py_common cras_topic_tools image_transport_codecs tf_static_publisher |
|
Package Summary
Tags | No category tags. |
Version | 2.4.4 |
License | BSD |
Build type | CATKIN |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ctu-vras/ros-utils.git |
VCS Type | git |
VCS Version | master |
Last Updated | 2024-09-14 |
Dev Status | DEVELOPED |
CI status |
|
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Martin Pecka
Authors
- Martin Pecka
cras_py_common
A Czech-army knife for ROS code written in Python.
The aim of this package is to provide some missing utility functions to rospy. 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.
List of Provided Modules
The most useful functions and classes from these modules are available directly from the cras
package, i.e.
from cras import to_str
# instead of
from cras.string_utils import to_str
-
ctypes_utils
: Utilities for working with the ctypes library. -
geometry_utils
: Finally THE module providing easy and foolproof conversion between quaternions and roll/pitch/yaw notation. -
log_utils
: Some convenience forrospy
logging. Provideslog*_once_identical()
functions to log unique messages. -
message_utils
: Conversion ofstd_msgs/String
to Python type etc. Generic access to message fields using a string “address”. -
node_utils
: Utilities for easier writing of nodes, adding e.g. easy-to-writereset()
function that is automatically called when ROS time jumps back/forward. -
param_utils
: Utilities for type-safe, easy, unified and configurable access to ROS parameters. See below for examples and more details. -
python_utils
: General Python utilities. -
static_transform_broadcaster
: An drop-in replacement oftf2_ros.static_transform_broadcaster
that can safely publish multiple transforms from a single node (upstreaming to tf2_ros in progress). -
string_utils
: Universalto_str()
that converts almost anything to a sensible string. -
test_utils
: Utilities for writing unit tests, e.g. a tool that can “read” what was written byrospy.loginfo()
. -
time_utils
: Conversions betweenrospy.Rate
and frequency.rospy.Rate
equality comparison. Min/max time and duration constants.WallTime
,WallRate
,SteadyTime
,SteadyRate
, and aTimer
that can use these custom rates. -
topic_utils
: Generic topic subscriber.
node_utils
: Resettable nodes
Nodes can support resetting of their state. This is a concept very useful for simulation or postprocessing. Each node that supports resetting should be marked like this in its documentation:
Note This node is resettable and checks for time jumps.
This particularly means that the node subscribes to topics /reset
and ~reset
(any type). Whenever a message is received on either of these topics, the node’s reset()
method is called.
Resetting is also done automatically any time the node figures out ROS time jumped back/forward too much. It is configured via these parameters:
-
/jump_back_tolerance
(float, default 3.0 in wall time and 0.0 in sim time): Threshold for ROS time jump back detection. -
~jump_back_tolerance
(float, default from/jump_back_tolerance
): Threshold for ROS time jump back detection. -
~reset_on_time_jump_back
(bool, default True): Whether to callreset()
when ROS time jumps back. -
/jump_forward_tolerance
(float, default 10.0 in sim time and max duration in wall time): Threshold for ROS time jump forward detection. -
~jump_forward_tolerance
(float, default from/jump_forward_tolerance
): Threshold for ROS time jump forward detection. -
~reset_on_time_jump_forward
(bool, default True in sim time and False in wall time): Whether to callreset()
when ROS time jumps forward.
The node should either call self.check_time_jump()
in each message callback, or call self.start_auto_check_time_jump()
when the node is initialized (this runs a background thread doing the checks).
Please note that you may have to increase the jump forward tolerance if playing bag files with very high rates. In such case, it is safer to increase the threshold to 60 seconds or even more.
param_utils
: Parameter Reading Helpers
param_utils
provide a type-safe, unified and highly configurable interface for reading ROS parameters. Read a numpy matrix, vector of unsigned ints, rospy.Duration
or geometry_msgs.msg.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 result_type
parameter.
Example usage:
from cras import get_param, GetParamException
from geometry_msgs.msg import Vector3
# read array of 3 doubles from parameter server into a geometry_msgs.msg.Vector3, defaulting to the specified vector if not set.
gravity = get_param("gravity", Vector3(0, 0, -9.81), "m.s^-2")
# required parameters are specified by not having a default; if you still want conversion to some type, use result_type
try:
gravity2 = get_param("gravity", "m.s^-2", result_type=Vector3)
except GetParamException as e:
# the exception is raised if the required parameter is not set
# e.info contains details about the unsuccessful lookup
print(e.info.message)
You can also configure the parameter lookup behavior, e.g. to throw exception if the value cannot be converted to the requested type (normally, the default value is used in such case):
# will throw GetParamException if int_param has a value different from 0 and 1
from cras import get_param
bool_param = get_param("int_param", False, throw_if_convert_fails=True)
Finally, there is also a more verbose version of get_param()
that tells more about how the lookup went:
from cras import get_param_verbose
res = get_param_verbose("int", 0)
int_param = res.value
was_default_used = res.info.default_used
Changelog for package cras_py_common
2.4.4 (2024-09-14)
2.4.3 (2024-09-14)
2.4.2 (2024-09-05)
- log_utils: Addded log_once_identical() functions.
- log_utils: Fixed stack information for cras.log().
- Contributors: Martin Pecka
2.4.1 (2024-09-04)
2.4.0 (2024-09-04)
- string_utils: Fixed iconv functions when running with LC_ALL=C or other weird locale.
- Added python_utils.
- string_utils: Added methods for iconv-like conversions of strings and sanitization or ROS names.
- Contributors: Martin Pecka
2.3.9 (2024-02-27)
- Removed catkin_lint buildfarm hacks.
- Contributors: Martin Pecka
2.3.8 (2024-01-12)
2.3.7 (2024-01-09)
2.3.6 (2024-01-09)
2.3.5 (2023-11-21)
2.3.4 (2023-10-25)
2.3.3 (2023-10-06)
2.3.2 (2023-10-06)
- param_utils: Removed deprecated numpy aliases.
- Contributors: Martin Pecka
2.3.1 (2023-07-13)
2.3.0 (2023-07-12)
- Increased minimum CMake version to 3.10.2.
- Contributors: Martin Pecka
2.2.3 (2023-06-16)
2.2.2 (2023-05-15)
- ctypes_utils: Added ScalarAllocator.
- Contributors: Martin Pecka
2.2.1 (2023-05-15)
- message_utils: Added dict_to_dynamic_config_msg().
- ctypes_utils: Added c_array() method.
- message_utils: Added get_srv_types() and get_cfg_module().
- Contributors: Martin Pecka
2.2.0 (2023-04-09)
2.1.2 (2023-02-10)
2.1.1 (2023-02-08)
2.1.0 (2023-02-08)
- ctypes_utils: Added specialized allocators for ROS messages and for rosconsole logs.
- string_utils: Register genpy Time and Duration for to_str() conversion, too.
- ctypes_utils: Do not add one byte to StringAlloc allocated size. The caller has to do it now.
- ctypes_utils: Autodetection of length of a BufferStringIO stream.
- ctypes_utils: Added get_ro_c_buffer.
- Added utilities for working with ctypes.
- Allow resetting nodes by topic.
- Added support for enums in to_str() and param utils.
- Hide tf2_ros includes in geometry_utils.py inside function calls.
- Contributors: Martin Pecka
2.0.10 (2022-11-24)
- Fix test bug.
- Contributors: Martin Pecka
2.0.9 (2022-11-24)
- Relay attribute access in GenericMessageSubscriber to the raw subscriber (to allow e.g. calling unsubscribe()).
- Contributors: Martin Pecka
2.0.8 (2022-11-24)
- Pass connection header to user callback in GenericMessageSubscriber.
- Contributors: Martin Pecka
2.0.7 (2022-11-24)
- Moved get_msg_type from type_utils to message_utils and added get_msg_field there.
- Contributors: Martin Pecka
2.0.6 (2022-11-24)
- Added topic_utils and type_utils.
- Contributors: Martin Pecka
2.0.5 (2022-10-23)
- Added static_transform_broadcaster docs to readme.
- Contributors: Martin Pecka
2.0.4 (2022-10-14)
- Fixed StaticTransformBroadcaster on Noetic and added unit test for it.
- Added missing license notices.
- Contributors: Martin Pecka
2.0.3 (2022-10-07)
- Improved time_utils, added node_utils.
- Added geometry_utils.py.
- Remove support for long integer type to achieve compatibility with Python 3.
- Extended functionality to get closer to cras_cpp_common.
- Improved readmes and added more badges to them.
- Contributors: Martin Pecka
2.0.2 (2022-08-29)
- De-flake throttle test and enable catkin_lint when it has chance to run correctly.
- Added website links.
- Add linters and licenses.
- Contributors: Martin Pecka
2.0.1 (2022-08-26)
- Moved hack_frame_id from cras_py_common to cras_topic_tools.
1.0.0
- Added improved static_transform_broadcaster for Python.
- Added hack_frame_id
- Added cras_py_common
- Contributors: Martin Pecka
Wiki Tutorials
Package Dependencies
Deps | Name |
---|---|
catkin | |
dynamic_reconfigure | |
geometry_msgs | |
rosgraph | |
rosgraph_msgs | |
rospy | |
tf | |
tf2_msgs | |
tf2_ros | |
cras_docs_common | |
rosdoc_lite | |
cras_cpp_common | |
roslint | |
rostest | |
rosunit |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged cras_py_common at Robotics Stack Exchange
cras_py_common package from cras_ros_utils repocamera_throttle cras_bag_tools cras_cpp_common cras_docs_common cras_py_common cras_topic_tools image_transport_codecs tf_static_publisher |
|
Package Summary
Tags | No category tags. |
Version | 2.4.4 |
License | BSD |
Build type | CATKIN |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/ctu-vras/ros-utils.git |
VCS Type | git |
VCS Version | master |
Last Updated | 2024-09-14 |
Dev Status | DEVELOPED |
CI status |
|
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Martin Pecka
Authors
- Martin Pecka
cras_py_common
A Czech-army knife for ROS code written in Python.
The aim of this package is to provide some missing utility functions to rospy. 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.
List of Provided Modules
The most useful functions and classes from these modules are available directly from the cras
package, i.e.
from cras import to_str
# instead of
from cras.string_utils import to_str
-
ctypes_utils
: Utilities for working with the ctypes library. -
geometry_utils
: Finally THE module providing easy and foolproof conversion between quaternions and roll/pitch/yaw notation. -
log_utils
: Some convenience forrospy
logging. Provideslog*_once_identical()
functions to log unique messages. -
message_utils
: Conversion ofstd_msgs/String
to Python type etc. Generic access to message fields using a string “address”. -
node_utils
: Utilities for easier writing of nodes, adding e.g. easy-to-writereset()
function that is automatically called when ROS time jumps back/forward. -
param_utils
: Utilities for type-safe, easy, unified and configurable access to ROS parameters. See below for examples and more details. -
python_utils
: General Python utilities. -
static_transform_broadcaster
: An drop-in replacement oftf2_ros.static_transform_broadcaster
that can safely publish multiple transforms from a single node (upstreaming to tf2_ros in progress). -
string_utils
: Universalto_str()
that converts almost anything to a sensible string. -
test_utils
: Utilities for writing unit tests, e.g. a tool that can “read” what was written byrospy.loginfo()
. -
time_utils
: Conversions betweenrospy.Rate
and frequency.rospy.Rate
equality comparison. Min/max time and duration constants.WallTime
,WallRate
,SteadyTime
,SteadyRate
, and aTimer
that can use these custom rates. -
topic_utils
: Generic topic subscriber.
node_utils
: Resettable nodes
Nodes can support resetting of their state. This is a concept very useful for simulation or postprocessing. Each node that supports resetting should be marked like this in its documentation:
Note This node is resettable and checks for time jumps.
This particularly means that the node subscribes to topics /reset
and ~reset
(any type). Whenever a message is received on either of these topics, the node’s reset()
method is called.
Resetting is also done automatically any time the node figures out ROS time jumped back/forward too much. It is configured via these parameters:
-
/jump_back_tolerance
(float, default 3.0 in wall time and 0.0 in sim time): Threshold for ROS time jump back detection. -
~jump_back_tolerance
(float, default from/jump_back_tolerance
): Threshold for ROS time jump back detection. -
~reset_on_time_jump_back
(bool, default True): Whether to callreset()
when ROS time jumps back. -
/jump_forward_tolerance
(float, default 10.0 in sim time and max duration in wall time): Threshold for ROS time jump forward detection. -
~jump_forward_tolerance
(float, default from/jump_forward_tolerance
): Threshold for ROS time jump forward detection. -
~reset_on_time_jump_forward
(bool, default True in sim time and False in wall time): Whether to callreset()
when ROS time jumps forward.
The node should either call self.check_time_jump()
in each message callback, or call self.start_auto_check_time_jump()
when the node is initialized (this runs a background thread doing the checks).
Please note that you may have to increase the jump forward tolerance if playing bag files with very high rates. In such case, it is safer to increase the threshold to 60 seconds or even more.
param_utils
: Parameter Reading Helpers
param_utils
provide a type-safe, unified and highly configurable interface for reading ROS parameters. Read a numpy matrix, vector of unsigned ints, rospy.Duration
or geometry_msgs.msg.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 result_type
parameter.
Example usage:
from cras import get_param, GetParamException
from geometry_msgs.msg import Vector3
# read array of 3 doubles from parameter server into a geometry_msgs.msg.Vector3, defaulting to the specified vector if not set.
gravity = get_param("gravity", Vector3(0, 0, -9.81), "m.s^-2")
# required parameters are specified by not having a default; if you still want conversion to some type, use result_type
try:
gravity2 = get_param("gravity", "m.s^-2", result_type=Vector3)
except GetParamException as e:
# the exception is raised if the required parameter is not set
# e.info contains details about the unsuccessful lookup
print(e.info.message)
You can also configure the parameter lookup behavior, e.g. to throw exception if the value cannot be converted to the requested type (normally, the default value is used in such case):
# will throw GetParamException if int_param has a value different from 0 and 1
from cras import get_param
bool_param = get_param("int_param", False, throw_if_convert_fails=True)
Finally, there is also a more verbose version of get_param()
that tells more about how the lookup went:
from cras import get_param_verbose
res = get_param_verbose("int", 0)
int_param = res.value
was_default_used = res.info.default_used
Changelog for package cras_py_common
2.4.4 (2024-09-14)
2.4.3 (2024-09-14)
2.4.2 (2024-09-05)
- log_utils: Addded log_once_identical() functions.
- log_utils: Fixed stack information for cras.log().
- Contributors: Martin Pecka
2.4.1 (2024-09-04)
2.4.0 (2024-09-04)
- string_utils: Fixed iconv functions when running with LC_ALL=C or other weird locale.
- Added python_utils.
- string_utils: Added methods for iconv-like conversions of strings and sanitization or ROS names.
- Contributors: Martin Pecka
2.3.9 (2024-02-27)
- Removed catkin_lint buildfarm hacks.
- Contributors: Martin Pecka
2.3.8 (2024-01-12)
2.3.7 (2024-01-09)
2.3.6 (2024-01-09)
2.3.5 (2023-11-21)
2.3.4 (2023-10-25)
2.3.3 (2023-10-06)
2.3.2 (2023-10-06)
- param_utils: Removed deprecated numpy aliases.
- Contributors: Martin Pecka
2.3.1 (2023-07-13)
2.3.0 (2023-07-12)
- Increased minimum CMake version to 3.10.2.
- Contributors: Martin Pecka
2.2.3 (2023-06-16)
2.2.2 (2023-05-15)
- ctypes_utils: Added ScalarAllocator.
- Contributors: Martin Pecka
2.2.1 (2023-05-15)
- message_utils: Added dict_to_dynamic_config_msg().
- ctypes_utils: Added c_array() method.
- message_utils: Added get_srv_types() and get_cfg_module().
- Contributors: Martin Pecka
2.2.0 (2023-04-09)
2.1.2 (2023-02-10)
2.1.1 (2023-02-08)
2.1.0 (2023-02-08)
- ctypes_utils: Added specialized allocators for ROS messages and for rosconsole logs.
- string_utils: Register genpy Time and Duration for to_str() conversion, too.
- ctypes_utils: Do not add one byte to StringAlloc allocated size. The caller has to do it now.
- ctypes_utils: Autodetection of length of a BufferStringIO stream.
- ctypes_utils: Added get_ro_c_buffer.
- Added utilities for working with ctypes.
- Allow resetting nodes by topic.
- Added support for enums in to_str() and param utils.
- Hide tf2_ros includes in geometry_utils.py inside function calls.
- Contributors: Martin Pecka
2.0.10 (2022-11-24)
- Fix test bug.
- Contributors: Martin Pecka
2.0.9 (2022-11-24)
- Relay attribute access in GenericMessageSubscriber to the raw subscriber (to allow e.g. calling unsubscribe()).
- Contributors: Martin Pecka
2.0.8 (2022-11-24)
- Pass connection header to user callback in GenericMessageSubscriber.
- Contributors: Martin Pecka
2.0.7 (2022-11-24)
- Moved get_msg_type from type_utils to message_utils and added get_msg_field there.
- Contributors: Martin Pecka
2.0.6 (2022-11-24)
- Added topic_utils and type_utils.
- Contributors: Martin Pecka
2.0.5 (2022-10-23)
- Added static_transform_broadcaster docs to readme.
- Contributors: Martin Pecka
2.0.4 (2022-10-14)
- Fixed StaticTransformBroadcaster on Noetic and added unit test for it.
- Added missing license notices.
- Contributors: Martin Pecka
2.0.3 (2022-10-07)
- Improved time_utils, added node_utils.
- Added geometry_utils.py.
- Remove support for long integer type to achieve compatibility with Python 3.
- Extended functionality to get closer to cras_cpp_common.
- Improved readmes and added more badges to them.
- Contributors: Martin Pecka
2.0.2 (2022-08-29)
- De-flake throttle test and enable catkin_lint when it has chance to run correctly.
- Added website links.
- Add linters and licenses.
- Contributors: Martin Pecka
2.0.1 (2022-08-26)
- Moved hack_frame_id from cras_py_common to cras_topic_tools.
1.0.0
- Added improved static_transform_broadcaster for Python.
- Added hack_frame_id
- Added cras_py_common
- Contributors: Martin Pecka
Wiki Tutorials
Package Dependencies
Deps | Name |
---|---|
catkin | |
dynamic_reconfigure | |
geometry_msgs | |
rosgraph | |
rosgraph_msgs | |
rospy | |
tf | |
tf2_msgs | |
tf2_ros | |
cras_docs_common | |
rosdoc_lite | |
cras_cpp_common | |
roslint | |
rostest | |
rosunit |
System Dependencies
Dependant Packages
Name | Deps |
---|---|
cras_topic_tools | |
point_cloud_transport |