G-3: Stable Sort Data Generator

Generates synthetic datasets for training and evaluating vision models on stable sorting tasks. Each sample contains shapes that must be grouped by type and sorted by size while maintaining relative order.

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-3
Task	Stable Sort
Category	Perception
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-3_stable_sort_data-generator.git
cd G-3_stable_sort_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

The scene contains two types of shapes, each type has three shapes of different sizes arranged randomly. Keep all shapes unchanged in appearance (type, size, and color). Only rearrange their positions: first group the shapes by type, then within each group, sort the shapes from smallest to largest (left to right), and arrange all shapes in a single horizontal line from left to right.

Visual

Initial Frame Shapes in random positions	Animation Grouping and sorting process	Final Frame Shapes grouped by type, sorted by size

---

📖 Task Description

Objective

Rearrange shapes into groups based on their type, then sort each group by size (smallest to largest), maintaining a stable sort order.

Task Setup

• Shape types: 2 different types per scene (e.g., circles and squares)
• Shapes per type: 3 shapes of different sizes
• Initial layout: Random positions
• Final layout: Single horizontal line
• Sorting criteria:
  1. Primary: Group by shape type
  2. Secondary: Sort by size (ascending) within each group
• Background: Pure white

Key Features

• Tests understanding of stable sorting algorithms
• Requires grouping by categorical attribute (shape type)
• Requires ordering by continuous attribute (size)
• Maintains relative order for equal elements
• Smooth animation showing the sorting process
• Multiple shape combinations for variety

---

📦 Data Format

data/questions/stable_sort_task/stable_sort_00000000/
├── first_frame.png      # Shapes in random arrangement
├── final_frame.png      # Shapes after grouping and sorting
├── prompt.txt           # Sorting instruction
├── ground_truth.mp4     # Animation of the sorting process
└── question_metadata.json # Task metadata

File specifications:

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

---

🏷️ Tags

sorting stable-sort grouping logic size-comparison visual-reasoning

---