Implementation:Facebookresearch Habitat lab TopdownMap Visualization Tutorial

Knowledge Sources	Facebookresearch_Habitat_lab
Domains	Embodied_AI, Tutorials, Visualization
Last Updated	2026-02-15 00:00 GMT

Overview

The Habitat_Lab_TopdownMap_Visualization tutorial demonstrates how to generate and visualize top-down maps, bird's-eye views, and agent navigation videos using Habitat Lab's mapping and visualization utilities.

Description

This tutorial provides four progressive examples of top-down map visualization in Habitat:

1. example_pointnav_draw_target_birdseye_view(): Draws a simple bird's-eye view image showing the relative positions of an agent and a navigation goal. Creates a dummy NavigationEpisode with a goal at position [10, 0.25, 10] and an agent at [0, 0.25, 0], then uses maps.pointnav_draw_target_birdseye_view() to render the spatial relationship.

2. example_pointnav_draw_target_birdseye_view_agent_on_border(): Tests edge cases by placing the agent at four border positions relative to a centered goal. Iterates over combinations of x_edge and y_edge values (-1, 0, 1) and generates bird's-eye view images for each configuration.

3. example_get_topdown_map(): Generates a full top-down occupancy map of a scene. Creates a Habitat environment, loads the first episode, and calls maps.get_topdown_map_from_sim() at 1024 resolution. Recolors the map (white=occupied, gray=unoccupied, black=border) and displays it with matplotlib.

4. example_top_down_map_measure(): Creates a complete navigation visualization with a ShortestPathFollowerAgent that follows the optimal path to the goal. Configures the TopDownMap and Collisions measurement plugins with settings for fog-of-war (5.0m visibility, 90-degree FOV), shortest path drawing, goal positions, and AABBs. Records each frame with the top-down map overlay and produces a video using images_to_video().

The tutorial also defines ShortestPathFollowerAgent, a simple agent implementation that wraps ShortestPathFollower to always take the next action on the shortest path to the goal.

Usage

This tutorial is intended for users who want to generate top-down map visualizations of Habitat environments, useful for debugging navigation policies, creating figures for papers, or understanding scene layouts. Requires Habitat test scenes and pointnav episode datasets.

Code Reference

Source Location

Repository: Facebookresearch_Habitat_lab
File: examples/tutorials/nb_python/Habitat_Lab_TopdownMap_Visualization.py
Lines: 1-319

Signature

def example_pointnav_draw_target_birdseye_view():
    ...

def example_pointnav_draw_target_birdseye_view_agent_on_border():
    ...

def example_get_topdown_map():
    ...

class ShortestPathFollowerAgent(Agent):
    def __init__(self, env: habitat.Env, goal_radius: float):
        ...
    def act(self, observations: "Observations") -> Union[int, np.ndarray]:
        ...
    def reset(self) -> None:
        ...

def example_top_down_map_measure():
    ...

Import

import habitat
from habitat.config.default_structured_configs import (
    CollisionsMeasurementConfig,
    FogOfWarConfig,
    TopDownMapMeasurementConfig,
)
from habitat.core.agent import Agent
from habitat.tasks.nav.nav import NavigationEpisode, NavigationGoal
from habitat.tasks.nav.shortest_path_follower import ShortestPathFollower
from habitat.utils.visualizations import maps
from habitat.utils.visualizations.utils import (
    images_to_video,
    observations_to_image,
    overlay_frame,
)

I/O Contract

Inputs

Name	Type	Required	Description
PointNav config	str	Yes	Path to pointnav_habitat_test.yaml configuration
Test scenes	files	Yes	Habitat test scene data (downloadable via habitat_sim.utils.datasets_download)
PointNav episodes	files	Yes	Habitat test pointnav dataset

Outputs

Name	Type	Description
Bird's-eye view images	matplotlib plots	Rendered images showing agent-goal spatial relationships
Top-down map	matplotlib plot	Occupancy grid visualization of the scene
Navigation video	MP4	Video of agent following shortest path with top-down map overlay

Usage Examples

Basic Usage

import habitat
import numpy as np
from habitat.utils.visualizations import maps
from habitat.tasks.nav.nav import NavigationEpisode, NavigationGoal
from typing import cast

# Draw a bird's-eye view of agent and goal
goal = NavigationGoal(position=[10, 0.25, 10], radius=0.5)
agent_position = np.array([0, 0.25, 0])
agent_rotation = -np.pi / 4

target_image = maps.pointnav_draw_target_birdseye_view(
    agent_position,
    agent_rotation,
    np.asarray(goal.position),
    goal_radius=goal.radius,
    agent_radius_px=25,
)

# Generate a top-down map from a scene
config = habitat.get_config(
    config_path="habitat-lab/habitat/config/benchmark/nav/pointnav/pointnav_habitat_test.yaml"
)
with habitat.Env(config=config) as env:
    env.reset()
    top_down_map = maps.get_topdown_map_from_sim(
        cast("HabitatSim", env.sim), map_resolution=1024
    )
    # Recolor: 0=occupied(white), 1=unoccupied(gray), 2=border(black)
    recolor_map = np.array(
        [[255, 255, 255], [128, 128, 128], [0, 0, 0]], dtype=np.uint8
    )
    top_down_map = recolor_map[top_down_map]

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment