# Certificate Photo & Text Replacement Pipeline

Automated pipeline for replacing both portrait and text fields on document/ID images while preserving background noise, lighting, and security micro-patterns.

## Pipeline Stages

### Stage 1: Portrait Removal & Background Restoration
- **Segmentation**: BiRefNet (primary) or RMBG-2.0 for high-precision person masking
- **Mask Dilation**: 5-8 pixel dilation for complete hair/neck/collar coverage
- **Inpainting**: LaMa (Large Mask Inpainting) for background texture and watermark restoration

### Stage 2: Portrait Foreground Extraction & Compositing
- **Foreground Extraction**: BiRefNet for target portrait segmentation
- **Alignment**: InsightFace 68/106-point facial landmarks for affine transformation
- **Blending**: Multi-band blending for seamless composition

### Stage 3: Targeted Text Erasure & Reconstruction
- **Text Detection**: PP-OCRv4/PaddleOCR for field localization
- **Text Inpainting**: LaMa for local text region erasure
- **Font/Noise Matching**: Color, size, spacing analysis + Gaussian blur + noise injection
- **Composition**: Alpha blending with artifact simulation

## Installation

```bash
cd /data/onlyface

# Install dependencies
pip install -r requirements.txt

# Download models
python download_models.py
```

## Usage

```bash
# Basic usage
python certificate_pipeline.py \
  --original /path/to/original_certificate.jpg \
  --portrait /path/to/new_portrait.jpg \
  --output /path/to/result.jpg \
  --fields '{"Sex": "M", "Date of Issue": "12 DEC 2026", "Name": "JOHN DOE"}'

# Use RMBG instead of BiRefNet
python certificate_pipeline.py \
  --original original.jpg \
  --portrait portrait.jpg \
  --output result.jpg \
  --fields '{"Sex": "M"}' \
  --use-rmbg

# CPU mode
python certificate_pipeline.py \
  --original original.jpg \
  --portrait portrait.jpg \
  --output result.jpg \
  --fields '{"Sex": "M"}' \
  --device cpu
```

## Programmatic Usage

```python
from certificate_pipeline import CertificatePipeline, PipelineConfig

config = PipelineConfig(
    model_dir=Path("/data/onlyface/models"),
    device="cuda"
)

pipeline = CertificatePipeline(config)

result = pipeline.process(
    original_image="original.jpg",
    target_portrait="portrait.jpg",
    text_fields={
        "Sex": "M",
        "Date of Issue": "12 DEC 2026",
        "Name": "JOHN DOE"
    },
    output_path="result.jpg"
)
```

## Model Files

All models are stored in `/data/onlyface/models/`:
- `BiRefNet-general-epoch_244.onnx` - Portrait segmentation
- `rmbg-2.0.onnx` - Alternative segmentation
- `big-lama.pt` - Large mask inpainting
- `inswapper_128.onnx` - Face swapping (optional)
- `genderage.onnx` - Gender/age estimation (optional)
- `buffalo_l/` - InsightFace landmark detection (auto-downloaded)
- `paddleocr/` - OCR models (auto-downloaded)

## Requirements

- Python 3.10+
- CUDA-capable GPU (recommended)
- 8GB+ VRAM for full pipeline
- Models auto-download on first run

## Architecture

```
certificate_pipeline.py
├── PipelineConfig          # Configuration dataclass
├── ModelManager           # Model loading & caching
├── Stage1_PortraitRemoval # Portrait segmentation + LaMa inpainting
├── Stage2_PortraitCompositing # Foreground extraction + alignment + blending
├── Stage3_TextReplacement # OCR detection + text inpainting + rendering
└── CertificatePipeline    # Main orchestrator
```

## Notes

- BiRefNet provides superior hair/edge segmentation vs RMBG
- LaMa handles large masks better than cv2.inpaint for textured backgrounds
- Multi-band blending preserves high-frequency details better than seamlessClone
- Font matching uses median color from detected text region
- Gaussian noise simulates camera sensor artifacts
- All models cached in memory after first load