NAV Navbar
c# http json
  • Facial Recognition SDK
  • Windows .NET
  • Linux Java
  • Web API
  • VIN Recognition Service
  • VeriScan Desktop
  • Facial Recognition SDK

    The SDK allows you to capture faces, evaluate gender, age group, emotions, and create face templates to compare them and find similarity percentages.

    Face templates can be compared to each other, one-to-one, or one-to-many using a collection of templates.

    Windows .NET

    Description

    The SDK allows you to capture faces, evaluate gender, age group, emotions, and create face templates to compare them and find similarity percentages.

    Face templates can be compared to each other, one-to-one, or one-to-many using a collection of templates.

    The sdk also includes a video frame processor that simplifies detection, tracking, estimation, and facial recognition.

    Recognition Type

    There are two types of recognition:

    Fast

    Fast Recognition type is recommended in cases where the fastest recognition is needed and the accuracy of recognition is not as important. For example, this recognition type is great for video processing.

    Quality

    Quality Recognition type requires more processing time but the result is more accurate.

    Installation

    Download fast or quality recognition package from the developer portal, run setup, and follow installation steps.

    Requirements

    Software

    Face SDK require .NET Framework v. 4.7.2.

    .NET Framework v. 4.7.2 can be download at microsoft.com

    Facial Processing API usage

    SDK Configuration and Initialization

    Building service :

    var settings = new Settings
    {
      LicenseFilePath = path to license file,
      SdkDataDirectoryPath = path to SDK Data directory
    };
    var service = new FacialProcessingServiceBuilder(settings)
      .AddRecognizing()
      .AddVideoProcessor()
      .Build())
    

    Face Capturing

    First create service:

    //  create service
    Service = new FacialProcessingServiceBuilder(new Settings
    {
      LicenseFilePath = ...,
      SdkDataDirectoryPath = path to SDK Data
    })
    .AddRecognizing()
    .Build());
    
    //  create face processor
    FaceProcessor = Service.CreateFaceProcessor();
    

    Get FaceSamples by calling CaptureFaces method

    // read image data
    var imageData = File.ReadAllBytes(imagePath);
    // capture face samples
    var faceSamples = FaceProcessor.CaptureFaces(imageData);
    

    The face capturing used to detect faces on an image and their characteristics such as position on image, eyes position, face rotation, and face landmarks.

    Face Template creation

    First create service:

    //  create service
    Service = new FacialProcessingServiceBuilder(new Settings
    {
      LicenseFilePath = ...,
      SdkDataDirectoryPath = path to SDK Data
    })
    .AddRecognizing()
    .Build());
    
    //  create face processor
    FaceProcessor = Service.CreateFaceProcessor();
    

    To create FaceTemplate use this code snippet:

    // read image data
    var imageData = File.ReadAllBytes(imagePath1);
    // capture face sample
    var faceSample = FaceProcessor.CaptureSingleFace(imageData);
    // compute face template from sample
    var faceTemplate = FaceProcessor.ComputeTemplate(faceSample);
    // optionally set id or tag properties
    faceTemplate.Id = 1;
    faceTemplate.Tag = "group 1";
    // optionally set custom data with your model
    var personInfo = new PersonInfo();
    faceTemplate.SetCustomData(personInfo);
    // to receive data back call GetCustomData<T>() where T is a class of your model
    

    Face Templates comparison

    First create service:

    //  create service
    Service = new FacialProcessingServiceBuilder(new Settings
    {
      LicenseFilePath = ...,
      SdkDataDirectoryPath = path to SDK Data
    })
    .AddRecognizing()
    .Build());
    
    //  create face processor
    FaceProcessor = Service.CreateFaceProcessor();
    

    To compare two FaceTemplate use this code snippet:

    // read images data
    var imageData1 = File.ReadAllBytes(imagePath1);
    var imageData2 = File.ReadAllBytes(imagePath2);
    // capture samples
    var faceSample1 = FaceProcessor.CaptureSingleFace(imageData1);
    var faceSample2 = FaceProcessor.CaptureSingleFace(imageData2);
    // compute templates
    var faceTemplate1 = FaceProcessor.ComputeTemplate(faceSample1);
    var faceTemplate2 = FaceProcessor.ComputeTemplate(faceSample2);
    // compare templates and get comparisonValue - float value from 0.0f to 1.0f
    var comparisonValue = FaceProcessor.CompareTemplates(faceTemplate1, faceTemplate2);
    

    Face Templates searching

    First create service:

    //  create service
    Service = new FacialProcessingServiceBuilder(new Settings
    {
      LicenseFilePath = ...,
      SdkDataDirectoryPath = path to SDK Data
    })
    .AddRecognizing()
    .Build());
    
    //  create face processor
    FaceProcessor = Service.CreateFaceProcessor();
    

    To compare two FaceTemplate use this code snippet:

    // read images data
    var bytes1 = File.ReadAllBytes("face1.jpg");
    var bytes2 = File.ReadAllBytes("face2.jpg");
    var bytes3 = File.ReadAllBytes("face3.jpg");
    
    // capture samples
    var sample1 = FaceProcessor.CaptureSingleFace(bytes1);
    var sample2 = FaceProcessor.CaptureSingleFace(bytes2);
    var sample3 = FaceProcessor.CaptureSingleFace(bytes3);
    
    // compute templates
    var template1 = FaceProcessor.ComputeTemplate(sample1);
    template1.SetCustomData("person1");
    var template2 = FaceProcessor.ComputeTemplate(sample2);
    template2.SetCustomData("person2");
    var template3 = FaceProcessor.ComputeTemplate(sample3);
    template3.SetCustomData("person3");
    
    var list = new List<FaceTemplate> {template1, template2, template3};
    
    // search
    var searchResult = FaceProcessor.SearchTemplate(template1, list);
    

    The SearchResult type contains IsRecognized property that represent search state. If IsRecognized property is 'true' you can use Template property to get matched template info. The SearchResult type also contain ConfidencePercent property to show search confidence.

    Samples

    SDK Contain a set of samples with source code. Source code can be founded at [SdkInstallationPath]/Samples

    FaceMatchingSample

    FaceMatchingSample created to show basic API usage such as creating FaceSamples, creating FaceTemplates, storing FaceTemplates, usage of TemplateCollection and FaceTemplate comparison.

    FaceTrackingWpfSample

    FaceTrackingWpfSample shows the result of IFrameProcessor work such as face tracking, creating FaceTemplate from file and realtime face recognition.

    API Reference

    Settings references:

    Properties Description
    LicenseFilePath Path to file containing license key
    SdkDataDirectoryPath SDK Data directory path
    RecognitionThreads Threads count for templates search
    ProcessingThreads Threads count for processing
    RecognitionConfidenceThreshold Recognizer search confidence (Accepts values from 0.0f to 1.0f), default value is 0.6f

    IFaceProcessor references:

    IFaceProcessor used to capture faces on an image file, compute face templates, compare one-to-one or one-to-many face templates.

    Method Return type Description
    CaptureSingleFace(byte[] imageBytes) FaceSample Capture single FaceSample on given image or videoframe. Supported encoded image with JPEG, PNG, TIF and BMP formats with 8 or 24 bits per pixel.
    CaptureSingleFaceAsync(byte[] imageBytes) Task<FaceSample> Capture single FaceSample async on given image or videoframe. Supported encoded image with JPEG, PNG, TIF and BMP formats with 8 or 24 bits per pixel.
    CaptureFaces(byte[] imageBytes) List<FaceSample> Capture FaceSamples on given image or videoframe. Supported encoded image with JPEG, PNG, TIF and BMP formats with 8 or 24 bits per pixel.
    CaptureFacesAsync(byte[] imageBytes) Task<List<FaceSample>> Capture FaceSamples async on given image or videoframe. Supported encoded image with JPEG, PNG, TIF and BMP formats with 8 or 24 bits per pixel.
    ComputeTemplate(FaceSample faceSample) FaceTemplate Create FaceTemplate from given FaceSample.
    ComputeTemplateAsync(FaceSample faceSample) Task<FaceTemplate> Create FaceTemplate async from given FaceSample.
    Compare(FaceSample first, FaceSample second) float Compare two previously created FaceSample
    CompareTemplatesAsync(FaceTemplate first, FaceTemplate second) float Compare async two previously created FaceTemplate
    SearchTemplate(FaceTemplate template) SearchResult Search for the most similar template from the TemplateCollection. Templates with a matching result below the Settings.RecognizerSearchThreshold are ignored.
    SearchTemplateAsync(FaceTemplate template) Task<SearchResult> Search async for the most similar template from the TemplateCollection. Templates with a matching result below the Settings.RecognizerSearchThreshold are ignored.

    FaceTemplate references:

    Properties Return type Description
    Id long User defined id
    Data NativeMemory Template data
    Id long User defined id
    Tag string User defined tag
    CustomData object User custom data model

    SearchResult references:

    Properties Return type Description
    Confidence float Searched confidence (from 0.0f to 1.0f)
    ConfidencePercent float Search confidence in percents
    IsRecognized bool True if matched with one of FaceTemplate
    Template FaceTemplate Matched FaceTemplate

    Linux Java

    Description

    The SDK allows you to capture faces, evaluate gender, age group, emotions, and create face templates to compare them and find similarity percentages.

    Face templates can be compared to each other, one-to-one, or one-to-many using a collection of templates.

    Recognition Type

    There are two types of recognition:

    Fast

    Fast Recognition type is recommended in cases where the fastest recognition is needed and the accuracy of recognition is not as important. For example, this recognition type is great for video processing.

    Quality

    Quality Recognition type requires more processing time but the result is more accurate.

    Installation

    Download SDK package from developer portal. The archive contains following parts:

    Add FaceSDK-fast-x86-64-1.0.0.jar or FaceSDK-quality-x86-64-1.0.0.jar to the Java project as a regular java library.

    Requirements

    Software

    Facial Recognition SDK requires 64-bit JDK 8 or newer.

    Information about installation of JDK 8 on Linux can be found at oracle.com

    Hardware

    Minimal

    Facial Recognition API usage

    Analyze faces

    // 1. Create service instance.
    FacialRecognitionService srv = FacialRecognitionService.createInstance("LICENSE_KEY");
    // 2. Find faces.
    List<Face> faces = srv.findFaces(input);
    // 3. Analyze faces.
    for(Face f : faces) {
        FaceAnalytics analytics = srv.analyzeFace(f);  
        ...
    }
    

    For analyze faces on the image you need:

    1. Create instance of the Facial Recognition Service by calling FacialRecognitionService.createInstance(String licKey). As a result, you will get instance of the Facial Recognition Service that can be used to analyze faces on images.
    2. Find faces on the image by calling FacialRecognitionService.findFaces(Image image). As a result, you will get the set of faces that have been detected on the Image. Each entity in the set contains the basic information about the face such as position of eyes, position the face on the image and set of characteristic points.
    3. Analyze the faces by calling either FacialRecognitionService.analyzeFace(Face face) or FacialRecognitionService.analyzeFace(Face face, int flags). As a result, you will get advanced information about faces on the image such as emotions, age and gender.

    Matching faces

    For matching faces you need build Templates and TemplateIndexes. With Templates you can match faces each other. With TemplateIndexes you cat search one face in set of faces.

    // 1. Create service instance.
    FacialRecognitionService srv = FacialRecognitionService.createInstance("LICENSE_KEY");
    // 2. Find faces on the first photo.
    List<Face> faces1 = srv.findFaces(photo1);
    // 3. Find faces on the second photo.
    List<Face> faces2 = srv.findFaces(photo2);
    //4. Compare two faces.
    double distance = srv.compareFaces(faces1.get(0), faces2.get(0));
    

    For matching two faces each other you can either build Template for each face by calling FacialRecognitionService.buildTemplate(Face f) and then compare templates by calling compareFaces(Template first, Template second) or call compareFaces(Face first, Face second). In the second case templates for the faces will be build implicitly. As a result, you will get normal distance between two faces in range [0.0, 1.0]. The 0.0 value means the faces are similar, 1.0 value means the faces are different.

    // 1. Create service instance.
    FacialRecognitionService srv = FacialRecognitionService.createInstance("LICENSE_KEY");
    // 2. Create index builder.
    TemplateIndexBuilder<String> indexBuilder = srv.buildIndex();
    // 3. Add faces to index.
    List<Face> faces = ...;
    for(Face f : faces) {
      indexBuilder.add(f, "Some Name");
    }
    // 4. Build index.
    TemplateIndex<String> index = indexBuilder.build();
    // 5. Search face in index.
    Face face = ...;
    FaceMatch<String> match = index.search(f);
    

    For searching face in set of faces you need:

    1. Create TemplateIndexBuilder by calling FacialRecognitionService.buildIndex();
    2. Add one or more faces to the index by calling either TemplateIndexBuilder<T>.add(Face face, T data) or TemplateIndexBuilder<T>.add(Template template, T data). In the second case template will be build implicitly.
    3. Build TemplateIndex by calling TemplateIndexBuilder<T>.build().
    4. Search the face in the index by calling either TemplateIndex<T>.search(Face face) or TemplateIndex<T>.search(Template template). As a result, you will get FaceMatch structure.

    API references

    Samples

    SDK contains samples with source code. Runnable example can be found at [SdkPath]/example/bin. Source code of the example can be found at [SdkPath]/example-sources.

    Matching faces on group photo

    ./facesdk-example match --faces ./data/faces --photo ./data/group.jpg > ./data/group.json
    
    • --faces - directory with photos.
    • --photo - group photo.
    • stdout - result of matching.
    ./facesdk-example visualize --photo ./data/group.jpg  --input ./data/group.json --output ./data/result.png
    
    • --photo - group photo.
    • --input - result of match command.
    • --output - result image.

    match command matches faces from the specific directory with faces on the group photo. As a result, you will get description of matching faces in JSON format. You can visualize this JSON data by using visualize command.

    Comparing faces

    ./facesdk-example distance first_photo.jpg second_photo.jpg
    
    • first_photo.jpg - photo with first face.
    • second_photo.jpg - photo with second face.

    distance command compares two faces each other. As a result, you will get distance between two faces in range [0.0, 1.0], where 0.0 value means the faces are similar and 1.0 value means the faces are different.

    Web API

    Endpoint: http://faces.idscan.net/upload.php

    Token is required: “token”: “[Authentication Token]”

    Methods

    Analytics

    Upload one image in query body. Returns the analytics after uploading the image.

    POST-query example:

        POST /upload.php HTTP/1.1
        Host: faces.idscan.net
        Referer: http://faces.idscan.net/upload.php
        User-Agent: Mozilla
        Content-Type: multipart/form-data; boundary=-------------573cf973d5228
        Content-Length: 288
        Connection: keep-alive
        Keep-Alive: 300
    
        ---------------573cf973d5228
        Content-Disposition: form-data; name="file"; filename="1.jpg"
        Content-Type: image/jpeg
    
        Content file
        ---------------573cf973d5228--
    

    Compare 2 images

    Upload two images in query body. Returns match of the 2 images.

    POST-query example:

        POST /upload.php HTTP/1.1
        Host: faces.idscan.net
        Referer: http://faces.idscan.net/upload.php
        User-Agent: Mozilla
        Content-Type: multipart/form-data; boundary=-------------573cf973d5228
        Content-Length: 288
        Connection: keep-alive
        Keep-Alive: 300
    
        ---------------573cf973d5228
        Content-Disposition: form-data; name="file" filename="1.jpg"
    
        Content-Type: image/jpeg
    
    
        Content file
        ---------------573cf973d5228
        Content-Disposition: form-data; name="file2"; filename="2.jpg"
        Content-Type: image/jpeg
    
        Content file
        ---------------573cf973d5228--
    

    Live demo

    Live demo can be found at http://faces.idscan.net

    VIN Recognition Service

    Example

    Request:

    POST /vin HTTP/1.1
    Accept-Charset: UTF-8
    Content-Length: 60682
    Host: vin.idscan.net:9000
    X-Token: ""
    Content-Type: application/json
    {"image_base64":"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP..."}
    

    Response: json {"valid":[{"vin":"1J4GX48S51C589421"}],"invalid":[],"message":"The image size is too big. For best performance image size should be less than 1 megabyte.","status":0}

    Service endpoint URL: http://vin.idscan.net:9000/vin

    Service extracts all VIN-codes from picture as text.

    Upload base64-image in body of POST request, it returns the analytics after uploading the image as a JSON.

    Image size must be less than 10 megabytes.

    Response format:

    {"valid":[{"vin":"1J4GX48S51C589421"}],"invalid":[],"message":"","status":0}

    Section “valid” contains valid VIN codes.

    Section “invalid” contains invalid VIN codes or mistakes of recognition.

    Section “messages” contains error or warning messages.

    Field “status” is 0(zero) if service works, and the other digit if service has fallen.

    Live demo: http://vin.idscan.net