grepros 1.2.2
grep for ROS bag files and live topics
Loading...
Searching...
No Matches
grepros.api Namespace Reference

ROS interface, shared facade for ROS1 and ROS2. More...

Classes

class  Bag
 Bag factory metaclass. More...
 
class  BaseBag
 ROS bag interface. More...
 
class  TypeMeta
 Container for caching and retrieving message type metadata. More...
 

Functions

 calculate_definition_hash (typename, msgdef, extradefs=())
 Returns MD5 hash for message type definition.
 
 canonical (typename, unbounded=False)
 Returns "pkg/Type" for "pkg/subdir/Type", standardizes various ROS2 formats.
 
 create_publisher (topic, cls_or_typename, queue_size)
 Returns a ROS publisher instance, with .get_num_connections() and .unregister().
 
 create_subscriber (topic, cls_or_typename, handler, queue_size)
 Returns a ROS subscriber instance.
 
 deserialize_message (msg, cls_or_typename)
 Returns ROS message or service request/response instantiated from serialized binary.
 
 dict_to_message (dct, msg)
 Returns given ROS message populated from Python dictionary.
 
 filter_fields (fieldmap, top=(), include=(), exclude=())
 Returns fieldmap filtered by include and exclude patterns.
 
 format_message_value (msg, name, value)
 Returns a message attribute value as string.
 
 get_alias_type (typename)
 Returns ROS built-in type for alias like "char", if any; reverse of get_alias_type().
 
 get_message_class (typename)
 Returns ROS message class, or None if unavailable.
 
 get_message_definition (msg_or_type)
 Returns ROS message type definition full text, including subtype definitions.
 
 get_message_fields (val)
 Returns OrderedDict({field name: field type name}) if ROS message, else {}.
 
 get_message_type (msg_or_cls)
 Returns ROS message type name, like "std_msgs/Header".
 
 get_message_type_hash (msg_or_type)
 Returns ROS message type MD5 hash, or "" if unknown type.
 
 get_message_value (msg, name, typename=None, default=Ellipsis)
 Returns object attribute value, with numeric arrays converted to lists.
 
 get_ros_time_category (msg_or_type)
 Returns "time" or "duration" for time/duration type or instance, else original argument.
 
 get_rostime (fallback=False)
 Returns current ROS time, as rospy.Time or rclpy.time.Time.
 
 get_topic_types ()
 Returns currently available ROS topics, as [(topicname, typename)].
 
 get_type_alias (typename)
 Returns alias like "char" for ROS built-in type, if any; reverse of get_type_alias().
 
 init_node (name=None)
 Initializes a ROS1 or ROS2 node if not already initialized.
 
 is_ros_message (val, ignore_time=False)
 Returns whether value is a ROS message or special like ROS time/duration class or instance.
 
 is_ros_time (val)
 Returns whether value is a ROS time/duration class or instance.
 
 iter_message_fields (msg, messages_only=False, flat=False, scalars=(), include=(), exclude=(), top=())
 Yields ((nested, path), value, typename) from ROS message.
 
 make_bag_time (stamp, bag)
 Returns value as ROS timestamp, conditionally as relative to bag start/end time.
 
 make_duration (secs=0, nsecs=0)
 Returns a ROS duration.
 
 make_full_typename (typename, category="msg")
 Returns "pkg/msg/Type" for "pkg/Type".
 
 make_live_time (stamp)
 Returns value as ROS timestamp, conditionally as relative to system time.
 
 make_message_hash (msg, include=(), exclude=())
 Returns hashcode for ROS message, as a hex digest.
 
 make_time (secs=0, nsecs=0)
 Returns a ROS time.
 
 message_to_dict (msg, replace=None)
 Returns ROS message as nested Python dictionary.
 
 parse_definition_fields (typename, typedef)
 Returns field names and type names from a message definition text.
 
 parse_definition_subtypes (typedef, nesting=False)
 Returns subtype names and type definitions from a full message definition.
 
 scalar (typename)
 Returns scalar type from ROS message data type, like "uint8" from uint8-array.
 
 serialize_message (msg)
 Returns ROS message as a serialized binary.
 
 set_message_value (obj, name, value)
 Sets message or object attribute value.
 
 shutdown_node ()
 Shuts down live ROS node.
 
 time_message (val, to_message=True, clock_type=None)
 Converts ROS2 time/duration between rclpy and builtin_interfaces objects.
 
 to_datetime (val)
 Returns value as datetime.datetime if value is ROS time/duration, else value.
 
 to_decimal (val)
 Returns value as decimal.Decimal if value is ROS time/duration, else value.
 
 to_duration (val)
 Returns value as ROS duration if convertible (int/float/time/datetime/decimal), else value.
 
 to_nsec (val)
 Returns value in nanoseconds if value is ROS time/duration, else value.
 
 to_sec (val)
 Returns value in seconds if value is ROS time/duration, else value.
 
 to_sec_nsec (val)
 Returns value as (seconds, nanoseconds) if value is ROS time/duration, else value.
 
 to_time (val)
 Returns value as ROS time if convertible (int/float/duration/datetime/decimal), else value.
 
 validate (live=False)
 Initializes ROS bindings, returns whether ROS environment set, prints or raises error if not.
 

