Skip to content

README.md

Latest commit

 

History

History
143 lines (105 loc) · 5.52 KB

README.md

File metadata and controls

143 lines (105 loc) · 5.52 KB

Multi-22: Pointer Chasing Arrows Data Generator

Generates synthetic datasets for arrow-pointer chasing. The agent must traverse a grid of cells where every cell contains an arrow that dictates allowed movement directions, finding a valid step-by-step path from the start dot to a target cell — a deterministic execution of "follow the pointers" semantics.

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 Multi-22
Task Pointer Chasing (Arrow Route)
Category Algorithmic Execution
Resolution 1024×1024 px
FPS 16 fps
Duration varies
Output PNG images + MP4 video

🚀 Usage

Installation

# 1. Clone the repository
git clone https://github.com/VBVR-DataFactory/Multi-22_pointer_chasing_arrows_data-generator.git
cd Multi-22_pointer_chasing_arrows_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

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

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

# Without videos (faster, images only)
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

[Scenario] The image displays a grid-based maze containing a red start dot, black walls, and several cells labeled with letters.
[Rules]
1. The agent must move exactly according to the provided sequence of steps.
2. The path strictly follows empty cells and does not cross walls.
[Task] Generate a video animating the agent executing the following exact moves step-by-step: right 1, up 1, up 1, up 1. The agent will eventually arrive at a target letter. Hold the final position and highlight that letter and its cell.

Visual

Initial Frame
Grid of arrow cells + start dot + target letter		 Animation
Path traced cell-by-cell along valid arrow directions		 Final Frame
Complete blue path from start to target

📖 Task Description

Objective

Trace a valid path on a grid where each cell holds an arrow that constrains the allowed movement directions out of that cell. The path must connect the start dot to the labeled target cell, drawn one step at a time as a blue line.

Task Setup

  • Grid: 4×4 to 7×7 cells, each containing a directional arrow.
  • Start: A red dot pinned to one cell.
  • Target: A red letter (label) marking the destination cell.
  • Movement rule: At each step, the move direction must agree with the current cell's arrow (or one of the allowed directions encoded by it).
  • Goal: Draw a continuous blue trace, cell-by-cell, that reaches the target.
  • Solver: BFS over the directed graph induced by the arrows guarantees a valid (shortest) path.

Key Features

  • Pointer-chasing semantics: Each cell encodes a local "next-step" rule, generalizing data-structure pointer traversal.
  • Strict execution discipline: Skipping or violating any arrow invalidates the entire trace.
  • Sequential dependency: The reachable cell at step k depends on the cells visited at steps 1..k-1.
  • Visible cell-by-cell trace: Each step is rendered as a new blue segment, providing fine-grained correctness signal.

📦 Data Format

data/questions/Multi-22_pointer_chasing_arrows_data-generator_task/Multi-22_pointer_chasing_arrows_data-generator_00000000/
├── first_frame.png            # Arrow grid + start + target
├── final_frame.png            # Trace complete from start to target
├── prompt.txt                 # Task instruction
├── ground_truth.mp4           # Animation of stepwise path drawing
└── question_metadata.json     # Standardized VBVR task metadata

File specifications:

  • Images: 1024×1024 PNG format
  • Video: MP4 format, 16 fps, H.264 + yuv420p
  • Metadata: VBVR canonical schema with task_id, vbvr_task_code, media, parameters

🏷️ Tags

pointer-chasing arrow-route directed-graph algorithmic-execution deterministic path-tracing multi-step-reasoning

Part of the 36-Task Long-Horizon Multi-Step Reasoning Benchmark.