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**:
```bash
git clone <repository-url>
cd IDcardsGenerator
```

2. **Install dependencies**:
```bash
pip install opencv-python numpy pyyaml pillow
```

3. **Activate conda environment** (if using GPU):
```bash
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`)

```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

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

### Command Line Options

```bash
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**:
```bash
python main.py --preview --input-dir data/IDcards/processed --output-dir test_output
```

2. **Show image information**:
```bash
python main.py --info --input-dir data/IDcards/processed
```

3. **Custom number of augmentations**:
```bash
python main.py --input-dir data/IDcards/processed --output-dir out --num-augmentations 5
```

4. **Custom target size**:
```bash
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.