Luxand FaceSDK

https://github.com/luxand/facesdk-documentation
Admin
Luxand FaceSDK is a comprehensive facial recognition and analysis software development kit that...
Tokens:112,898
Snippets:728
Trust Score:7.5
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Full recognition pipeline example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/python-wrapper.md

Complete example of the recognition pipeline: activate library, initialize, set parameters, load an image, detect faces, get face templates, and finalize. Replace "your-license-key-here" with a valid license key.

```python
from fsdk import FSDK

FSDK.ActivateLibrary("your-license-key-here")
FSDK.Initialize()
FSDK.SetParameters(FaceDetectionPatchSize=256, FaceDetectionThreshold=0.64)

image = FSDK.Image("photo.jpg")
faces = image.DetectMultipleFaces()
for face in faces:
    tpl = image.GetFaceTemplate(face)
    print(face.rect, face.score)

FSDK.FreeImage(image)
FSDK.Finalize()
```

--------------------------------

### Complete workflow (Python)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-attributes.md

Python example demonstrating a complete workflow: activating the library, initializing, loading an image, detecting features, detecting attributes, and printing results. It uses the ret_dict=True option to get a dictionary of attribute confidences.

```python
from fsdk import FSDK

FSDK.ActivateLibrary("your-license-key-here")
FSDK.Initialize()

image = FSDK.LoadImageFromFile("photo.jpg")
features = image.DetectFacialFeatures()
attrs = image.DetectFacialAttributeUsingFeatures(
    features, "Gender;Age;Expression", ret_dict=True
)

gender = "Male" if attrs["Male"] > 0.5 else "Female"
print(f"Gender: {gender} (confidence: {max(attrs['Male'], attrs['Female']):.1%})")
print(f"Age: {attrs['Age']:.0f}")
print(f"Smiling: {'Yes' if attrs['Smile'] > 0.5 else 'No'} ({attrs['Smile']:.1%})")
print(f"Eyes open: {'Yes' if attrs['EyesOpen'] > 0.5 else 'No'} ({attrs['EyesOpen']:.1%})")

FSDK.FreeImage(image)
```

--------------------------------

### Python load tracker from memory with FSDK.Tracker.FromMemory

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/tracker-memory.md

Python example: get tracker memory as bytes, create a new tracker from it, and set parameters afterward. Note that parameters are not persisted in the memory buffer.

```python
memory = tracker.GetMemory()            # bytes
tracker2 = FSDK.Tracker.FromMemory(memory)
tracker2.SetParameters(RecognizeFaces=True)   # parameters are NOT persisted
```

--------------------------------

### Python query dimensions and buffer

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/image-saving.md

Python example showing how to load an image, get its dimensions, and convert to a buffer. Uses FSDK.Image and image.ToBuffer.

```python
image = FSDK.Image("photo.jpg")
w, h = image.size          # image.width, image.height
data = image.ToBuffer(FSDK.IMAGE_COLOR_24BIT)
```

--------------------------------

### Python lifecycle example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/activation-and-initialization.md

Python example showing activation, initialization, work, saving tracker memory with error handling, and finalization. Activation raises FSDK.NotActivated on failure.

```python
from fsdk import FSDK

FSDK.ActivateLibrary("your-license-key-here")   # raises FSDK.NotActivated on failure
FSDK.Initialize()
# ... work ...
try:
    tracker.SaveToFile("faces.db")
except Exception as e:
    print(f"Warning: Failed to save tracker memory: {e}")
FSDK.Finalize()
```

--------------------------------

### Usage Examples

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/image-saving.md

Examples demonstrating image saving, loading, and dimension querying using the FaceSDK library.

```APIDOC
## Usage Examples

### Save then re-load round trip (C++)
```cpp
int img1;
FSDK_ActivateLibrary("your-license-key-here");
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.bmp");  // load .bmp file
FSDK_SetJpegCompressionQuality(95);
FSDK_SaveImageToFile(img1, "test.jpg");     // save as .jpg
FSDK_FreeImage(img1);
```

### Copy pixels out with error handling (C++)
```cpp
int bufSize = 0;
if (FSDK_GetImageBufferSize(img, &bufSize, FSDK_IMAGE_COLOR_24BIT) != FSDKE_OK) {
    // handle error
    return;
}
std::vector<unsigned char> buffer(bufSize);
if (FSDK_SaveImageToBuffer(img, buffer.data(), FSDK_IMAGE_COLOR_24BIT) != FSDKE_OK) {
    // handle error
    return;
}
```

### Query dimensions (Python)
```python
image = FSDK.Image("photo.jpg")
w, h = image.size          # image.width, image.height
data = image.ToBuffer(FSDK.IMAGE_COLOR_24BIT)
```

```

--------------------------------

### Full Recognition Pipeline Example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/python-wrapper.md

Complete example of using the Python wrapper to activate, initialize, set parameters, detect faces, and extract face templates.

```APIDOC
## Full Recognition Pipeline Example

### Description
Demonstrates the complete face recognition pipeline using the Python wrapper: activation, initialization, parameter setting, face detection, and template extraction.

### Code Example
```python
from fsdk import FSDK

FSDK.ActivateLibrary("your-license-key-here")
FSDK.Initialize()
FSDK.SetParameters(FaceDetectionPatchSize=256, FaceDetectionThreshold=0.64)

image = FSDK.Image("photo.jpg")
faces = image.DetectMultipleFaces()
for face in faces:
    tpl = image.GetFaceTemplate(face)
    print(face.rect, face.score)

