==== Messages ====
Library ''messages'' contains support wrappers for data structures commonly used in robotics. The individual message types allow for standardizing the interfaces between the functional parts of the robot software architecture. The implementation of the library is inspired by the [[https://www.ros.org/|ROS]] middleware which is commonly used in robotics to manage software architecture of the robots. While the ROS messages are only data wrappers, our implementation features several simplifications and some of the message classes include additional code to simplify work with them.    

The messages used in the tasks within the UIR course are inherited from the ''Message'' class and are following:
  - ''Header''
  - ''Vector3''
  - ''Quaternion''
  - ''Pose''
  - ''Odometry''
  - ''Twist''
  - ''Path''
  - ''LaserScan''
  - ''OccupancyGrid''
  - ''NavGraph''
The structure of the individual message classes and the description of their methods follows.
----

=== Header ===
General message header that contains information common for most of the message types 

''Attributes''
  * ''timestamp'' - float - creation timestamp of the message
  * ''frame_id'' - string - string identification of the coordinate reference frame in which the data are represented (default to ''base_frame'')  

----


=== Vector3 ===
Message for representation of 3D vectors with $x$,$y$,$z$ components

''Attributes''
  * ''x'' - float - x coordinate 
  * ''y'' - float - y coordinate 
  * ''z'' - float - z coordinate 

----

=== Quaternion ===
Message for representation of 3D orientation using unit [[https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation|quaternion]]. There are multiple ways how to represent the rotations in the robotics, with the rotation matrices and quaternions being superior to [[https://en.wikipedia.org/wiki/Euler_angles|Euler angles]] with their commonly used variant Tait–Bryan angles.
The Euler angles is a representation of the robot orientation in 3D using rotations around principal axes of the robot. In particular, the original Euler angles are prescribed by one of the following orders of rotation ($zxz$, $xyx$, $yzy$, $zyz$, $xzx$, $yxy$) with the more common representation using the Tait–Bryan angles variant prescribed by one of the following orders of rotation ($xyz$, $yzx$, $zxy$, $xzy$, $zyx$, $yxz$) commonly referred to as yaw (rotation around $z$ axis), pitch (rotation around $y$ axis), and roll (rotation around $x$ axis) of the robot, similar to the following figure (courtesy of [[https://upload.wikimedia.org/wikipedia/commons/thumb/c/c1/Yaw_Axis_Corrected.svg/250px-Yaw_Axis_Corrected.svg.png|Wikipedia]]).

{{:courses:b4m36uir:hw:support:yaw_axis_corrected.svg.png?400|}}

There are two principal problems in usage of Euler (Tait–Bryan) angles. First is the missing standardization of rotation order which leaves us with twelve possible sequences of rotations. Second, the [[https://en.wikipedia.org/wiki/Gimbal_lock|Gimball-lock]] effect which is a loss of Degree of Freedom that occurs when two axes are driven into a parallel configuration by the sequence of the rotations. Hence, representation of the orientation using quaternions and rotation matrices is therefore better considered a better option.


''Attributes''
  * ''x'' - float - x component
  * ''y'' - float - y component 
  * ''z'' - float - z component 
  * ''w'' - float - w component 


''Methods''
  *  ''to_R()'' - Method to convert quaternion into the rotation matrix
  * ''from_R(R)'' - Method to convert rotation matrix ''R'' into the quaternion representation
  * ''to_Euler()'' - Method to convert quaternion into euler angles (yaw, pitch, roll) - $xyz$ order
  * ''from_Euler(yaw, pitch, roll)'' - Method to convert euler ($xyz$ order) angles ''yaw,pitch,roll'' into the quaternion

----

=== Pose ===
Basic class for representing robot pose in free space in form of $x,y,z$ position vector and orientation quaternion


''Attributes''
  * ''position'' - Vector3 - position component
  * ''orientation'' - Quaternion - orientation component

''Methods''
  * ''dist(other)'' - Method to calculate the euclidean distance between self and the ''other'' Pose
  * ''plot(ax)'' - Method to 2D plot the pose into the ''matplotlib.pyplot'' axes ''ax'' 

----

=== Path ===
Basic class for representing the robot path in free space
 
''Attributes''
  * ''poses'' - Pose[] - list of poses of the robot

''Methods''
  * ''plot(ax, skipstep=0)'' - 2D plot of the path with an optional skipstep 

----

=== Odometry ===
Basic class for representing robot odometry as a timestamped pose in the given reference frame

''Attributes''
  * ''header'' - Header - timestamp and reference frame id of the Odometry message
  * ''pose'' - Pose - pose of the robot

----

=== Twist ===
Basic class for representing velocity in free space broken into the linear and angular components
    
''Attributes''
  * ''linear'' - Vector3 - $(v_x, v_y, v_z)$ components of the linear speed  
  * ''angular'' - Vector3 - $(\omega_x, \omega_y, \omega_z)$ components of the angular speed

----

=== LaserScan ===
Basic class for representing a single line scan from planar laser scanner
    
''Attributes''
  * ''header'' - Header - timestamp and reference frame id of the Odometry message
  * ''angle_min'' - float - start angle of the scan [rad]
  * ''angle_max'' - float - end angle of the scan [rad]
  * ''angle_increment'' - float - angular distance between measurements [rad]
  * ''range_min'' - float - minimum measurable distance [m]
  * ''range_max'' - float - maximum measurable distance [m]
  * ''distances'' - float[] - distance data [m] (note: distance data out of range should be discarded) 
  * 
''Methods''
  * ''plot(ax)'' - Method to 2D plot the LaserScan into the ''matplotlib.pyplot'' axes ''ax'' 

----

=== OccupancyGrid ===
Basic class for representing occupancy grid map

''Attributes''
  * ''header'' - Header - timestamp and reference frame id of the Odometry message
  * ''resolution'' - float - the map resolution [m/cell]
  * ''width'' - float - width of the map [cells]
  * ''height'' - float - height of the map [cells]
  * ''origin'' - Pose - the origin of the map [m, m, rad]. This is the real-world pose of the cell (0,0) in the map.
  * ''data'' - float[] - the map data in row-major order

''Methods''
  * ''plot(ax)'' - Method to plot the grid map into the ''matplotlib.pyplot'' axes ''ax'' 

----

=== NavGraph ===
Basic class for representing the navigation graph $\mathcal{G}=(V,E)$, where $V$ is a set of vertices and $E$ is a set of edges.

''Attributes''
  * ''poses'' - Pose[] - list of graph vertices $V$
  * ''edges'' - list( (i,j) ) - list of index tuples representing the graph edges $E$

''Methods''
  * ''plot(ax)'' - Method to plot the grid map into the ''matplotlib.pyplot'' axes ''ax'' 

----