Generates synthetic datasets for training and evaluating vision models on planar homography and geometric transformation tasks. Each sample contains a grid that must be warped to align with a red target quadrilateral outline.
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.
| Property | Value |
|---|---|
| Task ID | O-83 |
| Task | Planar Warp Verification |
| Category | Spatiality |
| Resolution | 1024×1024 px |
| FPS | 16 fps |
| Duration | ~2-3 seconds |
| Output | PNG images + MP4 video |
# 1. Clone the repository
git clone https://github.com/VBVR-DataFactory/O-83_planar_warp_verification_data-generator.git
cd O-83_planar_warp_verification_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 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| 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) |
Transform the blue grid by aligning its four corners to the four corners of the red quadrilateral. Apply a perspective transformation so the grid matches the red outline. Keep all background elements, colored dots, and gray patches unchanged. Output the transformed grid.
 |
 |
 |
| Initial Frame Axis-aligned grid with red target quad |
Animation Grid warps to match target outline |
Final Frame Grid aligned with target quadrilateral |
Apply a planar homography transformation to warp the source grid so it perfectly aligns with the red target quadrilateral outline.
- Source grid: Blue grid lines forming a rectangular mesh (6-12 rows/cols)
- Target outline: Red quadrilateral with perspective distortion
- Transformation: Single planar warp (homography matrix)
- Fixed elements: Background noise dots and occlusion patches remain stationary
- Center marker: Emphasized cross-lines on source grid
- Corner markers: Small circles marking grid corners
- Background: Light gray with subtle noise
- Planar homography estimation and application
- Perspective transformation with varying distortion strength
- Target corners include random jitter for complexity
- Optional occlusion patches (40% probability)
- Optional blur on final frame (25% probability)
- Tests understanding of geometric transformations
- Requires spatial reasoning and projective geometry knowledge
data/questions/planar_warp_verification_task/planar_warp_verification_00000000/
├── first_frame.png # Source grid with target outline
├── final_frame.png # Warped grid aligned with target
├── prompt.txt # Planar warp instruction
├── ground_truth.mp4 # Animation of warp transformation
└── question_metadata.json # Task metadata
File specifications:
- Images: 1024×1024 PNG format
- Video: MP4 format, 16 fps
- Duration: ~2-3 seconds
transformation planar-homography geometric-transformation perspective-warp spatial-reasoning projective-geometry