Variables

tuple BAG_EXTENSIONS = ()
 Bagfile extensions to seek, including leading dot, populated after init.
 
str NODE_NAME = "grepros"
 Node base name for connecting to ROS (will be anonymized).
 
 realapi = None
 Module grepros.ros1 or grepros.ros2.
 
 ROS1 = None
 Flag denoting ROS1 environment, populated on validate()
 
 ROS2 = None
 Flag denoting ROS2 environment, populated on validate()
 
dict ROS_ALIAS_TYPES = {}
 Mapping between type aliases and real types, like {"byte": "int8"} in ROS1.
 
dict ROS_BUILTIN_CTORS
 Python constructors for ROS built-in types, as {ROS name: type class}.
 
list ROS_BUILTIN_TYPES = ROS_NUMERIC_TYPES + ROS_STRING_TYPES
 All built-in basic types in ROS.
 
list ROS_COMMON_TYPES = []
 All built-in basic types plus time types in ROS, populated after init.
 
 ROS_FAMILY = None
 ROS Python module family, "rospy" or "rclpy", populated on validate()
 
list ROS_NUMERIC_TYPES
 All built-in numeric types in ROS.
 
list ROS_STRING_TYPES = ["string", "wstring"]
 All built-in string types in ROS.
 
dict ROS_TIME_CLASSES = {}
 ROS1 time/duration types mapped to type names, populated after init.
 
list ROS_TIME_TYPES = []
 ROS time/duration types, populated after init.
 
 ROS_VERSION = None
 ROS version from environment, populated on validate() as integer.
 
tuple SKIP_EXTENSIONS = ()
 Bagfile extensions to skip, including leading dot, populated after init.
 

Detailed Description

ROS interface, shared facade for ROS1 and ROS2.

Function Documentation

◆ calculate_definition_hash()

calculate_definition_hash (   typename,
  msgdef,
  extradefs = () 
)

Returns MD5 hash for message type definition.

Parameters
extradefsadditional subtype definitions as ((typename, msgdef), )

Definition at line 671 of file api.py.

◆ canonical()

canonical (   typename,
  unbounded = False 
)

Returns "pkg/Type" for "pkg/subdir/Type", standardizes various ROS2 formats.

Converts ROS2 DDS types like "octet" to "byte", and "sequence<uint8, 100>" to "uint8[100]".

Parameters
unboundeddrop constraints like array bounds, and string bounds in ROS2, e.g. returning "uint8[]" for "uint8[10]"

Definition at line 714 of file api.py.

◆ create_publisher()

create_publisher (   topic,
  cls_or_typename,
  queue_size 
)

Returns a ROS publisher instance, with .get_num_connections() and .unregister().

Definition at line 718 of file api.py.

◆ create_subscriber()

create_subscriber (   topic,
  cls_or_typename,
  handler,
  queue_size 
)

Returns a ROS subscriber instance.

Supplemented with .unregister(), .get_message_class(), .get_message_definition(), .get_message_type_hash(), and .get_qoses().

Definition at line 729 of file api.py.

◆ deserialize_message()

deserialize_message (   msg,
  cls_or_typename 
)

Returns ROS message or service request/response instantiated from serialized binary.

Definition at line 1154 of file api.py.

◆ dict_to_message()

dict_to_message (   dct,
  msg 
)

Returns given ROS message populated from Python dictionary.

Raises TypeError on attribute value type mismatch.

Definition at line 1045 of file api.py.

