signlib 1.0.2
Automated signature placement for synthetic data generation - designed for creating ML training datasets
License: MIT
Requires Python: >=3.6
Keywords: signature, synthetic-data, ai, machine-learning, document-processing, image-processing, automation, pdf, training-data, dataset-generation

# SignLib - Signature Placement for Synthetic Data Generation

[![PyPI version](https://badge.fury.io/py/signlib.svg)](https://badge.fury.io/py/signlib)
[![Python 3.6+](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

SignLib is a Python library for automatically placing signatures on documents. It is specifically designed for generating synthetic training data for AI and machine learning models. The library processes signature images, removes backgrounds, and intelligently positions them on documents.

## Use Cases

- Generate synthetic signed documents for training machine learning models
- Create diverse training datasets with varied signature positions and styles
- Automate document processing pipelines for testing and development
- Batch process large document collections with consistent signature placement
- Augment existing datasets with signature variations

## Features

- Automatic background removal from signature images
- Intelligent positioning to find optimal white space in documents
- Color adaptation: auto-detect document text color or specify custom colors
- Automatic scaling based on document dimensions
- Optional rotation for natural appearance and variation
- Support for multiple formats: PDF, TIFF, PNG, JPEG
- Customizable position control with bottom_percent and right_percent parameters
- High-quality image processing with contrast enhancement

## Installation

```bash
pip install signlib
```

## Quick Start

### Basic Usage

```python
from signlib import create_sign

# Simplest usage - auto-detect signature color
create_sign('document.pdf', 'signature.png')

# Specify output path
create_sign('document.pdf', 'signature.png', output_path='signed_document.pdf')
```

### Custom Color

```python
from signlib import create_sign

# Blue signature
create_sign('document.pdf', 'signature.png', signature_color=(0, 0, 255))

# Black signature
create_sign('document.pdf', 'signature.png', signature_color=(0, 0, 0))

# Dark gray signature
create_sign('document.pdf', 'signature.png', signature_color=(50, 50, 50))
```

### Position Control (New Feature)

```python
from signlib import create_sign

# Search in bottom 40% and right 40% of document
create_sign(
    'document.pdf',
    'signature.png',
    bottom_percent=40,  # Search from bottom 40% upward
    right_percent=40    # Search from right 40% leftward
)

# Place signature in bottom-left area
create_sign(
    'document.pdf',
    'signature.png',
    bottom_percent=30,  # Bottom 30%
    right_percent=70    # Left 70% (starting from right)
)
```

### Advanced Usage

```python
from signlib import create_sign

# Full control over all parameters
create_sign(
    document_path='document.tif',
    sign_path='signature.png',
    output_path='signed.tif',
    signature_color=(0, 0, 100),  # Dark blue
    scale_factor=0.15,             # 15% of document width
    rotation_angle=5.0,            # 5 degrees clockwise
    bottom_percent=25,             # Bottom 25%
    right_percent=50               # Right 50%
)
```

### Batch Processing for Synthetic Training Data

```python
from signlib import create_sign
from pathlib import Path

# Create synthetic training data
doc_folder = Path('documents/')
signature_folder = Path('signatures/')
output_folder = Path('synthetic_data/')
output_folder.mkdir(exist_ok=True)

# Generate diverse signed documents
for doc_file in doc_folder.glob('*.pdf'):
    for sig_file in signature_folder.glob('*.png'):
        output_name = f"{doc_file.stem}_{sig_file.stem}_signed.pdf"
        output_path = output_folder / output_name
        
        create_sign(
            str(doc_file),
            str(sig_file),
            output_path=str(output_path),
            scale_factor=0.12,         # Vary these for diversity
            rotation_angle=0.0,
            bottom_percent=25,
            right_percent=50
        )
        print(f"Generated: {output_name}")
```

### Class-Based Usage (Advanced)

```python
from signlib import SignatureProcessor

processor = SignatureProcessor()

# Step-by-step processing
result = processor.create_sign(
    document_path='document.pdf',
    sign_path='signature.png',
    signature_color=None,      # Auto-detect
    scale_factor=0.12,
    rotation_angle=0.0,
    enhance_contrast=True,
    bottom_percent=25,
    right_percent=50
)

print(f"Signed document: {result}")
```

## API Reference

### create_sign() Function

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `document_path` | str | **Required** | Path to document file |
| `sign_path` | str | **Required** | Path to signature file |
| `output_path` | str | None | Output file path (auto-generated if None) |
| `signature_color` | tuple | None | RGB color (r, g, b). None for auto-detect |
| `scale_factor` | float | 0.12 | Signature size ratio (0.12 = 12% of document width) |
| `rotation_angle` | float | 0.0 | Rotation angle in degrees |
| `bottom_percent` | float | 25 | Search area from bottom (25 = bottom 25%) |
| `right_percent` | float | 50 | Search area from right (50 = right 50%) |

### Position Control

- **bottom_percent**: Controls how far from the bottom to search
  - 25 = Search in bottom 25% of document (default, professional)
  - 40 = Search in bottom 40% (more flexible)
  - 50 = Search in bottom 50% (entire lower half)

- **right_percent**: Controls how far from the right to search
  - 50 = Search in right 50% of document (default, typical signature position)
  - 40 = Search in rightmost 40% (more to the right)
  - 70 = Search in right 70% (includes left-center area)

## Designed for Synthetic Data Generation

SignLib is designed for generating synthetic training data:

- Consistent Quality: Generate thousands of signed documents with consistent quality
- Variation Control: Easily control position, size, rotation, and color for data diversity
- Batch Processing: Process large datasets efficiently
- Reproducible: Same parameters produce same results for reproducible experiments

## Notes

- Signature files should be in PNG format (for transparent background support)
- Supported document formats: PDF, TIFF, PNG, JPEG
- When `signature_color=None`, the library auto-detects the most common dark color from the document
- Signatures are typically placed in the bottom-right area within the whitest available space
- Background is automatically removed and contrast is enhanced

## Requirements

- Python 3.6+
- Pillow >= 9.0.0
- NumPy >= 1.20.0

## License

MIT License - Free to use in commercial and open-source projects.

## Author

Cagri Gungor ([@cagrigungor](https://github.com/cagrigungor))

Specialized in synthetic data generation for machine learning applications.

## Contributing

Contributions are welcome. Please feel free to submit a Pull Request.

## Issues

Found a bug or have a feature request? Please open an issue on [GitHub](https://github.com/cagrigungor/signlib).

## Example: Generate Training Dataset

```python
import random
from signlib import create_sign
from pathlib import Path

# Generate diverse training dataset
documents = list(Path('documents').glob('*.pdf'))
signatures = list(Path('signatures').glob('*.png'))

for i in range(1000):  # Generate 1000 synthetic samples
    doc = random.choice(documents)
    sig = random.choice(signatures)
    
    # Vary parameters for diversity
    create_sign(
        str(doc),
        str(sig),
        output_path=f'training_data/sample_{i:04d}.pdf',
        scale_factor=random.uniform(0.10, 0.15),
        rotation_angle=random.uniform(-10, 10),
        bottom_percent=random.randint(20, 35),
        right_percent=random.randint(40, 60)
    )
```

---

SignLib - Automated signature placement for synthetic data generation and machine learning training datasets.