Kairos SDK (Android)

Kairos is the easist way add Face-Recognition to your Android apps. Our API provides a full-featured and robust Face-Recognition backend, right out of the box. This is the Android client for the Kairos Facial Recognition API. The package includes both the SDK .jar file, as well as an example app project (IntelliJ IDEA). Continue reading to learn how to integrate Kairos into your Android apps.

We also have official SDKs for iOS, Javascript and PHP.

*Thanks to fan contributions, we also have unofficial wrappers for Ruby and .NET. do

What You'll Need

An Android app project
Internet connectivity for your device or emulator

Limitations in this Version

This is an early version and has a few limitations. First of which, the SDK is bundled with the loopj network library (v 1.4.6) and will cause conflicts if your android app also uses loopj. Please use a different network library to avoid conflicts, if possible. Secondly, this version does not provide any camera views for image capture -- although this feature is on the roadmap for a near-future update. Finally, the example app project included was built using an IDE called IntelliJ IDEA. If you use a different IDE you'll need to move the source code files manually into your project.

How to do a Quick Demo

If you just want to do a quick test run, open the example app project (Intellij IDEA) that is included with the SDK and follow these steps:

Create your free developer account
Log into the Kairos Developer Dashboard
Create an application and copy your App Id & App Key
Paste them into the lines above the authentication method in MyActivity.java
Run the app on your device, and watch for the API response in the log output.

How to Install Kairos in your own App