◆ filter_fields()

filter_fields (   fieldmap,
  top = (),
  include = (),
  exclude = () 
)

Returns fieldmap filtered by include and exclude patterns.

Parameters
fieldmap{field name: field type name}
topparent path as (rootattr, ..)
include[((nested, path), re.Pattern())] to require in parent path
exclude[((nested, path), re.Pattern())] to reject in parent path

Definition at line 741 of file api.py.

◆ format_message_value()

format_message_value (   msg,
  name,
  value 
)

Returns a message attribute value as string.

Result is at least 10 chars wide if message is a ROS time/duration (aligning seconds and nanoseconds).

Definition at line 765 of file api.py.

◆ get_alias_type()

get_alias_type (   typename)

Returns ROS built-in type for alias like "char", if any; reverse of get_alias_type().

In ROS1, byte and char are aliases for int8 and uint8; in ROS2 the reverse.

Definition at line 856 of file api.py.

◆ get_message_class()

get_message_class (   typename)

Returns ROS message class, or None if unavailable.

Definition at line 769 of file api.py.

◆ get_message_definition()

get_message_definition (   msg_or_type)

Returns ROS message type definition full text, including subtype definitions.

Returns None if unknown type.

Definition at line 779 of file api.py.

◆ get_message_fields()

get_message_fields (   val)

Returns OrderedDict({field name: field type name}) if ROS message, else {}.

Parameters
valROS message class or instance

Definition at line 793 of file api.py.

◆ get_message_type()

get_message_type (   msg_or_cls)

Returns ROS message type name, like "std_msgs/Header".

Definition at line 797 of file api.py.

◆ get_message_type_hash()

get_message_type_hash (   msg_or_type)

Returns ROS message type MD5 hash, or "" if unknown type.

Definition at line 783 of file api.py.

◆ get_message_value()

get_message_value (   msg,
  name,
  typename = None,
  default = Ellipsis 
)

Returns object attribute value, with numeric arrays converted to lists.

Parameters
namemessage attribute name
typenamevalue ROS type name, for identifying byte arrays
defaultvalue to return if attribute does not exist; raises exception otherwise

Definition at line 809 of file api.py.

◆ get_ros_time_category()

get_ros_time_category (   msg_or_type)

Returns "time" or "duration" for time/duration type or instance, else original argument.

Definition at line 822 of file api.py.

◆ get_rostime()

get_rostime (   fallback = False)

Returns current ROS time, as rospy.Time or rclpy.time.Time.

Parameters
fallbackuse wall time if node not initialized

Definition at line 818 of file api.py.

◆ get_topic_types()

get_topic_types ( )

Returns currently available ROS topics, as [(topicname, typename)].

Omits topics that the current ROS node itself has published.

Definition at line 838 of file api.py.

◆ get_type_alias()

get_type_alias (   typename)

Returns alias like "char" for ROS built-in type, if any; reverse of get_type_alias().

In ROS1, byte and char are aliases for int8 and uint8; in ROS2 the reverse.

Definition at line 847 of file api.py.

◆ init_node()

init_node (   name = None)

Initializes a ROS1 or ROS2 node if not already initialized.

In ROS1, blocks until ROS master available.

Definition at line 619 of file api.py.

◆ is_ros_message()

is_ros_message (   val,
  ignore_time = False 
)

Returns whether value is a ROS message or special like ROS time/duration class or instance.

Parameters
ignore_timewhether to ignore ROS time/duration types

Definition at line 865 of file api.py.

◆ is_ros_time()

is_ros_time (   val)

Returns whether value is a ROS time/duration class or instance.

Definition at line 869 of file api.py.

◆ iter_message_fields()

iter_message_fields (   msg,
  messages_only = False,
  flat = False,
  scalars = (),
  include = (),
  exclude = (),
  top = () 
)

Yields ((nested, path), value, typename) from ROS message.

Parameters
messages_onlywhether to yield only values that are ROS messages themselves or lists of ROS messages, else will yield scalar and scalar list values
flatrecurse into lists of nested messages, ignored if messages_only
scalarssequence of ROS types to consider as scalars, like ("time", duration")
include[((nested, path), re.Pattern())] to require in field path, if any
exclude[((nested, path), re.Pattern())] to reject in field path, if any
topinternal recursion helper

Definition at line 885 of file api.py.

◆ make_bag_time()

make_bag_time (   stamp,
  bag 
)

Returns value as ROS timestamp, conditionally as relative to bag start/end time.

Stamp is interpreted as relative offset from bag start/end time if numeric string with sign prefix, or timedelta, or ROS duration.

Parameters
stampconverted to ROS timestamp if int/float/str/duration/datetime/timedelta/decimal
bagan open bag to use for relative start/end time

Definition at line 936 of file api.py.

◆ make_duration()

make_duration (   secs = 0,
  nsecs = 0 
)

Returns a ROS duration.

Definition at line 977 of file api.py.

◆ make_full_typename()

make_full_typename (   typename,
  category = "msg" 
)

Returns "pkg/msg/Type" for "pkg/Type".

Parameters
categorytype category like "msg" or "srv"

Definition at line 920 of file api.py.

◆ make_live_time()

make_live_time (   stamp)

Returns value as ROS timestamp, conditionally as relative to system time.

Stamp is interpreted as relative offset from system time if numeric string with sign prefix, or timedelta, or ROS duration.

Parameters
stampconverted to ROS timestamp if int/float/str/duration/datetime/timedelta/decimal

Definition at line 962 of file api.py.

◆ make_message_hash()

make_message_hash (   msg,
  include = (),
  exclude = () 
)

Returns hashcode for ROS message, as a hex digest.

Parameters
includemessage fields to include if not all, as [((nested, path), re.Pattern())]
excludemessage fields to exclude, as [((nested, path), re.Pattern())]

Definition at line 993 of file api.py.

◆ make_time()

make_time (   secs = 0,
  nsecs = 0 
)

Returns a ROS time.

Definition at line 982 of file api.py.

◆ message_to_dict()

message_to_dict (   msg,
  replace = None 
)

Returns ROS message as nested Python dictionary.

Parameters
replacemapping of {value: replaced value}, e.g. {math.nan: None, math.inf: None}

Definition at line 1021 of file api.py.

◆ parse_definition_fields()

parse_definition_fields (   typename,
  typedef 
)

Returns field names and type names from a message definition text.

Does not recurse into subtypes.

Parameters
typenameROS message type name, like "my_pkg/MyCls"
typedefROS message definition, like "Header header\nbool a\nMyCls2 b"
Returns
ordered {field name: type name}, like "std_msgs/Header", "a": "bool", "b": "my_pkg/MyCls2"}

Definition at line 1078 of file api.py.

◆ parse_definition_subtypes()

parse_definition_subtypes (   typedef,
  nesting = False 
)

Returns subtype names and type definitions from a full message definition.

Parameters
typedefmessage type definition including all subtype definitions
nestingwhether to additionally return type nesting information as {typename: [typename contained in parent]}
Returns
{"pkg/MsgType": "full definition for MsgType including subtypes"} or ({typedefs}, {nesting}) if nesting

Definition at line 1109 of file api.py.

◆ scalar()

scalar (   typename)

Returns scalar type from ROS message data type, like "uint8" from uint8-array.

Returns type unchanged if an ordinary type. In ROS2, returns unbounded type, e.g. "string" from "string<=10[<=5]".

Definition at line 1165 of file api.py.

◆ serialize_message()

serialize_message (   msg)

Returns ROS message as a serialized binary.

Definition at line 1149 of file api.py.

◆ set_message_value()

set_message_value (   obj,
  name,
  value 
)

Sets message or object attribute value.

Definition at line 1169 of file api.py.

◆ shutdown_node()

shutdown_node ( )

Shuts down live ROS node.

Definition at line 623 of file api.py.

◆ time_message()

time_message (   val,
  to_message = True,
  clock_type = None 
)

Converts ROS2 time/duration between rclpy and builtin_interfaces objects.

Returns input value as-is in ROS1.

Parameters
valROS2 time/duration object from rclpy or builtin_interfaces
to_messagewhether to convert from rclpy to builtin_interfaces or vice versa
clock_typeClockType for converting to rclpy.Time, defaults to ROS_TIME
Returns
value converted to appropriate type, or original value if not convertible

Definition at line 1183 of file api.py.

◆ to_datetime()

to_datetime (   val)

Returns value as datetime.datetime if value is ROS time/duration, else value.

Definition at line 1188 of file api.py.

◆ to_decimal()

to_decimal (   val)

