O-52: Traffic Light Data Generator (4-Light Crossroad with 3-Color Cycle)

Generates synthetic traffic light countdown reasoning tasks with four traffic lights at a crossroad (North, South, East, West) and Red/Yellow/Green cycle. The goal is to understand the 3-color traffic light cycle and predict the final state after a specified simulation time. Each light follows an independent cycle: Red (5-15s) → Yellow (3s) → Green (10s) → Yellow (3s) → Red.

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	O-52
Task	Traffic Light
Category	Knowledge
Resolution	1024×1024 px
FPS	16 fps
Duration	~5-15 seconds
Output	PNG images + MP4 video

---

🚀 Usage

Installation

# Clone the repository
git clone https://github.com/Jiaqi-Gong/Gong_VBVR_Data.git
cd Gong_VBVR_Data/O-52_traffic_light_data-generator

# Install dependencies
pip install -r requirements.txt

Generate Data

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

# Generate with specific seed
python examples/generate.py --num-samples 100 --seed 42

# Generate without videos
python examples/generate.py --num-samples 100 --no-videos

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

# Generate specific task types
python examples/generate.py --num-samples 100 --types 1 2

Command-Line Options

Argument	Type	Description	Default
--num-samples	int	Number of samples to generate	Required
--seed	int	Random seed for reproducibility	Random
--output	str	Output directory	data/questions
--no-videos	flag	Skip video generation	False
--types	list[int]	Specific task types to generate (1-4)	All types

---

📖 Task Example

Prompt

This scene shows a crossroad with two traffic lights (North, South). Each light independently follows a 3-color cycle: Red (4s) → Yellow (4s) → Green (4s) → Yellow (4s) → Red. Currently: North light is red with 1s countdown, South light is yellow with 3s countdown. Simulate 4 seconds and show the final state of both traffic lights.

Visual

Initial Frame Traffic lights with countdown timers	Animation Countdown decrementing to zero	Final Frame Traffic lights after countdown reaches zero

---

📖 Task Description

Objective

Understand the 3-color traffic light cycle behavior at a 4-way crossroad and predict the final state of all four lights after a specified simulation time. Each light independently cycles through states: Red → Yellow → Green → Yellow → Red.

Task Setup

• Traffic Lights: Four traffic lights at a crossroad (North, South, East, West)
• 3-Color Cycle: Each light independently follows: Red (5-15s random) → Yellow (3s fixed) → Green (10s fixed) → Yellow (3s fixed) → Red
• Independent Rule: Each light transitions to the next state in its cycle only when its own countdown reaches zero
• Simulation Time: Tasks specify how many seconds to simulate (e.g., "Simulate 13 seconds")
• Task Types:
  • Type 1: Single light countdown (simple)
  • Type 2: Two lights with countdowns (medium)
  • Type 3/4: Multiple lights coordination (hard)
• Countdown Display: Shows countdown numbers that decrement over time
• State Transition: When a light's countdown reaches 0, that light transitions to the next state in its cycle

Key Features

• Temporal reasoning: Tests ability to understand countdown timers and time progression
• State prediction: Requires predicting final states after countdown completion
• Independent switching: Must understand that each light switches independently
• Multiple difficulty levels: Four task types with increasing complexity
• Visual countdown: Clear numeric countdown display on traffic lights
• Smooth animation: Shows countdown decrementing frame by frame

---

📦 Data Format

data/questions/traffic_light_task/traffic_light_00000000/
├── first_frame.png      # Initial state (traffic lights with countdown)
├── final_frame.png      # Goal state (after countdown reaches zero)
├── prompt.txt           # Task instructions
├── ground_truth.mp4     # Solution video (16 fps)
└── question_metadata.json # Task metadata

File specifications: Images are 1024×1024 PNG. Videos are MP4 at 16 fps, approximately 5-15 seconds long depending on countdown duration.

---

🏷️ Tags

traffic-light countdown temporal-reasoning state-prediction time-understanding abstraction rule-inference

---