Invoke-BWSQualityCheck

NAME
    Invoke-BWSQualityCheck

SYNOPSIS
    Performs a rigorous quality check, which is crucial for enrollment, verification or identification.


SYNTAX
    Invoke-BWSQualityCheck [-BWS] <string> [-Certificate] <X509Certificate> [-Path] <string[]> [-Issuer <string>]
    [-ICAOChecks <SwitchParameter>] [<CommonParameters>]

    Invoke-BWSQualityCheck [-BWS] <string> [-Certificate] <X509Certificate> [-Samples] <Sample[]> [-Issuer <string>]
    [-ICAOChecks <SwitchParameter>] [<CommonParameters>]


DESCRIPTION
    The quality checks of face images are performed according to ICAO requirements. ICAO (International Civil Aviation
    Organization) is the leading organization in creating standards for machine readable travel documents (MRTDs).
    This includes a standard for the digital image quality of facial images, defining requirements for photographic
    and digital characteristics.

    Quality checks of voice samples can be performed as well. These are just some generic tests to find out, whether
    we can use the samples for biometric operations or not. The ICAOChecks and Issuer parameters are ignored for voice
    samples.


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

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

        Required?                    true
        Position?                    3
        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 quality check. 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?                    3
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Issuer <string>
        The quality checks of face images can be performed according to document-issuer specific settings defined by
        this parameter. Currently supported issuers are: 'ICAO' (the default settings as specified by ICAO), 'BioID'
        (similar to 'ICAO' but with a bigger token image) and various ISO 3166-1 alpha-2 country codes specifying the
        document issuing country like 'US', 'DE', etc.

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

    -ICAOChecks [<SwitchParameter>]
        Performs checks according to the ICAO specifications (the so called document mode) and creates output samples
        according to these specifications (currently only for facial images), but does typically not modify the
        content of the input samples.

        The default behaviour is to extract the so called token data from the given samples, which is typically
        intended to be stored on a chip, in a database or somewhere else for later use with a biometric recognition
        system.

        Required?                    false
        Position?                    named
        Default value                Extract the token data.
        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-BWSQualityCheck.


OUTPUTS
    BioID.Cmdlets.QualityCheckResult
        Returns an object containing the results of the quality check. The object contains the processed "Samples" 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.


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

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

    Performs a standard BioID quality check of the two images supplied. As the Path allows wildcard characters, the
    following command uses at least the same sample files as above and performs a full document mode ICAO check:

    $cert = get-childitem -path Cert:\CurrentUser\My\1234567890ABCDEF1234567890ABCDEF12345678
    $result = Invoke-BWSQualityCheck bws.bioid.com $cert c:\samples\image*.png -Issuer DE -ICAOChecks

    -------------------------- 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-BWSQualityCheck bws.bioid.com $cert $samples -Issuer BioID

    Performs a standard BioID quality check of the three samples images supplied.
RELATED LINKS
BWS QualityCheck API
BioID Web Service reference
ICAO Document 9303
ICAO MRTD Programme