Migration guide

Overview

Here you can find information about important changes in the next releases of LUNA SDK.

v.5.20.0

ILivenessFlowEstimator

Since v.5.20.0 the ILivenessFlowEstimator estimator has been removed.

v.5.19.0

ILivenessFlowEstimator

Since v.5.19.0 the ILivenessFlowEstimator estimator has been deprecated. If you still need this estimator, please, contact VisionLabs for details.

v.5.18.0

IChildEstimator

Since v.5.18.0 the IChildEstimator estimator has been removed. Use the IAttributeEstimator (See IAttributeEstimator.h) with IAttributeEstimator::EstimationRequest::estimateAge instead.

IHeadAndShouldersLivenessEstimator

Since v.5.18.0 the IHeadAndShouldersLivenessEstimator estimator has been removed. If you still need this estimator, please, contact VisionLabs for details.

v.5.17.0

IHeadAndShouldersLivenessEstimator

Since v.5.17.0 the estimator IHeadAndShouldersLivenessEstimator has been deprecated (See IHeadAndShouldersLivenessEstimator.h). If you need this estimator, please, contact VisionLabs for details.

IChildEstimator

Since v.5.17.0 the estimator IChildEstimator has been deprecated (See IChildEstimator.h). Use the IAttributeEstimator (See IAttributeEstimator.h) with IAttributeEstimator::EstimationRequest::estimateAge instead.

Example of code (before version v.5.17.0):

    // Create child estimator.
    auto resChildEstimator = faceEngine->createChildEstimator();
    if(!resChildEstimator) {
        std::cerr << "Failed to create child estimator instance. Reason: " << resChildEstimator.what();
        std::cerr << std::endl;
        return -1;
    }
    fsdk::IChildEstimatorPtr childEstimator = resChildEstimator.getValue();

    // Get child estimation.
    fsdk::ChildEstimation childEstimation;
    fsdk::Result<fsdk::FSDKError> childEstimationResult = childEstimator->estimate(warp, childEstimation);
    if(childEstimationResult.isOk()) {
        std::cout << "\nChild estimate:";
        std::cout << "\nchildScore: " << childEstimation.childScore << " (range [0, 1])";
        std::cout << "\nis child: " << childEstimation.isChild << " (1 - is child, 0 - is adult)";
        std::cout << std::endl;
    } else {
        std::cerr << "Failed child estimation. Reason: " << childEstimationResult.what() << std::endl;
    }

Example of code (from version v.5.17.0):

    // Create attribute estimator.
    auto resAttributeEstimator = faceEngine->createAttributeEstimator();
    if(!resAttributeEstimator) {
        std::cerr << "Failed to create attribute estimator instance. Reason: " << resAttributeEstimator.what();
        std::cerr << std::endl;
        return -1;
    }
    fsdk::IAttributeEstimatorPtr attributeEstimator = resAttributeEstimator.getValue();

    // Get attribute estimation.
    using AttrsRequest = fsdk::IAttributeEstimator::EstimationRequest;
    AttrsRequest attributesRequest = AttrsRequest::estimateAge;
    fsdk::IAttributeEstimator::EstimationResult attributeEstimation;

    fsdk::Result<fsdk::FSDKError> attributeEstimatorResult =
        attributeEstimator->estimate(warp, attributesRequest, attributeEstimation);

    if(attributeEstimatorResult.isOk()) {
        std::cout << "\nAttribute estimate:";
        std::cout << "\nage: " << attributeEstimation.age.value() << " (in years)" << std::endl;
        std::cout << std::endl;
    } else {
        std::cerr << "Failed to make attribute estimation. Reason: " << attributeEstimatorResult.what();
        std::cerr << std::endl;
    }

Index

Since v.5.17.0 IDynamicIndex can be saved as a file to hard disc after removing of descriptors.

Example of code (before version v.5.17.0):

// index with removed descriptors could not be saved
for (std::size_t i = 0; i < nRemoved; ++i) {
    auto resRemove = index->removeDescriptor(i);
    if (resRemove.isError()) {
        // process error
        ...
    }
}

Example of code (from version v.5.17.0):

// remove descriptors
for (std::size_t i = 0; i < nRemoved; ++i) {
    auto resRemove = index->removeDescriptor(i);
    if (resRemove.isError()) {
        // process error
        ...
    }
}

// erase descriptors 
auto resEraseRemovedDescs = index->eraseRemovedDescriptors();
if(resEraseRemovedDescs.isError()) {
    // process error
    ...
}

