NAME
    Invoke-BWSEnroll

SYNOPSIS
    Performs the enrollment of an individual by calculating and storing a biometric template for each trait
    represented by the given samples.


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

    Invoke-BWSEnroll [-BWS] <string> [-Certificate] <X509Certificate> [-BCID] <string> [[-Samples] <Samples[]>]
    [-LiveFaceDetection <SwitchParameter>] [-LivePeriocularDetection <SwitchParameter>] [<CommonParameters>]


DESCRIPTION
    The enrollment method simultaneously trains all given samples, which can even represent multiple traits, e.g. face
    and voice samples. The training creates a so called biometric template for each trait specified by the given
    samples, which can later on be used for verification and identification purposes.

    Even if there are no samples given for a single trait, it is re-trained in case a template is already associated
    with the given class for this trait. This allows the re-generation of the templates after the stored data has been
    modified for any reason, e.g. when already trained sample-data is removed from the storage.

    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
    enrollment 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 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
    enrollment is performed. Therefore you might get results from these operations as well together with the
    enrollment 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>
        The Biometric ClassID (BCID) identifies a class within the BWS. A class is an anonymous entity representing
        all the biometric data associated with a single individual.

        The BCID is a combination of a string, a partition id and the class id itself. The string specifies the
        Storage, e.g. the Windows Azure Storage Service to use, whereas the partition and class id is used within this
        storage to address the class.

        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 enrollment. 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 enrollment. 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="Periocular";Tag="something"})

        Required?                    false
        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

    <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-BWSEnroll.


OUTPUTS
    BioID.Cmdlets.EnrollJobResult
        Returns an object containing the results of the enrollment. The object contains 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
    Identification

        Please note that it may take up to 10 seconds until all identifiers are updated with newly enrolled classes!
        Verifiers do not need to get updated, so a verification of a newly enrolled class can be performed immediately.

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

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

    Performs an enrollment of the class bws.123.12345 using the two images supplied. 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-BWSEnroll bws.bioid.com $cert bws.123.12345 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"})

    Invoke-BWSEnroll bws.bioid.com $cert bws.123.12345 $samples

    Performs an enrollment of the class bws.123.12345 using the three samples supplied.