Invoke-BWSIdentify

NAME
    Invoke-BWSIdentify

SYNOPSIS
    Performs a one-to-many comparison of the given samples with the stored biometric templates in order to identify
    the individuals that are most likely represented by the given samples.


SYNTAX
    Invoke-BWSIdentify [-BWS] <string> [-Certificate] <X509Certificate> [-BCID] <string> [-Path] <string[]>
    [-LiveFaceDetection <SwitchParameter>] [-LivePeriocularDetection <SwitchParameter>] [-MaxResults <Int32>]
    [<CommonParameters>]

    Invoke-BWSIdentify [-BWS] <string> [-Certificate] <X509Certificate> [-BCID] <string> [-Samples]
    <BioID.Cmdlets.BWS.Sample[]> [-LiveFaceDetection <SwitchParameter>] [-LivePeriocularDetection <SwitchParameter>]
    [-MaxResults <Int32>] [<CommonParameters>]


DESCRIPTION
    A biometric identification tests the given samples against all samples (biometric templates) stored in the the
    specified partition of the cloud storage. A list of identified BCIDs (Biometric Class IDs) is generated and sorted
    according to the score (a kind of probability or similarity) that has been calculated for each BCID. Note that
    only those BCIDs are considered that have a biometric template available for each trait specified by the delivered
    samples.

    This method supports live detection (currently only for the face and periocular trait). To activate live
    detection, simply use the switch LiveFaceDetection or LivePeriocularDetection. Note that in this case the
    identification will only succeed, when it can undoubtedly determine that the given data is live data. In case that
    the live detection for the face trait succeeds, the degree of the head rotation between two subsequent images is
    reported with the returned result.

    Internally this operation always performs a QualityCheck (in BioID ExtractTokenData mode) for all submitted
    samples before they are forwarded to the live detection - in case a live-detection flag is set - and finally the
    identification is performed. Therefore you might get results from these operations as well together with the
    verification results.


PARAMETERS
    -BWS <string>
        Specifies the BioID Web Service (BWS) installation where the command shall be executed. You can simply use the
        hostname like 'bws.bioid.com' or the entire URL, e.g. 'https://bws.bioid.com/BioIDWebService.svc'. If scheme
        and/or path are not given, the defaults (https, BioIDWebService.svc) are used.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Certificate <X509Certificate>
        Specifies the client certificate that is used to authenticate the BWS client. Enter a variable that contains a
        certificate or a command or expression that gets the certificate.

        To find a certificate, use Get-PfxCertificate or use the Get-ChildItem cmdlet in the Certificate (Cert:)
        drive. For example:
        get-childitem -path Cert:\CurrentUser\My\1234567890ABCDEF1234567890ABCDEF12345678

        If the certificate is not valid or does not have sufficient authority, the command fails.

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -BCID <string>
        In the case of identification, the Biometric ClassID (BCID) specifies the range of classes that shall be
        tested against the given samples. All classes in the specified partition at the specified storage are compared
        with the given samples. Therefore the class id part of the BCID is ignored.

        Required?                    true
        Position?                    3
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Path <string[]>
        A list of files containing the samples to be uploaded to BWS and used for the identification. Files with the
        extension .wav are assumed to be voice-samples, all others files are assigned to the face trait.

        Required?                    true
        Position?                    4
        Default value
        Accept pipeline input?       true (ByValue)
        Accept wildcard characters?  true

    -Samples <BioID.Cmdlets.BWS.Sample[]>
        The array of samples that shall be uploaded to the BWS and used for the identification. You can use BWS
        samples instead of files in case you explicitely need to specify the trait of the sample or have to add a tag
        to the sample.

        To create a sample array from a file-path you can use a command like:
        $samples =
        @([BioID.Cmdlets.BWS.Sample]@{Data=[System.IO.File]::ReadAllBytes(path);Trait="Face";Tag="something"})

        Required?                    true
        Position?                    4
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -LiveFaceDetection [<SwitchParameter>]
        Enables live face detection. In this case the operation typically fails, as soon as it cannot undoubtedly
        determine that the given data is live data.

        Required?                    false
        Position?                    named
        Default value                No live face detection.
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -LivePeriocularDetection [<SwitchParameter>]
        Enables live periocular detection. In this case the operation typically fails, as soon as it cannot
        undoubtedly determine that the given data is live data.

        Required?                    false
        Position?                    named
        Default value                No live periocular detection.
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -MaxResults [<Int32>]
        The maximum number of matches that shall be returned.

        Required?                    false
        Position?                    named
        Default value                20
        Accept pipeline input?       false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

INPUTS
    System.String[]
        You can pipe sample files to Invoke-BWSIdentify.


OUTPUTS
    BioID.Cmdlets.IdentifyResult
        Returns an object containing the results of the identification. The object contains a sorted list of "Matches"
        and a generic BWS "JobResult" with information about the performed "Command", a unique "JobID", whether the
        operation "Succeeded" and a list of operation specific "Errors". It also contains information about the
        "Samples" that have been received by the operation, including sample specific "Errors" that might have
        occurred.


NOTES
    Enrollment

        The identification procedure can only consider classes that have previously been enrolled. Use the
        Invoke-BWSEnroll cmdlet to perform an enrollment. But note that it may take up to 10 seconds until all
        identifiers are updated with newly enrolled classes!

    -------------------------- EXAMPLE 1 --------------------------

    $cert = get-childitem -path Cert:\CurrentUser\My\1234567890ABCDEF1234567890ABCDEF12345678
    $result = Invoke-BWSIdentify -BWS bws.bioid.com/BioIDWebService.svc -Certificate $cert -BCID bws.123.0 -Path
    c:\samples\image1.png, c:\samples\image2.png

    Performs an identification by comparing the two provided samples with all classes in the partition '123' on the
    storage 'bws'. If you want to have a look at the detailed results, use something like:

    $result.Matches | select ClassID, Score

    As the Path allows wildcard characters, the following command uses at least the same sample files as above and
    additionally performs a live detection:

    $result = Invoke-BWSIdentify bws.bioid.com $cert bws.123.0 c:\samples\image*.png -lfd

    -------------------------- EXAMPLE 2 --------------------------

    $cert = gci Cert:\CurrentUser\My\1234567890ABCDEF1234567890ABCDEF12345678
    $samples = @(
      [BioID.Cmdlets.BWS.Sample]@{
        Data=[System.IO.File]::ReadAllBytes("c:\samples\image1.png");
        Trait="Face"},
      [BioID.Cmdlets.BWS.Sample]@{
        Data=[System.IO.File]::ReadAllBytes("c:\samples\image2.png");
        Trait="Periocular"},
      [BioID.Cmdlets.BWS.Sample]@{
        Data=[System.IO.File]::ReadAllBytes("c:\samples\audio1.wav");
        Trait="Voice"})

    $result = Invoke-BWSIdentify bws.bioid.com $cert bws.123.0 $samples

    Performs an identification by comparing the three provided samples with all classes in the partition '123' on the
    storage 'bws'.
RELATED LINKS
BWS Identification API
BioID Web Service reference