O-4: Symbol Substitution Data Generator

Generates synthetic tasks where a sequence of colored geometric symbols is shown with one marked by a red border. The goal is to replace the marked symbol with a specified new symbol while keeping all other symbols unchanged.

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-4
Task	Symbol Substitution
Category	Transformation
Resolution	1024×1024 px
FPS	16 fps
Duration	~3.1 seconds
Output	PNG images + MP4 video

---

🚀 Usage

Installation

# Clone the repository
git clone https://github.com/VBVR-DataFactory/O-4_symbol_substitution_data-generator.git
cd O-4_symbol_substitution_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

Command-Line Options

Argument	Type	Description	Default
--num-samples	int	Number of samples to generate	100
--seed	int	Random seed for reproducibility	Random
--output	str	Output directory	data/questions
--no-videos	flag	Skip video generation	False

---

📖 Task Example

Prompt

The scene shows a horizontal sequence of colored geometric symbols arranged from left to right. Each symbol is a distinct geometric shape with a specific color, and exactly one symbol is marked as the substitution target by a red rectangular border surrounding it. In symbol substitution tasks, the target symbol identified by the red border must be replaced with a new symbol while all other symbols remain unchanged in their original positions. First identify the symbol marked with the red border, then replace it with a yellow circle. The final state must show the sequence with the target symbol substituted by the yellow circle at the same position, while all other symbols retain their original shapes, colors, and sequential positions. The substitution operation affects only the single marked symbol, replacing it with the yellow circle.

Visual

Initial Frame Symbol sequence with red-bordered target	Animation Target symbol transforms to new symbol	Final Frame Target replaced, others unchanged

---

📖 Task Description

Objective

Replace the symbol marked with a red border with a specified new symbol while keeping all other symbols in the sequence unchanged.

Task Setup

• Symbol Sequence: Horizontal arrangement of colored geometric symbols
• Target Marking: Exactly one symbol marked with red rectangular border
• Substitution: Replace marked symbol with specified new symbol (e.g., orange square)
• Preservation: All other symbols retain original shape, color, and position
• Position Invariant: Substitution occurs at the same position in sequence
• Single Target: Only one symbol is modified per task

Key Features

• Target identification: Finding the symbol marked with red border
• Selective modification: Changing only the marked symbol
• Position preservation: Maintaining sequence order and positions
• Shape transformation: Replacing one geometric shape with another
• Color specification: New symbol has specified color (e.g., orange)
• Instruction following: Executing precise substitution as directed

---

📦 Data Format

data/questions/symbol_substitution_task/symbol_substitution_00000000/
├── first_frame.png      # Initial state (sequence with marked target)
├── final_frame.png      # Goal state (target substituted)
├── 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 3.1 seconds long.

---

🏷️ Tags

sequential-reasoning symbol-manipulation substitution target-identification shape-transformation instruction-following selective-editing

---