insightface/cpp-package/inspireface/python/README.md

# InspireFace Python API

We provide a Python API for calling InspireFace, which is implemented by wrapping the dynamic link library using ctypes. You can install the latest release version on your computer via pip from PyPI, or you can configure it using a self-compiled dynamic library with this project.

## Quick Install

For Python users on Linux and MacOS, InspireFace can be quickly installed via pip:

```bash
pip install inspireface
```


## Setup Library

#### Copy the compiled dynamic library

You need to compile the dynamic linking library in the main project and then place it in **inspireface/modules/core/SYSTEM/CORE_ARCH/**.

```Bash
# copy or link
cp YOUR_BUILD_DIR/libInspireFace.so inspireface/modules/core/SYSTEM/CORE_ARCH/
```

#### Install

Run the command to install: 

```
python setup.py install
```

## Require

You need to install some dependencies beforehand.

```Bash
pip install loguru
pip install tqdm
pip install opencv-python
```

## Simple example

You can easily call the api to implement a number of functions:

```Python
import cv2
import inspireface as isf

# Optional features, loaded during session creation based on the modules specified.
opt = isf.HF_ENABLE_NONE
session = isf.InspireFaceSession(opt, isf.HF_DETECT_MODE_ALWAYS_DETECT)
# Set detection confidence threshold
session.set_detection_confidence_threshold(0.5)

# Load the image using OpenCV.
image = cv2.imread(image_path)
assert image is not None, "Please check that the image path is correct."

# Perform face detection on the image.
faces = session.face_detection(image)
print(f"face detection: {len(faces)} found")

# Copy the image for drawing the bounding boxes.
draw = image.copy()
for idx, face in enumerate(faces):
    print(f"{'==' * 20}")
    print(f"idx: {idx}")
    print(f"detection confidence: {face.detection_confidence}")
    # Print Euler angles of the face.
    print(f"roll: {face.roll}, yaw: {face.yaw}, pitch: {face.pitch}")

    # Get face bounding box
    x1, y1, x2, y2 = face.location

    # Calculate center, size, and angle
    center = ((x1 + x2) / 2, (y1 + y2) / 2)
    size = (x2 - x1, y2 - y1)
    angle = face.roll

    # Apply rotation to the bounding box corners
    rect = ((center[0], center[1]), (size[0], size[1]), angle)
    box = cv2.boxPoints(rect)
    box = box.astype(int)

    # Draw the rotated bounding box
    cv2.drawContours(draw, [box], 0, (100, 180, 29), 2)

    # Draw landmarks
    lmk = session.get_face_dense_landmark(face)
    for x, y in lmk.astype(int):
        cv2.circle(draw, (x, y), 0, (220, 100, 0), 2)
```


You can also check out other sample files, which contain more diverse examples of functionality.

## Test


In the Python API, we have integrated a relatively simple unit test. You can adjust the content of the unit test by modifying the parameters in the configuration file **test/test_settings.py**.

```Bash
# Run total test
python -m unittest discover -s test
```