# PalletDataGenerator
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
**Professional Blender library for synthetic pallet and warehouse dataset generation with advanced rendering capabilities and comprehensive annotation support.**
## ๐ Features
- **๐ฏ Multi-Generator Support**: Single pallet and complex warehouse scene generation
- **๐จ Advanced Rendering**: GPU-accelerated Cycles rendering with Filmic color management
- **๐ Multiple Export Formats**: YOLO, COCO, PASCAL VOC annotation formats
- **๐ง Professional Architecture**: Clean, modular, and extensible codebase
- **โก High Performance**: Optimized for batch processing and large dataset generation
- **๐ก๏ธ Robust Quality Assurance**: Comprehensive testing, linting, and type checking
- **๐ Complete Documentation**: Detailed API docs and usage examples
- **๏ฟฝ Docker Support**: Containerized development and deployment
- **๐ Multi-Platform**: Windows, macOS, Linux support with automated setup
## ๐ Quick Start
### Option 1: Quick Installation (Recommended for Users)
```bash
# Install from PyPI (coming soon)
pip install palletdatagenerator
# Or install from source
pip install git+https://github.com/boubakriibrahim/PalletDataGenerator.git
```
### Option 2: Development Setup (Recommended for Contributors)
**Choose your platform:**
#### ๐ฅ๏ธ **Windows (Command Prompt/PowerShell)**
```cmd
# Clone repository
git clone https://github.com/boubakriibrahim/PalletDataGenerator.git
cd PalletDataGenerator
# Run setup script
scripts\setup-dev.bat
# or for PowerShell
powershell -ExecutionPolicy Bypass -File scripts\setup-dev.ps1
```
#### ๐ **macOS / ๐ง Linux**
```bash
# Clone repository
git clone https://github.com/boubakriibrahim/PalletDataGenerator.git
cd PalletDataGenerator
# Run setup script
./scripts/setup-dev.sh
```
#### ๐ณ **Docker (All Platforms)**
```bash
# Clone repository
git clone https://github.com/boubakriibrahim/PalletDataGenerator.git
cd PalletDataGenerator
# Start development environment
./scripts/docker-dev.sh dev
# Open shell in container
./scripts/docker-dev.sh shell
```
### Basic Usage
```python
import bpy
from palletdatagenerator import PalletGenerator, GenerationConfig
# Configure dataset generation
config = GenerationConfig(
output_dir="outputs/my_dataset",
num_images=100,
resolution=(1280, 720),
export_formats=["yolo", "coco"]
)
# Initialize generator
generator = PalletGenerator(config)
# Generate dataset
stats = generator.generate_dataset()
print(f"Generated {stats['images_generated']} images")
```
### Advanced Example
```python
from palletdatagenerator import WarehouseGenerator, GenerationConfig
from palletdatagenerator.utils import setup_logging
# Setup logging
setup_logging(level="INFO", log_file="generation.log")
# Advanced configuration
config = GenerationConfig(
output_dir="outputs/warehouse_dataset",
num_images=500,
resolution=(1920, 1080),
render_engine="CYCLES",
camera_config={
"focal_mm": 35.0,
"height_range": (1.4, 2.0),
"path_variation": 0.3
},
lighting_config={
"randomize_per_frame": True,
"light_count_range": (2, 4),
"use_colored_lights": True,
"colored_light_probability": 0.3
},
export_formats=["yolo", "coco", "voc"]
)
# Generate warehouse dataset
generator = WarehouseGenerator(config)
# Enable GPU rendering
gpu_backend = generator.enable_gpu()
print(f"Using GPU backend: {gpu_backend}")
# Generate dataset with progress tracking
stats = generator.generate_dataset()
# Print generation statistics
print("Generation Complete!")
print(f"Images: {stats['images_generated']}")
print(f"Pallets found: {stats['pallets_found']}")
print(f"Boxes found: {stats['boxes_found']}")
```
## ๐ Project Structure
```
PalletDataGenerator/
โโโ src/palletdatagenerator/
โ โโโ __init__.py # Main package interface
โ โโโ core/ # Core generation functionality
โ โ โโโ generator.py # Main generator classes
โ โ โโโ renderer.py # Blender rendering interface
โ โโโ exporters/ # Annotation exporters
โ โ โโโ yolo.py # YOLO format exporter
โ โ โโโ coco.py # COCO format exporter
โ โ โโโ voc.py # PASCAL VOC exporter
โ โโโ utils.py # Utility functions
โโโ tests/ # Comprehensive test suite
โโโ docs/ # Documentation
โโโ .github/workflows/ # CI/CD automation
โโโ configs/ # Configuration examples
```
## ๐ฏ Use Cases
### Computer Vision Research
- **Object Detection**: Generate labeled datasets for pallet detection models
- **Pose Estimation**: Create datasets with precise 3D pose annotations
- **Segmentation**: Generate pixel-perfect segmentation masks
- **Domain Adaptation**: Bridge sim-to-real gap with photorealistic rendering
### Industrial Applications
- **Warehouse Automation**: Train robots for pallet handling and navigation
- **Quality Control**: Generate datasets for automated inspection systems
- **Logistics Optimization**: Create data for warehouse layout optimization
- **Safety Systems**: Train models for accident prevention in warehouses
### Academic Research
- **Synthetic Data Studies**: Investigate effectiveness of synthetic vs real data
- **Benchmark Creation**: Generate standardized evaluation datasets
- **Algorithm Development**: Rapid prototyping with unlimited labeled data
## ๐ง Configuration
### Generation Config
```python
config = GenerationConfig(
# Basic settings
output_dir="outputs/dataset",
num_images=100,
resolution=(1280, 720),
render_engine="CYCLES",
# Camera settings
camera_config={
"focal_mm": 35.0, # Focal length
"sensor_mm": 36.0, # Sensor size
"height_range": (1.0, 3.0), # Camera height range
},
# Lighting settings
lighting_config={
"randomize_per_frame": True,
"light_count_range": (2, 4),
"use_colored_lights": True,
"colored_light_probability": 0.6,
},
# Export formats
export_formats=["yolo", "coco", "voc"]
)
```
### YAML Configuration
```yaml
# config.yaml
output_dir: "outputs/my_dataset"
num_images: 200
resolution: [1920, 1080]
render_engine: "CYCLES"
camera_config:
focal_mm: 50.0
height_range: [1.2, 2.5]
lighting_config:
randomize_per_frame: true
light_count_range: [3, 6]
use_colored_lights: true
export_formats:
- "yolo"
- "coco"
```
## ๐ Output Formats
### Directory Structure
```
outputs/
โโโ my_dataset/
โโโ images/ # RGB images
โโโ depth/ # Depth maps (16-bit PNG)
โโโ normals/ # Surface normal maps
โโโ index/ # Object index maps
โโโ yolo_labels/ # YOLO format annotations
โโโ voc_xml/ # PASCAL VOC XML files
โโโ annotations.json # COCO format annotations
โโโ dataset_manifest.json # Complete dataset metadata
```
### YOLO Format
```
# frame_000001.txt
0 0.5123 0.3456 0.2345 0.1678 # class_id center_x center_y width height
1 0.7234 0.6789 0.1234 0.0987
```
### COCO Format
```json
{
"images": [{"id": 1, "file_name": "frame_000001.png", "width": 1280, "height": 720}],
"annotations": [{"id": 1, "image_id": 1, "category_id": 1, "bbox": [100, 200, 150, 120]}],
"categories": [{"id": 1, "name": "pallet", "supercategory": "logistics"}]
}
```
## ๐งช Development
### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/boubakriibrahim/PalletDataGenerator.git
cd PalletDataGenerator
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\\Scripts\\activate
# Install in development mode
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=palletdatagenerator --cov-report=html
# Run specific test categories
pytest -m "not slow" # Skip slow tests
pytest -m "unit" # Only unit tests
pytest -m "integration" # Only integration tests
```
### Code Quality
```bash
# Format code
black src/ tests/
# Lint code
ruff check src/ tests/
# Type checking
mypy src/
# Security scan
bandit -r src/
```
### Building Documentation
```bash
# Install docs dependencies
pip install -e ".[docs]"
# Build and serve docs locally
cd docs && make html && open _build/html/index.html
# Build for deployment
cd docs && make html
```
## ๐ค Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Workflow
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Make** your changes with proper tests and documentation
4. **Run** quality checks (`pre-commit run --all-files`)
5. **Commit** your changes (`git commit -m 'Add amazing feature'`)
6. **Push** to your branch (`git push origin feature/amazing-feature`)
7. **Open** a Pull Request
### Code Standards
- **Black** for code formatting
- **Ruff** for linting
- **MyPy** for type checking
- **Pytest** for testing (>90% coverage required)
- **Conventional Commits** for commit messages
### Command Line Interface
Once installed, you can use the CLI:
```bash
# Get version info
palletgen info --version
# Create config file
palletgen config create --output configs/my_config.yaml
# Generate dataset
palletgen generate --config configs/my_config.yaml --output datasets/my_dataset
# Validate config
palletgen config validate --config configs/my_config.yaml
```
### Available Aliases (After Development Setup)
The setup scripts create convenient aliases:
```bash
pgen info --version # Short version of palletgen
pgen-test # Run all tests
pgen-lint # Run code quality checks
pgen-docs # Build documentation
pgen-format # Format code with Black and Ruff
pgen-clean # Clean Python cache files
```
## ๐ณ Docker Usage
### Development with Docker
```bash
# Build and start development environment
./scripts/docker-dev.sh dev
# Open shell in development container
./scripts/docker-dev.sh shell
# Run tests in container
./scripts/docker-dev.sh test
# Build and serve documentation
./scripts/docker-dev.sh docs # Available at http://localhost:8080
# Start Blender development environment (with GUI support)
./scripts/docker-dev.sh blender
```
### Docker Compose Services
| Service | Purpose | Ports |
|---------|---------|-------|
| `pallet-dev` | Development environment | 8000, 8888 |
| `pallet-prod` | Production container | - |
| `pallet-blender` | Blender development | 8000 |
| `pallet-test` | Testing and CI/CD | - |
| `pallet-docs` | Documentation server | 8080 |
### Production Deployment
```bash
# Build production image
docker build --target production -t palletgenerator:latest .
# Run production container
docker run -v $(pwd)/output:/home/pallet/app/output \
-v $(pwd)/configs:/home/pallet/app/configs \
palletgenerator:latest generate --config configs/production.yaml
```
## ๐ ๏ธ Development
### Development Setup (Automatic)
The setup scripts handle everything automatically:
- Python environment (conda or venv)
- Dependencies installation
- Pre-commit hooks
- Shell aliases
- Development tools
**After running setup scripts:**
```bash
# Activate environment (if using conda)
conda activate blender
# Or activate venv (if using venv)
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# Start developing!
pgen-test # Run tests
pgen-lint # Check code quality
```
### Manual Development Setup
If you prefer manual setup:
```bash
# Create environment
conda create -n blender python=3.11 -y
conda activate blender
# Install dependencies
pip install -r requirements-dev.txt
# Install package in development mode
pip install -e .
# Setup pre-commit
pre-commit install
# Run tests
pytest tests/ -v
```
### Project Structure
```
PalletDataGenerator/
โโโ src/palletdatagenerator/ # Main package
โ โโโ core/ # Core generation logic
โ โโโ exporters/ # Format exporters (YOLO, COCO, VOC)
โ โโโ cli.py # Command-line interface
โ โโโ utils.py # Utilities
โโโ tests/ # Test suite
โโโ docs/ # Documentation
โโโ configs/ # Configuration templates
โโโ scripts/ # Development and deployment scripts
โโโ requirements*.txt # Dependencies
โโโ Dockerfile # Docker configuration
โโโ docker-compose.yml # Docker services
โโโ pyproject.toml # Project configuration
```
### Code Quality
This project maintains high code quality standards:
- **Black** for code formatting
- **Ruff** for linting and code quality
- **Pre-commit hooks** for automated checks
- **Pytest** for comprehensive testing
- **Type hints** throughout codebase
- **Documentation** for all public APIs
```bash
# Run all quality checks
pgen-lint
# Format code
pgen-format
# Run tests with coverage
pgen-test
```
## ๐ Performance
### Optimization Tips
- **Use GPU rendering** for 5-10x speedup
- **Enable persistent data** for batch rendering
- **Adjust sample count** based on quality needs
- **Use adaptive sampling** for automatic optimization
## ๐ ๏ธ Requirements
### System Requirements
- **Python**: 3.11+ (3.11 recommended)
- **Blender**: 4.5+ (4.5 recommended)
- **Memory**: 8GB RAM minimum, 16GB+ recommended
- **Storage**: SSD recommended for large datasets
### GPU Support
- **NVIDIA**: CUDA/OptiX (RTX series recommended)
- **AMD**: HIP/OpenCL
- **Apple**: Metal (M series)
- **Intel**: OneAPI (Arc series)
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐ Acknowledgments
- **Blender Foundation** for the amazing 3D creation suite
- **Computer Vision Community** for inspiration and best practices
- **Open Source Contributors** who make projects like this possible
## ๐ Support
- **๐ Documentation**: [https://boubakriibrahim.github.io/PalletDataGenerator/](https://boubakriibrahim.github.io/PalletDataGenerator/)
- **๐ Bug Reports**: [GitHub Issues](https://github.com/boubakriibrahim/PalletDataGenerator/issues)
- **๐ฌ Discussions**: [GitHub Discussions](https://github.com/boubakriibrahim/PalletDataGenerator/discussions)
- **๐ง Email**: [ibrahim@example.com](mailto:ibrahim@example.com)
---
<div align="center">
**[โญ Star this project](https://github.com/boubakriibrahim/PalletDataGenerator) if you find it useful!**
Made with โค๏ธ by [Ibrahim Boubakri](https://github.com/boubakriibrahim)
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "palletdatagenerator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "3d-rendering, blender, computer-vision, dataset-generation, machine-learning, pallet-detection, synthetic-data",
"author": null,
"author_email": "Ibrahim Boubakri <ibrahimbouakri1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4c/7d/ed09cf3c526baa0a410e10a497992bb9b9294cf5862a6b121ec43fcadb45/palletdatagenerator-0.1.0.tar.gz",
"platform": null,
"description": "# PalletDataGenerator\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/psf/black)\n[](https://github.com/astral-sh/ruff)\n\n**Professional Blender library for synthetic pallet and warehouse dataset generation with advanced rendering capabilities and comprehensive annotation support.**\n\n## \ud83c\udf1f Features\n\n- **\ud83c\udfaf Multi-Generator Support**: Single pallet and complex warehouse scene generation\n- **\ud83c\udfa8 Advanced Rendering**: GPU-accelerated Cycles rendering with Filmic color management\n- **\ud83d\udcca Multiple Export Formats**: YOLO, COCO, PASCAL VOC annotation formats\n- **\ud83d\udd27 Professional Architecture**: Clean, modular, and extensible codebase\n- **\u26a1 High Performance**: Optimized for batch processing and large dataset generation\n- **\ud83d\udee1\ufe0f Robust Quality Assurance**: Comprehensive testing, linting, and type checking\n- **\ud83d\udcda Complete Documentation**: Detailed API docs and usage examples\n- **\ufffd Docker Support**: Containerized development and deployment\n- **\ud83d\ude80 Multi-Platform**: Windows, macOS, Linux support with automated setup\n\n## \ud83d\ude80 Quick Start\n\n### Option 1: Quick Installation (Recommended for Users)\n\n```bash\n# Install from PyPI (coming soon)\npip install palletdatagenerator\n\n# Or install from source\npip install git+https://github.com/boubakriibrahim/PalletDataGenerator.git\n```\n\n### Option 2: Development Setup (Recommended for Contributors)\n\n**Choose your platform:**\n\n#### \ud83d\udda5\ufe0f **Windows (Command Prompt/PowerShell)**\n```cmd\n# Clone repository\ngit clone https://github.com/boubakriibrahim/PalletDataGenerator.git\ncd PalletDataGenerator\n\n# Run setup script\nscripts\\setup-dev.bat\n# or for PowerShell\npowershell -ExecutionPolicy Bypass -File scripts\\setup-dev.ps1\n```\n\n#### \ud83c\udf4e **macOS / \ud83d\udc27 Linux**\n```bash\n# Clone repository\ngit clone https://github.com/boubakriibrahim/PalletDataGenerator.git\ncd PalletDataGenerator\n\n# Run setup script\n./scripts/setup-dev.sh\n```\n\n#### \ud83d\udc33 **Docker (All Platforms)**\n```bash\n# Clone repository\ngit clone https://github.com/boubakriibrahim/PalletDataGenerator.git\ncd PalletDataGenerator\n\n# Start development environment\n./scripts/docker-dev.sh dev\n\n# Open shell in container\n./scripts/docker-dev.sh shell\n```\n\n### Basic Usage\n\n```python\nimport bpy\nfrom palletdatagenerator import PalletGenerator, GenerationConfig\n\n# Configure dataset generation\nconfig = GenerationConfig(\n output_dir=\"outputs/my_dataset\",\n num_images=100,\n resolution=(1280, 720),\n export_formats=[\"yolo\", \"coco\"]\n)\n\n# Initialize generator\ngenerator = PalletGenerator(config)\n\n# Generate dataset\nstats = generator.generate_dataset()\nprint(f\"Generated {stats['images_generated']} images\")\n```\n\n### Advanced Example\n\n```python\nfrom palletdatagenerator import WarehouseGenerator, GenerationConfig\nfrom palletdatagenerator.utils import setup_logging\n\n# Setup logging\nsetup_logging(level=\"INFO\", log_file=\"generation.log\")\n\n# Advanced configuration\nconfig = GenerationConfig(\n output_dir=\"outputs/warehouse_dataset\",\n num_images=500,\n resolution=(1920, 1080),\n render_engine=\"CYCLES\",\n camera_config={\n \"focal_mm\": 35.0,\n \"height_range\": (1.4, 2.0),\n \"path_variation\": 0.3\n },\n lighting_config={\n \"randomize_per_frame\": True,\n \"light_count_range\": (2, 4),\n \"use_colored_lights\": True,\n \"colored_light_probability\": 0.3\n },\n export_formats=[\"yolo\", \"coco\", \"voc\"]\n)\n\n# Generate warehouse dataset\ngenerator = WarehouseGenerator(config)\n\n# Enable GPU rendering\ngpu_backend = generator.enable_gpu()\nprint(f\"Using GPU backend: {gpu_backend}\")\n\n# Generate dataset with progress tracking\nstats = generator.generate_dataset()\n\n# Print generation statistics\nprint(\"Generation Complete!\")\nprint(f\"Images: {stats['images_generated']}\")\nprint(f\"Pallets found: {stats['pallets_found']}\")\nprint(f\"Boxes found: {stats['boxes_found']}\")\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nPalletDataGenerator/\n\u251c\u2500\u2500 src/palletdatagenerator/\n\u2502 \u251c\u2500\u2500 __init__.py # Main package interface\n\u2502 \u251c\u2500\u2500 core/ # Core generation functionality\n\u2502 \u2502 \u251c\u2500\u2500 generator.py # Main generator classes\n\u2502 \u2502 \u2514\u2500\u2500 renderer.py # Blender rendering interface\n\u2502 \u251c\u2500\u2500 exporters/ # Annotation exporters\n\u2502 \u2502 \u251c\u2500\u2500 yolo.py # YOLO format exporter\n\u2502 \u2502 \u251c\u2500\u2500 coco.py # COCO format exporter\n\u2502 \u2502 \u2514\u2500\u2500 voc.py # PASCAL VOC exporter\n\u2502 \u2514\u2500\u2500 utils.py # Utility functions\n\u251c\u2500\u2500 tests/ # Comprehensive test suite\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 .github/workflows/ # CI/CD automation\n\u2514\u2500\u2500 configs/ # Configuration examples\n```\n\n## \ud83c\udfaf Use Cases\n\n### Computer Vision Research\n- **Object Detection**: Generate labeled datasets for pallet detection models\n- **Pose Estimation**: Create datasets with precise 3D pose annotations\n- **Segmentation**: Generate pixel-perfect segmentation masks\n- **Domain Adaptation**: Bridge sim-to-real gap with photorealistic rendering\n\n### Industrial Applications\n- **Warehouse Automation**: Train robots for pallet handling and navigation\n- **Quality Control**: Generate datasets for automated inspection systems\n- **Logistics Optimization**: Create data for warehouse layout optimization\n- **Safety Systems**: Train models for accident prevention in warehouses\n\n### Academic Research\n- **Synthetic Data Studies**: Investigate effectiveness of synthetic vs real data\n- **Benchmark Creation**: Generate standardized evaluation datasets\n- **Algorithm Development**: Rapid prototyping with unlimited labeled data\n\n## \ud83d\udd27 Configuration\n\n### Generation Config\n\n```python\nconfig = GenerationConfig(\n # Basic settings\n output_dir=\"outputs/dataset\",\n num_images=100,\n resolution=(1280, 720),\n render_engine=\"CYCLES\",\n\n # Camera settings\n camera_config={\n \"focal_mm\": 35.0, # Focal length\n \"sensor_mm\": 36.0, # Sensor size\n \"height_range\": (1.0, 3.0), # Camera height range\n },\n\n # Lighting settings\n lighting_config={\n \"randomize_per_frame\": True,\n \"light_count_range\": (2, 4),\n \"use_colored_lights\": True,\n \"colored_light_probability\": 0.6,\n },\n\n # Export formats\n export_formats=[\"yolo\", \"coco\", \"voc\"]\n)\n```\n\n### YAML Configuration\n\n```yaml\n# config.yaml\noutput_dir: \"outputs/my_dataset\"\nnum_images: 200\nresolution: [1920, 1080]\nrender_engine: \"CYCLES\"\n\ncamera_config:\n focal_mm: 50.0\n height_range: [1.2, 2.5]\n\nlighting_config:\n randomize_per_frame: true\n light_count_range: [3, 6]\n use_colored_lights: true\n\nexport_formats:\n - \"yolo\"\n - \"coco\"\n```\n\n## \ud83d\udcca Output Formats\n\n### Directory Structure\n```\noutputs/\n\u2514\u2500\u2500 my_dataset/\n \u251c\u2500\u2500 images/ # RGB images\n \u251c\u2500\u2500 depth/ # Depth maps (16-bit PNG)\n \u251c\u2500\u2500 normals/ # Surface normal maps\n \u251c\u2500\u2500 index/ # Object index maps\n \u251c\u2500\u2500 yolo_labels/ # YOLO format annotations\n \u251c\u2500\u2500 voc_xml/ # PASCAL VOC XML files\n \u251c\u2500\u2500 annotations.json # COCO format annotations\n \u2514\u2500\u2500 dataset_manifest.json # Complete dataset metadata\n```\n\n### YOLO Format\n```\n# frame_000001.txt\n0 0.5123 0.3456 0.2345 0.1678 # class_id center_x center_y width height\n1 0.7234 0.6789 0.1234 0.0987\n```\n\n### COCO Format\n```json\n{\n \"images\": [{\"id\": 1, \"file_name\": \"frame_000001.png\", \"width\": 1280, \"height\": 720}],\n \"annotations\": [{\"id\": 1, \"image_id\": 1, \"category_id\": 1, \"bbox\": [100, 200, 150, 120]}],\n \"categories\": [{\"id\": 1, \"name\": \"pallet\", \"supercategory\": \"logistics\"}]\n}\n```\n\n## \ud83e\uddea Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/boubakriibrahim/PalletDataGenerator.git\ncd PalletDataGenerator\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\\\Scripts\\\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=palletdatagenerator --cov-report=html\n\n# Run specific test categories\npytest -m \"not slow\" # Skip slow tests\npytest -m \"unit\" # Only unit tests\npytest -m \"integration\" # Only integration tests\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Lint code\nruff check src/ tests/\n\n# Type checking\nmypy src/\n\n# Security scan\nbandit -r src/\n```\n\n### Building Documentation\n\n```bash\n# Install docs dependencies\npip install -e \".[docs]\"\n\n# Build and serve docs locally\ncd docs && make html && open _build/html/index.html\n\n# Build for deployment\ncd docs && make html\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Make** your changes with proper tests and documentation\n4. **Run** quality checks (`pre-commit run --all-files`)\n5. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n6. **Push** to your branch (`git push origin feature/amazing-feature`)\n7. **Open** a Pull Request\n\n### Code Standards\n\n- **Black** for code formatting\n- **Ruff** for linting\n- **MyPy** for type checking\n- **Pytest** for testing (>90% coverage required)\n- **Conventional Commits** for commit messages\n\n### Command Line Interface\n\nOnce installed, you can use the CLI:\n\n```bash\n# Get version info\npalletgen info --version\n\n# Create config file\npalletgen config create --output configs/my_config.yaml\n\n# Generate dataset\npalletgen generate --config configs/my_config.yaml --output datasets/my_dataset\n\n# Validate config\npalletgen config validate --config configs/my_config.yaml\n```\n\n### Available Aliases (After Development Setup)\n\nThe setup scripts create convenient aliases:\n\n```bash\npgen info --version # Short version of palletgen\npgen-test # Run all tests\npgen-lint # Run code quality checks\npgen-docs # Build documentation\npgen-format # Format code with Black and Ruff\npgen-clean # Clean Python cache files\n```\n\n## \ud83d\udc33 Docker Usage\n\n### Development with Docker\n\n```bash\n# Build and start development environment\n./scripts/docker-dev.sh dev\n\n# Open shell in development container\n./scripts/docker-dev.sh shell\n\n# Run tests in container\n./scripts/docker-dev.sh test\n\n# Build and serve documentation\n./scripts/docker-dev.sh docs # Available at http://localhost:8080\n\n# Start Blender development environment (with GUI support)\n./scripts/docker-dev.sh blender\n```\n\n### Docker Compose Services\n\n| Service | Purpose | Ports |\n|---------|---------|-------|\n| `pallet-dev` | Development environment | 8000, 8888 |\n| `pallet-prod` | Production container | - |\n| `pallet-blender` | Blender development | 8000 |\n| `pallet-test` | Testing and CI/CD | - |\n| `pallet-docs` | Documentation server | 8080 |\n\n### Production Deployment\n\n```bash\n# Build production image\ndocker build --target production -t palletgenerator:latest .\n\n# Run production container\ndocker run -v $(pwd)/output:/home/pallet/app/output \\\n -v $(pwd)/configs:/home/pallet/app/configs \\\n palletgenerator:latest generate --config configs/production.yaml\n```\n\n## \ud83d\udee0\ufe0f Development\n\n### Development Setup (Automatic)\n\nThe setup scripts handle everything automatically:\n- Python environment (conda or venv)\n- Dependencies installation\n- Pre-commit hooks\n- Shell aliases\n- Development tools\n\n**After running setup scripts:**\n```bash\n# Activate environment (if using conda)\nconda activate blender\n\n# Or activate venv (if using venv)\nsource venv/bin/activate # Linux/macOS\nvenv\\Scripts\\activate # Windows\n\n# Start developing!\npgen-test # Run tests\npgen-lint # Check code quality\n```\n\n### Manual Development Setup\n\nIf you prefer manual setup:\n\n```bash\n# Create environment\nconda create -n blender python=3.11 -y\nconda activate blender\n\n# Install dependencies\npip install -r requirements-dev.txt\n\n# Install package in development mode\npip install -e .\n\n# Setup pre-commit\npre-commit install\n\n# Run tests\npytest tests/ -v\n```\n\n### Project Structure\n\n```\nPalletDataGenerator/\n\u251c\u2500\u2500 src/palletdatagenerator/ # Main package\n\u2502 \u251c\u2500\u2500 core/ # Core generation logic\n\u2502 \u251c\u2500\u2500 exporters/ # Format exporters (YOLO, COCO, VOC)\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 utils.py # Utilities\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 configs/ # Configuration templates\n\u251c\u2500\u2500 scripts/ # Development and deployment scripts\n\u251c\u2500\u2500 requirements*.txt # Dependencies\n\u251c\u2500\u2500 Dockerfile # Docker configuration\n\u251c\u2500\u2500 docker-compose.yml # Docker services\n\u2514\u2500\u2500 pyproject.toml # Project configuration\n```\n\n### Code Quality\n\nThis project maintains high code quality standards:\n\n- **Black** for code formatting\n- **Ruff** for linting and code quality\n- **Pre-commit hooks** for automated checks\n- **Pytest** for comprehensive testing\n- **Type hints** throughout codebase\n- **Documentation** for all public APIs\n\n```bash\n# Run all quality checks\npgen-lint\n\n# Format code\npgen-format\n\n# Run tests with coverage\npgen-test\n```\n\n## \ud83d\udcc8 Performance\n\n### Optimization Tips\n\n- **Use GPU rendering** for 5-10x speedup\n- **Enable persistent data** for batch rendering\n- **Adjust sample count** based on quality needs\n- **Use adaptive sampling** for automatic optimization\n\n## \ud83d\udee0\ufe0f Requirements\n\n### System Requirements\n- **Python**: 3.11+ (3.11 recommended)\n- **Blender**: 4.5+ (4.5 recommended)\n- **Memory**: 8GB RAM minimum, 16GB+ recommended\n- **Storage**: SSD recommended for large datasets\n\n### GPU Support\n- **NVIDIA**: CUDA/OptiX (RTX series recommended)\n- **AMD**: HIP/OpenCL\n- **Apple**: Metal (M series)\n- **Intel**: OneAPI (Arc series)\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **Blender Foundation** for the amazing 3D creation suite\n- **Computer Vision Community** for inspiration and best practices\n- **Open Source Contributors** who make projects like this possible\n\n## \ud83d\udcde Support\n\n- **\ud83d\udcd6 Documentation**: [https://boubakriibrahim.github.io/PalletDataGenerator/](https://boubakriibrahim.github.io/PalletDataGenerator/)\n- **\ud83d\udc1b Bug Reports**: [GitHub Issues](https://github.com/boubakriibrahim/PalletDataGenerator/issues)\n- **\ud83d\udcac Discussions**: [GitHub Discussions](https://github.com/boubakriibrahim/PalletDataGenerator/discussions)\n- **\ud83d\udce7 Email**: [ibrahim@example.com](mailto:ibrahim@example.com)\n\n---\n\n<div align=\"center\">\n\n**[\u2b50 Star this project](https://github.com/boubakriibrahim/PalletDataGenerator) if you find it useful!**\n\nMade with \u2764\ufe0f by [Ibrahim Boubakri](https://github.com/boubakriibrahim)\n\n</div>\n",
"bugtrack_url": null,
"license": null,
"summary": "Professional Blender library for synthetic pallet dataset generation.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://boubakriibrahim.github.io/PalletDataGenerator/",
"Homepage": "https://github.com/boubakriibrahim/PalletDataGenerator",
"Issues": "https://github.com/boubakriibrahim/PalletDataGenerator/issues",
"Repository": "https://github.com/boubakriibrahim/PalletDataGenerator.git"
},
"split_keywords": [
"3d-rendering",
" blender",
" computer-vision",
" dataset-generation",
" machine-learning",
" pallet-detection",
" synthetic-data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1662bc7477f58f8ab3c7adf63271edc628f36349378f27bcc5a880448947fc75",
"md5": "fbdf192b4678e1e84879fb4cf00c2985",
"sha256": "a63df5010835e67eebfb5b11f07935028cc9e26ce5485d0d6f158007d8ef2249"
},
"downloads": -1,
"filename": "palletdatagenerator-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fbdf192b4678e1e84879fb4cf00c2985",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 49370,
"upload_time": "2025-09-09T03:06:49",
"upload_time_iso_8601": "2025-09-09T03:06:49.670538Z",
"url": "https://files.pythonhosted.org/packages/16/62/bc7477f58f8ab3c7adf63271edc628f36349378f27bcc5a880448947fc75/palletdatagenerator-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4c7ded09cf3c526baa0a410e10a497992bb9b9294cf5862a6b121ec43fcadb45",
"md5": "8da982b1ed5c2eb2a94e5e3aefca81ee",
"sha256": "64fb57fa2f36cd19f510c9bebb359a22a63ca2759958dca32b13d86a1a4d4771"
},
"downloads": -1,
"filename": "palletdatagenerator-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8da982b1ed5c2eb2a94e5e3aefca81ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 54116,
"upload_time": "2025-09-09T03:06:50",
"upload_time_iso_8601": "2025-09-09T03:06:50.953218Z",
"url": "https://files.pythonhosted.org/packages/4c/7d/ed09cf3c526baa0a410e10a497992bb9b9294cf5862a6b121ec43fcadb45/palletdatagenerator-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 03:06:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "boubakriibrahim",
"github_project": "PalletDataGenerator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"9.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
}
],
"lcname": "palletdatagenerator"
}
JSON