FSDK.FreeImage(image)
FSDK.Finalize()
```

### Notes
- `FSDK.ActivateLibrary` activates the library with a license key.
- `FSDK.Initialize` initializes the library.
- `FSDK.SetParameters` sets detection parameters.
- `FSDK.Image` loads an image.
- `image.DetectMultipleFaces` detects faces in the image.
- `image.GetFaceTemplate` extracts a face template from a detected face.
- `FSDK.FreeImage` releases the image resources.
- `FSDK.Finalize` finalizes the library.

```

--------------------------------

### C++ example loading tracker memory

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/tracker-memory.md

C++ example loading a tracker from 'faces.db'. Handles FSDKE_UNSUPPORTED_FILE_VERSION by resetting the tracker and re-enrolling. Note that parameters are reset to defaults and must be re-applied.

```cpp
HTracker tracker;
int err = FSDK_LoadTrackerMemoryFromFile(&tracker, "faces.db");
if (err == FSDKE_UNSUPPORTED_FILE_VERSION) {
    // saved with an older FaceSDK -> re-enroll from stored face images
    tracker = 0;
}
// parameters were reset to defaults - re-apply them:
FSDK_SetTrackerMultipleParameters(tracker, "RecognizeFaces=true; Threshold=0.8", &errpos);
```

--------------------------------

### FSDK_ExtractFaceImage example (C++)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-features.md

C++ example showing how to load an image, detect facial features, extract a 128x128 face image, save it, and free resources. Uses FSDK_LoadImageFromFile, FSDK_DetectFacialFeatures, FSDK_ExtractFaceImage, FSDK_SaveImageToFile, FSDK_FreeImage, and FSDK_FreeImage.

```cpp
HImage img, faceImage;
FSDK_Features features, resizedFeatures;

FSDK_LoadImageFromFile(&img, "photo.jpg");
if (FSDK_DetectFacialFeatures(img, &features) == FSDKE_OK) {
    FSDK_ExtractFaceImage(img, &features, 128, 128, &faceImage, &resizedFeatures);
    FSDK_SaveImageToFile(faceImage, "face.jpg");
    FSDK_FreeImage(faceImage);
}
FSDK_FreeImage(img);
```

--------------------------------

### Usage Example - Modern Pattern

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/dotnet-wrapper.md

Modern usage example for the FaceSDK .NET wrapper.

```APIDOC
## Usage Example - Modern Pattern

### Description
Demonstrates the modern usage pattern for the FaceSDK .NET wrapper: activation, initialization, parameter setting, face detection, and finalization.

### Steps
1. Activate the library with a license key.
2. Initialize the library.
3. Set parameters (e.g., FaceDetectionThreshold, FaceDetectionPatchSize).
4. Load an image and detect faces.
5. Iterate over detected faces and output their bounding boxes, angles, and scores.
6. Finalize the library.

### Code Example
```csharp
using Luxand;

FSDK.ActivateLibrary("your-license-key-here");
FSDK.InitializeLibrary();
FSDK.SetParameters("FaceDetectionThreshold=0.64; FaceDetectionPatchSize=256", out int errorPosition);

using (CImage image = new CImage("photo.jpg"))
{
    FSDK.TFace[] faces = image.DetectMultipleFaces(100);
    foreach (FSDK.TFace face in faces)
    {
        Console.WriteLine($"box=({face.left}, {face.top})-({face.right}, {face.bottom}), " +
                          $"angle={face.angle:F1}, score={face.score:F3}");
    }
}

FSDK.FinalizeLibrary();
```
```

--------------------------------

### Batch processing with FSDK_SetNumThreads and OpenMP

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/multicore-and-threads.md

Shows how to limit FaceSDK to half the cores and parallelize at the application level for high-throughput batch processing. The example gets the total number of threads, sets FaceSDK to use half, then processes multiple images in parallel with OpenMP.

```cpp
int totalCores;
FSDK_GetNumThreads(&totalCores);
FSDK_SetNumThreads(totalCores / 2);   // leave the rest for application threads

#pragma omp parallel for
for (int i = 0; i < imageCount; i++) {
    HImage img;
    FSDK_LoadImageFromFile(&img, filenames[i]);
    FSDK_FaceTemplate tmpl;
    if (FSDK_GetFaceTemplate(img, &tmpl) == FSDKE_OK) { /* store template */ }
    FSDK_FreeImage(img);
}
```

--------------------------------

### Python example: tracker.SaveToFile

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/tracker-memory.md

Python example that saves tracker memory to a file and catches FSDK.IOError on failure.

```python
try:
    tracker.SaveToFile("faces.db")
except FSDK.IOError as e:
    print("Warning: Failed to save tracker memory:", e)
```

--------------------------------

### FSDK_DetectFace C++ example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-detection.md

C++ example that activates the library, initializes it, loads an image, and calls FSDK_DetectFace. It prints the bounding box, angle, score, and eye coordinates on success, or a message when FSDKE_FACE_NOT_FOUND is returned. The image handle is freed with FSDK_FreeImage.

```cpp
HImage img1;
TFace Face;

FSDK_ActivateLibrary("your-license-key-here");
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.jpg");

int err = FSDK_DetectFace(img1, &Face);
if (err == FSDKE_OK) {
    printf("face at (%d,%d)-(%d,%d), angle %.1f, score %.3f\n",
        Face.bbox.p0.x, Face.bbox.p0.y, Face.bbox.p1.x, Face.bbox.p1.y,
        Face.angle, Face.score);
    printf("left eye: (%d,%d), right eye: (%d,%d)\n",
        Face.features[0].x, Face.features[0].y,
        Face.features[1].x, Face.features[1].y);
} else if (err == FSDKE_FACE_NOT_FOUND) {
    printf("No face found in the image\n");
}

FSDK_FreeImage(img1);
```

