Metadata-Version: 2.4
Name: signlib
Version: 1.0.1
Summary: AI Signature Generator for Synthetic Data - Automatically add signatures to documents for ML training datasets
Home-page: https://github.com/cagrigungor/signlib
Author: Cagri Gungor
Author-email: Cagri Gungor <cagrigungor@example.com>
License: MIT
Project-URL: Homepage, https://github.com/cagrigungor/signlib
Project-URL: Bug Reports, https://github.com/cagrigungor/signlib/issues
Project-URL: Source, https://github.com/cagrigungor/signlib
Project-URL: Documentation, https://github.com/cagrigungor/signlib#readme
Keywords: signature,synthetic-data,ai,machine-learning,document-processing,image-processing,automation,pdf,training-data,dataset-generation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0.0
Requires-Dist: numpy>=1.20.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# SignLib - AI Signature Generator for Synthetic Data

[![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 adding signatures to documents, designed specifically for **synthetic data generation** and **AI/ML training datasets**. It intelligently removes backgrounds, adapts colors, and positions signatures naturally on documents.

## 🎯 Use Cases

- **AI Training Data**: Generate synthetic signed documents for machine learning models
- **Dataset Augmentation**: Create diverse training samples with varied signature positions and styles
- **Document Automation**: Batch process documents with automated signature placement
- **Testing & Development**: Generate test documents without manual signing

## ✨ Features

✅ **Automatic Background Removal** - Removes signature background automatically  
✅ **Smart Positioning** - Finds optimal white space in document (customizable)  
✅ **Color Adaptation** - Auto-detects text color from document or use custom colors  
✅ **Auto-Scaling** - Scales signature based on document size  
✅ **Rotation Support** - Optional signature rotation for natural appearance  
✅ **Multiple Formats** - Supports PDF, TIFF, PNG, JPEG  
✅ **Position Control** - Customize signature placement with `bottom_percent` and `right_percent`

## 📦 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!)

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

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

## 🤖 Perfect for AI & Machine Learning

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 = 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 - feel free to use in commercial and open-source projects.

## 👨‍💻 Author

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

Specialized in AI training data generation and synthetic document creation.

## 🤝 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 Use Case: AI 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** - Professional signature placement for AI and synthetic data generation 🚀
