Tutorial: Generate an Occupancy Map for Navigation
==================================================

This tutorial walks you through the creation of a 2D occupancy map of your environment.
This map can the be used for autonomous navigation.

Instructions
------------

1. SSH into the robot (:ref:`instructions<nova-carter-ssh-setup>`).

2. Make sure you have successfully connected the PS5 joystick to the robot
   (:ref:`instructions<nova-carter-joystick-setup>`).

3. Build and install the required packages:

.. run_ros_app::
    :repo_setup: <nova-carter-dev-setup>
    :repo: nova_carter
    :image: isaac/nova_carter_bringup:release_3.1-aarch64
    :package: nova_carter_bringup
    :app: lidar_mapping.launch.py
    :skip_packages: isaac_ros_ess_models_install:isaac_ros_peoplesemseg_models_install

4. Make sure you complete :ref:`visualization-setup-carter`.
   Open Foxglove Studio on your remote machine,
   open the ``nova_carter_navigation.json`` layout file downloaded in the previous step.

   Verify that you see a visualization of the part of the map that is in close proximity to the
   robot.

.. figure::
    :ir_lfs:`<resources/isaac_ros_docs/robots/nova_carter/foxglove_mapping.png>`
    :width: 800px
    :alt: foxglove_mapping
    :align: center

5. To map your entire environment move the robot around using the joystick. Verify that you can
   see the map visualization in Foxglove expand in real-time as you are moving the robot around.

6. To store the map open a new terminal, SSH into the robot, and attach to the
   Docker container that's running the Lidar mapping application. This depends on
   what approach you chose above to build and install the app.

.. tabs::

    .. tab:: Docker Image

        Get the name of the Docker container by running:

        .. code:: bash

          docker ps

        Then attach to the Docker container with the following command. Make
        sure to replace ``<name-of-docker-container>`` with the name found
        above.

        .. code:: bash

          docker exec -it <name-of-docker-container> /bin/bash

    .. tab:: Binary Package

        Isaac ROS development Docker container using the ``run_dev.sh`` script:

        .. code:: bash

          cd $ISAAC_ROS_WS/src/isaac_ros_common && \
            ./scripts/run_dev.sh

    .. tab:: Build from Source

        Isaac ROS development Docker container using the ``run_dev.sh`` script:

        .. code:: bash

          cd $ISAAC_ROS_WS/src/isaac_ros_common && \
            ./scripts/run_dev.sh


7. Run the following command to save the map ``.png`` and ``.yaml`` file:

   This ``.yaml`` file can be used as the input map in the
   :doc:`navigation tutorial</reference_workflows/isaac_perceptor/tutorials_on_carter/demo_navigation>`.

.. code:: bash

    source /opt/ros/humble/setup.bash
    cd /workspaces/isaac_ros-dev
    ros2 run nav2_map_server map_saver_cli --fmt png -f <path/to/my/map>

.. note::

   Replace ``<path/to/my/map>`` with the path where the map
   will be stored. To keep the map when the Docker container is
   stopped, it is recommended to use a path that is mounted to the Docker
   container, for example ``/tmp/my_map.png``. If you are running this example
   with the pre-built Docker image, then no suitable path is mounted. In this case
   store the map to ``/tmp/my_map.png`` and then copy it out of the container with
   ``docker cp <name-of-docker-container>:/tmp/my_map.png .``.