BiyoVes - Python Library

AI-powered biometric, passport, and visa photo generation for Python.

Resources: PyPI · Source · Issues · License

Overview

BiyoVes provides a compact API for background removal, face alignment, standards-based cropping, and print-ready photo layouts.

Installation

pip install biyoves

Or from source:

git clone https://github.com/mehmetaytugyuruk/biyoves-python-library.git
cd biyoves-python-library
pip install -e .

Quick Start

Method 1: Class-Based Usage (Recommended)

from biyoves import BiyoVes

# Specify the photo path
img = BiyoVes("photo.jpg")

# Create a passport photo (2-up layout)
passport = img.create_image("vesikalik", "2li", "result_passport.jpg")

# Create a biometric photo (4-up layout)
biometric = img.create_image("biyometrik", "4lu", "result_biometric.jpg")

# US visa photo
us_visa = img.create_image("abd_vizesi", "2li", "result_us_visa.jpg")

# Schengen visa photo
schengen = img.create_image("schengen", "4lu", "result_schengen.jpg")

Method 2: Function-Based Usage

from biyoves import create_image

# Single-line processing
passport = create_image("photo.jpg", "vesikalik", "2li", "result.jpg")

Batch Processing

from biyoves import BiyoVes

results = BiyoVes.batch_process(
    input_dir="photos/",
    photo_type="biyometrik",
    layout_type="4lu",
    output_dir="results/",
)

for result in results:
    print(result)

Models are loaded once and shared across the batch. A failed photo is reported with status="error" without stopping the remaining files. If output_dir is omitted, results are written to input_dir/results.

Photo Quality Preflight

from biyoves import BiyoVes

img = BiyoVes("photo.jpg")
report = img.check_quality("biyometrik")

print(report["is_acceptable"])
print(report["warnings"])

The preflight checks face-region blur, eye openness, estimated frontal face angle, and whether the detected face has enough source pixels for the selected standard at 300 DPI. These automated heuristics help catch common problems but do not guarantee acceptance by an issuing authority.

Photo Types

• "biyometrik" - Standard biometric photo (50x60mm)
• "vesikalik" - Passport photo (45x60mm)
• "abd_vizesi" - US visa photo (50x50mm)
• "schengen" - Schengen visa photo (35x45mm)

Layout Types

• "2li" - 2 photos stacked vertically (2x1)
• "4lu" - 4 photos in a grid (2x2)
• "6li" - 6 photos in a grid (3x2)
• "8li" - 8 photos in a grid (4x2)

Features

• AI-powered automatic background removal
• Automatic face angle correction
• Automatic cropping to standard dimensions
• Batch directory processing with per-file results
• Preflight checks for blur, eye openness, face angle, and resolution
• Print templates (2-up / 4-up / 6-up / 8-up layouts)
• Print-ready PDF output at 300 DPI
• Cut lines for print-ready output

Requirements

• Python >= 3.7
• OpenCV
• NumPy
• ONNX Runtime

Models Used

This project uses the following ONNX models:

Model Directory: All models are stored in the src/biyoves/models/ directory.

Model Citations

• MODNet: Zhanghan Ke et al., "MODNet: Real-Time Trimap-Free Portrait Matting via Objective Decomposition," AAAI 2022.
• InsightFace: Jiankang Deng et al., "InsightFace: 2D and 3D Face Analysis Project."

Third-Party Models and Licensing

The BiyoVes source code is MIT-licensed. Bundled model weights retain their original terms and are not relicensed by this repository:

• MODNet code and published models are provided under Apache-2.0 by the MODNet project.
• InsightFace model-zoo weights, including the SCRFD and 2D106 components used here, are provided for non-commercial research purposes only according to the InsightFace model-zoo notice.

Review the upstream terms before redistributing the weights or using them in a commercial product.

License

The BiyoVes source code is released under the MIT License. Third-party model weights are governed by the terms listed above.