Attention

As of June 30, 2025, the Isaac ROS Buildfarm for Isaac ROS 2.1 on Ubuntu 20.04 Focal is no longer supported.

Due to an isolated infrastructure event, all ROS 2 Humble Debian packages that were previously built for Ubuntu 20.04 are no longer available in the Isaac Apt Repository. All artifacts for Isaac ROS 3.0 and later are built and maintained with a more robust pipeline.

Users are encouraged to migrate to the latest version of Isaac ROS. The source code for Isaac ROS 2.1 continues to be available on the release-2.1 branches of the Isaac ROS GitHub repositories.

The original documentation for Isaac ROS 2.1 is preserved below.

isaac_ros_occupancy_grid_localizer

Source code on GitHub.

Quickstart

1. Set up your development environment by following these instructions.

2. Clone isaac_ros_common and this repository under ${ISAAC_ROS_WS}/src.

   cd ${ISAAC_ROS_WS}/src
   

   git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common.git
   

   git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_map_localization.git
   

3. Pull down a ROS bag of sample data:

   cd ${ISAAC_ROS_WS}/src/isaac_ros_map_localization && \
     git lfs pull -X "" -I "**/rosbags/"
   

4. Launch the Docker container using the run_dev.sh script:

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

5. Install this package’s dependencies.

sudo apt-get install -y ros-humble-isaac-ros-occupancy-grid-localizer

6. Run rviz2:

   rviz2 -d  src/isaac_ros_map_localization/isaac_ros_occupancy_grid_localizer/rviz/quickstart.rviz
   

7. Create another terminal in the Docker container using the run_dev.sh script:

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

8. Run the launch file to spin up a demo of this package:

   ros2 launch isaac_ros_occupancy_grid_localizer isaac_ros_occupancy_grid_localizer_quickstart.launch.py
   

9. Create another terminal in the Docker container using the run_dev.sh script:

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

10. Run the rosbag:

    ros2 bag play -l src/isaac_ros_map_localization/isaac_ros_occupancy_grid_localizer/data/rosbags/flatscan
    

11. Create another terminal in the docker container using the run_dev.sh script:

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

12. Trigger the localization using a command line service call :

    ros2 service call trigger_grid_search_localization std_srvs/srv/Empty {}
    

13. You should see a frame being generated in the map showing the position of the LIDAR.

Try More Examples

To continue your exploration, check out the following suggested examples:

• Tutorial with Isaac Sim

Troubleshooting

Isaac ROS Troubleshooting

For solutions to problems with Isaac ROS, please check here.

API

Usage

ros2 launch isaac_ros_occupancy_grid_localizer isaac_ros_occupancy_grid_localizer.launch.py

Note

Use the flatscan topic with the trigger_grid_search_localization service to trigger localization using a service.

Or publish directly to the flatscan_localization topic to trigger localization every time a FlatScan message is received on this topic.

Do not publish FlatScan messages to both flatscan and flatscan_localization topics.

ROS Parameters

Note

The ROS parameter names are the same as the Nav2 map_server YAML parameters. This allows to load and pass the same YAML file to both Nav2 and isaac_ros_occupancy_grid_localizer as shown in the Isaac Sim Launch File

ROS Parameter	Type	Default	Description
loc_result_frame	std::string	map	frame_id of localization result
resolution	double	0.05	The meters per pixel of the .png map being loaded. This parameter is loaded from the the map YAML file.
origin	std::vector<double>	[0.0, 0.0, 0.0]	The origin of the map loaded. Used to transform the output to compensate for the same transform made to the PNG file loaded by the Nav2 map_server.
occupied_thresh	double	0.65	Pixels with occupancy probability greater than this threshold are considered completely occupied. This parameter is loaded from the the map YAML file. Supported values: [0,1)
image	std::string	""	Name of the PNG file used to load map. This should be in the same directory as the map YAML file specified in map_yaml_path. This parameter is loaded from the the map YAML file.
map_yaml_path	std::string	""	Absolute path to the map YAML file. From which we load the resolution and occupied_thresh
max_points	int	20000	Maximum number of points in FlatScan Message that can be received used to pre-allocate GPU memory.
robot_radius	double	0.25	The radius of the robot. This parameter is used to exclude poses which are too close to an obstacle.memory.
min_output_error	double	0.22	The minimal output error used to normalize and compute confidence, if output error from best sample smaller or equal to this, the confidence is 1
max_output_error	double	0.35	The max output error from our best sample, if output error larger than this threshold, we conclude localization failed
max_beam_error	double	0.5	The maximum beam error used when comparing range scans.
num_beams_gpu	int	512	The GPU accelerated scan-and-match function can only handle a certain number of beams per range scan. The allowed values are {32, 64, 128, 256, 512}. If the number of beams in the range scan does not match this number a subset of beams will be taken.
batch_size	int	512	This is the number of scans to collect into a batch for the GPU kernel. Choose a value which matches your GPU well.
sample_distance	double	0.1	Distance between sample points in meters. The smaller this number, the more sample poses will be considered. This leads to a higher accuracy and lower performance.
out_of_range_threshold	double	100.0	Points range larger than this threshold will be marked as out of range and not used.
invalid_range_threshold	double	0.0	Points range smaller than this threshold will be marked as invalid and not used.
min_scan_fov_degrees	double	270.0	Minimal required scan FoV to run the localizer.
use_closest_beam	bool	true	Whether or not pick the closest angle beam in angle bucket, if not pick the average within an angular bucket

ROS Topics Subscribed

ROS Topic	Type	Description
flatscan	isaac_ros_pointcloud_interfaces::msg::FlatScan	The input FlatScan messages buffer. The last message on this topic will be used as input for localization when the trigger_grid_search_localization service is called.
flatscan_localization	isaac_ros_pointcloud_interfaces::msg::FlatScan	The topic to trigger localization directly without a buffer. Localization will be triggered every time a FlatScan message is received on this topic.

ROS Topic	Interface	Description
localization_result	geometry_msgs::msg::PoseWithCovarianceStamped	Pose of the scan data with respect to the map origin, as specified in the first note in the overview section

ROS Services Advertised

ROS Service	Interface	Description
trigger_grid_search_localization	std_srvs::srv::Empty	The service to trigger the global localization using the last scan received on the flatscan input topic.