Skip to content

README.md

Latest commit

 

History

History
140 lines (103 loc) · 4.45 KB

README.md

File metadata and controls

140 lines (103 loc) · 4.45 KB

G-48: Multiple Bounces Data Generator

Generates synthetic datasets for training and evaluating vision models on physics simulation and trajectory prediction tasks. Each sample contains a ball that bounces multiple times off vertical walls following reflection laws to hit a target.

Each sample pairs a task (first frame + prompt describing what needs to happen) with its ground truth solution (final frame showing the result + video demonstrating how to achieve it). This structure enables both model evaluation and training.

📌 Basic Information

Property Value
Task ID G-48
Task Multiple Bounces
Category Knowledge
Resolution 1024×1024 px
FPS 16 fps
Duration ~6 seconds
Output PNG images + MP4 video

🚀 Usage

Installation

# 1. Clone the repository
git clone https://github.com/VBVR-DataFactory/G-48_multiple_bounces_data-generator.git
cd G-48_multiple_bounces_data-generator

# 2. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
pip install -e .

Generate Data

# Generate 50 samples
python examples/generate.py --num-samples 50

# Custom output directory
python examples/generate.py --num-samples 100 --output data/my_dataset

# Reproducible generation with seed
python examples/generate.py --num-samples 50 --seed 42

# Without videos (faster)
python examples/generate.py --num-samples 50 --no-videos

Command-Line Options

Argument Description
--num-samples Number of tasks to generate (required)
--output Output directory (default: data/questions)
--seed Random seed for reproducibility
--no-videos Skip video generation (images only)

📖 Task Example

Prompt

A black ball starts with the shown initial direction arrow. It moves in straight lines and reflects off the two vertical walls following the law of reflection (the angle of reflection equals the angle of incidence). Follow this unique trajectory until the ball hits one of the red hollow circle targets in the lower-right area. Identify which target circle is hit and show the full trajectory step by step.

Visual

Initial Frame
Ball with direction, vertical walls, target circles		 Animation
Ball bounces multiple times off walls		 Final Frame
Ball hits one target after multiple bounces

📖 Task Description

Objective

Predict which target a ball will hit after bouncing multiple times off vertical walls following physics reflection laws.

Task Setup

  • Ball: Black circle with initial direction arrow
  • Walls: Two vertical boundaries that cause reflections
  • Targets: Multiple red hollow circles in lower-right area
  • Physics law: Angle of incidence = Angle of reflection
  • Trajectory: Multiple bounces before hitting target
  • Background: White with clear visibility
  • Goal: Simulate complete multi-bounce trajectory to identify target

Key Features

  • Multiple sequential wall bounces
  • Physics-based trajectory with repeated reflections
  • Law of reflection applied at each bounce
  • Multiple target options requiring full simulation
  • Tests complex spatial reasoning and physics understanding
  • Longer trajectory than single-bounce tasks

📦 Data Format

data/questions/multiple_bounces_task/multiple_bounces_00000000/
├── first_frame.png      # Ball with direction, walls, and targets
├── final_frame.png      # Ball at target after multiple bounces
├── prompt.txt           # Multi-bounce trajectory prediction instruction
├── ground_truth.mp4     # Animation of complete bounce sequence
└── question_metadata.json # Task metadata

File specifications:

  • Images: 1024×1024 PNG format
  • Video: MP4 format, 16 fps
  • Duration: ~6 seconds

🏷️ Tags

physics trajectory-prediction reflection multiple-bounces spatial-reasoning law-of-reflection