IDcardsGenerator/README.md

ID Cards Data Augmentation Tool

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

1. Rotation - Simulates cards at different angles
2. Random Cropping - Simulates partially visible cards
3. Random Noise - Simulates worn-out cards
4. Horizontal Blockage - Simulates occluded card details
5. Grayscale Transformation - Simulates Xerox/scan copies
6. Blurring - Simulates blurred but readable cards
7. 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

1. Clone the repository:

git clone <repository-url>
cd IDcardsGenerator

2. Install dependencies:

pip install opencv-python numpy pyyaml pillow

3. 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

1. Preview augmentation:

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

2. Show image information:

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

3. Custom number of augmentations:

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

4. 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

1. Add the method to src/data_augmentation.py
2. Update configuration in config/config.yaml
3. Update default config in src/config_manager.py
4. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. 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:

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

---

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