Get started

Install the SDK with one command, then use the Python example below to detect faces in an image and save the annotated result.

Install Python dependencies

python -m pip install inspireface opencv-python

The current PyPI package is 1.2.4.post3 and includes the 1.2.4 CPU SDK for Windows x64, Linux x86_64 / ARM64 and macOS Intel / Apple Silicon. For an existing installation, use python -m pip install --upgrade inspireface. Platform packages and requirements are listed in the Python guide.

Detect faces in an image

Save this as first_face.py and place a face image named face.jpg beside it:

import cv2
import inspireface as isf

image = cv2.imread("face.jpg")
if image is None:
    raise FileNotFoundError("Cannot read face.jpg")

# The first call may download the Pikachu resource pack.
isf.launch("Pikachu")
session = None
try:
    session = isf.InspireFaceSession(
        isf.HF_ENABLE_NONE,
        isf.HF_DETECT_MODE_ALWAYS_DETECT,
        max_detect_num=10,
        detect_pixel_level=320,
    )
    faces = session.face_detection(image)
    print(f"Detected {len(faces)} faces")
    for face in faces:
        x1, y1, x2, y2 = face.location
        cv2.rectangle(image, (x1, y1), (x2, y2), (60, 170, 80), 2)
    if not cv2.imwrite("detected.jpg", image):
        raise RuntimeError("Could not write detected.jpg")
finally:
    if session is not None:
        session.release()
    isf.terminate()

Run it:

python first_face.py

Open detected.jpg to see the boxes. If no faces meet the detection settings, the script prints Detected 0 faces. Try a clear, upright face first. If a face is small in the original image, a larger supported detector level can help, at the cost of more work per frame.

Use a model you already downloaded

For an offline application, pass the path to the downloaded resource-pack file:

isf.launch(resource_path="/path/to/Pikachu")

On Windows, forward slashes also work, for example isf.launch(resource_path="C:/models/Pikachu").

Resource packs may have no file extension. If you downloaded a ZIP archive, extract it first and pass the pack file to launch. Deploy the resource pack and SDK as a tested pair.

To pass image, model and output paths on the command line, save the complete program below as detect.py:

"""Detect faces in one image and save an annotated copy."""
import argparse
from pathlib import Path

import cv2
import inspireface as isf


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("image", type=Path)
    parser.add_argument("--model", type=Path, help="Path to an unpacked resource pack")
    parser.add_argument("--output", type=Path, default=Path("detected.jpg"))
    args = parser.parse_args()

    image = cv2.imread(str(args.image))
    if image is None:
        parser.error(f"Cannot read image: {args.image}")
    if args.model is None:
        isf.launch("Pikachu")  # Downloads the model on first use.
    else:
        isf.launch(resource_path=str(args.model))

    session = None
    try:
        session = isf.InspireFaceSession(
            isf.HF_ENABLE_NONE, isf.HF_DETECT_MODE_ALWAYS_DETECT,
            max_detect_num=10, detect_pixel_level=320,
        )
        faces = session.face_detection(image)
        print(f"Detected {len(faces)} faces")
        output = image.copy()
        for face in faces:
            x1, y1, x2, y2 = face.location
            cv2.rectangle(output, (x1, y1), (x2, y2), (60, 170, 80), 2)
            print(face.location, face.detection_confidence)
        if not cv2.imwrite(str(args.output), output):
            raise RuntimeError(f"Cannot write image: {args.output}")
        print(f"Saved {args.output}")
    finally:
        if session is not None:
            session.release()
        isf.terminate()


if __name__ == "__main__":
    main()

Run it:

python detect.py face.jpg --model /path/to/Pikachu --output detected.jpg

What the example sets up

Keep the session alive across frames in a real application. Creating a new session for every image repeats model setup and loses tracking history.

Continue from here

• Python: run optional analysis, handle raw image streams and manage resources.
• Java: load the SDK on a regular JVM and run a complete image-detection program.
• C API: compile a complete native example without OpenCV.
• Objective-C and Swift: build an Apple app with the iOS or macOS frameworks.
• Tracking: use a video sequence and tune detection work.
• Recognition: compare two faces and add a gallery.
• Troubleshooting: diagnose model, library and image-format problems.