Metadata-Version: 2.4
Name: habitat-obstacle-tools
Version: 0.1.0
Summary: A library for dynamic obstacle management in Habitat-Sim simulations
Author: Habitat Obstacle Tools Contributors
License: MIT
Project-URL: Homepage, https://github.com/Yuchen-byte/habitat-obstacle-tools
Project-URL: Documentation, https://github.com/Yuchen-byte/habitat-obstacle-tools#readme
Project-URL: Repository, https://github.com/Yuchen-byte/habitat-obstacle-tools
Project-URL: Issues, https://github.com/Yuchen-byte/habitat-obstacle-tools/issues
Keywords: habitat-sim,robotics,simulation,obstacle,3d,navigation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: examples
Requires-Dist: pillow; extra == "examples"
Provides-Extra: all
Requires-Dist: pillow; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Dynamic: license-file

# Habitat Obstacle Tools

A Python library for dynamic obstacle management in [Habitat-Sim](https://github.com/facebookresearch/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
```bash
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)**
```bash
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](https://github.com/facebookresearch/habitat-sim#installation)

### Dependencies
The package installs these dependencies automatically:
- `numpy`

## Quick Start

```python
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:

```yaml
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:

```bash
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](https://www.ycbbenchmarks.com/) |
| OVMM | 2540+ objects | [Habitat OVMM](https://github.com/facebookresearch/habitat-sim/blob/main/DATASETS.md) |

```python
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:
```bash
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