Create your free Kairos developer account if you don't already have one.
Log into the dashboard and create a new app.
Copy your App ID & App Key (you'll need them later).
Download the SDK and unzip the package.
Navigate to the 'libs' folder which contains the SDK library file KairosSDK.jar.
Add the SDK library file (KairosSDK.jar) into your Android project.
Import the library files wherever you want to use the SDK

import com.kairos.*;

Authenticate Once

Before you can make API calls you'll need to create a Kairos object and set your credentials App Id and App Key (You only need to do this once). Add your App Id and App Key into the setAuthentication() method like so:

// instantiate a new kairos instance
Kairos myKairos = new Kairos();

// set authentication
String app_id = "your_app_id";
String api_key = "your_application_key";
myKairos.setAuthentication(this, app_id, api_key);

The KairosListener

Before we can start calling methods, we'll need a place to receive notifications and data when the methods return. For this purpose, the SDK provides a listener class to return the results of all asynchronous method calls. A Kairos listener is like a callback method. Instantiate a listener like so, and pass the instance into your desired kairos method. You can add your own code inside of the provided success and fail code blocks and use the provided response object as you like:

// Create an instance of the KairosListener
KairosListener listener = new KairosListener() {

  @Override
  public void onSuccess(String response) {
     // your code here!
     Log.d("KAIROS DEMO", response);
  }

  @Override
  public void onFail(String response) {
     // your code here!
     Log.d("KAIROS DEMO", response);
  }
};

The Detect Method

The detect method returns you detailed information on face attributes for any images you send it. It can provide you with coordinates of features such as eyes, nose, mouth, etc. See the examples below:

###Parameters:

Bitmap image, or String image
String selector (optional: can be null)
String minHeadScale (optional: can be null)
KairosListener listener
(See the API Docs for details on what the parameters do)

###Returns:

String response (face attribute data)

###Example Usage:

// Bare-essentials Example:
// This example uses only an image url, setting optional params to null
String image = "http://media.kairos.com/liz.jpg";
myKairos.detect(image, null, null, listener);


// Fine-grained Example:  
// This example uses a bitmap image and also optional parameters
Bitmap image = BitmapFactory.decodeResource(getResources(), R.drawable.liz);
String selector = "FULL";
String minHeadScale = "0.25"; 
myKairos.detect(image, selector, minHeadScale, listener);

The Enroll Method

The enroll methods let you register a face for later recognition. You can enroll a new face, or enroll different photos of an already enrolled for better recognition accuracy. See the examples below: ###Parameters:

Bitmap image, or String image
String galleryId
String subjectId
String selector (optional: can be null)
String multipleFaces (optional: can be null)
String minHeadScale (optional: can be null)
KairosListener listener
(See the API Docs for details on what the parameters do)

###Returns:

String response (details of the enroll request)

###Example Usage:

// Bare-essentials Example:
// This example uses only an image url, setting optional params to null
String image = "http://media.kairos.com/liz.jpg";
String subjectId = "Elizabeth";
String galleryId = "friends";
myKairos.enroll(image, subjectId, galleryId, null, null, null, listener);
            
         
// Fine-grained Example:     
// This example uses a bitmap image and also optional parameters
Bitmap image = BitmapFactory.decodeResource(getResources(), R.drawable.liz);
String subjectId = "Elizabeth";
String galleryId = "friends";
String selector = "FULL";
String multipleFaces = "false";
String minHeadScale = "0.25";
myKairos.enroll(image, 
				subjectId, 
				galleryId, 
				selector, 
				multipleFaces, 
				minHeadScale, 
				listener);

The Recognize Method

The recognize method attempts to recognize an image against a specified gallery, and returns a list of subjectIds and their confidence values as possible matches. For best recognition accuracy, it's reccomended that you have multiple enrollments (different images) per face. See examples below:

###Parameters:

Bitmap image, or String image
String galleryId
String selector (optional: can be null)
String threshold (optional: can be null)
String minHeadScale (optional: can be null)
String maxNumResults (optional: can be null)
KairosListener listener
(See the API Docs for details on what the parameters do)

###Returns:

String response (list of possible matching subjects and their confidence values)

###Example Usage:

// Bare-essentials Example:
// This example uses only an image url, setting optional params to null
String image = "http://media.kairos.com/liz.jpg";
String galleryId = "friends";
myKairos.recognize(image, galleryId, null, null, null, null, listener);
            
        
// Fine-grained Example:    
// This example uses a bitmap image and also optional parameters
Bitmap image = BitmapFactory.decodeResource(getResources(), R.drawable.liz);
String galleryId = "friends";
String selector = "FULL";
String threshold = "0.75";
String minHeadScale = "0.25";
String maxNumResults = "25";
myKairos.recognize(image, 
				    galleryId, 
				    selector, 
				    threshold, 
				    minHeadScale, 
				    maxNumResults, 
				    listener);

List All Galleries

This method lists out all galleries you have created.

###Parameters:

KairosListener listener

###Returns:

String response (list of all galleries)

###Example Usage:

// List out all your galleries
myKairos.listGalleries(listener);

List All Subjects in a Gallery

This method lists out all subjects enrolled in a given gallery.

###Parameters:

String galleryId
KairosListener listener

###Returns:

String response (list of all subjects in a given gallery)

###Example Usage:

// List out all subjects in a given gallery
String galleryId = "friends";
myKairos.listSubjectsForGallery(galleryId, listener);

Delete a Gallery

This method deletes a given gallery and all of its subjects.

###Parameters:

String galleryId
KairosListener listener

###Returns:

String response (confirmation of the results of the request)

###Example Usage:

// List out all subjects in a given gallery
String galleryId = "friends";
myKairos.deleteGallery(galleryId, listener);

Delete a Subject from a Gallery

This method deletes a given subject. All enrollments for the given subject will be removed from the gallery.

###Parameters:

String subjectId
String galleryId
KairosListener listener

###Returns:

String response (confirmation of the results of the request)

###Example Usage:

// List out all subjects in a given gallery
String subjectId = "Tyrion";
String galleryId = "friends";
myKairos.deleteSubject(subjectId, galleryId, listener);

View the Examples

Also see provided examples included in the example project. It contains clear examples on how to use all of the available methods in the file MyActivity.java. Just make sure to plug in your application credentials (Create an account if you don't have one). Also, check out the API documentation at https://www.kairos.com/docs/face-recognition

Source Code

Note: We have added the raw source code to the SDK so that you can make any changes / modifications as needed. In the future we plan to add better documentation around the source code, build instructions, etc. but we wanted to get it out there as soon as possible as requested by a number of our customers. Feel free to use / modify / redistribute this as needed in your apps.

If you see anything you'd like to change, fix, etc. please feel free to submit a pull request, that we will happily accept.

##Support Have an issue? Visit our Support page or create an issue on GitHub

kairosinc/Kairos-SDK-Android

Kairos SDK (Android)

What You'll Need

Limitations in this Version

How to do a Quick Demo

How to Install Kairos in your own App

Authenticate Once

The KairosListener

The Detect Method

The Enroll Method

The Recognize Method

List All Galleries

List All Subjects in a Gallery

Delete a Gallery

Delete a Subject from a Gallery

View the Examples

Source Code