PalletDataGenerator

A professional Python library for generating high-quality synthetic pallet datasets using Blender for computer vision and machine learning applications.

---

🎯 Overview

PalletDataGenerator is a comprehensive, production-ready solution for creating photorealistic synthetic datasets of pallets and warehouse environments. Designed with professional computer vision workflows in mind, it bridges the gap between research needs and industry-grade dataset generation.

✨ Key Features

• 🎬 Dual Generation Modes: Single pallet focus and complex warehouse scenarios
• 📊 Multiple Export Formats: YOLO, COCO JSON, and PASCAL VOC XML annotations
• 🎯 Advanced Keypoints Generation: Automatic face detection with 6 keypoints per face, visibility tracking, and 3D debug visualization
• 🔍 3D Debug Visualization: Interactive HTML figures and coordinate tracking for keypoints analysis
• ⚡ GPU-Accelerated Rendering: High-performance generation with Blender Cycles
• 🔧 Flexible Configuration: YAML configs with CLI parameter overrides
• 📦 Professional Output Structure: Organized generated_XXXX batch folders with comprehensive metadata
• 🏗️ Modular Architecture: Clean, extensible, and thoroughly tested codebase
• 🌟 Photorealistic Results: Advanced lighting, materials, and post-processing

🚀 Quick Start

Prerequisites

• Python 3.11+
• Blender 4.5+ (automatically detected or manually specified)
• NVIDIA GPU (recommended for optimal performance)

Installation

# Install from PyPI (recommended)
pip install palletdatagenerator

# Or install from source for latest features
git clone https://github.com/boubakriibrahim/PalletDataGenerator.git
cd PalletDataGenerator
pip install -e .

Basic Usage

Generate Warehouse Dataset

# Generate 50 warehouse scene images with multiple pallets and boxes
palletgen -m warehouse scenes/warehouse_objects.blend

# Custom configuration
palletgen -m warehouse scenes/warehouse_objects.blend \
    --frames 100 \
    --resolution 1920 1080 \
    --output custom_output_dir

Generate Single Pallet Dataset

# Generate focused single pallet images
palletgen -m single_pallet scenes/one_pallet.blend

# High-resolution batch
palletgen -m single_pallet scenes/one_pallet.blend \
    --frames 200 \
    --resolution 2048 1536

📸 Example Outputs

Warehouse Mode

Generate complex warehouse scenes with multiple pallets, stacked boxes, and realistic lighting:

Single Pallet Mode

Generate focused single pallet scenes with detailed box arrangements:

Multi-Modal Outputs

Each frame generates comprehensive data for training:

RGB Image	Analysis Overlay	Depth Map	Normal Map

🎯 Keypoints Generation Examples

Advanced face detection and keypoints tracking with 3D visualization:

Original Image	Keypoints Analysis	3D Debug Visualization

Keypoints Features:

• Selective face detection: 1-2 most visible faces per pallet (not all faces)
• 6 keypoints per selected face with precise 2D/3D coordinates
• Visibility tracking using ray casting for occlusion detection
• Interactive 3D HTML figures for detailed analysis
• Comprehensive debug information including face selection criteria
• YOLO format compatibility for seamless integration with training pipelines

🔍 3D Debug Visualization

Advanced debugging tools for keypoints analysis and face detection:

Interactive 3D Figure	Debug Coordinates	3D Visualization
🎯 Open Interactive 3D	📄 View Coordinates

Debug Features:

• Interactive 3D visualization with Plotly.js for real-time exploration
• Face selection analysis showing which faces were chosen and why
• Camera positioning with distance calculations to each face
• Pallet corner visualization with camera-to-corner distance lines
• Comprehensive coordinate tracking for debugging and validation
• Note: Keypoints are only visible in 2D analysis images, not in 3D visualization

🏗️ Architecture & Features

Generation Modes

🏭 Warehouse Mode

• Multi-pallet scenes with realistic warehouse layouts
• Dynamic box stacking with collection-aware placement
• Procedural lighting and environment variations
• Complex occlusion scenarios for robust model training

📦 Single Pallet Mode

