A comprehensive data augmentation tool specifically designed for ID card images, implementing 7 different augmentation techniques to simulate real-world scenarios.

🎯 Overview

This tool provides data augmentation capabilities for ID card images, implementing various transformation techniques that mimic real-world conditions such as worn-out cards, partial occlusion, different lighting conditions, and more.

✨ Features

7 Augmentation Techniques

Rotation - Simulates cards at different angles
Random Cropping - Simulates partially visible cards
Random Noise - Simulates worn-out cards
Horizontal Blockage - Simulates occluded card details
Grayscale Transformation - Simulates Xerox/scan copies
Blurring - Simulates blurred but readable cards
Brightness & Contrast - Simulates different lighting conditions

Key Features

Separate Methods: Each augmentation technique is applied independently
Quality Preservation: Maintains image quality with white background preservation
OpenCV Integration: Uses OpenCV functions for reliable image processing
Configurable: Easy configuration through YAML files
Progress Tracking: Real-time progress monitoring
Batch Processing: Process multiple images efficiently

🚀 Installation

Prerequisites

Python 3.7+
OpenCV
NumPy
PyYAML
PIL (Pillow)

Setup

Clone the repository:

git clone <repository-url>
cd IDcardsGenerator

Install dependencies:

pip install opencv-python numpy pyyaml pillow

Activate conda environment (if using GPU):

conda activate gpu

📁 Project Structure

IDcardsGenerator/
├── config/
│   └── config.yaml          # Main configuration file
├── data/
│   └── IDcards/
│       └── processed/       # Input images directory
├── src/
│   ├── data_augmentation.py # Core augmentation logic
│   ├── config_manager.py    # Configuration management
│   ├── image_processor.py   # Image processing utilities
│   └── utils.py             # Utility functions
├── logs/                    # Log files
├── out/                     # Output directory
└── main.py                  # Main script

⚙️ Configuration

Main Configuration (`config/config.yaml`)

# Data augmentation parameters
augmentation:
  # Rotation
  rotation:
    enabled: true
    angles: [30, 60, 120, 150, 180, 210, 240, 300, 330]
    probability: 1.0
  
  # Random cropping
  random_cropping:
    enabled: true
    ratio_range: [0.7, 1.0]
    probability: 1.0
  
  # Random noise
  random_noise:
    enabled: true
    mean_range: [0.0, 0.7]
    variance_range: [0.0, 0.1]
    probability: 1.0
  
  # Partial blockage
  partial_blockage:
    enabled: true
    num_occlusions_range: [1, 100]
    coverage_range: [0.0, 0.25]
    variance_range: [0.0, 0.1]
    probability: 1.0
  
  # Grayscale transformation
  grayscale:
    enabled: true
    probability: 1.0
  
  # Blurring
  blurring:
    enabled: true
    kernel_ratio_range: [0.0, 0.0084]
    probability: 1.0
  
  # Brightness and contrast
  brightness_contrast:
    enabled: true
    alpha_range: [0.4, 3.0]
    beta_range: [1, 100]
    probability: 1.0

# Processing configuration
processing:
  target_size: [640, 640]
  num_augmentations: 3
  save_format: "jpg"
  quality: 95

🎮 Usage

Basic Usage

python main.py --input-dir data/IDcards/processed --output-dir out

Command Line Options

python main.py [OPTIONS]

Options:
  --config CONFIG           Path to configuration file (default: config/config.yaml)
  --input-dir INPUT_DIR     Input directory containing images
  --output-dir OUTPUT_DIR   Output directory for augmented images
  --num-augmentations N     Number of augmented versions per image (default: 3)
  --target-size SIZE        Target size for images (width x height)
  --preview                 Preview augmentation on first image only
  --info                    Show information about images in input directory
  --list-presets           List available presets and exit
  --log-level LEVEL        Logging level (DEBUG, INFO, WARNING, ERROR)

Examples

Preview augmentation:

python main.py --preview --input-dir data/IDcards/processed --output-dir test_output

Show image information:

python main.py --info --input-dir data/IDcards/processed

Custom number of augmentations:

python main.py --input-dir data/IDcards/processed --output-dir out --num-augmentations 5

Custom target size:

python main.py --input-dir data/IDcards/processed --output-dir out --target-size 512x512

📊 Output

File Naming Convention

The tool creates separate files for each augmentation method:

im1_rotation_01.png          # Rotation method
im1_cropping_01.png          # Random cropping method
im1_noise_01.png             # Random noise method
im1_blockage_01.png          # Partial blockage method
im1_grayscale_01.png         # Grayscale method
im1_blurring_01.png          # Blurring method
im1_brightness_contrast_01.png  # Brightness/contrast method

Output Summary

After processing, you'll see a summary like:

==================================================
AUGMENTATION SUMMARY
==================================================
Original images: 106
Augmented images: 2226
Augmentation ratio: 21.00
Successful augmentations: 106
Output directory: out
==================================================

🔧 Augmentation Techniques Details

1. Rotation

Purpose: Simulates cards at different angles
Angles: 30°, 60°, 120°, 150°, 180°, 210°, 240°, 300°, 330°
Method: OpenCV rotation with white background preservation

2. Random Cropping

Purpose: Simulates partially visible ID cards
Ratio Range: 0.7 to 1.0 (70% to 100% of original size)
Method: Random crop with white background preservation

3. Random Noise

Purpose: Simulates worn-out cards
Mean Range: 0.0 to 0.7
Variance Range: 0.0 to 0.1
Method: Gaussian noise addition

4. Horizontal Blockage

Purpose: Simulates occluded card details
Lines: 1 to 100 horizontal lines
Coverage: 0% to 25% of image area
Colors: Multiple colors to simulate various objects

5. Grayscale Transformation

Purpose: Simulates Xerox/scan copies
Method: OpenCV cv2.cvtColor() function
Output: 3-channel grayscale image

6. Blurring

Purpose: Simulates blurred but readable cards
Kernel Ratio: 0.0 to 0.0084
Method: OpenCV cv2.filter2D() with Gaussian kernel

7. Brightness & Contrast

Purpose: Simulates different lighting conditions
Alpha Range: 0.4 to 3.0 (contrast)
Beta Range: 1 to 100 (brightness)
Method: OpenCV cv2.convertScaleAbs()

🛠️ Development

Adding New Augmentation Methods

Add the method to src/data_augmentation.py
Update configuration in config/config.yaml
Update default config in src/config_manager.py
Test with preview mode

Code Structure

main.py: Entry point and command-line interface
src/data_augmentation.py: Core augmentation logic
src/config_manager.py: Configuration management
src/image_processor.py: Image processing utilities
src/utils.py: Utility functions

📝 Logging

The tool provides comprehensive logging:

File logging: logs/data_augmentation.log
Console logging: Real-time progress updates
Log levels: DEBUG, INFO, WARNING, ERROR

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

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

🙏 Acknowledgments

OpenCV for image processing capabilities
NumPy for numerical operations
PyYAML for configuration management

📞 Support

For issues and questions:

Check the logs in logs/data_augmentation.log
Review the configuration in config/config.yaml
Test with preview mode first
Create an issue with detailed information

Note: This tool is specifically designed for ID card augmentation and may need adjustments for other image types.

README.md

ID Cards Data Augmentation Tool