OVMS Face Recognition Client

A lightweight Python client for OpenVINO Model Server (OVMS) face recognition pipeline.

Supports:

• Single image inference with face detection + recognition + known face matching
• Real-time RTSP / MJPEG stream processing with face recognition
• Automatic feature extraction from a folder of face images at startup
• MJPEG streaming output (viewable in browser or VLC)
• Docker deployment for easy distribution

Features

• Auto-generates known_faces.json from an images/ directory on startup
• Each image filename prefix becomes the person ID (e.g. zhang3.jpg → ID: zhang3)
• Real-time face matching with cosine similarity threshold (configurable)
• MJPEG HTTP stream output (http://host:8080/stream.mjpg)
• Silent handling: minimal logs when no faces or inference fails
• English logging for all key steps
• Fully Dockerized — mount images folder and JSON externally

Requirements

• Python 3.11+
• OVMS server running with model face_recognition_yiqisoft
• Input model expects: 448×448 RGB float32

Python dependencies (see requirements.txt):

• opencv-python
• numpy
• ovmsclient

Project Structure

face-recognition-client/
├── client.py               # Main script
├── requirements.txt        # Dependencies
├── Dockerfile              # Docker build file
├── images/                 # (mounted) Folder of face images (jpg/png)
└── known_faces.json        # (mounted/generated) Auto-generated face features

Quick Start

1. Build the Docker image

docker build -t face-rec-client:latest .

2. Run for single image inference

docker run --rm \
  -v $(pwd)/images:/app/images \
  -v $(pwd)/known_faces.json:/app/known_faces.json \
  -v $(pwd)/input.jpg:/app/input.jpg \
  -v $(pwd)/output.jpg:/app/output.jpg \
  face-rec-client:latest \
  --host your-ovms-ip \
  --port 31734 \
  --images-dir /app/images \
  --faces /app/known_faces.json \
  --image /app/input.jpg \
  --output /app/output.jpg \
  --threshold 0.65

3. Run for real-time stream + MJPEG output

docker run -d --restart unless-stopped \
  -p 8080:8080 \
  -v $(pwd)/images:/app/images \
  -v $(pwd)/known_faces.json:/app/known_faces.json \
  --name face-mjpeg \
  face-rec-client:latest \
  --host your-ovms-ip \
  --port 31734 \
  --stream "rtsp://user:pass@camera-ip:554/stream" \
  --images-dir /app/images \
  --faces /app/known_faces.json \
  --http-port 8080 \
  --threshold 0.65

Then open in browser or VLC:

http://your-server-ip:8080/stream.mjpg

Command Line Arguments

Argument	Description	Default	Required
--host	OVMS server IP or hostname	—	Yes
--port	OVMS gRPC port	—	Yes
--image	Path to single input image (inside container)	—	No
--stream	Input video stream URL (RTSP / MJPEG)	—	No
--output	Output path for image or stream recording	result.jpg	No
--http-port	MJPEG streaming port	8080	No
--images-dir	Directory of face images to extract features from	/app/images	No
--faces	Path to save/load known_faces.json	/app/known_faces.json	No
--threshold	Cosine similarity threshold (0~1)	0.60	No

You can also set THRESHOLD via environment variable:

-e THRESHOLD=0.7

Logs

All important steps are logged in English:

• Startup and OVMS connection
• Feature extraction from images/
• Stream connection / reconnection
• Face detection & matching results (when faces are found)
• MJPEG client connections

Inference failures and no-face frames are logged at DEBUG level only (silent in INFO mode).

View logs:

docker logs -f face-mjpeg

Development Tips

To see more detailed logs (including per-frame info):

Edit the first line of logging setup:

logging.basicConfig(level=logging.DEBUG, ...)

License

Apache License