Cleanup the tf2 tutorials (#4056)

* Cleanup Introduction to Tf2.

In particular, make it less Linux centric.  Also cleanup
a few typos I noticed while reading.  And finally, change
the packages we install to be the ones actually needed
by the tutorial nowadays.

* Cleanup Writing-A-Tf2-Broadcaster-* tutorials.

Just make the C++ and the Python one a little more similar,
and fix a few minor typos.

* Minor cleanup in Writing-A-Tf2-Static-Broadcaster-* tutorials.

* Small cleanups in the Writing-A-Tf2-Listener tutorials.

Make the Python and C++ tutorials more alike.

* Minor updates to the Adding-A-Frame tutorials.

Just to make the Python and C++ tutorials more similar.

Signed-off-by: Chris Lalancette <[email protected]>
(cherry picked from commit 7f369d3)

source/Tutorials/Intermediate/Tf2/Adding-A-Frame-Cpp.rst

@@ -2,8 +2,6 @@
 
     Tutorials/Tf2/Adding-A-Frame-Cpp
 
-.. _AddingAFrameCpp:
-
 Adding a frame (C++)
 ====================
 
@@ -49,8 +47,9 @@ Tasks
 In our turtle example, we'll add a new frame ``carrot1``, which will be the child of the ``turtle1``.
 This frame will serve as the goal for the second turtle.
 
-Let's first create the source files. Go to the ``learning_tf2_cpp`` package we created in the previous tutorials.
-Download the fixed frame broadcaster code by entering the following command:
+Let's first create the source files.
+Go to the ``learning_tf2_cpp`` package we created in the previous tutorials.
+Inside the ``src`` directory download the fixed frame broadcaster code by entering the following command:
 
 .. tabs::
 
@@ -185,7 +184,7 @@ Finally, add the ``install(TARGETS…)`` section so ``ros2 run`` can find your e
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Now let's create a launch file for this example.
-With your text editor, create a new file called ``turtle_tf2_fixed_frame_demo.launch.py``, and add the following lines:
+With your text editor, create a new file called ``launch/turtle_tf2_fixed_frame_demo.launch.py``, and add the following lines:
 
 .. code-block:: python
 
@@ -250,7 +249,7 @@ Run ``rosdep`` in the root of your workspace to check for missing dependencies.
 
         rosdep only runs on Linux, so you will need to install ``geometry_msgs`` and ``turtlesim`` dependencies yourself
 
-From the root of your workspace, build your updated package:
+Still in the root of your workspace, build your package:
 
 .. tabs::
 
@@ -343,7 +342,8 @@ Now rebuild the package, restart the ``turtle_tf2_fixed_frame_demo.launch.py``,
 The extra frame we published in this tutorial is a fixed frame that doesn't change over time in relation to the parent frame.
 However, if you want to publish a moving frame you can code the broadcaster to change the frame over time.
 Let's change our ``carrot1`` frame so that it changes relative to ``turtle1`` frame over time.
-Now download the dynamic frame broadcaster code by entering the following command:
+Go to the ``learning_tf2_cpp`` package we created in the previous tutorial.
+Inside the ``src`` directory download the dynamic frame broadcaster code by entering the following command:
 
 .. tabs::
 
@@ -473,7 +473,7 @@ Finally, add the ``install(TARGETS…)`` section so ``ros2 run`` can find your e
 2.3 Write the launch file
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To test this code, create a new launch file ``turtle_tf2_dynamic_frame_demo.launch.py`` and paste the following code:
+To test this code, create a new launch file ``launch/turtle_tf2_dynamic_frame_demo.launch.py`` and paste the following code:
 
 .. code-block:: python
 
@@ -526,7 +526,7 @@ Run ``rosdep`` in the root of your workspace to check for missing dependencies.
 
         rosdep only runs on Linux, so you will need to install ``geometry_msgs`` and ``turtlesim`` dependencies yourself
 
-From the root of your workspace, build your updated package:
+Still in the root of your workspace, build your package:
 
 .. tabs::
 

source/Tutorials/Intermediate/Tf2/Adding-A-Frame-Py.rst

@@ -2,8 +2,6 @@
 
     Tutorials/Tf2/Adding-A-Frame-Py
 
-.. _AddingAFramePy:
-
 Adding a frame (Python)
 =======================
 
@@ -279,7 +277,7 @@ Open a new terminal, navigate to the root of your workspace, and source the setu
 1.5 Run
 ~~~~~~~
 
-Now you are ready to run the launch file:
+Now you can start the turtle broadcaster demo:
 
 .. code-block:: console
 
@@ -311,7 +309,7 @@ To do so, open the ``turtle_tf2_fixed_frame_demo.launch.py`` file, and add the `
             launch_arguments={'target_frame': 'carrot1'}.items(),
             )
 
-Now just rebuild the package, restart the ``turtle_tf2_fixed_frame_demo.launch.py``, and you'll see the second turtle following the carrot instead of the first turtle!
+Now rebuild the package, restart the ``turtle_tf2_fixed_frame_demo.launch.py``, and you'll see the second turtle following the carrot instead of the first turtle!
 
 .. image:: images/carrot_static.png
 
@@ -533,7 +531,7 @@ Open a new terminal, navigate to the root of your workspace, and source the setu
 1.5 Run
 ~~~~~~~
 
-Now you are ready to run the launch file:
+Now you can start the dynamic frame demo:
 
 .. code-block:: console
 

source/Tutorials/Intermediate/Tf2/Introduction-To-Tf2.rst

@@ -24,17 +24,22 @@ Let's start by installing the demo package and its dependencies.
 
 .. tabs::
 
-   .. group-tab:: Linux Binaries
+   .. group-tab:: Ubuntu Packages
 
       .. code-block:: console
 
-         sudo apt-get install ros-{DISTRO}-turtle-tf2-py ros-{DISTRO}-tf2-tools ros-{DISTRO}-tf-transformations
+         sudo apt-get install ros-{DISTRO}-rviz2 ros-{DISTRO}-turtle-tf2-py ros-{DISTRO}-tf2-ros ros-{DISTRO}-tf2-tools ros-{DISTRO}-turtlesim
+
+   .. group-tab:: RHEL Packages
+
+      .. code-block:: console
+
+         sudo dnf install ros-{DISTRO}-rviz2 ros-{DISTRO}-turtle-tf2-py ros-{DISTRO}-tf2-ros ros-{DISTRO}-tf2-tools ros-{DISTRO}-turtlesim
 
    .. group-tab:: From Source
 
       .. code-block:: console
 
-         # Clone and build the geometry_tutorials repo using the branch that matches your installation
          git clone https://github.com/ros/geometry_tutorials.git -b ros2
 
 Running the demo
@@ -69,7 +74,7 @@ What is happening?
 ------------------
 
 This demo is using the tf2 library to create three coordinate frames: a ``world`` frame, a ``turtle1`` frame, and a ``turtle2`` frame.
-This tutorial uses a tf2 broadcaster to publish the turtle coordinate frames and a tf2 listener to compute the difference in the turtle frames and move one turtle to follow the other.
+This tutorial uses a *tf2 broadcaster* to publish the turtle coordinate frames and a *tf2 listener* to compute the difference in the turtle frames and move one turtle to follow the other.
 
 tf2 tools
 ---------
@@ -81,6 +86,7 @@ We can use ``tf2_tools`` to look at what tf2 is doing behind the scenes.
 ^^^^^^^^^^^^^^^^^^^
 
 ``view_frames`` creates a diagram of the frames being broadcast by tf2 over ROS.
+Note that this utility only works on Linux; if you are Windows, skip to "Using tf2_echo" below.
 
 .. code-block:: console
 
@@ -98,15 +104,15 @@ To view the tree, open the resulting ``frames.pdf`` with your favorite PDF viewe
 
 .. image:: images/turtlesim_frames.png
 
-Here we can see three frames that are broadcasted by tf2: ``world``, ``turtle1``, and ``turtle2``.
-The ``world`` here is the parent of the ``turtle1`` and ``turtle2`` frames.
-``view_frames`` also report some diagnostic information about when the oldest and most
+Here we can see three frames that are broadcast by tf2: ``world``, ``turtle1``, and ``turtle2``.
+The ``world`` frame is the parent of the ``turtle1`` and ``turtle2`` frames.
+``view_frames`` also reports some diagnostic information about when the oldest and most
 recent frame transforms were received and how fast the tf2 frame is published to tf2 for debugging purposes.
 
 2 Using tf2_echo
 ^^^^^^^^^^^^^^^^
 
-``tf2_echo`` reports the transform between any two frames broadcasted over ROS.
+``tf2_echo`` reports the transform between any two frames broadcast over ROS.
 
 Usage:
 
@@ -120,7 +126,7 @@ Let's look at the transform of the ``turtle2`` frame with respect to ``turtle1``
 
    ros2 run tf2_ros tf2_echo turtle2 turtle1
 
-You will see the transform displayed as the ``tf2_echo`` listener receives the frames broadcasted over ROS 2.
+You will see the transform displayed as the ``tf2_echo`` listener receives the frames broadcast over ROS 2.
 
 .. code-block:: console
 
@@ -133,17 +139,27 @@ You will see the transform displayed as the ``tf2_echo`` listener receives the f
 
 As you drive your turtle around you will see the transform change as the two turtles move relative to each other.
 
-rviz and tf2
-------------
+rviz2 and tf2
+-------------
 
-``rviz`` is a visualization tool that is useful for examining tf2 frames.
-Let's look at our turtle frames using rviz.
-Let's start rviz with the ``turtle_rviz.rviz`` configuration file using the ``-d`` option:
+``rviz2`` is a visualization tool that is useful for examining tf2 frames.
+Let's look at our turtle frames using ``rviz2`` by starting it with a configuration file using the ``-d`` option:
 
-.. code-block:: console
+.. tabs::
+
+  .. group-tab:: Linux
+
+    .. code-block:: console
+
+      ros2 run rviz2 rviz2 -d $(ros2 pkg prefix --share turtle_tf2_py)/rviz/turtle_rviz.rviz
+
+  .. group-tab:: Windows
+
+    .. code-block:: console
 
-   ros2 run rviz2 rviz2 -d $(ros2 pkg prefix --share turtle_tf2_py)/rviz/turtle_rviz.rviz
+      for /f "usebackq tokens=*" %a in (`ros2 pkg prefix --share turtle_tf2_py`) do rviz2 -d %a/rviz/turtle_rviz.rviz
 
 .. image:: images/turtlesim_rviz.png
 
-In the side bar you will see the frames broadcasted by tf2. As you drive the turtle around you will see the frames move in rviz.
+In the side bar you will see the frames broadcast by tf2.
+As you drive the turtle around you will see the frames move in rviz.

source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Broadcaster-Cpp.rst

@@ -2,8 +2,6 @@
 
     Tutorials/Tf2/Writing-A-Tf2-Broadcaster-Cpp
 
-.. _WritingATf2BroadcasterCpp:
-
 Writing a broadcaster (C++)
 ===========================
 
@@ -21,14 +19,15 @@ Background
 ----------
 
 In the next two tutorials we will write the code to reproduce the demo from the :doc:`Introduction to tf2 <./Introduction-To-Tf2>` tutorial.
-After that, following tutorials focus on extending the demo with more advanced tf2 features, including the usage of timeouts in transformation lookups and time travel.
+After that, the following tutorials focus on extending the demo with more advanced tf2 features, including the usage of timeouts in transformation lookups and time travel.
 
 Prerequisites
 -------------
 
 This tutorial assumes you have a working knowledge of ROS 2 and you have completed the :doc:`Introduction to tf2 tutorial <./Introduction-To-Tf2>` and :doc:`tf2 static broadcaster tutorial (C++) <./Writing-A-Tf2-Static-Broadcaster-Cpp>`.
+We'll be reusing the ``learning_tf2_cpp`` package from that last tutorial.
+
 In previous tutorials, you learned how to :doc:`create a workspace <../../Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace>` and :doc:`create a package <../../Beginner-Client-Libraries/Creating-Your-First-ROS2-Package>`.
-You also have created the ``learning_tf2_cpp`` :doc:`package <./Writing-A-Tf2-Static-Broadcaster-Cpp>`, which is where we will continue working from.
 
 Tasks
 -----
@@ -321,7 +320,7 @@ Make sure to save the file.
 2.3 CMakeLists.txt
 ~~~~~~~~~~~~~~~~~~
 
-Reopen ``CMakeLists.txt`` and add the line so that the launch files from the ``launch/`` folder would be installed.
+Reopen ``CMakeLists.txt`` and add the line so that the launch files from the ``launch/`` folder will be installed.
 
 .. code-block:: console
 
@@ -351,7 +350,7 @@ Run ``rosdep`` in the root of your workspace to check for missing dependencies.
 
         rosdep only runs on Linux, so you will need to install ``geometry_msgs`` and ``turtlesim`` dependencies yourself
 
-From the root of your workspace, build your updated package:
+Still in the root of your workspace, build your package:
 
 .. tabs::
 

source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Broadcaster-Py.rst

@@ -2,8 +2,6 @@
 
     Tutorials/Tf2/Writing-A-Tf2-Broadcaster-Py
 
-.. _WritingATf2BroadcasterPy:
-
 Writing a broadcaster (Python)
 ==============================
 
@@ -21,14 +19,15 @@ Background
 ----------
 
 In the next two tutorials we will write the code to reproduce the demo from the :doc:`Introduction to tf2 <./Introduction-To-Tf2>` tutorial.
-After that, following tutorials focus on extending the demo with more advanced tf2 features, including the usage of timeouts in transformation lookups and time travel.
+After that, the following tutorials focus on extending the demo with more advanced tf2 features, including the usage of timeouts in transformation lookups and time travel.
 
 Prerequisites
 -------------
 
-This tutorial assumes you have a working knowledge of ROS 2 and you have completed the :doc:`Introduction to tf2 tutorial <./Introduction-To-Tf2>`.
+This tutorial assumes you have a working knowledge of ROS 2 and you have completed the :doc:`Introduction to tf2 tutorial <./Introduction-To-Tf2>` and :doc:`tf2 static broadcaster tutorial (Python) <./Writing-A-Tf2-Static-Broadcaster-Py>`.
+We'll be reusing the ``learning_tf2_py`` package from that last tutorial.
+
 In previous tutorials, you learned how to :doc:`create a workspace <../../Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace>` and :doc:`create a package <../../Beginner-Client-Libraries/Creating-Your-First-ROS2-Package>`.
-You also have created the ``learning_tf2_py`` :doc:`package <./Writing-A-Tf2-Static-Broadcaster-Py>`, which is where we will continue working from.
 
 Tasks
 -----
@@ -236,19 +235,13 @@ Finally we take the transform that we constructed and pass it to the ``sendTrans
     # Send the transformation
     self.tf_broadcaster.sendTransform(t)
 
-.. note::
-
-    You can also publish static transforms with the same pattern by instantiating a ``tf2_ros.StaticTransformBroadcaster`` instead of a ``tf2_ros.TransformBroadcaster``.
-    The static transforms will be published on the ``/tf_static`` topic and will be sent only when required, not periodically.
-    For more details see :doc:`here <./Writing-A-Tf2-Static-Broadcaster-Py>`.
-
 1.2 Add an entry point
 ~~~~~~~~~~~~~~~~~~~~~~
 
 To allow the ``ros2 run`` command to run your node, you must add the entry point
 to ``setup.py`` (located in the ``src/learning_tf2_py`` directory).
 
-Finally, add the following line between the ``'console_scripts':`` brackets:
+Add the following line between the ``'console_scripts':`` brackets:
 
 .. code-block:: python
 
@@ -315,7 +308,7 @@ Now we run our nodes that start the turtlesim simulation and broadcast ``turtle1
 2.2 Add dependencies
 ~~~~~~~~~~~~~~~~~~~~
 
-Navigate one level back to the ``src/learning_tf2_py`` directory, where the ``setup.py``, ``setup.cfg``, and ``package.xml`` files are located.
+Navigate one level back to the ``learning_tf2_py`` directory, where the ``setup.py``, ``setup.cfg``, and ``package.xml`` files are located.
 
 Open ``package.xml`` with your text editor.
 Add the following dependencies corresponding to your launch file's import statements:
@@ -332,7 +325,7 @@ Make sure to save the file.
 2.3 Update setup.py
 ~~~~~~~~~~~~~~~~~~~
 
-Reopen ``setup.py`` and add the line so that the launch files from the ``launch/`` folder would be installed.
+Reopen ``setup.py`` and add the line so that the launch files from the ``launch/`` folder will be installed.
 The ``data_files`` field should now look like this:
 
 .. code-block:: python
@@ -435,7 +428,7 @@ In the second terminal window type the following command:
 
     ros2 run turtlesim turtle_teleop_key
 
-You will now see that the turtlesim simulation have started with one turtle that you can control.
+You will now see that the turtlesim simulation has started with one turtle that you can control.
 
 .. image:: images/turtlesim_broadcast.png
 

source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Listener-Cpp.rst

@@ -2,8 +2,6 @@
 
     Tutorials/Tf2/Writing-A-Tf2-Listener-Cpp
 
-.. _WritingATf2ListenerCpp:
-
 Writing a listener (C++)
 ========================
 
@@ -36,7 +34,8 @@ Tasks
 1 Write the listener node
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Let's first create the source files. Go to the ``learning_tf2_cpp`` package we created in the previous tutorial.
+Let's first create the source files.
+Go to the ``learning_tf2_cpp`` package we created in the previous tutorial.
 Inside the ``src`` directory download the example listener code by entering the following command:
 
 .. tabs::
@@ -219,14 +218,16 @@ The ``tf2_ros`` contains a ``TransformListener`` header file implementation that
 
     #include "tf2_ros/transform_listener.h"
 
-Here, we create a ``TransformListener`` object. Once the listener is created, it starts receiving tf2 transformations over the wire, and buffers them for up to 10 seconds.
+Here, we create a ``TransformListener`` object.
+Once the listener is created, it starts receiving tf2 transformations over the wire, and buffers them for up to 10 seconds.
 
 .. code-block:: C++
 
     tf_listener_ =
       std::make_shared<tf2_ros::TransformListener>(*tf_buffer_);
 
-Finally, we query the listener for a specific transformation. We call ``lookup_transform`` method with following arguments:
+Finally, we query the listener for a specific transformation.
+We call ``lookup_transform`` method with following arguments:
 
 #. Target frame
 
@@ -345,7 +346,7 @@ Run ``rosdep`` in the root of your workspace to check for missing dependencies.
 
         rosdep only runs on Linux, so you will need to install ``geometry_msgs`` and ``turtlesim`` dependencies yourself
 
-From the root of your workspace, build your updated package:
+Still in the root of your workspace, build your package:
 
 .. tabs::