habitat-obstacle-tools 0.1.0

A library for dynamic obstacle management in Habitat-Sim simulations

Habitat Obstacle Tools

A Python library for dynamic obstacle management in Habitat-Sim simulations.

Features

• Dynamic object management: Spawn, move, and remove obstacles at runtime
• Multiple coordinate frames: World (Habitat), robot current, robot start frames
• Physics properties: Mass, friction, restitution, motion types (DYNAMIC/KINEMATIC/STATIC)
• Object library: Includes basic test objects (chair, sphere, donut); supports additional object datasets
• Interactive control: Terminal keyboard control with real-time visualization
• Event-driven: Pre-configured object spawn/move events via YAML configuration

Installation

Core Package

pip install habitat-obstacle-tools

Habitat-Sim Installation

This library requires habitat-sim to be installed separately, as it is not available on PyPI and must be built from source or installed via conda:

Option 1: Conda (Recommended)

conda create -n habitat python=3.9
conda activate habitat
conda install habitat-sim -c conda-forge -c aihabitat

Option 2: Build from Source Follow the Habitat-Sim installation instructions

Dependencies

The package installs these dependencies automatically:

• numpy

Quick Start

from habitat_obstacle_tools import (
    spawn_object, move_object, PhysicsProperties, MotionType, ReferenceFrame
)

# Spawn a chair at world coordinates (1, 0, 2)
obj = spawn_object(sim, "chair", position=(1, 0, 2))

# Spawn a sphere 2 meters in front of the robot
obj2 = spawn_object(
    sim,
    obj_source="sphere",
    position=(0, 0, -2),  # Forward is -Z direction
    frame="robot"
)

# Move object to new position
move_object(obj, sim, position=(3, 0, 5))

# Use verbose to see coordinate transforms
obj3 = spawn_object(sim, "chair", position=(0, 0, -2), frame="robot", verbose=True)
# prints: [spawn] 'chair' at frame=robot local=(0.000, 0.000, -2.000) -> world=(...)

Coordinate Frames

Frame	Description	Usage
habitat	World coordinate system	Absolute positions
robot	Robot's current position as origin	Relative to robot, forward is -Z
robot_start	Robot's start position as origin	Relative to start position

Motion Types

Type	Description	Collision Detection	Use Case
DYNAMIC	Controlled by physics engine, affected by gravity and collisions	Requires manual NavMesh updates	Movable objects
KINEMATIC	Can be moved via code, not affected by physics	None	Animated objects
STATIC	Completely static, immovable	Automatic (with update_navmesh=True)	Fixed obstacles

Configuration

See config.yaml for complete configuration examples:

scene:
  glb: "/path/to/scene.glb"
  navmesh: "/path/to/scene.navmesh"

object_events:
  - step: 5
    action: "spawn"
    obj_source: "chair"
    position: [0.0, 0.0, -2.0]
    frame: "robot"
    physics:
      mass: 5.0
      motion_type: "static"

interactive_objects:
  - name: "chair"
    obj_source: "chair"
    physics: { mass: 5.0, motion_type: "static" }

Interactive Test

Run the interactive test application:

python -m habitat_obstacle_tools.test_interactive --config config.yaml

Controls:

• W/↑: Move forward
• S/↓: Move backward
• A/←: Turn left
• D/→: Turn right
• 1-9: Spawn preset objects 2m in front of robot
• M: Move most recently spawned object to robot's right side
• Q/ESC: Exit and save video

Additional Object Libraries

The package includes basic objects (chair, sphere, donut). For more objects, download from the official Habitat datasets and register the directory:

Dataset	Objects	Source
YCB	77 everyday objects	YCB Benchmarks
OVMM	2540+ objects	Habitat OVMM

from habitat_obstacle_tools import add_object_dir

# Point to your downloaded object configs
add_object_dir("/path/to/ycb/configs")
add_object_dir("/path/to/ovmm/ai2thorhab/configs/objects")

Or set the HABITAT_OBJECTS_DIR environment variable:

export HABITAT_OBJECTS_DIR=/path/to/your/objects

API Reference### Core Functions

• spawn_object() - Create object in simulator
• move_object() - Move existing object to new pose
• recompute_navmesh() - Recompute navigation mesh for collision detection
• parse_physics() - Parse physics properties from dictionary

Types

• MotionType - Enum: DYNAMIC, KINEMATIC, STATIC
• PhysicsProperties - Dataclass for physical properties
• ReferenceFrame - Enum: HABITAT, ROBOT, ROBOT_START

License

MIT