// get map of new descriptors
auto map = resEraseRemovedDescs.getValue();
for (std::size_t i = 0; i < count; ++i) {
    // if the old ID is not found, the error InvalidDescriptorId will be returned
    auto resMapFind = map->getId(i);
        if (resMapFind.isError()) {
            // process error or skip not found id
            ...
        }
        // we can get new id by old id
        auto newId = resMapFind.getValue();

}

// now we can save index
auto resSave = index->saveToDynamicIndex("your_index_name.bin");
if (resSave.isError()) {
    // process error
}

FishEyeEstimator

Since v.5.13.0 method estimate of IFishEyeEstimator by crop and detection has been deprecated (See IFishEyeEstimator.h). Use estimate by warped image instead.

Example of code (before version 5.13.0):

    fsdk::FishEyeEstimation estimation;
    fsdk::Result<fsdk::FSDKError> res = fishEyeEstimator->estimate(image, detection, estimation);

Example of code (from version 5.13.0):

    fsdk::FishEyeEstimation estimation;
    fsdk::Result<fsdk::FSDKError> res = fishEyeEstimator->estimate(warp, estimation);

v.5.6.0

Vector2

Since v.5.6.0, the member array in fsdk::Vector2 has been removed. You should use the x andy members instead of the removed array one.

Example of code (before version 5.6.0):

    fsdk::Vector2<int> vector2;
    vector2.x = 10; 
    vector2.y = 20;
    // or
    vector2.array[0] = 10; 
    vector2.array[1] = 20;

Example of code (from version 5.6.0):

    fsdk::Vector2<int> vector2;
    vector2.x = 10; 
    vector2.y = 20;

BlackWhiteEstimator

Since v.5.6.0 method estimate of IBlackWhiteEstimator by full image has been deprecated (See IBlackWhiteEstimator.h). Use estimate by warped image instead.

Example of code (before version 5.6.0):

    bool isGray = false;
    Result<FSDKError> res = BlackWhiteEstimator->estimate(fullImage, isGray);

Example of code (from version 5.6.0):

    fsdk::ImageColorEstimation estimation;
    Result<FSDKError> res = BlackWhiteEstimator->estimate(warp, estimation);

v.5.5.0

From v.5.5.0 the default value of numThreads (runtime.conf) was replaced by -1. Which means that will be taken the maximum number of available threads. This number of threads is equal to according number of available processor cores.

Example of setting (before version 5.5.0):

<param name="numThreads" type="Value::Int1" x="4" />

Example of setting (from version 5.5.0):

<param name="numThreads" type="Value::Int1" x="-1" />

From v.5.5.0 the method loadFromFile(const char* path) (See ILicense.h) is deprecated. The use is allowed, but can be useless. Please use the method loadFromFile(const char* path, const fsdk::ISettingsProvider* settings) instead.

Examples of code

Example of code (before version 5.5.0):

    const bool isLicenseFileLoadedSuccessfully = license->loadFromFile(path).isOk());

Example of code (from version 5.5.0):

    auto resSettings = fsdk::createSettingsProvider("License Config Path");
    if (!resSettings.isOk()) {
        return -1;
    }

    fsdk::ISettingsProviderPtr settings = resSettings.getValue();

    // Create new license from file
    const bool isLicenseFileLoadedSuccessfully = license->loadFromFile(path, settings).isOk());

v.5.2.0

From v.5.2.0 the 101 version of human descriptor is not supported, it was changed by 104. Currently, three versions are available: 102 (tracker), 103 (precise), 104 (regular). It means that all instances (such as IDescriptorExtractor, IDescriptorMatcher and etc.) cannot be created with the version 101.

v.5.1.0

From version v.5.1.0 IHeadPoseEstimatorPtr and IAGSEstimatorPtr are deprecated. Use IBestShotQualityEstimatorPtr instead.

Note. AGS score thresholds are different for IAGSEstimatorPtr and IBestShotQualityEstimatorPtr. Read more on the BestShotQuality estimation page.

v.5.0.0

Objects creation

The fsdk::acquire(...) method for the pointer acquiring for IFaceEngine objects is not allowed for usage starting from version 5.0.0. In addition, the types of values returned from the create methods of IFaceEngine were changed.

