Quick start

Before you start

This SDK documentation uses generic naming conventions for clarity across multiple languages and platforms. Please adapt to your language with the following conventions:

Python

This SDK complies with the PEP 8 recommendations.

• Class, struct and enumeration names are written in PascalCase. Ex: FaceLicense.activate_buffer

• Class and struct member names are written in snake_case. Ex: Point.x

• Enumeration fields are written in UPPER_CASE_WITH_UNDERSCORE. Ex: LicenseError.INVALID_LICENSE

Dart

• Class, struct and enumeration names are written in PascalCase. Ex: FaceLicense.activateBuffer

• Class and struct member names are written in lowerCamelCase. Ex: Point.x

• Enumeration fields are written in lowerCamelCase. Ex: LicenseError.invalidLicense

C#

• Class, struct and enumeration names are written in PascalCase. Ex: FaceLicense.ActivateBuffer

• Class and struct member names are written in PascalCase. Ex: Point.X

• Enumeration fields are written in PascalCase. Ex: LicenseError.InvalidLicense

Java

• Class, struct and enumeration names are written in PascalCase. Ex: FaceLicense.activateBuffer

• Class and struct member names are written in lowerCamelCase. Ex: Point.x

• Enumeration fields are written in UPPER_CASE_WITH_UNDERSCORE. Ex: LicenseError.INVALID_LICENSE

Kotlin

• Class, struct and enumeration names are written in PascalCase. Ex: FaceLicense.activateBuffer

• Class and struct member names are written in lowerCamelCase. Ex: Point.x

• Enumeration fields are written in UPPER_CASE_WITH_UNDERSCORE. Ex: LicenseError.INVALID_LICENSE

Swift

• Class, struct and enumeration names are written in PascalCase. Ex: FaceLicense.activateBuffer

• Class and struct member names are written in lowerCamelCase. Ex: Point.x

• Enumeration fields are written in lowerCamelCase. Ex: LicenseError.invalidLicense

C++

• Class are written in PascalCase. Ex: FaceLicense.activateBuffer

• Class member functions are written in lowerCamelCase.

• For enumerations and structures, refer to the C language..

C

id3FaceLicense_ActivateBuffer
id3FacePoint.X
id3FaceLicenseError_InvalidLicense

Note

The C API implements pseudo object-oriented programming concepts where the object is passed explicitly to a member function as first parameter.

Initialization

1) Load & check your license file. See Load and check the license. On Android and IOS, please activate a license instead (see Activating a license in your app (Android/iOS))

2) Load all the necessary AI models. We recommend loading them in the app initialization, and it’s unnecessary to unload them.

Static classes (e.g. FaceLibrary, FaceLicense) provide static utility functions with global effect on the SDK.

import id3face as id3

try:
    id3.FaceLicense.check_license("path_to_license_file.lic")
    id3.FaceLibrary.load_model("model_directory", id3.FaceModel.FACE_DETECTOR_4B, id3.ProcessingUnit.CPU)
    id3.FaceLibrary.load_model("model_directory", id3.FaceModel.FACE_ENCODER_9B, id3.ProcessingUnit.CPU)
except id3.FaceException as ex:
    print(ex.message)

3) Instantiate computation modules

Computation classes (e.g., FaceDetector, FaceEncoder, FaceMatcher) handle AI models and their underlying memory and computation resources. These classes are resource-intensive and should be instantiated once during initialization (or a limited number of times if needed for specific use cases), then reused throughout your application lifecycle. Avoid creating them repeatedly for each operation.

face_detector = id3.FaceDetector(thread_count=2, confidence_threshold=50)
face_encoder  = id3.FaceEncoder()
face_matcher  = id3.FaceMatcher()

Call the computation modules

POD-like classes (Plain Old Data, e.g., DetectedFace, FaceTemplate, Portrait) contain business data and associated methods. These lightweight classes represent the actual biometric data you work with and can be created as needed for each computation without performance concerns.

1) Transform your input image into SDK object

According to your need, you can ingest data from disk files, from image-formats encoded buffer, from raw pixels buffers, from YUV planes. In python, you can also input a numpy array. See Image Class for method details. Computation modules require the pixels to be loaded in a certain format. For most modules, it is bgr24Bits.

2) Process/check the input Low-level computation modules often require some preprocessing steps or checks before computing the results (resizing, IOD checks, etc). Follow our detailed tutorials in order to provide adequate data to each module of the Toolkit.

3) Call the computation functions, and retrieve the results

def my_process_function(face_detector: id3.FaceDetector, img_buffer: bytearray) -> id3.DetectedFace:
    
    # Load image from a JPG/PNG/etc buffer
    id3_image = id3.Image.from_buffer(img_buffer, id3.PixelFormat.BGR_24_BITS)

    # Preprocess image if needed
    ratio = id3_image.downscale(384)

    # Computation
    detected_face_list = face_detector.detect_faces(id3_image)

    print(f"Number of detected faces: {len(detected_face_list)}")
    
    # Retrieve and post-process results
    main_face = detected_face_list.get_largest_face()
    main_face.rescale(1/ratio)

    return main_face

Use high-level computation modules

For complex processes, including realtime tracking with quality checks, liveness, identification, we provide the high-level computation modules PortraitProcessor.

For more details, see the full tutorial Portrait processing