BiyoVes

BiyoVes is an open-source CLI for automated Turkish portrait preparation using MediaPipe and BiRefNet.

Examples

Public demo portraits are fully synthetic and separate from private evaluation data. Each pair shows the original input on the left and the BiyoVes output on the right.

The canonical approved source files remain in examples/inputs and examples/outputs.

How BiyoVes sees a portrait

MediaPipe Face Landmarker provides facial geometry used to derive roll correction and placement references. The eye-line, facial axis/center reference, and chin anchor shown here come from that geometry. BiRefNet independently provides the foreground matte and visible-head region used during composition. These are documentation crops, not production outputs.

What BiyoVes does

• Removes the original background with soft foreground matting.
• Corrects eye-line roll and establishes a facial midline.
• Places the visible head automatically on a white-background canvas.
• Supports single-image and batch CLI processing.
• Provides biometric and vesikalik Turkish portrait presets.
• Processes locally; images and model inference stay on the machine.

Supported presets

These are BiyoVes composition targets, not statutory guarantees. The vesikalik preset can reduce scale slightly when needed to avoid horizontal clipping from a wide hairstyle.

Preset comparison

The same portrait can be prepared in either supported format. Each pair shows the 50×60 mm biometric output on the left and the 45×60 mm vesikalik output on the right.

Installation

The primary supported installation path is macOS 14 or newer on native Apple Silicon (arm64):

curl -fsSL https://raw.githubusercontent.com/mehmetaytugyuruk/biyoves/main/distribution/install-macos.sh | sh

The installer does not require an existing Python installation. It creates an isolated BiyoVes runtime, downloads and verifies the required models, and leaves normal processing local/offline afterward. The official installer supports native Apple Silicon execution only.

The installer keeps routine dependency and model-loader output out of the normal summary. Set BIYOVES_VERBOSE=1 when troubleshooting to replay the captured command output.

After installation, open a new Terminal window and run:

biyoves

With no arguments in an interactive terminal, BiyoVes opens a small guided menu for processing one photo, processing a folder, checking readiness, preparing models, or getting help. Advanced commands remain available for automation and direct control. Inside a guided action, type b or back to return to the menu, or q or quit to exit.

For manual or developer installation, Python 3.10–3.13 is supported. From a local checkout:

python -m pip install .

The core install does not include PyTorch or torchvision. For manual processing/development, install the optional inference dependencies as well:

python -m pip install ".[inference]"

Download the pinned model assets explicitly and cache them locally:

biyoves models download

The default cache is ~/.cache/biyoves. Set BIYOVES_CACHE_DIR to use another location. Processing commands use verified local assets and do not download models implicitly.

Show the installed package version:

biyoves --version

Inspect local runtime and model readiness:

biyoves doctor
biyoves doctor --strict --deep --json

doctor is read-only with respect to model downloads: it never downloads missing assets. --strict returns a failing status when required runtime dependencies, cache access, model assets, or a requested deep check are not ready. MPS availability is reported when present, but CPU fallback remains valid for the cross-platform package. Routine third-party startup chatter is hidden during checks; with BIYOVES_VERBOSE=1, captured diagnostics are replayed to stderr. The official installer uses a private managed Python runtime and does not modify the user's Python or uv installation.

CLI usage

Process one portrait with the biometric preset:

biyoves process input.jpg \
  --output output.png \
  --preset biometric

Process one portrait with the vesikalik preset:

biyoves process input.jpg \
  --output output.png \
  --preset vesikalik

Process a directory in deterministic filename order:

biyoves batch ./inputs \
  --output-dir ./outputs \
  --preset biometric

biometric is the default when --preset is omitted. The default resolution is 300 DPI, producing 591 × 709 px biometric or 531 × 709 px vesikalik outputs. batch continues after individual file failures and returns a failing status if any file failed.

Human-readable processing output shows one concise status per image. Successful files are marked ready, Quality Gate review results are marked for review, and failures are clearly separated. Use --json for the existing deterministic machine-readable result format. Set BIYOVES_VERBOSE=1 to replay captured MediaPipe, TFLite, Transformers, and model-loading diagnostics to stderr.

JSON results include raw eye-openness diagnostics for the selected face. Each eye score is the median of the three specified vertical landmark distances divided by that eye's horizontal landmark width; min_openness is the smaller score. The v1 quality gate adds review_reasons: eyes_closed when min_openness < 0.15, eyes_uncertain when 0.15 <= min_openness < 0.28, and no eye reason when min_openness >= 0.28. A face_count > 1 adds multiple_faces; the largest face is still processed. Review images are written normally, and review status does not produce a failing CLI exit code. This is an operational review aid, not a guarantee of official biometric compliance.

Pipeline overview

Input
  ↓
EXIF orientation
  ↓
MediaPipe Face Landmarker 0.10.35
  ↓
Eye-line roll correction + facial midline
  ↓
BiRefNet Lite soft matting
  ↓
Automatic head placement
  ↓
White-background 50 × 60 / 45 × 60 mm output

Continuous alpha is preserved for compositing. Connected-component thresholding (alpha >= 0.5) is used only for geometry analysis.

Model and runtime provenance

• BiRefNet Lite matting, revision 99c33412e3f58e1f33187abdc8c435c645243690; model weight SHA-256 ce8bcfc045e336322c0424a5863dcfb7e9ce8fed0a5fd4d1b2b20adf12d97243. The upstream model card identifies it as MIT licensed.
• MediaPipe Face Landmarker, package 0.10.35; task SHA-256 64184e229b263107bc2b804c6625db1341ff2bb731874b0bcc2fe6544e0bc9ff. The MediaPipe project is Apache-2.0 licensed; the downloaded task bundle remains subject to its upstream terms.
• Model weights are not bundled in Git or the Python package. biyoves models download downloads and verifies the pinned assets before local use.

Review upstream terms before redistribution or commercial use. BiyoVes source code is released under the MIT License.

Limitations

• Very fine hair strands can still be limited by the underlying matte.
• Unusually wide hairstyles may require vesikalik scale reduction to fit horizontally.
• Multiple-face inputs use the current policy: select the largest detected face.
• Detection or matting can fail with unusual poses, severe occlusion, poor lighting, or insufficient background separation.
• BiyoVes does not guarantee acceptance by a government authority or official biometric compliance.

Development and tests

Install the package and test dependencies, then run:

python -m pytest

The public examples are fully synthetic and tracked for documentation. Private/local evaluation images are not included in the repository.

Contributing and license

Keep changes focused on the CLI, runtime, tests, packaging, and documentation. Do not add private portraits, model weights, generated evaluation runs, or unsupported features to the repository.

MIT. See LICENSE.