Implementation:Facebookresearch Habitat lab HitlTutorial

Knowledge Sources	Facebookresearch_Habitat_lab
Domains	Embodied_AI, Human_in_the_Loop, Tutorial_System
Last Updated	2026-02-15 00:00 GMT

Overview

Implements an animated tutorial system for the Human-in-the-Loop (HITL) framework, guiding users through scene overview, target objects, robot companion, and avatar control using camera transitions, object animations, and display text.

Description

This module provides a multi-stage tutorial system with three main classes:

ObjectAnimation:

• Animates a rigid object from its starting position to a camera-facing target position and back.
• Uses smooth interpolation (mn.math.lerp for position, mn.math.slerp for rotation) with easing.
• Applies a continuous slow rotation around a fixed axis to give the user perspective on the object.
• Has configurable duration, place-back time, and rotation speed.

TutorialStage:

• Represents a single stage of the tutorial with a camera look-at transition.
• Interpolates between previous and next camera look-at vectors using a quintic ease-in-out function.
• Can optionally include an ObjectAnimation.
• Tracks elapsed time and reports completion.
• Provides a get_look_at_matrix method for computing the camera transform.

Tutorial:

• Orchestrates a sequence of TutorialStage instances.
• Supports skipping stages and stopping animations.
• Manages pending object animations that need to complete even after their stage ends.
• Provides display text and help text for the current stage.

generate_tutorial function:

• Factory function that builds a complete tutorial from a simulation state.
• Creates stages for: scene overview (top-down), each target object (zoom and showcase), robot companion focus, avatar focus, and final camera transition.
• Uses bounding box calculations and navmesh sampling to find good camera viewpoints.

Predefined text constants: TEXT_SCENE_OVERVIEW, TEXT_ROBOT_FOCUS, TEXT_AVATAR_FOCUS, and TEXT_HELP.

Usage

Use this module to create guided introductory tutorials for HITL tasks. Call generate_tutorial with the simulator, agent index, and final camera look-at to generate a tutorial. Update each frame with tutorial.update(dt) and use tutorial.get_look_at_matrix() to drive the camera.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-hitl/habitat_hitl/environment/hitl_tutorial.py
• Lines: 1-497

Signature

class ObjectAnimation:
    def __init__(
        self,
        obj: habitat_sim.physics.ManagedBulletRigidObject,
        view_lookat: Tuple[mn.Vector3, mn.Vector3],
        distance_from_view: float,
        duration: float,
        place_back_time: float = 0.3,
        rotation_animation_speed: float = 25.0,
    ) -> None: ...
    def update(self, dt: float): ...
    def reset(self): ...

class TutorialStage:
    def __init__(
        self,
        stage_duration: float,
        next_lookat: Tuple[mn.Vector3, mn.Vector3],
        prev_lookat: Tuple[mn.Vector3, mn.Vector3] = None,
        transition_duration: float = 0.0,
        display_text: str = "",
        object_animation: ObjectAnimation = None,
    ) -> None: ...
    def update(self, dt: float) -> None: ...
    def get_look_at_matrix(self) -> mn.Matrix4: ...
    def is_completed(self) -> bool: ...
    def get_display_text(self) -> str: ...

class Tutorial:
    def __init__(self, tutorial_stages: List[TutorialStage]) -> None: ...
    def update(self, dt: float) -> None: ...
    def is_completed(self) -> bool: ...
    def get_look_at_matrix(self) -> mn.Matrix4: ...
    def get_display_text(self) -> str: ...
    def get_help_text(self) -> str: ...
    def skip_stage(self) -> None: ...
    def stop_animations(self) -> None: ...

def generate_tutorial(
    sim, agent_idx: int, final_lookat: Tuple[mn.Vector3, mn.Vector3]
) -> Tutorial: ...

Import

from habitat_hitl.environment.hitl_tutorial import (
    Tutorial,
    TutorialStage,
    ObjectAnimation,
    generate_tutorial,
)

I/O Contract

Inputs (generate_tutorial)

Name	Type	Required	Description
sim	RearrangeSim	Yes	The Habitat simulator instance with scene and agents loaded
agent_idx	int	Yes	The index of the agent being controlled by the user
final_lookat	Tuple[mn.Vector3, mn.Vector3]	Yes	The final camera eye and target positions (the gameplay camera)

Outputs (generate_tutorial)

Name	Type	Description
return	Tutorial	A fully constructed Tutorial object with all stages configured

Usage Examples

Generating and Running a Tutorial

import magnum as mn
from habitat_hitl.environment.hitl_tutorial import generate_tutorial

# Create the tutorial from the current sim state
final_lookat = (mn.Vector3(0, 1.5, 0), mn.Vector3(0, 1.5, -3))
tutorial = generate_tutorial(sim, agent_idx=0, final_lookat=final_lookat)

# Main loop
while not tutorial.is_completed():
    dt = get_delta_time()
    tutorial.update(dt)

    # Apply the camera transform
    cam_matrix = tutorial.get_look_at_matrix()
    set_camera_transform(cam_matrix)

    # Display tutorial text
    display_text(tutorial.get_display_text())

    # Allow skipping with spacebar
    if spacebar_pressed():
        tutorial.skip_stage()

Creating a Custom Tutorial Stage

from habitat_hitl.environment.hitl_tutorial import TutorialStage, Tutorial

stage1 = TutorialStage(
    stage_duration=5.0,
    next_lookat=(mn.Vector3(0, 5, 0), mn.Vector3(0, 0, 0)),
    display_text="Overview of the scene",
)
stage2 = TutorialStage(
    stage_duration=3.0,
    prev_lookat=(mn.Vector3(0, 5, 0), mn.Vector3(0, 0, 0)),
    next_lookat=(mn.Vector3(1, 1.5, 1), mn.Vector3(0, 0.5, 0)),
    transition_duration=1.5,
    display_text="Focus on target area",
)

tutorial = Tutorial([stage1, stage2])