Package: numpy-ros
Seamlessly convert between ROS messages and NumPy arrays. Installable via your
favorite Python dependency management system (pip, poetry, pipenv, ...) –
no matter what ROS version you're on.Table of ContentsInstallationUsageSupported TypesCustom HandlersLicenseAcknowledgementsInstallationnumpy-ros is distributed via PyPI for Python 3.6 and higher. To install, run:# pip$pipinstallnumpy-ros# poetry$poetryaddnumpy-ros# pipenv$pipenvinstallnumpy-rosROS messages of typeQuaternionare by default converted into numpy arrays of
typenp.quaternion, which are provided by thenumpy-quaternionpackage. To make use
of hardware acceleration and certain advanced features of numpy-quaternion,
consider installing with the optional scipy and numba dependencies. For more
information, see the numpy-quaternion documentation.$pipinstall'numpy-ros[quaternion-extras]'Support for installation via conda is targeted for future releases.UsageConverting a ROS message into a NumPy representation and back is as simple as
calling theto_numpyandto_messagefunctions:fromnumpy_rosimportto_numpy,to_messagefromgeometry_msgs.msgimportPointpoint=Point(3.141,2.718,42.1337)# ROS to NumPyas_array=to_numpy(point)# NumPy to ROSmessage=to_message(Point,as_array)Note thatto_numpyexpects the ROS message to convert as its first
positional argument, whereasto_messageexpects the ROS messagetype(i.e.
the specific subclass ofgenpy.Message). Other than that, either function may
take any number of positional and keyword arguments.For some message types, keyword arguments can be used to finely control the
conversion process. For example,Pointmessages (among others) can be
converted directly into homogeneous coordinates:# Returns array([ 3.141 ,  2.718 , 42.1337])as_array=to_numpy(point)# Returns array([ 3.141 , 2.718 , 42.1337 , 1.0])as_array_hom=to_numpy(point,homogeneous=True)Also note thatto_numpymay return multiple values, depending on the message
type. Similarly,to_messagemay require multiple positional arguments to
assemble the message object:fromgeometry_msgs.msgimportInertiainertia=Inertia(...)mass,center_of_mass,inertia_tensor=to_numpy(inertia)message=to_message(Inertia,mass,center_of_mass,inertia_tensor)inertia==message# trueSupported TypesCurrently, numpy-ros provides conversions of the message types listed below. More extensive documentation will be provided in the near future.geometry_msgsMessage Typeto_numpyfrom_numpykwargsAccel✅✅homogeneous(default:False)AccelStamped✅N/Ahomogeneous(default:False)AccelWithCovariance✅✅homogeneous(default:False)AccelWithCovarianceStamped✅N/Ahomogeneous(default:False)Inertia✅✅homogeneous(default:False)InertiaStamped✅N/Ahomogeneous(default:False)Point✅✅homogeneous(default:False)Point32✅✅homogeneous(default:False)PointStamped✅N/Ahomogeneous(default:False)Polygon✅✅homogeneous(default:False)PolygonStamped✅N/Ahomogeneous(default:False)Pose✅✅homogeneous(default:False)PoseArray✅✅homogeneous(default:False)as_array(default:False)PoseStamped✅N/Ahomogeneous(default:False)PoseWithCovariance✅✅homogeneous(default:False)PoseWithCovarianceStamped✅N/Ahomogeneous(default:False)Quaternion✅✅QuaternionStamped✅N/ATransform✅✅homogeneous(default:False)TransformStamped✅N/Ahomogeneous(default:False)Twist✅✅homogeneous(default:False)TwistStamped✅N/Ahomogeneous(default:False)TwistWithCovariance✅✅homogeneous(default:False)TwistWithCovarianceStamped✅N/Ahomogeneous(default:False)Vector3✅✅homogeneous(default:False)Vector3Stamped✅N/Ahomogeneous(default:False)Wrench✅✅homogeneous(default:False)WrenchStamped✅N/Ahomogeneous(default:False)More message types will be added in future versions.Custom HandlersCustom conversion handlers can be registred by decorating them withconverts_to_numpyorconverts_to_message, respectively.frommy_ros_package.msgimportMyMessageType,MyOtherMessageTypefromnumpy_rosimportconverts_to_numpy,converts_to_message@converts_to_numpy(MyMessageType,MyOtherMessageType)defmy_messages_to_numpy(message,option1=True,option2=False):as_array=...returnas_array@converts_to_message(MyMessageType,MyOtherMessageType)defnumpy_to_my_messages(message_type,arg1,arg2,option3='foo'):ifissubclass(message_type,MyMessageType):...elifissubclass(message,MyOtherMessageType):...else:raiseTypeErroras_message=message_type(...)returnas_message# This works now!message=MyMessage(...)as_array=to_numpy(message)After registring,to_numpyandto_messagewill transparently dispatch to the
respective handlers. Note that the same handler can be registered to multiple
message types, as in the example above. Moreover, to-message-handlers are
required to expect the message type as their first positional argument.Licensenumpy-ros is available under the MIT license. For more information, see theLICENSEfile in this repository.AcknowledgementsThis work started as a side-project during my internship atV-R Robotics, inspired by anearlier workby Eric Wieser.numpy-ros is in no way, shape, or form affiliated with numpy, NumFocus, ROS, or
the Open Robotics Foundation.