Generates synthetic datasets for the Numbrix logic puzzle. The agent must fill every cell of a grid with consecutive integers from 1 to N², such that consecutive numbers occupy orthogonally adjacent cells, forming a Hamiltonian path through the grid.
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 | Multi-15 |
| Task | Numbrix Path Filling |
| Category | Constraint Satisfaction Puzzles |
| Resolution | 1024×1024 px |
| FPS | 16 fps |
| Duration | varies |
| Output | PNG images + MP4 video |
# 1. Clone the repository
git clone https://github.com/VBVR-DataFactory/Multi-15_numbrix_pathfilling_data-generator.git
cd Multi-15_numbrix_pathfilling_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
# 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| 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) |
[Scenario] The image shows a grid containing a few scattered numbers.
[Rules]
1. The grid must be filled with consecutive numbers from 1 to the highest number.
2. Consecutive numbers must be placed in orthogonally adjacent cells (up, down, left, or right). Diagonal connections are not allowed.
[Task] Generate a video showing the step-by-step completion of the Numbrix grid. Animate the placement of the missing numbers in sequence to form a single continuous orthogonal path.
Implicit rules (encoded in the puzzle's pre-printed clues):
- Fill every cell with a unique number from 1 to N² (where N is the grid side length).
- Consecutive numbers (k and k+1) must occupy orthogonally adjacent cells.
- Pre-printed clue numbers are fixed and cannot be moved.
- The completed grid forms a Hamiltonian path traversing all cells exactly once.
 |
 |
 |
| Initial Frame Sparse clue cells in NxN grid |
Animation Numbers filled in valid 1→N² sequence |
Final Frame Complete Hamiltonian path drawn |
Fill every cell of an NxN grid with consecutive integers 1, 2, …, N² so that each pair (k, k+1) lies in orthogonally adjacent cells, and the pre-printed clue numbers remain in place.
- Grid: NxN cells (typically 6×6 to 9×9).
- Clues: A subset of cells starts with fixed integer values (including 1 and N²).
- Adjacency rule: Cells holding consecutive numbers must be 4-connected neighbors.
- Uniqueness: Each puzzle has exactly one valid solution (verified by backtracking solver at generation time).
- Animation: Numbers are revealed in their natural 1→N² sequence to visualize the Hamiltonian path emerging.
- Hamiltonian path constraint: Stronger than Sudoku — the solution must trace a single connected snake-like path covering every cell.
- Bi-directional propagation: Each clue constrains both forward (k+1) and backward (k−1) cells, enabling pincer-style deduction.
- No backtracking shortcut: Greedy or local strategies fail; long-range reachability arguments are required.
- Visible path emergence: Frame-by-frame number placement makes intermediate state correctness directly verifiable.
data/questions/Multi-15_numbrix_pathfilling_data-generator_task/Multi-15_numbrix_pathfilling_data-generator_00000000/
├── first_frame.png # Sparse clue grid
├── final_frame.png # Fully filled Hamiltonian-path grid
├── prompt.txt # Task instruction
├── ground_truth.mp4 # Animation of stepwise filling
└── 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
numbrix hamiltonian-path csp logic-puzzle path-filling multi-step-reasoning long-horizon
Part of the 36-Task Long-Horizon Multi-Step Reasoning Benchmark.