• Focused pallet detection with controlled backgrounds
• Precise annotation quality for fine-grained training
• Camera angle variations including side and corner views
• Configurable cropping and occlusion levels

🎯 Advanced Keypoints Generation

• Automatic face detection by scanning for objects with "face" in their name
• Selective face detection: Detects 1-2 most visible faces from the pallet (not all faces)
• 6 keypoints per selected face: 2 middle (top-down), 2 left (top-down), 2 right (top-down)
• Visibility tracking using ray casting to detect obstacles between face and camera
• YOLO format output with normalized coordinates and visibility flags
• Analysis visualization showing keypoints with different colors for visible/hidden states
• 3D coordinate tracking with detailed debug information for each selected face
• Interactive HTML figures for 3D visualization and analysis
• Comprehensive metadata including face selection criteria and camera positioning

Export Formats

🎯 YOLO Format

# Example: 000000.txt
0 0.475345 0.595753 0.247050 0.102537

🎯 Keypoints Labels (YOLO Format)

# Example: keypoints_labels/000000.txt
0 0.573150 0.639442 0.284453 0.139362 0.580366 0.603590 2 0.578420 0.669213 2 0.715376 0.569761 2 0.710409 0.633069 2 0.430924 0.641035 2 0.432683 0.709123 2

Format: class_id x_center y_center width height kp1_x kp1_y kp1_v kp2_x kp2_y kp2_v ...

• Visibility: 2=visible, 0=hidden
• 6 keypoints per face: middle (top/bottom), left (top/bottom), right (top/bottom)
• Real example from generated dataset with actual face detection results

📋 COCO JSON

{
    "images": [{"id": 1, "file_name": "000000.png", "width": 1024, "height": 768}],
    "annotations": [{"id": 1, "image_id": 1, "category_id": 1, "bbox": [...]}],
    "categories": [{"id": 1, "name": "pallet", "supercategory": "object"}]
}

📄 PASCAL VOC XML

<annotation>
    <object>
        <name>pallet</name>
        <bndbox>
            <xmin>123</xmin><ymin>456</ymin>
            <xmax>789</xmax><ymax>654</ymax>
        </bndbox>
    </object>
</annotation>

Output Structure

output/
├── warehouse/
│   ├── generated_000001/
│   │   ├── images/          # RGB images (PNG)
│   │   ├── analysis/        # Overlay analysis images with keypoints
│   │   ├── depth/           # Depth maps (PNG)
│   │   ├── normals/         # Normal maps (PNG)
│   │   ├── index/           # Index/segmentation maps
│   │   ├── yolo_labels/     # YOLO format annotations
│   │   ├── keypoints_labels/ # Keypoints annotations (YOLO format)
│   │   ├── face_2d_boxes/   # 2D bounding boxes for detected faces
│   │   ├── face_3d_coordinates/ # 3D coordinates for keypoints
│   │   ├── debug_3d/        # 3D debug visualization
│   │   │   ├── coordinates/ # Detailed coordinate information
│   │   │   ├── figures/     # Interactive HTML 3D figures
│   │   │   └── images/      # 3D debug visualization images
│   │   ├── voc_xml/         # PASCAL VOC annotations
│   │   └── coco/            # COCO JSON annotations
│   └── generated_000002/    # Next batch...
└── single_pallet/
    └── generated_000001/    # Same structure

🔍 Debug 3D Output Details

The debug_3d/ folder contains comprehensive debugging information:

Interactive HTML Figures (figures/)

• Real-time 3D visualization using Plotly.js
• Interactive controls: rotate, zoom, pan, reset view
• Face highlighting: selected faces in red, unselected in blue
• Keypoint visualization: 6 keypoints per selected face
• Camera position: green diamond showing camera location
• Distance calculations: real-time distance from camera to each face

Coordinate Files (coordinates/)

Detailed text files containing:

Frame 0 - 3D Coordinates Debug
Object: pallet
Camera Position: (0.944, 2.536, 1.366)
Selected Faces: face_3, face_1