--------------------------------

### C++ camera usage example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/camera.md

Initializes capturing, lists cameras, selects the first video format, opens the first camera, grabs frames in a loop, and cleans up. Requires FSDK_InitializeCapturing() before use and FSDK_FinalizeCapturing() at the end.

```cpp
FSDK_InitializeCapturing();

wchar_t** CameraList;
int CameraCount;
if (FSDK_GetCameraList(&CameraList, &CameraCount) == FSDKE_OK) {
    for (int i = 0; i < CameraCount; i++)
        wprintf(L"camera: %s\n", CameraList[i]);
}

FSDK_VideoFormatInfo* VideoFormatList;
int VideoFormatCount;
FSDK_GetVideoFormatList(CameraList[0], &VideoFormatList, &VideoFormatCount);
if (VideoFormatCount > 0)
    FSDK_SetVideoFormat(CameraList[0], VideoFormatList[0]);

int cameraHandle;
if (FSDK_OpenVideoCamera(CameraList[0], &cameraHandle) == FSDKE_OK) {
    HImage frame;
    while (running) {
        if (FSDK_GrabFrame(cameraHandle, &frame) == FSDKE_OK) {
            // detect faces / feed to tracker ...
            FSDK_FreeImage(frame);
        }
    }
    FSDK_CloseVideoCamera(cameraHandle);
}

FSDK_FreeVideoFormatList(VideoFormatList);
FSDK_FreeCameraList(&CameraList, CameraCount);
FSDK_FinalizeCapturing();
```

--------------------------------

### Detect facial features example (Python)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-features.md

Python example that activates the library, initializes, loads an image, detects facial features, and prints the left and right eye locations. Requires a valid license key and an existing image file.

```python
from fsdk import FSDK

FSDK.ActivateLibrary("your-license-key-here")
FSDK.Initialize()
features = FSDK.Image("test.jpg").DetectFacialFeatures()
print(f"Left eye location: {features[FSDK.FSDKP_LEFT_EYE]}")
print(f"Right eye location: {features[FSDK.FSDKP_RIGHT_EYE]}")
```

--------------------------------

### Modern usage example with CImage and DetectMultipleFaces

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/dotnet-wrapper.md

Shows the modern pattern for using the FaceSDK .NET wrapper: activate and initialize the library, set parameters, load an image, detect faces, and print bounding boxes and scores. Ends with FinalizeLibrary.

```csharp
using Luxand;

FSDK.ActivateLibrary("your-license-key-here");
FSDK.InitializeLibrary();
FSDK.SetParameters("FaceDetectionThreshold=0.64; FaceDetectionPatchSize=256", out int errorPosition);

using (CImage image = new CImage("photo.jpg"))
{
    FSDK.TFace[] faces = image.DetectMultipleFaces(100);   // trimmed to faces found
    foreach (FSDK.TFace face in faces)
    {
        Console.WriteLine($"box=({face.left}, {face.top})-({face.right}, {face.bottom}), " +
                          $"angle={face.angle:F1}, score={face.score:F3}");
    }
}

FSDK.FinalizeLibrary();
```

--------------------------------

### Python camera usage example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/camera.md

Initializes capturing, lists camera names, selects the first video format, opens the first camera, grabs a frame, and cleans up. Raises RuntimeError if no cameras are found.

```python
FSDK.InitializeCapturing()
camera_names = FSDK.ListCameraNames()
if not camera_names:
    raise RuntimeError("No cameras found")

formats = FSDK.ListVideoFormats(camera_names[0])
if formats:
    FSDK.SetVideoFormat(camera_names[0], formats[0])

camera = FSDK.OpenVideoCamera(camera_names[0])
# ...
frame = camera.GrabFrame()          # new Image each call
FSDK.FreeImage(frame)
camera.Close()
FSDK.FinalizeCapturing()
```

--------------------------------

### Detect facial features example (C++)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-features.md

C++ example that activates the library, initializes, loads an image, detects facial features, and prints the left and right eye locations. Requires a valid license key and an existing image file.

```cpp
HImage img1;
FSDK_Features Features;

FSDK_ActivateLibrary("your-license-key-here");
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.jpg");
if (FSDK_DetectFacialFeatures(img1, &Features) == FSDKE_OK) {
    printf("Left eye location: (%.1f, %.1f)\n", Features[FSDKP_LEFT_EYE].x, Features[FSDKP_LEFT_EYE].y);
    printf("Right eye location: (%.1f, %.1f)\n", Features[FSDKP_RIGHT_EYE].x, Features[FSDKP_RIGHT_EYE].y);
}
FSDK_FreeImage(img1);
```

--------------------------------

### Basic lifecycle C++ example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/activation-and-initialization.md

Shows the minimal C++ lifecycle: activate, initialize, work, then finalize. Activation failure prints a message and returns.

```cpp
if (FSDK_ActivateLibrary("your-license-key-here") != FSDKE_OK) {
    printf("Failed to activate FaceSDK\n");
    return;
}
FSDK_Initialize("");
// ... detection/recognition calls ...
FSDK_Finalize();
```

--------------------------------

### Python example: detect multiple faces with Image.DetectMultipleFaces

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-detection.md

Python example that loads an image, calls DetectMultipleFaces, and prints each face's rectangle and score. Returns an empty list when no faces are found (no exception). The example filters out faces with a score below 0.5 and frees the image at the end.

```python
image = FSDK.Image("test.jpg")
faces = image.DetectMultipleFaces()   # empty list if none found
for face in faces:
    if face.score < 0.5:      # filter weak detections per face
        continue
    print(f"face at {face.rect}, score {face.score:.3f}")
FSDK.FreeImage(image)
```

