Skip to content

README.md

Latest commit

 

History

History
131 lines (90 loc) · 4.54 KB

README.md

File metadata and controls

131 lines (90 loc) · 4.54 KB

CSSE2310 Assignment 4 - Face Detection & Replacement Server/Client

Overview

This project implements a TCP server (uqfacedetect) and client (uqfaceclient) for face detection and replacement in images using OpenCV. The server supports multiple concurrent clients, connection limiting, and statistics reporting via SIGHUP. Communication uses a custom binary protocol.

  • uqfaceclient: Sends image detection/replacement requests to the server and saves the response.
  • uqfacedetect: Multi-threaded server that processes requests, detects faces, and optionally replaces faces in images.

Project Structure

  • uqfaceclient.c — Client program source code
  • uqfacedetect.c — Server program source code
  • protocol.c/h — Shared protocol implementation for client/server communication
  • Makefile — Build instructions
  • spec.txt — Assignment specification (converted from PDF)
  • README.md — Project documentation

Features

  • Face detection in images using Haar cascade classifiers (OpenCV)
  • Face replacement: detected faces can be replaced with a provided image
  • Multi-threaded server: handles multiple clients simultaneously
  • Connection limiting: restricts number of concurrent clients (configurable)
  • SIGHUP statistics: server reports statistics to stderr on SIGHUP
  • Robust error handling and protocol compliance

Build Instructions

Run the following command in the project root directory:

make

This will build both uqfaceclient and uqfacedetect.

Usage

Start the Server

./uqfacedetect connectionlimit maxsize [portnumber]
  • connectionlimit: Maximum simultaneous client connections (0 for unlimited, max 10000)
  • maxsize: Maximum image size in bytes (0 for 2^32-1)
  • portnumber: Port to listen on (optional, ephemeral if omitted)

Example:

./uqfacedetect 5 10000000 2310

On startup, the server prints the actual port number to stderr.

Run the Client

./uqfaceclient port [--detectfile filename] [--output filename] [--replacefile filename]
  • port: Server port or service name for client connection
  • --detectfile: Input image file for face detection (optional, reads from stdin if omitted)
  • --replacefile: Image file to replace detected faces (optional)
  • --output: Output file for result (optional, writes to stdout if omitted)

Examples:

./uqfaceclient 2310 --detectfile input.jpg --output result.jpg
./uqfaceclient 2310 --detectfile input.jpg --replacefile face.png --output result.jpg
./uqfaceclient 2310 < input.jpg > result.jpg

Communication Protocol

Client and server communicate using a custom binary protocol:

Field Size (bytes) Description
Prefix 4 0x23107231 (little-endian)
Operation 1 0: detect, 1: replace, 2: output, 3: error
Image1 Size 4 Size of image 1 or error message
Image1 Data M Image data or error message
Image2 Size 4 (replace) Size of image 2 (only for replace)
Image2 Data N (replace) Replacement image data (only for replace)

See spec.txt for full protocol details.

Error Handling

  • Invalid command line: prints usage and exits with status 7 (server) or 12 (client)
  • File open errors: prints error and exits with status 10/18
  • Connection errors: prints error and exits with status 5/14
  • Protocol errors: prints error and exits with status 8/15
  • All error messages strictly follow the assignment specification

Dependencies

  • OpenCV 3.4.6 (server only, required for image processing)
  • gcc (recommended environment: moss.labs.eait.uq.edu.au)
  • POSIX threads and semaphores

Style & Documentation

  • Follows CSSE2310/CSSE7231 C programming style guide (see spec.txt)
  • No global variables, no functions >100 lines, no forbidden functions (see spec.txt)
  • All protocol logic is implemented in protocol.c/h
  • All memory is freed before exit

Testing

  • Test with provided demo programs (demo-uqfaceclient, demo-uqfacedetect)
  • Use netcat for protocol testing
  • SIGHUP statistics can be triggered with kill -HUP <pid>
  • See spec.txt for detailed test cases and requirements

References

  • Assignment specification: see spec.txt
  • OpenCV documentation: https://docs.opencv.org/3.4.6/
  • Example images: /local/courses/csse2310/resources/a4/testimages/ (on moss)

Contact

For questions, please contact course staff or refer to the course discussion forum.