Pallet Corner Points (8 corners):
  Corner 0: (-0.384, -0.600, 0.020) - Distance: 3.663
  Corner 1: (-0.384, -0.600, 0.165) - Distance: 3.612
  ...

All Face Definitions (6 faces total):
  face_0 (corners [0, 1, 2, 3]):
    Center: (-0.384, 0.000, 0.093) - Distance: 3.134
    Status: not selected
  face_1 (corners [4, 5, 6, 7]):
    Center: (0.400, 0.000, 0.093) - Distance: 2.890
    Status: SELECTED
  ...

Selected Face Details:
  face_3 (index 3):
    Center Position: (0.008, 0.600, 0.093)
    Distance from Camera: 2.499
    2D Bounding Box: x_min=441.3, y_min=437.6, x_max=732.5, y_max=544.6
    3D Bounding Box: {...}

Debug Images (images/)

• Static 3D visualization for quick reference
• Face selection visualization showing which faces were chosen
• Coordinate system reference for debugging

🎮 Using Debug 3D Features

Interactive HTML Visualization

1. Open the HTML file in any modern web browser
2. Navigate the 3D scene:
   • Rotate: Click and drag to rotate the view
   • Zoom: Use mouse wheel to zoom in/out
   • Pan: Right-click and drag to pan the view
   • Reset: Double-click to reset to default view
3. Analyze face selection:
   • Red circles: Pallet corners (8 corners total)
   • Blue diamond: Camera position
   • Gray dashed lines: Camera-to-corner distance visualization
   • Green/Orange faces: Selected faces for keypoints generation (face_3, face_1)
   • Note: Keypoints are only visible in 2D analysis images, not in 3D visualization

Coordinate Analysis

The coordinate files provide detailed information for debugging:

• Face selection criteria: Why certain faces were chosen
• Distance calculations: Camera-to-face distances for selection
• Bounding box data: Both 2D and 3D bounding box information
• Keypoint positions: Exact 3D coordinates of all keypoints

Example Usage

# Generate dataset with debug 3D enabled
palletgen -m single_pallet scenes/one_pallet.blend --frames 10

# View debug files
ls output/single_pallet/generated_XXXXXX/debug_3d/
# coordinates/  figures/  images/

# Open interactive 3D visualization
open output/single_pallet/generated_XXXXXX/debug_3d/figures/frame_000000_3d_interactive.html

# View coordinate details
cat output/single_pallet/generated_XXXXXX/debug_3d/coordinates/frame_000000_coordinates.txt

⚙️ Configuration

CLI Parameters

palletgen --help

usage: palletgen [-h] [-m {single_pallet,warehouse}] [-f FRAMES]
                 [-r WIDTH HEIGHT] [-o OUTPUT] scene_path

Generate synthetic pallet datasets using Blender

positional arguments:
  scene_path            Path to Blender scene file (.blend)

optional arguments:
  -h, --help            show this help message and exit
  -m, --mode           Generation mode: single_pallet or warehouse (default: single_pallet)
  -f, --frames         Number of frames to generate (default: 50)
  -r, --resolution     Image resolution as WIDTH HEIGHT (default: 1024 768)
  -o, --output         Output directory (default: output/{mode}/generated_XXXXXX)

Advanced Configuration

The system supports extensive customization through internal configuration:

# Single Pallet Configuration
SINGLE_PALLET_CONFIG = {
    "num_images": 50,
    "resolution_x": 1024,
    "resolution_y": 768,
    "render_engine": "CYCLES",
    "camera_focal_mm": 35.0,
    "side_face_probability": 0.9,
    "allow_cropping": True,
    "min_visible_area_ratio": 0.3,
    "add_floor": True,
    "depth_scale": 1000.0,
    # Keypoints Generation Options
    "generate_keypoints": True,
    "keypoints_min_face_area": 80,
    "keypoints_visibility_check": False,
    "keypoints_show_3d_labels": False,
    "keypoints_show_2d_labels": False,
    "analysis_show_keypoints": True,
    "analysis_show_2d_boxes": True,
    "analysis_show_3d_coordinates": True,
    # ... many more options
}