--------------------------------

### C++ example: detect multiple faces with FSDK_DetectMultipleFaces

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-detection.md

C++ example that loads an image, calls FSDK_DetectMultipleFaces with a fixed-size array, and prints each detected face's bounding box and score. Handles the FSDKE_FACE_NOT_FOUND error when no faces are present. The array capacity is computed with sizeof, and the image is freed at the end.

```cpp
HImage img1;
int DetectedCount;
TFace FaceArray[50];

FSDK_LoadImageFromFile(&img1, "test.jpg");
int err = FSDK_DetectMultipleFaces(img1, &DetectedCount, FaceArray,
                                   sizeof(FaceArray) / sizeof(FaceArray[0]));
if (err == FSDKE_OK) {
    for (int i = 0; i < DetectedCount; i++) {
        printf("face at (%d,%d)-(%d,%d), score %.3f\n",
            FaceArray[i].bbox.p0.x, FaceArray[i].bbox.p0.y,
            FaceArray[i].bbox.p1.x, FaceArray[i].bbox.p1.y,
            FaceArray[i].score);
    }
} else if (err == FSDKE_FACE_NOT_FOUND) {
    printf("No faces found in the image\n");
}
FSDK_FreeImage(img1);
```

--------------------------------

### C++ example using FSDK_DetectFacialFeaturesInRegion

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-features.md

C++ example that loads an image, detects multiple faces, and for each face calls FSDK_DetectFacialFeaturesInRegion to print the left and right eye coordinates. Frees the image at the end.

```cpp
int i, DetectedCount;
HImage img1;
FSDK_Features Features;
TFace FaceArray[50];

FSDK_LoadImageFromFile(&img1, "test.jpg");
FSDK_DetectMultipleFaces(img1, &DetectedCount, FaceArray,
                         sizeof(FaceArray) / sizeof(FaceArray[0]));

for (i = 0; i < DetectedCount; i++) {
    FSDK_DetectFacialFeaturesInRegion(img1, &FaceArray[i], &Features);
    printf("Left eye: (%.1f, %.1f), Right eye: (%.1f, %.1f)\n",
        Features[FSDKP_LEFT_EYE].x, Features[FSDKP_LEFT_EYE].y,
        Features[FSDKP_RIGHT_EYE].x, Features[FSDKP_RIGHT_EYE].y);
}
FSDK_FreeImage(img1);
```

--------------------------------

### FSDK_DetectFace Python example with exception handling

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-detection.md

Python example that loads an image and calls the Image.DetectFace() convenience method. It prints the face rectangle, angle, and score, and catches FSDK.FaceNotFound when no face is detected. The image is freed with FSDK.FreeImage.

```python
from fsdk import FSDK

image = FSDK.Image("test.jpg")
try:
    face = image.DetectFace()
    print(f"face at {face.rect}, angle {face.angle:.1f}, score {face.score:.3f}")
except FSDK.FaceNotFound:
    print("No face found in the image")
FSDK.FreeImage(image)
```

--------------------------------

### FSDK_GetValueConfidence example (C++)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-attributes.md

C++ example showing how to detect a facial attribute and then retrieve the confidence for specific values (Male and Female) using FSDK_GetValueConfidence.

```cpp
char AttributeValues[1024];
FSDK_DetectFacialAttributeUsingFeatures(image, features, "Gender", AttributeValues, sizeof(AttributeValues));
float ConfidenceMale = 0.0f;
float ConfidenceFemale = 0.0f;
FSDK_GetValueConfidence(AttributeValues, "Male", &ConfidenceMale);
FSDK_GetValueConfidence(AttributeValues, "Female", &ConfidenceFemale);
```

--------------------------------

### FSDK_GetFaceTemplateInRegion C++ example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-matching.md

C++ example that loads an image, detects multiple faces, and extracts a template for each detected face using FSDK_GetFaceTemplateInRegion. The template is stored or matched inside the loop. The image is freed with FSDK_FreeImage after processing.

```cpp
HImage img;
int detectedCount;
TFace faceArray[50];
FSDK_FaceTemplate faceTemplate;

FSDK_LoadImageFromFile(&img, "group.jpg");
FSDK_DetectMultipleFaces(img, &detectedCount, faceArray,
                         sizeof(faceArray) / sizeof(faceArray[0]));

for (int i = 0; i < detectedCount; i++) {
    if (FSDK_GetFaceTemplateInRegion(img, &faceArray[i], &faceTemplate) == FSDKE_OK) {
        // store or match faceTemplate
    }
}
FSDK_FreeImage(img);
```

--------------------------------

### Cleanup with error handling C++ example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/activation-and-initialization.md

Shows the required cleanup sequence with error handling: save tracker memory, free tracker, close camera, then finalize. Each step logs a warning on failure but continues.

```cpp
int err = FSDK_SaveTrackerMemoryToFile(tracker, "faces.db");
if (err != FSDKE_OK) {
    printf("Warning: Failed to save tracker memory (error %d)\n", err);
}
err = FSDK_FreeTracker(tracker);
if (err != FSDKE_OK) {
    printf("Warning: Failed to free tracker (error %d)\n", err);
}
err = FSDK_CloseVideoCamera(cameraHandle);
if (err != FSDKE_OK) {
    printf("Warning: Failed to close camera (error %d)\n", err);
}
```

--------------------------------

### FSDK_ExtractFaceImage example (Python)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-features.md

Python example using the Image class methods: load an image, detect facial features, extract a 128x128 face image, save it, and free resources. Uses FSDK.Image, DetectFacialFeatures, ExtractFaceImage, Save, and FSDK.FreeImage.

