Puzzle Reconstruction: Phase 1 - Preprocessing

This repository contains the code and data for Phase 1 of a puzzle reconstruction project, focusing on preprocessing puzzle pieces. The primary goal is to classify puzzle grid sizes, label the individual pieces, shuffle them, and extract essential visual features that will be used in the reconstruction phase.

Repository Structure

• data/: Contains all image data.
  • correct/: Ground-truth, fully assembled images.
  • puzzle_2x2/, puzzle_4x4/, puzzle_8x8/: Scrambled puzzle images for different grid sizes.
• labels/: Contains CSV files detailing the shuffled order of puzzle pieces. This is used for validating the reconstruction algorithm in the next phase.
• src/: Contains the main Python scripts for the preprocessing pipeline.
• notebooks/: Includes Jupyter notebooks used for testing, visualization, and experimentation purposes only.

Preprocessing Pipeline

The preprocessing workflow is divided into several key stages:

1. Grid Size Classification

• Script: src/data_labeling.py
• Process: This script analyzes each puzzle image to automatically determine its grid size (e.g., 2×2, 4×4, or 8×8).

2. Data Labeling and Shuffling

• Script: src/grid_classification.py
• Process: In the correct (ground-truth) image, each patch is assigned a sequential ID. When creating the puzzle version, the same IDs are attached to their corresponding patches, but the patches are shuffled, resulting in a scrambled order. As part of preprocessing for Phase 2, we export this shuffled order as a CSV for automated validation. If the reconstruction algorithm can reorder the patches correctly—without being given the IDs or the sorting logic—then the image is considered successfully reconstructed.

3. Feature Extraction

• Script: src/Puzzle.py
• Process: For each patch, detailed metadata and a set of precomputed visual features are extracted and stored. This rich data representation is crucial for the reconstruction algorithm.

The following information is stored for each patch:

• ID: A unique identifier for the patch.
• Grid Variant: The puzzle layout (2×2, 4×4, 8×8).
• Grid Position: The original (row, column) coordinates of the patch in the complete image.
• Shuffled Order: The position of the patch within the scrambled puzzle.
• Image Data: The raw tile image stored as a NumPy array.
• Features: A suite of precomputed visual features:
  • RGB: The standard Red, Green, Blue color representation.
  • Canny: An edge map for identifying contours.
  • Lab: A color space designed for perceptual analysis.
  • Gradient: Edge intensity information derived from Sobel operators.
  • Borders: Slices of the top, bottom, left, and right borders for each of the extracted features, used for comparing adjacent pieces.

4. Pipeline Management

• Script: src/PuzzleManager.py
• Process: This script serves as the final step, merging all previous stages to create a cohesive and automated preprocessing pipeline.

Goal for Phase 2

The output of this preprocessing phase is a structured dataset containing feature-rich puzzle pieces and their corresponding ground-truth labels. This data will serve as the input for Phase 2, which will focus on developing an algorithm to solve the puzzles by correctly reassembling the scrambled patches.