mroi-fd-amenji 0.0.4
A small example package
Requires Python: >=3.6

## Installation

This project is developed and tested on python version `3.7.4`. Please check
your python version using `python --version`. If your system has a different
python version, you may want to consider using
[pyenv](https://github.com/pyenv/pyenv) (See [Using pyenv](#using-pyenv-linux-windows-macos))

First, clone and `cd` into the repository:

```
git clone https://gitlab.com/ailabuser/bacha_hybrid_mroi_face_detection
cd bacha_hybrid_mroi_face_detection
```

### On Windows:

Create a python virtual environment:

```
mkvirtualenv venv
```

Activate the virtual environment (`deactivate` to deactivate the virtual
environment):

```
workon venv
```

Install all the required dependencies while still having the virtual environment
active:

```
pip install -r requirements.txt
```


### On Linux:

Create a python virtual environment:

```
virtualenv -p /usr/bin/python3 venv
```

Activate the virtual environment (`deactivate` to deactivate the virtual
environment):

```
source venv/bin/activate
```

Install all the required dependencies while still having the virtual environment
active:

```
pip install -r requirements.txt
```

### Using pyenv (Linux, Windows, MacOS)

If your python version is not 3.7.4, you may want to use
[pyenv](https://github.com/pyenv/pyenv). After you have installed `pyenv`,
install the specific python version. On Linux, this can be done by running the
following command:

```
env PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.7.4
```

Then, create a virtual environment:

```
pyenv virtualenv 3.7.4 bacha_mroi_face_detection
```

You can activate the virtual environment using `pyenv` like so:

```
pyenv activate bacha_mroi_face_detection
```

## Description 

The face detection technique used hybrid margin-based region of interest (MROI)
approach. It is hybrid in the sense that the implementation runs one main
routine to detect a face, but switch to an escape routine when the main routine
fails. Using MROI increase the face detection speed by having the selected face
detection algorithm to only consider a sub-region (where a face was previously
detected) instead of the full frame.

There are three pre-defined selection of main routines available for you to use:

1. Haar cascade classifier
2. Joint cascade
3. Multi-task Convolutional Neural Network (MTCNN)

When the main routine failed to detect a face, the implementation switch to the
escape routine which runs template matching algorithm.

Furthermore, there are five possible different hybrid combinations of the face
detection approach, in addition to a non-hybrid approach using only the main
routine.

1. Normal routine only (N)
2. Normal routine with fixed-margin (FM)
3. Normal routine with dynamic-margin (DM)
4. Normal routine with escape routine (NTM)
5. Normal routine with fixed-margin and escape routine (FMTM)
6. Normal routine with dynamic-margin and escape routine (DMTM)

Three video sources are also supported:

1. Webcam
2. Kinect
3. Video files

For example to use Haar cascade classifier as the main routine using FM
approach while using image frames from your webcam, you can run the following on
Linux (while having the virtual environment active):

```
./main.py webcam haar fm
```

You can run the program without any argument to print a help message (or by
supplying it with `-h`) for more information about the usage of the program.

# Example

## Using the hybrid MROI for your face detection implementation

In order to use your face detection algorithm with the hybrid MROI face
detector, you need to create a subclass which inherit from `FaceDetector`, and
override its `detect` method. The implementation requires the`detect` method
to return either a face ROI or `None`; otherwise, the hybrid MROI face detector
may fail.

Here's an example, in which we use a [python implementation of
MTCNN](https://pypi.org/project/mtcnn/):

```python
import cv2
from mtcnn.mtcnn import MTCNN
from routines import FaceDetector

class MROI_MTCNN(FaceDetector):

    def __init__(self):

    	# The main routine face detector object used to detect faces.
        fd_obj = MTCNN()

	# Initialize using base class constructor. We pass the face detector
	# object (fd_obj) and use the MROI with fixed-margin approach with
	# a template matching escape routine.
        super().__init__(fd_obj, mode=FaceDetector.FMTM)

    @staticmethod
    def detect(fd_obj, image):

        rgb_src = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
        result = fd_obj.detect_faces(rgb_src)

        if len(result) > 0:
            return result[0]['box']
        else:
            return None
```

Internally, this was basically how the pre-defined hyrbid MROI face detectors
(i.e., `MROI_HaarCascade` and `MROI_MTCNN`) was defined. Simply import them with

```python
from routines import MROI_HaarCascade, MROI_MTCNN
```

## Running the face detector

To use the face detector, simply instantiate the hybrid MROI face detector and
run it by invoking its `run` method. Below is a simple script that runs the
face detector and feed it images in a loop.

```python
fd = MROI_MTCNN()
fd.run() # This runs the face detector in the background.

while True:
	ret, frame = cv2.VideoCapture("/path/to/video/file")

	# No more images; exit.
	if not ret:
		break

	# Feed the image into the face detector.
	fd.input_image(frame)

	# Get the ROI containing the face. This will be `None` if no face is
	# detected.
	ROI = fd.get_face_region()

	if ROI is not None:
		x, y, w, h = ROI
		cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2)

	cv2.imshow("MROI_MTCNN Face Detector", frame)

	if cv2.waitKey(1) == ord('q'):
		break
```