```python
image = FSDK.Image("photo.jpg")
features = image.DetectFacialFeatures()
face_image, resized = image.ExtractFaceImage(features, 128, 128)
face_image.Save("face.jpg")
FSDK.FreeImage(face_image)
FSDK.FreeImage(image)
```

--------------------------------

### Python example using DetectFacialFeatures

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-features.md

Python example that loads an image, iterates over faces from DetectMultipleFaces, and prints the left eye location using the InRegion form. Frees the image at the end.

```python
image = FSDK.Image("test.jpg")
for face in image.DetectMultipleFaces():
    features = image.DetectFacialFeatures(face)   # InRegion form
    print("Left eye location:", features[FSDK.FSDKP_LEFT_EYE])
FSDK.FreeImage(image)
```

--------------------------------

### Complete workflow (Python)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-attributes.md

Complete workflow example for facial attribute detection using the Python SDK.

```APIDOC
## Complete workflow (Python)

### Description
Demonstrates a complete workflow for facial attribute detection using the Python SDK.

### Prerequisites
- Activate the library with a license key.
- Initialize the SDK.

### Steps
1. Load an image from a file.
2. Detect facial features.
3. Detect facial attributes using the features.
4. Interpret the returned attribute dictionary.
5. Free the image.

### Example
```python
from fsdk import FSDK

FSDK.ActivateLibrary("your-license-key-here")
FSDK.Initialize()

image = FSDK.LoadImageFromFile("photo.jpg")
features = image.DetectFacialFeatures()
attrs = image.DetectFacialAttributeUsingFeatures(
    features, "Gender;Age;Expression", ret_dict=True
)

gender = "Male" if attrs["Male"] > 0.5 else "Female"
print(f"Gender: {gender} (confidence: {max(attrs['Male'], attrs['Female']):.1%})")
print(f"Age: {attrs['Age']:.0f}")
print(f"Smiling: {'Yes' if attrs['Smile'] > 0.5 else 'No'} ({attrs['Smile']:.1%})")
print(f"Eyes open: {'Yes' if attrs['EyesOpen'] > 0.5 else 'No'} ({attrs['EyesOpen']:.1%})")

FSDK.FreeImage(image)
```
```

--------------------------------

### FSDK_SaveImageToFile - Python example

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/image-saving.md

Python example that loads a BMP file and saves it as a JPEG with a specified quality. The quality parameter is optional; if omitted, the default or previously set value is used.

```python
img = FSDK.Image("test.bmp")            # load .bmp file
img.SaveToFile("test.jpg", quality=50)  # save as .jpg with quality 50
```

--------------------------------

### C++ save then re-load round trip

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/image-saving.md

C++ example showing how to load a BMP, set JPEG quality, save as JPG, and free the image. Requires a valid license key and initialization.

```cpp
int img1;
FSDK_ActivateLibrary("your-license-key-here");
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.bmp");  // load .bmp file
FSDK_SetJpegCompressionQuality(95);
FSDK_SaveImageToFile(img1, "test.jpg");     // save as .jpg
FSDK_FreeImage(img1);
```

--------------------------------

### FSDK_SetParameters usage example in Python

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/configuration.md

Sets FaceDetectionThreshold and FaceDetectionPatchSize using keyword arguments in Python.

```python
FSDK.SetParameters(FaceDetectionThreshold=0.64, FaceDetectionPatchSize=640)
```

--------------------------------

### Compact Python example using tracker.FeedFrame, GetAllNames, and SetName

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/tracker-identifiers.md

Iterates over face IDs from a frame, retrieves all names (handles similar IDs), prints them if any, and tags the subject with a name.

```python
for face_id in tracker.FeedFrame(0, frame):
    names = tracker.GetAllNames(face_id)      # List[str], handles similar IDs
    if names:
        print("recognized:", "; ".join(names))
    tracker.SetName(face_id, "Alice")          # tag the subject
```

--------------------------------

### FSDK_MatchFaces

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-matching.md

Documentation for the FSDK_MatchFaces function, including signatures, parameters, return values, and usage examples in C++ and Python.

```APIDOC
## FSDK_MatchFaces

### Description
Matches two face templates and returns their similarity (0..1; higher = more likely the same person).

### Method
Function call

### Endpoint
FSDK_MatchFaces (C/C++), FSDK.MatchFaces (C#/Python), FaceTemplate.MatchFaces (Python)

### Parameters
- **FaceTemplate1** (const FSDK_FaceTemplate* / byte[] / FaceTemplate) - Required - First template.
- **FaceTemplate2** (const FSDK_FaceTemplate* / byte[] / FaceTemplate) - Required - Second template.
- **Similarity** (float* out) - Required - Receives the similarity of the two templates. (C/C++ only)

### Return
- C/C++: int - FSDKE_OK on success; FSDKE_INVALID_TEMPLATE if any template is in an invalid format; FSDKE_UNSUPPORTED_TEMPLATE_VERSION if any template was created with an unsupported FaceSDK version.
- Python: float - the similarity value.

### Request Example (C++)
```cpp
const float MATCHING_THRESHOLD = 0.65f;

float similarity;
err = FSDK_MatchFaces(&enrolledTemplate, &probeTemplate, &similarity);
if (err != FSDKE_OK) {
    if (err == FSDKE_INVALID_TEMPLATE)
        printf("Error: invalid face template\n");
    else if (err == FSDKE_UNSUPPORTED_TEMPLATE_VERSION)
        printf("Error: template version mismatch\n");
    return;
}
if (similarity >= MATCHING_THRESHOLD) {
    printf("MATCH: Same person (similarity=%.4f)\n", similarity);
} else {
    printf("NO MATCH: Different person (similarity=%.4f)\n", similarity);
}
```

### Request Example (Python)
```python
MATCHING_THRESHOLD = 0.60

