Metadata-Version: 2.4
Name: biyoves
Version: 2.2.0
Summary: Local CLI for white-background biometric photo generation.
Author-email: Mehmet Aytuğ Yürük <myuruk1@ogr.iu.edu.tr>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mehmetaytugyuruk/biyoves
Project-URL: Documentation, https://github.com/mehmetaytugyuruk/biyoves#readme
Project-URL: Repository, https://github.com/mehmetaytugyuruk/biyoves
Keywords: biometric,passport,visa,photo,background-removal,face-detection,computer-vision,biyometrik
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Digital Camera
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python-headless>=4.5.0
Requires-Dist: numpy>=1.19.0
Requires-Dist: Pillow<13,>=10
Requires-Dist: mediapipe==0.10.35
Requires-Dist: transformers<5.18,>=5.14
Requires-Dist: huggingface-hub<2,>=1.24
Requires-Dist: safetensors<1,>=0.4
Requires-Dist: timm<2,>=1.0
Requires-Dist: kornia<1,>=0.8
Requires-Dist: einops<1,>=0.8
Provides-Extra: inference
Requires-Dist: torch<2.15,>=2.13; extra == "inference"
Requires-Dist: torchvision<0.30,>=0.28; extra == "inference"
Dynamic: license-file

# 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.

<p align="center">
  <img src="docs/assets/readme/showcase.webp" alt="Nine selected portrait examples shown as input and output pairs" width="1000">
</p>

The canonical approved source files remain in [`examples/inputs`](examples/inputs) and [`examples/outputs`](examples/outputs).

## How BiyoVes sees a portrait

<p align="center">
  <img src="docs/assets/readme/analysis.webp" alt="Ten synthetic portraits with sparse MediaPipe facial-geometry overlays" width="980">
</p>

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

| Preset | Physical size | Preferred visible-head height |
| --- | --- | --- |
| `biometric` | 50 × 60 mm | 36 mm |
| `vesikalik` | 45 × 60 mm | 31 mm |

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.

<p align="center">
  <img src="docs/assets/readme/presets.webp" alt="Four synthetic subjects shown in biometric and vesikalik output pairs" width="980">
</p>

## Installation

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

```bash
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:

```bash
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:

```bash
python -m pip install .
```

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

```bash
python -m pip install ".[inference]"
```

Download the pinned model assets explicitly and cache them locally:

```bash
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:

```bash
biyoves --version
```

Inspect local runtime and model readiness:

```bash
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:

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

Process one portrait with the vesikalik preset:

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

Process a directory in deterministic filename order:

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

```text
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](https://huggingface.co/ZhengPeng7/BiRefNet_lite-matting), revision `99c33412e3f58e1f33187abdc8c435c645243690`; model weight SHA-256 `ce8bcfc045e336322c0424a5863dcfb7e9ce8fed0a5fd4d1b2b20adf12d97243`. The upstream model card identifies it as MIT licensed.
- [MediaPipe Face Landmarker](https://ai.google.dev/edge/mediapipe/solutions/vision/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](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:

```bash
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](LICENSE).