# Warehouse Configuration
WAREHOUSE_CONFIG = {
    "num_images": 50,
    "resolution_x": 1024,
    "resolution_y": 768,
    "max_boxes_per_pallet": 8,
    "stacking_probability": 0.7,
    "lighting_variations": True,
    "camera_movement_range": 5.0,
    # Keypoints Generation Options (same as single pallet)
    "generate_keypoints": True,
    "keypoints_min_face_area": 80,
    "keypoints_visibility_check": False,
    "analysis_show_keypoints": True,
    "analysis_show_2d_boxes": True,
    "analysis_show_3d_coordinates": True,
    # ... extensive warehouse-specific options
}

🛠️ Development Setup

Development Installation

# Clone and setup development environment
git clone https://github.com/boubakriibrahim/PalletDataGenerator.git
cd PalletDataGenerator

# Install in development mode with all dependencies
pip install -e ".[dev,docs,test]"

# Install pre-commit hooks for code quality
pre-commit install

Code Quality Tools

# Run code formatting
black src/ tests/

# Run linting
ruff check src/ tests/

# Run type checking
mypy src/

# Run all tests with coverage
pytest --cov=palletdatagenerator --cov-report=html

Project Structure

PalletDataGenerator/
├── src/palletdatagenerator/
│   ├── __init__.py
│   ├── cli.py                    # Command-line interface
│   ├── generator.py              # Main generator class
│   ├── config.py                 # Configuration management
│   ├── blender_runner.py         # Blender execution handler
│   ├── utils.py                  # Shared utilities
│   └── modes/
│       ├── base_generator.py     # Abstract base class
│       ├── single_pallet.py      # Single pallet mode
│       └── warehouse.py          # Warehouse mode
├── tests/                        # Comprehensive test suite
├── docs/                         # Sphinx documentation
├── scenes/                       # Example Blender scenes
├── original_files/               # Legacy reference implementations
├── scripts/                      # Development scripts
└── readme_images/               # README assets

📚 API Reference

Core Classes

PalletDataGenerator

Main generator class that orchestrates the entire generation process.

from palletdatagenerator import PalletDataGenerator

generator = PalletDataGenerator(
    scene_path="scenes/warehouse_objects.blend",
    mode="warehouse",
    output_dir="custom_output"
)

# Generate dataset
generator.generate_dataset(num_frames=100)

Mode-Specific Generators

from palletdatagenerator.modes import WarehouseMode, SinglePalletMode

# Warehouse mode with custom configuration
warehouse = WarehouseMode(config=custom_warehouse_config)
warehouse.generate_scene(frame_number=0)

# Single pallet mode
single = SinglePalletMode(config=custom_single_config)
single.generate_scene(frame_number=0)

Utility Functions

from palletdatagenerator.utils import (
    find_blender_executable,
    setup_logging,
    validate_scene_file
)

# Auto-detect Blender installation
blender_path = find_blender_executable()

# Validate scene compatibility
is_valid = validate_scene_file("path/to/scene.blend")

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository and create a feature branch
2. Make your changes with proper testing
3. Run quality checks: black, ruff, mypy, pytest
4. Update documentation if needed
5. Submit a Pull Request with clear description

📄 License & Citation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use PalletDataGenerator in your research, please cite:

@software{palletdatagenerator2025,
  title={PalletDataGenerator: Professional Synthetic Pallet Dataset Generation},
  author={Ibrahim Boubakri},
  year={2025},
  url={https://github.com/boubakriibrahim/PalletDataGenerator},
  version={0.1.3}
}

🔗 Links & Resources

• 📖 Documentation - Comprehensive guides and API reference
• 🐛 Issue Tracker - Report bugs and request features
• 💬 Discussions - Community support and ideas
• 📦 PyPI Package - Latest releases and installation
• 🎬 Blender - 3D rendering engine
• 🤖 Computer Vision Datasets - Related projects

🙏 Acknowledgments

• Blender Foundation for the incredible open-source 3D suite
• Computer Vision Community for inspiration and feedback
• Contributors who help improve this project
• Warehouse Industry Partners for real-world validation

---