img1 = FSDK.Image("enrolled.jpg")
template1 = img1.GetFaceTemplate()
img2 = FSDK.Image("probe.jpg")
template2 = img2.GetFaceTemplate()

similarity = FSDK.MatchFaces(template1, template2)
print("VERIFIED" if similarity >= MATCHING_THRESHOLD else "REJECTED",
      f"similarity={similarity:.4f}")

FSDK.FreeImage(img1)
FSDK.FreeImage(img2)
```
```

--------------------------------

### FSDK_GetFaceTemplate example (C++)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-matching.md

Extracts a face template from an image and checks for errors. On failure, prints an error message and returns.

```cpp
FSDK_FaceTemplate tmpl;
int err = FSDK_GetFaceTemplate(img, &tmpl);
if (err != FSDKE_OK) {
    printf("Error: could not extract template (error %d)\n", err);
    return;
}
// store tmpl.ftemplate (1040 bytes) in a database
```

--------------------------------

### FSDK_LoadTrackerMemoryFromFile

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/tracker-memory.md

Documentation for the FSDK_LoadTrackerMemoryFromFile function, including signatures, parameters, return values, and a C++ example.

```APIDOC
## FSDK_LoadTrackerMemoryFromFile

### Description
Loads the memory of a tracker from a file, creating a new tracker handle.

### Method
Function call

### Signature
C++: `int FSDK_LoadTrackerMemoryFromFile(HTracker * Tracker, const char * FileName);`

C#: `int FSDK.LoadTrackerMemoryFromFile(ref int Tracker, string FileName);`

Python: `def FSDK.LoadTrackerMemoryFromFile(fileName: str) -> Tracker;`

Python static method: `@staticmethod def Tracker.FromFile(fileName: str) -> Tracker;`

### Parameters
- **Tracker** (`HTracker*` out) - Required - Receives the handle of the loaded tracker.
- **FileName** (`const char*`) - Required - File from which to load.

### Return Value
- `int` - `FSDKE_OK`; `FSDKE_BAD_FILE_FORMAT` (unsupported format); `FSDKE_UNSUPPORTED_FILE_VERSION` (saved by an unsupported FaceSDK version); `FSDKE_FILE_NOT_FOUND` (error opening the file); `FSDKE_IO_ERROR`. Python returns a new `Tracker`; raises `FSDK.IOError`, `FSDK.BadFileFormat`, `FSDK.UnsupportedFileVersion`, `FSDK.FileNotFound`.

### Example (C++)
```cpp
HTracker tracker;
int err = FSDK_LoadTrackerMemoryFromFile(&tracker, "faces.db");
if (err == FSDKE_UNSUPPORTED_FILE_VERSION) {
    // saved with an older FaceSDK -> re-enroll from stored face images
    tracker = 0;
}
// parameters were reset to defaults - re-apply them:
FSDK_SetTrackerMultipleParameters(tracker, "RecognizeFaces=true; Threshold=0.8", &errpos);
```
```

--------------------------------

### C++ example: detect Gender, Age, Expression

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-attributes.md

Loads an image, detects a face, and calls FSDK_DetectFacialAttributeUsingFace with multiple attributes separated by semicolons. Prints the resulting attribute string. Frees the image afterward.

```cpp
HImage image;
TFace face;
char attrValues[1024];

FSDK_LoadImageFromFile(&image, "photo.jpg");
if (FSDK_DetectFace(image, &face) == FSDKE_OK) {
    FSDK_DetectFacialAttributeUsingFace(image, &face, "Gender;Age;Expression",
                                        attrValues, sizeof(attrValues));
    printf("%s\n", attrValues);
}
FSDK_FreeImage(image);
```

--------------------------------

### C++ copy pixels out with error handling

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/image-saving.md

C++ example showing how to get the buffer size and save image to buffer with error checking. Uses FSDK_GetImageBufferSize and FSDK_SaveImageToBuffer.

```cpp
int bufSize = 0;
if (FSDK_GetImageBufferSize(img, &bufSize, FSDK_IMAGE_COLOR_24BIT) != FSDKE_OK) {
    // handle error
    return;
}
std::vector<unsigned char> buffer(bufSize);
if (FSDK_SaveImageToBuffer(img, buffer.data(), FSDK_IMAGE_COLOR_24BIT) != FSDKE_OK) {
    // handle error
    return;
}
```

--------------------------------

### Python example: detect attributes with ret_dict

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/facial-attributes.md

Loads an image, iterates over detected faces, and calls DetectFacialAttributeUsingFace with ret_dict=True to get a dictionary of attribute values. Prints the result and frees the image.

```python
image = FSDK.Image("photo.jpg")
for face in image.DetectMultipleFaces():
    attrs = image.DetectFacialAttributeUsingFace(face, "Gender;Age", ret_dict=True)
    print(attrs)   # e.g. {'Male': 0.957, 'Female': 0.043, 'Age': 37.0}
FSDK.FreeImage(image)
```

--------------------------------

### FSDK.Image constructors

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/python-wrapper.md

Shows the three constructor signatures for FSDK.Image: loading from a file, wrapping a Windows HBITMAP, and creating an empty image.

```python
Image(fileName: str) -> Image            # load from file (JPG/PNG/BMP)
Image(bitmapHandle: HBITMAP) -> Image    # Windows HBITMAP
Image() -> Image                         # empty image
```

--------------------------------

### Initialize FaceSDK and detect face features in Python

Source: https://github.com/luxand/facesdk-documentation/blob/main/README.md

