Skip to content

Reidentification example#

What it does#

This example demonstrates how to detect a human body on an image, how to extract data of that body (so called human descriptor) and how to compare descriptors in different images. Available human descriptor versions HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION = 102 and HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION = 103, HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION = 104. This example demonstrates how to:

  • detect a human body in an image;
  • extract data of that body (so called human descriptor);
  • compare descriptors in different images.

Prerequisites#

This example assumes that you have already read the FaceEngine Handbook (or at least have it somewhere nearby for reference) and know some core concepts, like memory management, object ownership, and life-time control. This sample will not explain these aspects in detail.

Example walkthrough#

We present a rather rich human processing pipeline. In fact, it is a bit too rich for this sample, but it was made so intentionally to give you a clue of some real world usage scenarios.

Preparations#

SDK initialization. It is pretty straightforward and self-explanatory, so we will not discuss it here.

Human detection#

At this stage we have an image. Presumably, there is a human somewhere in it and we would like to find it. For that purpose, a human detector is used. We use it like so:

auto resHumanDetector = faceEngine->createHumanDetector();
if (!resHumanDetector) {
    ...
}
fsdk::IHumanDetectorPtr humanDetector = resHumanDetector.getValue();
...
// Detect no more than 10 humans in the image.
const int maxDetectionCount = 10;

// Detect humans in images.
fsdk::ResultValue<fsdk::FSDKError, fsdk::Ref<fsdk::IResultBatch<fsdk::Human>>> detectorResult = humanDetector->detect(
    fsdk::Span<const fsdk::Image>(images.data(), images.size()),
    fsdk::Span<const fsdk::Rect>(rects.data(), rects.size()),
    maxDetectionCount);

Extraction#

When we have a human detection, we need to extract some data from it that can be used for comparison or matching. Such data is contained in descriptor object. A descriptor may be extracted from an image using human detection. Later, one or multiple descriptors can be matched to determine human similarity.

// Create human descriptor. Available versions are presented in fsdk::HumanDescriptorVersion enum
auto resDescriptor = faceEngine->createDescriptor(fsdk::HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION);
if (!resDescriptor) {
    ...
}
fsdk::IDescriptorPtr descriptor = resDescriptor.getValue();

// Create descriptor extractor. Available versions are presented in fsdk::HumanDescriptorVersion enum
auto resDescriptorExtractor = engine->createExtractor(fsdk::HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION);
if (!resDescriptorExtractor) {
    ...
}
fsdk::IDescriptorExtractorPtr descriptorExtractor = resDescriptorExtractor.getValue();

// Extract human descriptor.
fsdk::ResultValue<fsdk::FSDKError, float> descriptorExtractorResult = descriptorExtractor->extractFromWarpedImage(
    humanWarpedImage,
    descriptor
);
if(descriptorExtractorResult.isError()) {
    ...
}

Descriptor matching#

This stage is pretty simple. For example for matching we take only first descriptor in the first image and all detections in other images. For that we use a descriptor matcher object.

// Create descriptor matcher. Available versions are presented in fsdk::HumanDescriptorVersion enum
auto resDescriptorMatcher = engine->createMatcher(fsdk::HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION);
if (!resDescriptorMatcher) {
    ...
}
fsdk::IDescriptorMatcherPtr descriptorMatcher = resDescriptorMatcher.getValue();

// Match descriptors.
// Returns similarity in range (0..1],
// where: 0 means totally different.
//        1 means totally the same.
fsdk::ResultValue<fsdk::FSDKError, fsdk::MatchingResult> descriptorMatcherResult =
    descriptorMatcher->match(descriptors[0][0], descriptors[i][j]);
if (descriptorMatcherResult.isError()) {
    ...
}

float similarity = descriptorMatcherResult.getValue().similarity;

Similarity score tells how similar these descriptors are. Its value is in (0..1] range. Values near 1 tell us that the descriptors are very similar.

How to run#

Use the following command to run the example. Run the command from ”FSDK_ROOT”.

<install_prefix>/example_human_extraction <some_image1> <some_image2>

Example output#

Similarity of current descriptor and all human descriptors in other images in descent order:
0.920459 :: image number is 1, detection number is 6
0.63473 :: image number is 1, detection number is 1
0.572745 :: image number is 1, detection number is 5
0.562269 :: image number is 1, detection number is 2
0.55178 :: image number is 1, detection number is 7
0.539377 :: image number is 1, detection number is 3
0.528099 :: image number is 1, detection number is 4
0.511602 :: image number is 1, detection number is 8
0.307247 :: image number is 1, detection number is 9
Back to top