Returns value as decimal.Decimal if value is ROS time/duration, else value.

Definition at line 1194 of file api.py.

◆ to_duration()

to_duration (   val)

Returns value as ROS duration if convertible (int/float/time/datetime/decimal), else value.

Definition at line 1201 of file api.py.

◆ to_nsec()

to_nsec (   val)

Returns value in nanoseconds if value is ROS time/duration, else value.

Definition at line 1206 of file api.py.

◆ to_sec()

to_sec (   val)

Returns value in seconds if value is ROS time/duration, else value.

Definition at line 1211 of file api.py.

◆ to_sec_nsec()

to_sec_nsec (   val)

Returns value as (seconds, nanoseconds) if value is ROS time/duration, else value.

Definition at line 1216 of file api.py.

◆ to_time()

to_time (   val)

Returns value as ROS time if convertible (int/float/duration/datetime/decimal), else value.

Definition at line 1221 of file api.py.

◆ validate()

validate (   live = False)

Initializes ROS bindings, returns whether ROS environment set, prints or raises error if not.

Parameters
livewhether environment must support launching a ROS node

Definition at line 633 of file api.py.

Variable Documentation

◆ BAG_EXTENSIONS

tuple BAG_EXTENSIONS = ()

Bagfile extensions to seek, including leading dot, populated after init.

Definition at line 36 of file api.py.

◆ NODE_NAME

str NODE_NAME = "grepros"

Node base name for connecting to ROS (will be anonymized).

Definition at line 33 of file api.py.

◆ realapi

realapi = None

Module grepros.ros1 or grepros.ros2.

Definition at line 82 of file api.py.

◆ ROS1

ROS1 = None

Flag denoting ROS1 environment, populated on validate()

Definition at line 42 of file api.py.

◆ ROS2

ROS2 = None

Flag denoting ROS2 environment, populated on validate()

Definition at line 45 of file api.py.

◆ ROS_ALIAS_TYPES

dict ROS_ALIAS_TYPES = {}

Mapping between type aliases and real types, like {"byte": "int8"} in ROS1.

Definition at line 79 of file api.py.

◆ ROS_BUILTIN_CTORS

dict ROS_BUILTIN_CTORS
Initial value:
1= {"byte": int, "char": int, "int8": int, "int16": int,
2 "int32": int, "int64": int, "uint8": int, "uint16": int,
3 "uint32": int, "uint64": int, "float32": float, "float64": float,
4 "bool": bool, "string": str, "wstring": str}

Python constructors for ROS built-in types, as {ROS name: type class}.

Definition at line 64 of file api.py.

◆ ROS_BUILTIN_TYPES

list ROS_BUILTIN_TYPES = ROS_NUMERIC_TYPES + ROS_STRING_TYPES

All built-in basic types in ROS.

Definition at line 61 of file api.py.

◆ ROS_COMMON_TYPES

list ROS_COMMON_TYPES = []

All built-in basic types plus time types in ROS, populated after init.

Definition at line 76 of file api.py.

◆ ROS_FAMILY

ROS_FAMILY = None

ROS Python module family, "rospy" or "rclpy", populated on validate()

Definition at line 51 of file api.py.

◆ ROS_NUMERIC_TYPES

list ROS_NUMERIC_TYPES
Initial value:
1= ["byte", "char", "int8", "int16", "int32", "int64", "uint8",
2 "uint16", "uint32", "uint64", "float32", "float64", "bool"]

All built-in numeric types in ROS.

Definition at line 54 of file api.py.

◆ ROS_STRING_TYPES

list ROS_STRING_TYPES = ["string", "wstring"]

All built-in string types in ROS.

Definition at line 58 of file api.py.

◆ ROS_TIME_CLASSES

dict ROS_TIME_CLASSES = {}

ROS1 time/duration types mapped to type names, populated after init.

Definition at line 73 of file api.py.

◆ ROS_TIME_TYPES

list ROS_TIME_TYPES = []

ROS time/duration types, populated after init.

Definition at line 70 of file api.py.

◆ ROS_VERSION

ROS_VERSION = None

ROS version from environment, populated on validate() as integer.

Definition at line 48 of file api.py.

◆ SKIP_EXTENSIONS

tuple SKIP_EXTENSIONS = ()

Bagfile extensions to skip, including leading dot, populated after init.

Definition at line 39 of file api.py.