Initializes the FaceSDK library with a license key, loads an image, detects a face and facial features, then frees resources and finalizes. Replace "your-license-key" with your actual key before running.

```python
import FSDK

FSDK.ActivateLibrary("your-license-key")
FSDK.Initialize()

image = FSDK.LoadImageFromFile("photo.jpg")
face = FSDK.DetectFace(image)
features = FSDK.DetectFacialFeatures(image)

FSDK.FreeImage(image)
FSDK.Finalize()
```

--------------------------------

### Camera frame loop with DetectFace

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/dotnet-wrapper.md

Initializes the camera, retrieves the camera list, opens the first camera, grabs a frame, and detects a face. The using statements ensure proper disposal of the camera and image resources.

```csharp
Camera.InitializeCapturing();
string[] cameras = Camera.GetCameraList();
using (Camera camera = new Camera(cameras[0]))    // opens the camera
using (CImage frame = camera.GrabFrame())
{
    FSDK.TFace face = frame.DetectFace();
    // process...
}
```

--------------------------------

### Basic image loading in C++

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/image-loading.md

Activates the library, initializes it, loads an image from a file, and frees the image. Every loaded image must be freed with FSDK_FreeImage.

```cpp
HImage img;
FSDK_ActivateLibrary("your-license-key-here");
FSDK_Initialize("");
int err = FSDK_LoadImageFromFile(&img, "test.jpg");
if (err != FSDKE_OK) {
    printf("Error loading image: %d\n", err);
    return;
}
// ... process image ...
FSDK_FreeImage(img);   // every loaded image must be freed
```

--------------------------------

### FSDK_InitializeCapturing signatures (C++, C#, Python)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/camera.md

Initializes the capturing process without opening a camera. On Windows, it initializes COM in the calling thread. Returns FSDKE_OK (int) in C++ and C#, and None in Python.

```cpp
int FSDK_InitializeCapturing(void);
```

```csharp
int FSDKCam.InitializeCapturing();
```

```python
def FSDK.InitializeCapturing();
```

--------------------------------

### Basic image loading in Python with error handling

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/image-loading.md

Activates the library, initializes it, loads an image from a file, and handles exceptions. The FSDK.Image constructor raises FSDK.FileNotFound or FSDK.BadFileFormat on failure.

```python
from fsdk import FSDK

FSDK.ActivateLibrary("your-license-key-here")
FSDK.Initialize()

try:
    image = FSDK.Image("photo.jpg")          # raises FSDK.FileNotFound / FSDK.BadFileFormat / ...
except FSDK.FSDK_Exception as e:
    print("Failed to load image:", e)
    quit(1)

faces = image.DetectMultipleFaces()
FSDK.FreeImage(image)
```

--------------------------------

### FSDK_OpenVideoCamera signatures (C++, C#, Python)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/camera.md

Opens the web camera of a given name and returns its handle. C++ and C# return FSDKE_OK; Python returns a new Camera object.

```cpp
int FSDK_OpenVideoCamera(wchar_t* CameraName, int* CameraHandle);
```

```csharp
int FSDKCam.OpenVideoCamera(ref string CameraName, ref int CameraHandle);
```

```python
def FSDK.OpenVideoCamera(cameraName: str) -> Camera;
```

--------------------------------

### FSDK_LoadTrackerMemoryFromBuffer

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/tracker-memory.md

Documentation for the FSDK_LoadTrackerMemoryFromBuffer function, including signatures, parameters, return values, and usage examples.

```APIDOC
## FSDK_LoadTrackerMemoryFromBuffer

### Description
Loads the tracker memory from a buffer, creating a new tracker handle.

### Method
N/A (C/C++/C#/Python function)

### Endpoint
N/A (C/C++/C#/Python function)

### Parameters
- **Tracker** (`HTracker*` out) - Required - Receives the handle of the loaded tracker.
- **Buffer** (`const unsigned char*`) - Required - Buffer from which to load.

### Request Example
```cpp
long long bufSize = 0;
FSDK_GetTrackerMemoryBufferSize(tracker, &bufSize);
std::vector<unsigned char> buffer(bufSize);
FSDK_SaveTrackerMemoryToBuffer(tracker, buffer.data(), bufSize);

// later, e.g. from a database:
HTracker newTracker;
FSDK_LoadTrackerMemoryFromBuffer(&newTracker, buffer.data());
```

### Response
#### Success Response
- **Return** (`int`) - `FSDKE_OK`; `FSDKE_BAD_FILE_FORMAT` (unsupported format); `FSDKE_UNSUPPORTED_FILE_VERSION`. Python returns a new `Tracker`.

#### Response Example
```python
memory = tracker.GetMemory()            # bytes
tracker2 = FSDK.Tracker.FromMemory(memory)
tracker2.SetParameters(RecognizeFaces=True)   # parameters are NOT persisted
```
```

--------------------------------

### FSDK.Image static factory methods

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/python-wrapper.md

Lists the static factory methods for creating FSDK.Image instances from files, files with alpha, or raw buffer data.

```python
@staticmethod Image.FromFile(fileName: str) -> Image
@staticmethod Image.FromFileWithAlpha(fileName: str) -> Image
@staticmethod Image.FromBuffer(buffer: bytes, width: int, height: int, scanLine: int, colorMode: int) -> Image
```

--------------------------------

### FSDK_InitializeCapturing

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/camera.md

Initializes the capturing process without opening a camera. On Windows, it initializes COM in the calling thread.

