# Signature Verification Module
A comprehensive Python package for signature verification and classification using deep learning models. This module supports both ResNet Siamese networks for verification and Vision Transformers (ViT) with ArcFace for classification.
## Features
- **Multiple Model Architectures**:
- ResNet50 Siamese network with contrastive loss for signature verification
- Vision Transformer (ViT) with ArcFace loss for signature classification
- **S3 Integration**: Seamless integration with AWS S3 for model weights and dataset storage
- **Flexible Configuration**: Environment variable-based configuration system
- **Complete Pipeline**: From data preprocessing to model training and inference
- **Production Ready**: Optimized for both research and production deployment
## Installation
### Requirements
- Python 3.8+
- PyTorch 1.9+
- torchvision
- timm (for ViT models)
- scikit-image
- scikit-learn
- pandas
- PIL/Pillow
- boto3 (for S3 support)
- pydantic
- scipy
### Install Dependencies
```bash
pip install torch torchvision torchaudio
pip install timm scikit-image scikit-learn pandas pillow boto3 pydantic scipy
```
## Quick Start
### Basic Usage
```python
from signature import SignatureConfig, load_model, classify_signatures
# Configure the module
config = SignatureConfig(
model_type="vit",
num_classes=100,
model_s3_path="s3://my-bucket/models/signature_vit.pth"
)
# Load a trained model
model = load_model()
# Classify signatures
results = classify_signatures(
model=model,
reference_path="path/to/reference/signatures",
detected_path="path/to/detected/signatures"
)
print(f"Accepted signatures: {results['accepted_signatures']}")
```
### Training a Model
```python
from signature import train_model, create_dataset_csv
# Create a dataset CSV from image directory
create_dataset_csv(
image_directory="path/to/signature/images",
output_csv="dataset.csv",
dataset_type="single" # or "pairs" for ResNet
)
# Train a model
model, metrics = train_model(
model_type="vit",
dataset_path="dataset.csv",
save_path="s3://my-bucket/models/trained_model.pth",
num_classes=100,
epochs=20
)
print(f"Test accuracy: {metrics['test_accuracy']:.4f}")
```
## Configuration
The module supports configuration through environment variables or programmatically:
### Environment Variables
```bash
# Model configuration
export SIGNATURE_MODEL_TYPE=vit
export SIGNATURE_NUM_CLASSES=100
export SIGNATURE_MODEL_S3_PATH=s3://my-bucket/models/model.pth
# AWS configuration
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-2
# Training configuration
export SIGNATURE_BATCH_SIZE=32
export SIGNATURE_LEARNING_RATE=5e-5
export SIGNATURE_EPOCHS=15
```
### Programmatic Configuration
```python
from signature import SignatureConfig, set_config
config = SignatureConfig(
model_type="vit",
num_classes=100,
batch_size=32,
learning_rate=5e-5,
aws_access_key_id="your_access_key",
aws_secret_access_key="your_secret_key"
)
set_config(config)
```
## Model Architectures
### ResNet50 Siamese
Best for signature verification (determining if two signatures are from the same person):
```python
from signature import ResNet50Siamese, train_resnet
# Create model
model = ResNet50Siamese(embedding_dim=512)
# Train model
model, metrics = train_resnet(
dataset_path="pairs_dataset.csv",
epochs=25,
margin=17.5
)
```
### Vision Transformer (ViT)
Best for signature classification (identifying which person signed):
```python
from signature import SignatureViT, train_vit
# Create model
model = SignatureViT(num_classes=100, embedding_dim=512)
# Train model
model, metrics = train_vit(
num_classes=100,
dataset_path="single_image_dataset.csv",
epochs=15
)
```
## Data Preparation
### Directory Structure
Organize your signature images in the following structure:
```
signatures/
├── person1/
│ ├── signature1.png
│ ├── signature2.png
│ └── signature3.png
├── person2/
│ ├── signature1.png
│ └── signature2.png
└── person3/
├── signature1.png
├── signature2.png
└── signature4.png
```
### Creating Dataset CSVs
```python
from signature import create_dataset_csv
# For ViT (single image classification)
create_dataset_csv(
image_directory="signatures/",
output_csv="vit_dataset.csv",
dataset_type="single"
)
# For ResNet (image pairs)
create_dataset_csv(
image_directory="signatures/",
output_csv="resnet_dataset.csv",
dataset_type="pairs",
pairs_per_person=50
)
```
## S3 Integration
The module seamlessly works with S3 for storing models, datasets, and reference signatures:
```python
from signature import S3Manager
# Create S3 manager
s3_manager = S3Manager()
# Download model weights
s3_manager.download_file(
"s3://my-bucket/models/model.pth",
"local_model.pth"
)
# Upload trained model
s3_manager.upload_file(
"local_model.pth",
"s3://my-bucket/models/new_model.pth"
)
```
## Advanced Usage
### Custom Feature Extraction
```python
from signature import get_fused_features, extract_deep_features
# Extract fused features (deep + HOG)
features = get_fused_features(model, "signature.png")
# Extract only deep features
deep_features = extract_deep_features(model, "signature.png")
```
### Custom Training Loop
```python
from signature import (
create_model, ContrastiveLoss, create_dataloader,
get_config
)
import torch
config = get_config()
# Create model and loss
model = create_model(model_type="resnet")
criterion = ContrastiveLoss(margin=17.5)
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
# Create data loaders
train_loader, val_loader, test_loader = create_dataloader(
"dataset.csv",
dataset_type="pairs",
batch_size=32
)
# Custom training loop
for epoch in range(10):
for img1, img2, labels in train_loader:
optimizer.zero_grad()
emb1, emb2 = model(img1, img2)
loss = criterion(emb1, emb2, labels)
loss.backward()
optimizer.step()
```
## API Reference
### Core Functions
- `load_model()`: Load a trained model with optional S3 weights
- `classify_signatures()`: Classify detected signatures against references
- `train_model()`: Train a model with automatic type detection
- `create_dataset_csv()`: Create dataset CSV from image directory
### Model Classes
- `ResNet50Siamese`: Siamese ResNet50 for signature verification
- `SignatureViT`: Vision Transformer with ArcFace for classification
- `ContrastiveLoss`: Contrastive loss for Siamese networks
- `ArcFace`: Angular margin loss implementation
### Data Classes
- `SignatureDataset`: Dataset for single signature images
- `SignaturePairDataset`: Dataset for signature image pairs
- `create_dataloader()`: Create train/val/test data loaders
### Utility Classes
- `SignatureConfig`: Configuration management
- `S3Manager`: S3 operations manager
## Performance Tips
1. **Use GPU**: Set `SIGNATURE_DEVICE=cuda` for faster training and inference
2. **Batch Processing**: Use larger batch sizes for better GPU utilization
3. **Data Augmentation**: Enable augmentation for better generalization
4. **Caching**: Models and datasets are automatically cached locally
5. **S3 Optimization**: Use appropriate S3 region for reduced latency
## Troubleshooting
### Common Issues
1. **Import Errors**: Ensure all dependencies are installed
2. **S3 Access**: Check AWS credentials and permissions
3. **Memory Issues**: Reduce batch size or use CPU if GPU memory is limited
4. **Image Format**: Ensure images are in supported formats (PNG, JPG, JPEG)
### Debug Mode
Enable detailed logging:
```python
from signature.utils import setup_logging
setup_logging("DEBUG")
```
## Examples
See the `examples/` directory for complete examples:
- `train_vit_example.py`: Training a ViT model
- `train_resnet_example.py`: Training a ResNet Siamese model
- `inference_example.py`: Running inference on new signatures
- `s3_integration_example.py`: Working with S3 storage
## License
This module is part of the LiteWave ML Models repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/aiorch/litewave-ml-models/tree/main/signature",
"name": "litewave-ml-models-signature",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "LitewaveAI <yash@litewave.ai>",
"keywords": "signature, verification, classification, machine-learning, computer-vision, pytorch",
"author": "LitewaveAI",
"author_email": "LitewaveAI <yash@litewave.ai>",
"download_url": "https://files.pythonhosted.org/packages/39/a0/dbca0936209b55c392d0e750a4df4e7044902182b62c3662671f43cfe8ad/litewave_ml_models_signature-0.0.8.tar.gz",
"platform": null,
"description": "# Signature Verification Module\n\nA comprehensive Python package for signature verification and classification using deep learning models. This module supports both ResNet Siamese networks for verification and Vision Transformers (ViT) with ArcFace for classification.\n\n## Features\n\n- **Multiple Model Architectures**: \n - ResNet50 Siamese network with contrastive loss for signature verification\n - Vision Transformer (ViT) with ArcFace loss for signature classification\n- **S3 Integration**: Seamless integration with AWS S3 for model weights and dataset storage\n- **Flexible Configuration**: Environment variable-based configuration system\n- **Complete Pipeline**: From data preprocessing to model training and inference\n- **Production Ready**: Optimized for both research and production deployment\n\n## Installation\n\n### Requirements\n\n- Python 3.8+\n- PyTorch 1.9+\n- torchvision\n- timm (for ViT models)\n- scikit-image\n- scikit-learn\n- pandas\n- PIL/Pillow\n- boto3 (for S3 support)\n- pydantic\n- scipy\n\n### Install Dependencies\n\n```bash\npip install torch torchvision torchaudio\npip install timm scikit-image scikit-learn pandas pillow boto3 pydantic scipy\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom signature import SignatureConfig, load_model, classify_signatures\n\n# Configure the module\nconfig = SignatureConfig(\n model_type=\"vit\",\n num_classes=100,\n model_s3_path=\"s3://my-bucket/models/signature_vit.pth\"\n)\n\n# Load a trained model\nmodel = load_model()\n\n# Classify signatures\nresults = classify_signatures(\n model=model,\n reference_path=\"path/to/reference/signatures\",\n detected_path=\"path/to/detected/signatures\"\n)\n\nprint(f\"Accepted signatures: {results['accepted_signatures']}\")\n```\n\n### Training a Model\n\n```python\nfrom signature import train_model, create_dataset_csv\n\n# Create a dataset CSV from image directory\ncreate_dataset_csv(\n image_directory=\"path/to/signature/images\",\n output_csv=\"dataset.csv\",\n dataset_type=\"single\" # or \"pairs\" for ResNet\n)\n\n# Train a model\nmodel, metrics = train_model(\n model_type=\"vit\",\n dataset_path=\"dataset.csv\",\n save_path=\"s3://my-bucket/models/trained_model.pth\",\n num_classes=100,\n epochs=20\n)\n\nprint(f\"Test accuracy: {metrics['test_accuracy']:.4f}\")\n```\n\n## Configuration\n\nThe module supports configuration through environment variables or programmatically:\n\n### Environment Variables\n\n```bash\n# Model configuration\nexport SIGNATURE_MODEL_TYPE=vit\nexport SIGNATURE_NUM_CLASSES=100\nexport SIGNATURE_MODEL_S3_PATH=s3://my-bucket/models/model.pth\n\n# AWS configuration\nexport AWS_ACCESS_KEY_ID=your_access_key\nexport AWS_SECRET_ACCESS_KEY=your_secret_key\nexport AWS_DEFAULT_REGION=us-east-2\n\n# Training configuration\nexport SIGNATURE_BATCH_SIZE=32\nexport SIGNATURE_LEARNING_RATE=5e-5\nexport SIGNATURE_EPOCHS=15\n```\n\n### Programmatic Configuration\n\n```python\nfrom signature import SignatureConfig, set_config\n\nconfig = SignatureConfig(\n model_type=\"vit\",\n num_classes=100,\n batch_size=32,\n learning_rate=5e-5,\n aws_access_key_id=\"your_access_key\",\n aws_secret_access_key=\"your_secret_key\"\n)\n\nset_config(config)\n```\n\n## Model Architectures\n\n### ResNet50 Siamese\n\nBest for signature verification (determining if two signatures are from the same person):\n\n```python\nfrom signature import ResNet50Siamese, train_resnet\n\n# Create model\nmodel = ResNet50Siamese(embedding_dim=512)\n\n# Train model\nmodel, metrics = train_resnet(\n dataset_path=\"pairs_dataset.csv\",\n epochs=25,\n margin=17.5\n)\n```\n\n### Vision Transformer (ViT)\n\nBest for signature classification (identifying which person signed):\n\n```python\nfrom signature import SignatureViT, train_vit\n\n# Create model\nmodel = SignatureViT(num_classes=100, embedding_dim=512)\n\n# Train model\nmodel, metrics = train_vit(\n num_classes=100,\n dataset_path=\"single_image_dataset.csv\",\n epochs=15\n)\n```\n\n## Data Preparation\n\n### Directory Structure\n\nOrganize your signature images in the following structure:\n\n```\nsignatures/\n\u251c\u2500\u2500 person1/\n\u2502 \u251c\u2500\u2500 signature1.png\n\u2502 \u251c\u2500\u2500 signature2.png\n\u2502 \u2514\u2500\u2500 signature3.png\n\u251c\u2500\u2500 person2/\n\u2502 \u251c\u2500\u2500 signature1.png\n\u2502 \u2514\u2500\u2500 signature2.png\n\u2514\u2500\u2500 person3/\n \u251c\u2500\u2500 signature1.png\n \u251c\u2500\u2500 signature2.png\n \u2514\u2500\u2500 signature4.png\n```\n\n### Creating Dataset CSVs\n\n```python\nfrom signature import create_dataset_csv\n\n# For ViT (single image classification)\ncreate_dataset_csv(\n image_directory=\"signatures/\",\n output_csv=\"vit_dataset.csv\",\n dataset_type=\"single\"\n)\n\n# For ResNet (image pairs)\ncreate_dataset_csv(\n image_directory=\"signatures/\",\n output_csv=\"resnet_dataset.csv\",\n dataset_type=\"pairs\",\n pairs_per_person=50\n)\n```\n\n## S3 Integration\n\nThe module seamlessly works with S3 for storing models, datasets, and reference signatures:\n\n```python\nfrom signature import S3Manager\n\n# Create S3 manager\ns3_manager = S3Manager()\n\n# Download model weights\ns3_manager.download_file(\n \"s3://my-bucket/models/model.pth\", \n \"local_model.pth\"\n)\n\n# Upload trained model\ns3_manager.upload_file(\n \"local_model.pth\",\n \"s3://my-bucket/models/new_model.pth\"\n)\n```\n\n## Advanced Usage\n\n### Custom Feature Extraction\n\n```python\nfrom signature import get_fused_features, extract_deep_features\n\n# Extract fused features (deep + HOG)\nfeatures = get_fused_features(model, \"signature.png\")\n\n# Extract only deep features\ndeep_features = extract_deep_features(model, \"signature.png\")\n```\n\n### Custom Training Loop\n\n```python\nfrom signature import (\n create_model, ContrastiveLoss, create_dataloader, \n get_config\n)\nimport torch\n\nconfig = get_config()\n\n# Create model and loss\nmodel = create_model(model_type=\"resnet\")\ncriterion = ContrastiveLoss(margin=17.5)\noptimizer = torch.optim.Adam(model.parameters(), lr=1e-3)\n\n# Create data loaders\ntrain_loader, val_loader, test_loader = create_dataloader(\n \"dataset.csv\", \n dataset_type=\"pairs\",\n batch_size=32\n)\n\n# Custom training loop\nfor epoch in range(10):\n for img1, img2, labels in train_loader:\n optimizer.zero_grad()\n emb1, emb2 = model(img1, img2)\n loss = criterion(emb1, emb2, labels)\n loss.backward()\n optimizer.step()\n```\n\n## API Reference\n\n### Core Functions\n\n- `load_model()`: Load a trained model with optional S3 weights\n- `classify_signatures()`: Classify detected signatures against references\n- `train_model()`: Train a model with automatic type detection\n- `create_dataset_csv()`: Create dataset CSV from image directory\n\n### Model Classes\n\n- `ResNet50Siamese`: Siamese ResNet50 for signature verification\n- `SignatureViT`: Vision Transformer with ArcFace for classification\n- `ContrastiveLoss`: Contrastive loss for Siamese networks\n- `ArcFace`: Angular margin loss implementation\n\n### Data Classes\n\n- `SignatureDataset`: Dataset for single signature images\n- `SignaturePairDataset`: Dataset for signature image pairs\n- `create_dataloader()`: Create train/val/test data loaders\n\n### Utility Classes\n\n- `SignatureConfig`: Configuration management\n- `S3Manager`: S3 operations manager\n\n## Performance Tips\n\n1. **Use GPU**: Set `SIGNATURE_DEVICE=cuda` for faster training and inference\n2. **Batch Processing**: Use larger batch sizes for better GPU utilization\n3. **Data Augmentation**: Enable augmentation for better generalization\n4. **Caching**: Models and datasets are automatically cached locally\n5. **S3 Optimization**: Use appropriate S3 region for reduced latency\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Import Errors**: Ensure all dependencies are installed\n2. **S3 Access**: Check AWS credentials and permissions\n3. **Memory Issues**: Reduce batch size or use CPU if GPU memory is limited\n4. **Image Format**: Ensure images are in supported formats (PNG, JPG, JPEG)\n\n### Debug Mode\n\nEnable detailed logging:\n\n```python\nfrom signature.utils import setup_logging\nsetup_logging(\"DEBUG\")\n```\n\n## Examples\n\nSee the `examples/` directory for complete examples:\n\n- `train_vit_example.py`: Training a ViT model\n- `train_resnet_example.py`: Training a ResNet Siamese model\n- `inference_example.py`: Running inference on new signatures\n- `s3_integration_example.py`: Working with S3 storage\n\n## License\n\nThis module is part of the LiteWave ML Models repository. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package for signature verification and classification.",
"version": "0.0.8",
"project_urls": {
"Bug Tracker": "https://github.com/aiorch/litewave-ml-models/tree/main/signatureissues",
"Documentation": "https://github.com/aiorch/litewave-ml-models/blob/main/signature/README.md",
"Homepage": "https://github.com/aiorch/litewave-ml-models/tree/main/signature",
"Repository": "https://github.com/aiorch/litewave-ml-models/tree/main/signature"
},
"split_keywords": [
"signature",
" verification",
" classification",
" machine-learning",
" computer-vision",
" pytorch"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "87c252537e3e3cf2e736d3587aab4c834aef6adf54290f8600ae7412c11bc5bc",
"md5": "6a588c01e1227813969dd0f3db46da2f",
"sha256": "72b5d65a257f7ebe0ed9f57ecba07fb332d1eaec8c1a642ceaa052f36e9faa6e"
},
"downloads": -1,
"filename": "litewave_ml_models_signature-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a588c01e1227813969dd0f3db46da2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31635,
"upload_time": "2025-08-01T02:20:25",
"upload_time_iso_8601": "2025-08-01T02:20:25.336946Z",
"url": "https://files.pythonhosted.org/packages/87/c2/52537e3e3cf2e736d3587aab4c834aef6adf54290f8600ae7412c11bc5bc/litewave_ml_models_signature-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "39a0dbca0936209b55c392d0e750a4df4e7044902182b62c3662671f43cfe8ad",
"md5": "f50ee894b7f7291cd063cbb9c1652b9b",
"sha256": "d5bba148841e8e2b10d66b86d86cfa325f8dc8914dabbf8c5f8b5eb38229870d"
},
"downloads": -1,
"filename": "litewave_ml_models_signature-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "f50ee894b7f7291cd063cbb9c1652b9b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27132,
"upload_time": "2025-08-01T02:20:26",
"upload_time_iso_8601": "2025-08-01T02:20:26.782345Z",
"url": "https://files.pythonhosted.org/packages/39/a0/dbca0936209b55c392d0e750a4df4e7044902182b62c3662671f43cfe8ad/litewave_ml_models_signature-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 02:20:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aiorch",
"github_project": "litewave-ml-models",
"github_not_found": true,
"lcname": "litewave-ml-models-signature"
}
JSON
