/// <summary>
/// Compares one <see cref="Person"/> against a set of other <see cref="Person"/>s and returns best matches.
/// </summary>
/// <param name="probe">Person to look up in the collection.</param>
/// <param name="candidates">Collection of persons that will be searched.</param>
/// <returns>All matching <see cref="Person"/> objects in the collection or an empty collection if
/// there is no match. Results are sorted by score in descending order. If you need only one best match,
/// call <see cref="Enumerable.FirstOrDefault{T}(IEnumerable{T})"/> method on the returned collection.</returns>
/// <remarks>
/// <para>
/// Compares probe <see cref="Person"/> to all candidate <see cref="Person"/>s and returns the most similar
/// candidates. Calling <see cref="Identify"/> is conceptually identical to calling <see cref="Verify"/> in a loop
/// except that <see cref="Identify"/> is significantly faster than loop of <see cref="Verify"/> calls.
/// If there is no candidate with score at or above <see cref="Threshold"/>, <see cref="Identify"/> returns
/// empty collection.
/// </para>
/// <para>
/// Most applications need only the best match, which can be obtained by calling
/// <see cref="Enumerable.FirstOrDefault{T}(IEnumerable{T})"/> method on the returned collection.
/// Matching score for every returned <see cref="Person"/> can be obtained by calling
/// <see cref="Verify"/> on probe <see cref="Person"/> and the matching <see cref="Person"/>.
/// </para>
/// <para>
/// <see cref="Person"/>s passed to this method must have valid <see cref="Fingerprint.Template"/>
/// for every <see cref="Fingerprint"/>, i.e. they must have passed through <see cref="Extract"/> method.
/// </para>
/// </remarks>
/// <seealso cref="Threshold"/>
/// <seealso cref="MinMatches"/>
/// <seealso cref="Verify"/>
public IEnumerable <Person> Identify(Person probe, IEnumerable <Person> candidates)
{
probe.CheckForNulls();
Person[] candidateArray = candidates.ToArray();
BestMatchSkipper.PersonsSkipScore[] results;
lock (this)
{
BestMatchSkipper collector = new BestMatchSkipper(candidateArray.Length, MinMatches - 1);
Parallel.ForEach(probe.Fingerprints, probeFp =>
{
List <int> personsByFingerprint = new List <int>();
List <Template> candidateTemplates = FlattenHierarchy(candidateArray, probeFp.Finger, out personsByFingerprint);
ParallelMatcher.PreparedProbe probeIndex = Matcher.Prepare(probeFp.Decoded);
float[] scores = Matcher.Match(probeIndex, candidateTemplates);
lock (collector)
for (int i = 0; i < scores.Length; ++i)
{
collector.AddScore(personsByFingerprint[i], scores[i]);
}
});
results = collector.GetSortedScores();
}
return(GetMatchingCandidates(candidateArray, results));
}
/// <summary>
/// Compares one <see cref="Person"/> against a set of other <see cref="Person"/>s and returns best matches.
/// </summary>
/// <param name="probe">Person to look up in the collection.</param>
/// <param name="candidates">Collection of persons that will be searched.</param>
/// <returns>All matching <see cref="Person"/> objects in the collection or an empty collection if
/// there is no match. Results are sorted by score in descending order. If you need only one best match,
/// call <see cref="Enumerable.FirstOrDefault{T}(IEnumerable{T})"/> method on the returned collection.</returns>
/// <remarks>
/// <para>
/// Compares probe <see cref="Person"/> to all candidate <see cref="Person"/>s and returns the most similar
/// candidates. Calling <see cref="Identify"/> is conceptually identical to calling <see cref="Verify"/> in a loop
/// except that <see cref="Identify"/> is significantly faster than loop of <see cref="Verify"/> calls.
/// If there is no candidate with score at or above <see cref="Threshold"/>, <see cref="Identify"/> returns
/// empty collection.
/// </para>
/// <para>
/// Most applications need only the best match, which can be obtained by calling
/// <see cref="Enumerable.FirstOrDefault{T}(IEnumerable{T})"/> method on the returned collection.
/// Matching score for every returned <see cref="Person"/> can be obtained by calling
/// <see cref="Verify"/> on probe <see cref="Person"/> and the matching <see cref="Person"/>.
/// </para>
/// <para>
/// <see cref="Person"/>s passed to this method must have valid <see cref="Fingerprint.Template"/>
/// for every <see cref="Fingerprint"/>, i.e. they must have passed through <see cref="Extract"/> method.
/// </para>
/// </remarks>
/// <seealso cref="Threshold"/>
/// <seealso cref="MinMatches"/>
/// <seealso cref="Verify"/>
public IEnumerable<Person> Identify(Person probe, IEnumerable<Person> candidates)
{
probe.CheckForNulls();
Person[] candidateArray = candidates.ToArray();
BestMatchSkipper.PersonsSkipScore[] results;
lock (this)
{
BestMatchSkipper collector = new BestMatchSkipper(candidateArray.Length, MinMatches - 1);
Parallel.ForEach(probe.Fingerprints, probeFp =>
{
List<int> personsByFingerprint = new List<int>();
List<Template> candidateTemplates = FlattenHierarchy(candidateArray, probeFp.Finger, out personsByFingerprint);
ParallelMatcher.PreparedProbe probeIndex = Matcher.Prepare(probeFp.Decoded);
float[] scores = Matcher.Match(probeIndex, candidateTemplates);
lock (collector)
for (int i = 0; i < scores.Length; ++i)
collector.AddScore(personsByFingerprint[i], scores[i]);
});
results = collector.GetSortedScores();
}
return GetMatchingCandidates(candidateArray, results);
}