```APIDOC
## FSDK_InitializeCapturing

### Description
Initializes the capturing process (does not open a camera). On Windows it initializes COM in the calling thread.

### Method
N/A - This is a function call, not an HTTP endpoint.

### Endpoint
N/A - This is a function call, not an HTTP endpoint.

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **Return** (int) - `FSDKE_OK`; Python returns `None`.

#### Response Example
N/A

### Signatures
```cpp
int FSDK_InitializeCapturing(void);
```

```csharp
int FSDKCam.InitializeCapturing();
```

```python
def FSDK.InitializeCapturing();
```
```

--------------------------------

### FSDK_GetFaceTemplateInRegion

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-matching.md

Documentation for the FSDK_GetFaceTemplateInRegion function, including signatures, parameters, return value, and a C++ example.

```APIDOC
## FSDK_GetFaceTemplateInRegion

### Description
Extracts a template for a face already returned by `FSDK_DetectFace`/`FSDK_DetectMultipleFaces`. Skips the face detection stage. Returns no error if the face is not clearly visible — it assumes that a face returned by the detector is of sufficient quality.

### Signatures

**C++**
```cpp
int FSDK_GetFaceTemplateInRegion(HImage Image, const TFace* Face, FSDK_FaceTemplate* FaceTemplate);
```

**C#**
```csharp
int FSDK.GetFaceTemplateInRegion(int Image, in FSDK.TFace Face, out byte[] FaceTemplate);
byte[] Luxand.CImage.GetFaceTemplateInRegion(in FSDK.TFace Face);
```

**Python**
```python
def FSDK.GetFaceTemplateInRegion(image: Image, face: Face) -> FaceTemplate;
# Image.GetFaceTemplate(face=face) calls this form
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Image | `HImage` | yes | — | Image from which to extract the template. |
| Face | `const TFace*` | yes | — | The detected face (see [types.md](../types.md)). |
| FaceTemplate | `FSDK_FaceTemplate*` (out) | yes | — | Receives the 1040-byte template. |

### Return
`int` — `FSDKE_OK`; Python returns a `FaceTemplate`.

### Example (C++)
```cpp
HImage img;
int detectedCount;
TFace faceArray[50];
FSDK_FaceTemplate faceTemplate;

FSDK_LoadImageFromFile(&img, "group.jpg");
FSDK_DetectMultipleFaces(img, &detectedCount, faceArray,
                         sizeof(faceArray) / sizeof(faceArray[0]));

for (int i = 0; i < detectedCount; i++) {
    if (FSDK_GetFaceTemplateInRegion(img, &faceArray[i], &faceTemplate) == FSDKE_OK) {
        // store or match faceTemplate
    }
}
FSDK_FreeImage(img);
```
```

--------------------------------

### Get face template as byte array

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/dotnet-wrapper.md

Retrieve a face template as a byte array of FSDK.TemplateSize (1040) bytes using FSDK.GetFaceTemplate.

```csharp
byte[] templateData;
FSDK.GetFaceTemplate(imageHandle, out templateData);
```

--------------------------------

### FSDK_OpenIPVideoCamera

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/camera.md

Opens an IP camera at the given URL and returns a handle to the opened camera. Set an HTTP proxy first with FSDK_SetHTTPProxy if needed.

```APIDOC
## FSDK_OpenIPVideoCamera

### Description
Opens the IP camera at a given URL and returns its handle. Set an HTTP proxy first with `FSDK_SetHTTPProxy` if needed.

### Method
Function call

### Endpoint
FSDK_OpenIPVideoCamera

### Parameters
#### Path Parameters
- **CompressionType** (FSDK_VIDEOCOMPRESSIONTYPE) - Required - Type of video stream (the enum currently only defines `FSDK_MJPEG`).
- **URL** (char*) - Required - URL of the IP camera to open.
- **Username** (char*) - Required - IP camera access username.
- **Password** (char*) - Required - IP camera access password.
- **TimeoutSeconds** (int) - Required - Connection timeout in seconds.
- **CameraHandle** (int*) - Required - Receives the opened camera handle.

### Request Example
```cpp
int FSDK_OpenIPVideoCamera(FSDK_VIDEOCOMPRESSIONTYPE CompressionType, char * URL, char * Username, char * Password, int TimeoutSeconds, int * CameraHandle);
```

### Response
#### Success Response
- **Return** (int) - `FSDKE_OK`; Python returns a new `Camera` object.

#### Response Example
```
FSDKE_OK
```
```

--------------------------------

### FSDK_SetParameters usage example in C++

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/configuration.md

Sets FaceDetectionThreshold and FaceDetectionPatchSize in C++. The error position variable is passed to receive syntax error position.

```cpp
int err = 0;
FSDK_SetParameters("FaceDetectionThreshold=0.64; FaceDetectionPatchSize=640", &err);
```

--------------------------------

### FSDK.InitializeLibrary

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/dotnet-wrapper.md

Initializes the FaceSDK library. Must be called before using other functions.

```APIDOC
## FSDK.InitializeLibrary

### Description
Initializes the FaceSDK library.

### Method
FSDK.InitializeLibrary

### Signature
int FSDK.InitializeLibrary()

### Returns
- **int** - Result code (FSDKE_OK on success).
```

--------------------------------

### FSDK_GetFaceTemplate example with error handling (Python)

Source: https://github.com/luxand/facesdk-documentation/blob/main/_autodocs/api-reference/face-matching.md

Extracts a face template from an enrolled image, catching the FaceNotFound exception. Prints an error and exits if no face is detected.

```python
img = FSDK.Image("enrolled.jpg")
try:
    template = img.GetFaceTemplate()          # raises FSDK.FaceNotFound
except FSDK.FaceNotFound:
    print("Error: no face detected in enrolled image")
    FSDK.FreeImage(img)
    exit(1)
```
Tokens:
Raw