Most of the create methods now return the following structure - fsdk::ResultValue<fsdk::FSDKError, ObjectClassPtr> Thus it is easy to check the correctness of the result (using one of the following methods result.isOk() or result.isError()) and get an error (using the result.getError() method). The result.what() method can be used to get the text description of the error.

Examples of code

Example of code (before version 5.0.0):

fsdk::IAttributeEstimatorPtr estimator = fsdk::acquire(faceEngine->createAttributeEstimator());
if (estimator.isNull())  {
    std::cout << "Object pointer is nullptr" << std::endl;
    ... // process error
}

Example of code (from version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, fsdk::IAttributeEstimatorPtr> resEstimator = faceEngine->createAttributeEstimator();
if (resEstimator.isError())  {
    std::cout << "Error: " << resEstimator.what() << std::endl;
    ... // process error
}

fsdk::IAttributeEstimatorPtr estimator = resEstimator.getValue();

Interface of ILicense

From version v.5.0.0 we changed the interface of ILicense. Now all methods of this class return fsdk::Result<fsdk::FSDKError>, fsdk::ResultValue<fsdk::FSDKError, bool> or fsdk::ResultValue<fsdk::FSDKError, uint32_t> instead of bool.

Examples of code

Example of code (before version 5.0.0):

    const bool res = license->isActivated();
    if (!res) {
        /* error case code */
    }

Example of code (from version 5.0.0):

    const fsdk::ResultValue<fsdk::FSDKError, bool> result = license->isActivated();
    if (result.isError()) {
        /* error case code */
    }

    const bool value = result.getValue();
    if (!value) {
        /* false case code */
    }

From version v.5.0.0 we changed the arguments of methods getExpirationDate and checkFeatureId in class ILicense. Now the input arguments of getExpirationDate and checkFeatureId is fsdk::LicenseFeature instead of uint32_t. And the second argument of getExpirationDate was removed. The return value of getExpirationDate is fsdk::ResultValue<fsdk::FSDKError, uint32_t>.

Example of code (before version 5.0.0):

    long long expDate = 0;
    const bool result =
        license->getExpirationDate(static_cast<uint32_t>(fsdk::LicenseFeature::Detection), expDate);

    if (result == false) {
        /* error case code */
    }

Example of code (from version 5.0.0):

    const fsdk::ResultValue<fsdk::FSDKError, uint32_t> result =
        license->getExpirationDate(fsdk::LicenseFeature::Detection);

    if (result.isError()) {
        /* error case code */
    }

    const uint32_t expDate = result.getValue();

Example of code (before version 5.0.0):

    const bool res = license->checkFeatureId(static_cast<uint32_t>(fsdk::LicenseFeature::Detection));
    if (!res) {
        /* error case code */
    }

Example of code (from version 5.0.0):

    const fsdk::ResultValue<fsdk::FSDKError, bool> result = license->checkFeatureId(fsdk::LicenseFeature::Detection);
    if (result.isError()) {
        /* error case code */
    }

    const bool value = result.getValue();
    if (!value) {
        /* false case code */
    }

Interface of HumanLandmark

From version v.5.0.0 we changed the interface of HumanLandmark. Now member point doesn't store zero coordinates in the case when it is not visible. For this purposes we added member visible which stores true if point is visible.

Example of code (before version 5.0.0):

if (humanLandmark.point.x == 0 && humanLandmark.point.y == 0) {
    // point is not visible case code
}
else {
    // point is visible case code
}

Example of code (from version 5.0.0):

if (humanLandmark.visible == false) {
    // point is not visible case code  
}
else {
    // point is visible case code
}

HumanDetectionType

Since v.5.19.0 the HDT_POINTS was dropped, but the the enum HumanDetectionType kept for backward compatibility

HumanLandmarks17

Since v.5.19.0 were dropped the HumanLandmarks17, special points for the body parts visible in the image, and the member function getLandmarks17, which was intended to return HumanLandmarks17 Span.

IHumanLandmarksDetector

Since v.5.19.0 were dropped the IHumanLandmarksDetector - a human landmark(HumanLandmarks17) detector.

Interface of IDescriptorBatch

From version v.5.0.0 we renamed method IDescriptorBatch::getDescriptorSize() to IDescriptorBatch::getDescriptorLength().

Example of code (before version 5.0.0):

uint32_t descriptorLength = descriptorBatch->getDescriptorSize();

Example of code (from version 5.0.0):

uint32_t descriptorLength = descriptorBatch->getDescriptorLength();

Interface of Detection

From version v.5.0.0 we changed the interface of the Detection structure. Now all members of this structure are private and could be available through the public methods.

Example of code (before version 5.0.0):

fsdk::Detection detection = ...; // Somehow initialized detection object
fsdk::Rect rect = detection.rect; // Get the detection rect
float score = detection.score; // Get the detection score

Example of code (from version 5.0.0):

fsdk::Detection detection = ...; // Somehow initialized detection object
fsdk::Rect rect = detection.getRect(); // Get the detection rect
float score = detection.getScore(); // Get the detection score

Interface of IDetector

From version v.5.0.0 we changed the interface of IDetector structure. Now method detect returns ResultValue<FSDKError, Ref<IFaceDetectionBatch>> instead of ResultValue<FSDKError, Ref<IResultBatch<Face>>>.

Example of code (before version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, fsdk::Ref<fsdk::IResultBatch<fsdk::Face>>> detectorResult = faceDetector->detect(
        fsdk::Span<const fsdk::Image>(&image, 1),
        fsdk::Span<const fsdk::Rect>(&imageRect, 1),
        detectionsCount,
        fsdk::DT_ALL);

Example of code (from version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, fsdk::Ref<fsdk::IFaceDetectionBatch>> detectorResult = faceDetector->detect(
        fsdk::Span<const fsdk::Image>(&image, 1),
        fsdk::Span<const fsdk::Rect>(&imageRect, 1),
        detectionsCount,
        fsdk::DT_ALL);

Also we changed input and output parameters of the method redetectOne. Now it takes Image and Detection instead of Face. And returns ResultValue<FSDKError, Face> instead of ResultValue<FSDKError, bool>.

Example of code (before version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, bool> redetectResult = faceDetector->redetectOne(face);

Example of code (from version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, fsdk::Face> redetectResult = faceDetector->redetectOne(image, detection);

IFaceDetectionBatch

We added IFaceDetectionBatch structure to replace IResultBatch<Face>.

Example of code (before version 5.0.0):

fsdk::Ref<IResultBatch<Face>> resultBatch = ...; // Somehow get the IResultBatch<Face>
for (std::size_t i = 0; i < resultBatch->getSize(); ++i) {
    fsdk::Span<fsdk::Face> faces = resultBatch->getResults(i);
    for (auto& face : faces) {
        const fsdk::Rect& rect = face.detection.rect;
        const float score = face.detection.score;
        const fsdk::Landmarks5& lm5 = face.landmarks5.value();
        const fsdk::Landmarks68& lm68 = face.landmarks68.value();
        // Some code which uses received objects
    }
}

Example of code (from version 5.0.0):

fsdk::Ref<fsdk::IFaceDetectionBatch> faceDetectionBatch = ...; // Somehow get the IFaceDetectionBatch
for (std::size_t i = 0; i < faceDetectionBatch->getSize(); ++i) {
    fsdk::Span<const fsdk::Detection> detections = faceDetectionBatch->getDetections(i);
    fsdk::Span<const fsdk::Landmarks5> landmarks5 = faceDetectionBatch->getLandmarks5(i);
    fsdk::Span<const fsdk::Landmarks68> landmarks68 = faceDetectionBatch->getLandmarks68(i);
    for (std::size_t j = 0; j < detections.size(); ++j) {
        const fsdk::Rect& rect = detections[j].getRect();
        const float score = detections[j].getScore();
        const fsdk::Landmarks5& lm5 = landmarks5[j];
        const fsdk::Landmarks68& lm68 = landmarks68[j];
        // Some code which uses received objects
    }
}

Interface of IHumanDetector

From version v.5.0.0 we changed the interface of IHumanDetector structure. Now method detect returns ResultValue<FSDKError, Ref<IHumanDetectionBatch>> instead of ResultValue<FSDKError, Ref<IResultBatch<Human>>>.

Example of code (before version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, fsdk::Ref<fsdk::IResultBatch<fsdk::Human>>> detectResult = humanDetector->detect(
        fsdk::Span<const fsdk::Image>(&image, 1),
        fsdk::Span<const fsdk::Rect>(&imageRect, 1),
        detectionsCount,
        fsdk::DCT_ALL);

Example of code (from version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, fsdk::Ref<fsdk::IHumanDetectionBatch>> detectResult = humanDetector->detect(
        fsdk::Span<const fsdk::Image>(&image, 1),
        fsdk::Span<const fsdk::Rect>(&imageRect, 1),
        detectionsCount,
        fsdk::HDT_ALL);

Also we changed input and output parameters of the method redetectOne. Now it takes Image and Detection instead of Human. And returns ResultValue<FSDKError, Human> instead of ResultValue<FSDKError, bool>.

Example of code (before version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, bool> redetectResult = humanDetector->redetectOne(human);

Example of code (from version 5.0.0):

fsdk::ResultValue<fsdk::FSDKError, fsdk::Human> redetectResult = humanDetector->redetectOne(image, detection);

IHumanDetectionBatch

Since v.5.19.0 were dropped the member function getLandmarks17, which was intended to return HumanLandmarks17 Span.

We added IHumanDetectionBatch structure to replace IResultBatch<Human>.

Example of code (before version 5.0.0):

fsdk::Ref<IResultBatch<Human>> resultBatch = ...; // Somehow get the IResultBatch<Human>
for (std::size_t i = 0; i < resultBatch->getSize(); ++i) {
    fsdk::Span<fsdk::Human> humans = resultBatch->getResults(i);
    for (auto& human : humans) {
        const fsdk::Rect& rect = human.detection.rect;
        const float score = human.detection.score;
        const fsdk::Landmarks17& lm17 = face.landmarks5.value();
        // Some code which uses received objects
    }
}

Example of code (from version 5.0.0):

const fsdk::Ref<fsdk::IHumanDetectionBatch> humanDetectionBatch = ...; // Somehow get the IHumanDetectionBatch
for (std::size_t i = 0; i < humanDetectionBatch->getSize(); ++i) {
    fsdk::Span<const fsdk::Detection> detections = humanDetectionBatch->getDetections(i);
    fsdk::Span<const fsdk::HumanLandmarks17> landmarks = humanDetectionBatch->getLandmarks17(i);
    for (std::size_t j = 0; j < detections.size(); ++j) {
        const fsdk::Rect rect = detections[j].getRect();
        const float score = detections[j].getScore();
        const fsdk::HumanLandmarks17 lm17 = landmarks[j];
        // Some code which uses received objects
    }
}

Interface of ILivenessFlyingFaces

From version v.5.0.0 we changed the interface of ILivenessFlyingFaces structure. Now both methods estimate take Image and Detection instead of Face.

Example of code (before version 5.0.0):

fsdk::LivenessFlyingFacesEstimation flyingFacesEstimation;
Result<fsdk::FSDKError> flyingFacesResult = livenessFlyingFacesEstimator->estimate(face, flyingFacesEstimation);

Example of code (from version 5.0.0):

fsdk::LivenessFlyingFacesEstimation flyingFacesEstimation;
Result<fsdk::FSDKError> flyingFacesResult = livenessFlyingFacesEstimator->estimate(
        image,
        detection,
        flyingFacesEstimation);

Example of code (before version 5.0.0):

Result<fsdk::FSDKError> flyingFacesResult = livenessFlyingFacesEstimator->estimate(
        fsdk::Span<const fsdk::Face>(&face, 1),
        fsdk::Span<fsdk::LivenessFlyingFacesEstimation>(&estimation, 1));

Example of code (from version 5.0.0):

fsdk::LivenessFlyingFacesEstimation flyingFacesEstimation;
Result<fsdk::FSDKError> flyingFacesResult = livenessFlyingFacesEstimator->estimate(
        fsdk::Span<const fsdk::Image>(&image, 1),
        fsdk::Span<const fsdk::Detection>(&detection, 1),
        fsdk::Span<fsdk::LivenessFlyingFacesEstimation>(&flyingFacesEstimation, 1));

v.3.10.1

Detector FaceDetV3 changes

From version 3.10.1 we changed the logic for image resizing in FaceDetV3 detector. Now you can change the minimum and maximum sizes of the faces that will be searched in the photo from the faceengine.conf configuration. To get new parameter which will be identical to old setting you need to set minFaceSize:

The old recommended imageSize=640 will be identical to new meaning of setting minFaceSize=20

config->setValue("FaceDetV3::Settings", "minFaceSize", 20);

and imageSize=320 will be identical to new meaning of setting minFaceSize=40

config->setValue("FaceDetV3::Settings", "minFaceSize", 40);

Detector FaceDetV1, FaceDetV2 changes

From version 3.10.1 we changed the name of parameter minSize to minFaceSize in faceengine.conf for FaceDetV1, FaceDetV2 detector types. The logic and default value for image resizing left unchanged.