Multithreaded Face Detection Server

A client-server application that detects and replaces faces in images using OpenCV's Haar cascade classifiers, with multithreaded client handling via POSIX threads.

Components

File	Description
facedetect.c	Server — listens for client connections, processes face detection/replacement requests using OpenCV
faceclient.c	Client — connects to the server, sends images, and receives processed results
protocol.c / protocol.h	Shared communication protocol helpers for reading/writing binary messages

Building

make            # build both facedetect and faceclient
make clean      # remove compiled binaries

Dependencies: OpenCV 2.x (C API) — specifically opencv_core, opencv_imgcodecs, opencv_objdetect, and opencv_imgproc. POSIX threads (-pthread).

Usage

Server

./facedetect maxclients maxsize [portnum]

Argument	Description
maxclients	Maximum number of queued client connections (0–10000)
maxsize	Maximum image size in bytes (0 = unlimited, up to 2³²−1)
portnum	(optional) Port to listen on; uses an ephemeral port if omitted

The server prints the listening port number to stderr on startup.

Client

./faceclient port [--output filename] [--replace filename] [--detect filename]

Option	Description
port	Server port to connect to
--detect filename	Input image file for face detection (reads from stdin if omitted)
--replace filename	Replacement image file — faces in the detect image are replaced with this
--output filename	Output file for the processed image (writes to stdout if omitted)

Examples

Detect faces in photo.jpg and save the annotated result:

./faceclient 12345 --detect photo.jpg --output result.jpg

Replace faces with emoji.png:

./faceclient 12345 --detect photo.jpg --replace emoji.png --output result.jpg

Read from stdin and write to stdout:

cat photo.jpg | ./faceclient 12345 > result.jpg

Communication Protocol

All messages use a binary protocol with the following structure:

Field	Size	Description
Prefix	4 bytes	Magic number 0x23107231
Operation	1 byte	0 = detect, 1 = replace, 2 = output response, 3 = error
Image size	4 bytes	Size of the following image/message data
Image data	N bytes	Raw image binary data (or error message text)

For replace requests, a second image (size + data) follows the first.

Exit Codes

Server (facedetect)

Code	Meaning
4	Cannot load cascade classifier files
16	Cannot listen on the specified port
17	Cannot open the temporary image file for writing
19	Invalid command-line arguments

Client (faceclient)

Code	Meaning
3	Server returned an error message
5	Unexpected communication/protocol error
6	Cannot open input file for reading
8	Invalid command-line arguments
13	Cannot connect to the server on the given port
15	Cannot open output file for writing