Metadata-Version: 2.4
Name: vibephysics
Version: 0.1.1
Summary: Physics simulation and annotation tools for Blender
Author-email: tsunyi <tsunyi@mimiaigen.com>
License: AGPL-3.0
Project-URL: Homepage, https://github.com/yourusername/vibephysics
Project-URL: Documentation, https://github.com/yourusername/vibephysics#readme
Project-URL: Repository, https://github.com/yourusername/vibephysics.git
Project-URL: Issues, https://github.com/yourusername/vibephysics/issues
Keywords: blender,physics,simulation,annotation,rigid-body,water,robotics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# VibePhysics

A Blender physics simulation framework for creating realistic robot animations, rigid body physics, water dynamics, and comprehensive annotation (point cloud track, bounding box, motion trails, ...) tools.

## Requirements

- **Python 3.11** (required for bpy compatibility)
- **bpy** (Blender as a Python module)

## Installation

```bash
# Create conda environment with Python 3.11
conda create -n vibephysics python=3.11
conda activate vibephysics

# Install bpy (Blender as Python module)
pip install bpy

# Install vibephysics
pip install vibephysics

# Or install from source
pip install -e .
```

## Quick Start

```bash
# Run water simulation
python examples/water/water_float.py --output output/water_float.blend

# Run robot simulation
./run_robot.sh

# Run all simulations
./run_water.sh
```

## Project Structure

```
vibephysics/
├── src/vibephysics/
│   ├── foundation/         # Core simulation modules
│   │   ├── physics.py      # Rigid body world, force fields
│   │   ├── ground.py       # Terrain generation
│   │   ├── water.py        # Water surfaces, ripples
│   │   ├── objects.py      # Floating objects
│   │   ├── materials.py    # Shaders (water, mud, etc.)
│   │   ├── lighting.py     # Lighting and camera
│   │   ├── open_duck.py    # Open Duck robot integration
│   │   ├── trajectory.py   # Waypoint paths
│   │   └── scene.py        # Scene initialization
│   └── annotation/         # Visualization tools
│       ├── bbox.py         # Bounding box annotations
│       ├── motion_trail.py # Motion path visualization
│       ├── point_tracking.py # Point cloud tracking
│       ├── viewport.py     # Dual viewport setup
│       └── manager.py      # Unified annotation API
├── examples/
│   ├── basics/             # Annotation demos
│   ├── water/              # Water simulations
│   └── robot/              # Robot simulations
├── run_water.sh            # Run water examples
├── run_robot.sh            # Run robot examples
└── run_annotation.sh       # Run annotation demos
```

## Examples

### Annotation Demos

```bash
# Bounding boxes
python examples/basics/demo_bbox.py

# Motion trails
python examples/basics/demo_motion_trail.py

# Point tracking
python examples/basics/demo_point_tracking.py

# All annotations combined
python examples/basics/demo_all_annotations.py
```

### Robot Simulations

```bash
# Robot walking through puddles
python examples/robot/robot_walking_water_puddle.py --output output/duck_walk.blend

# Duck following waypoints
python examples/robot/duck_waypoint_walk.py --waypoint-pattern exploration --output output/duck.blend
```

### Water Simulations

```bash
# Floating objects
python examples/water/water_float.py --output output/water_float.blend

# Rising water
python examples/water/water_rise.py --output output/water_rise.blend

# Storm with debris
python examples/water/storm.py --output output/storm.blend

# Water puddles
python examples/water/water_puddles.py --output output/water_puddles.blend
```

## Shell Scripts

```bash
# Run all water simulations
./run_water.sh

# Run robot simulations (auto-downloads Open Duck model)
./run_robot.sh

# Run annotation demos
./run_annotation.sh
```

## Common Arguments

| Argument | Description |
|----------|-------------|
| `--output` | Output .blend file path |
| `--start-frame` | Animation start frame |
| `--end-frame` | Animation end frame |
| `--num-spheres` | Number of floating objects |
| `--wave-scale` | Wave intensity |
| `--no-annotations` | Disable annotations |

## License

**© 2025 MIMI AI LTD, UK. All rights reserved.**

### Academic & Student Use (Free)
This software is **free to use** for:
- Students
- Academic research
- Educational purposes

### Commercial Use
For business or enterprise use, please contact: **tsunyi@mimiaigen.com**


### Dependency
We use the [Open Duck blender model](https://github.com/pollen-robotics/Open_Duck_Blender) as demo purpose. We do not own the model. Please refer to the original github repo.


### Citation
```
@misc{VibePhysics,
  author = {Tsun-Yi Yang},
  title = {VibePhysics: Physics and Robotics Simulation in Blender Without GPU Requirements},
  month = {December},
  year = {2025},
  url = {https://github.com/mimiaigen/vibephysics}
}
```
