Upgrade Guide: SFE Toolkit 3.x to 4.0
FFI Changes (C API)
Detection API
Before (3.x):
SFEFaceDetect faces[10];
size_t count = 10;
sfeFaceDetect(solver, image, 0.5f, faces, &count);
std::optional< std::string > solver
After (4.0):
SFEDetection detections[10];
size_t count = 10;
sfeDetect(solver, image, 0.5f, detections, &count);
// Check modality: detections[i].modality == SFE_MODALITY_FACE
Type Renames
| 3.x | 4.0 |
|---|---|
SFEBbox | SFEBoundingBox |
SFEOrientedBbox | SFEOrientedBoundingBox |
SFELicenseSource | SFELicenseType |
SFE_LICENSE_SOURCE_* | SFE_LICENSE_TYPE_* |
SFEFaceDetect | SFEDetection |
SFEIrisDetect | SFEDetection |
SFEPalmDetect | SFEDetection |
SFEObjectDetect | SFEDetection |
SFETattooDetection | SFEDetection |
SFEFaceDetectAccuracyType | SFEFaceDetectionAccuracyType |
Function Renames
| 3.x | 4.0 |
|---|---|
sfeImageLoad() | sfeImageDecode() |
sfeImageSave() | sfeImageEncode() |
sfeSolverCreateWithParameters() | sfeSolverCreate() |
sfeFaceDetect() | sfeDetect() |
sfeIrisDetect() | sfeDetect() |
sfePalmDetect() | sfeDetect() |
sfeObjectDetect() | sfeDetect() |
sfeTattooDetect() | sfeDetect() |
Signature Changes
License Validation
// 3.x
SFELicenseSource source;
sfeLicenseValidate(&source);
// 4.0
sfeLicenseValidate();
SFELicenseType type;
sfeLicenseType(&type);
SFELicenseType
Image Info
// 3.x
size_t width, height;
SFEImageFormat format;
sfeImageInfo(data, len, &width, &height, &format);
// 4.0
SFEImageInfo info;
sfeImageInfo(data, len, &info);
// Access: info.width, info.height, info.format
SFEImageFormat
Image Color Transpose
// 3.x (in-place)
sfeImageColorTranspose(image);
// 4.0 (returns new image)
SFEImage transposed;
sfeImageColorTranspose(image, &transposed);
Face Landmarks
// 3.x
sfeFaceLandmarks(solver, image, bbox, landmarks);
// 4.0
sfeFaceLandmarks(solver, image, &detection, landmarks);
Face Template Extract
// 3.x
sfeFaceTemplateExtract(solver, image, landmarks, &tmpl);
// 4.0
sfeFaceTemplateExtract(solver, image, &detection, landmarks, &tmpl);
Face Liveness
// 3.x
float score;
sfeFaceLivenessPassive(solver, image, landmarks, &score);
// 4.0
SFEFaceLiveness liveness;
sfeFaceLivenessPassive(solver, image, landmarks, &liveness);
// Access: liveness.score
Face Crop
// 3.x
sfeFaceCrop(image, landmarks, (uint32_t)extension, max_size, &crop);
// 4.0
sfeFaceCrop(image, landmarks, (float)extension, max_size, &crop);
Palm API Changes
New intermediate step with SFEPalmLandmarks:
// 3.x
sfePalmTemplateExtract(solver, image, &palm_detect, &tmpl);
sfePalmAttributes(solver, image, &palm_detect, &attrs);
// 4.0
SFEPalmLandmarks landmarks;
sfePalmLandmarks(solver, image, &detection, &landmarks);
sfePalmTemplateExtract(solver, image, &landmarks, &tmpl);
sfePalmAttributes(solver, image, &landmarks, &attrs);
Palm landmarks (keypoints, hand position, orientation, confidence)
Tracker API
// 3.x
SFEFaceTracker tracker;
sfeFaceTrackerCreate(0.5f, 0.6f, 0.3f, 30, &tracker);
sfeFaceTrackerUpdate(tracker, faces, count, tracked, &tracked_count);
sfeFaceTrackerFree(tracker);
// 4.0
SFETracker tracker;
sfeDetectionTrackerCreate(0.5f, 0.6f, 0.4f, 0.3f, 30, &tracker); // 5 params now
sfeDetectionTrackerUpdate(tracker, detections, count, tracked, &tracked_count);
sfeDetectionTrackerFree(tracker);
void * SFETracker
Removed Type Aliases
Replace deprecated aliases with unified types:
| Deprecated | Use Instead |
|---|---|
SFEFaceEntity, SFEIrisEntity, etc. | SFEEntity |
SFEIdentificationResult | SFETemplateIdentificationCandidate |
SFEFaceTemplateIdentificationCandidate | SFETemplateIdentificationCandidate |
SFEFaceEntityIdentificationCandidate | SFEEntityIdentificationCandidate |
SFEPalmQualityAttributes | SFEPalmAttributes |
UniFFI Changes (Python, Kotlin, Swift, .NET)
Detection API
Python:
# 3.x
from sfe_toolkit import sfe_face
detections = sfe_face.detect(solver, image, threshold)
# 4.0
from sfe_toolkit import sfe_core
detections = sfe_core.detect(solver, image, threshold)
# detections[i].modality indicates type
Kotlin:
// 3.x
val detections = Face.detect(solver, image, threshold)
// 4.0
val detections = Core.detect(solver, image, threshold)
Swift:
// 3.x
let detections = SFEToolkitFace.detect(solver: solver, image: image, threshold: threshold)
// 4.0
let detections = SFEToolkitCore.detect(solver: solver, image: image, threshold: threshold)
Type Renames
| 3.x | 4.0 |
|---|---|
Bbox | BoundingBox |
OrientedBbox | OrientedBoundingBox |
LicenseSource | LicenseType |
FaceDetect, IrisDetect, etc. | Detection |
Function Renames
| 3.x | 4.0 |
|---|---|
image_load() | image_decode() |
image_save() | image_encode() |
face.detect() | core.detect() |
iris.detect() | core.detect() |
palm.detect() | core.detect() |
Palm API
# 3.x
template = sfe_palm.extract(solver, image, detection)
attributes = sfe_palm.attributes(solver, image, detection)
# 4.0
landmarks = sfe_palm.landmarks(solver, image, detection)
template = sfe_palm.extract(solver, image, landmarks)
attributes = sfe_palm.attributes(solver, image, landmarks)
Tracker API
# 3.x
tracker = sfe_face.tracker_create(0.5, 0.6, 0.3, 30)
# 4.0
tracker = sfe_core.tracker_create(0.5, 0.6, 0.4, 0.3, 30) # new_track_thresh added
Face Liveness
# 3.x
score = sfe_face.liveness_passive(solver, image, landmarks)
# 4.0
result = sfe_face.liveness_passive(solver, image, landmarks)
score = result.score
Entity Identification Result
EntityIdentificationCandidate now includes an index field:
# 4.0
for candidate in candidates:
print(candidate.score, candidate.entity, candidate.index)