Documentation :: Code Example

Overview

Following is a code sample for training and recognizing faces using the face.com API. It starts by defining and training the index with 3 new users, and then attempts to search for them within untagged photos, printing out success whenever a user is found in a photo.

This code is the core for driving the site celebrityfindr.com, without the bells & whistles...

Training the index

In this example we're using private namespace users we just made up for this test. For each user, we obtain a list of photo URLs that he or she appears in. These could be tagged photos from facebook, a folder of photos on a local storage, or photos from any photo sharing sites (implementation for obtaining user photo URLs is left open for this example). The training-set photos are then processed through face detection to obtain the tag IDs, and then added to the face.com index:

function train(&$api, $uid)
{
    //obtain photos where this uid appears in (limit to 30)
    $urls = getTrainingUrls($uid);
    $urls = array_splice($urls, 0, 30);
    //run face detection on all images
    $tags = $api->faces_detect($urls);
    if (empty($tags->photos))
        return false;
    //build a list of tag ids for training
    $tids = array();
    foreach ($tags->photos as $photo)
    {
        //skip errors
        if (empty($photo->tags))
            continue;
        //skip photos with multiple faces (want to make sure only the uid appears)
        if (count($photo->tags) > 1)
            continue;
        $tid = $photo->tags[0]->tid;
        $tids[] = $tid;
    }
    //if faces were detected, save them for this uid
    if (count($tids) > 0)
        $api->tags_save($tids, $uid, $uid);
    //train the index with the newly saved tags
    $api->faces_train($uid);
    //all done, recognition for $uid can now begin
    return true;
}

Calling this training method looks like this (only needs to be called once for these UIDs):

//initialize API object with API key and Secret
$api = new FaceRestClient($yourApiKey, $yourApiSecret);
//the list of private-namespace UIDs to train and search for
$uids = array("john.doe@mynamespace.com", "jane.doe@mynamespace.com", "elmer@mynamespace.com");
//train the face.com index with the new uids
foreach ($uids as $uid)
    train($api, $uid);

Searching faces in photos

Now that we've got our users in the index, let's find them in photos:

function search(&$api, $uids)
{
    //obtain list of photos to search in
    $photoUrls = getPhotoUrls();
    $urls = array();
    $count = 0;
    foreach ($photoUrls as $photoUrl)
    {
        //max photos per recognition call is 30, so break photos to groups if needed
        $urls[] = $photoUrl;
        $count++;
        if (($count % 30) == 0 || $count == count($photoUrls))
        {
            $response = $api->faces_recognize($urls, $uids);
            foreach ($response->photos as $photo)
            {
                //skip empty tags and errors
                if (empty($photo->tags))
                    continue;
                $url = $photo->url;
                //echo all found tags
                foreach ($photo->tags as $tag)
                {
                    if (!empty($tag->uids))
                    {
                        //only interested in highest score for this tag
                        $uid = $tag->uids[0]->uid;
                        $conf = $tag->uids[0]->confidence;
                        //only print if confidence is higher than recommended threshold
                        if ($conf >= $tag->threshold)
                            echo "$uid was found in url $url ($conf % confidence)n";
                    }
                }
            }
            $urls = array();
        }
    }
}

Calling the search method (Can be called multiple times on any set of photos):

//initialize API object with API key and Secret
$api = new FaceRestClient($yourApiKey, $yourApiSecret);
//the list of private-namespace UIDs to train and search for
$uids = array("john.doe@mynamespace.com", "jane.doe@mynamespace.com", "elmer@mynamespace.com");
//search in untagged photos for these uids
search($api, $uids);

Putting it all together

Here's how the final code would look like:

<?php
//load the client PHP library
require_once(__DIR__ . "/FaceRestClient.php");
//initialize API object with API key and Secret
$api = new FaceRestClient($yourApiKey, $yourApiSecret);
//the list of private-namespace UIDs to train and search for
$uids = array("john.doe@mynamespace.com", "jane.doe@mynamespace.com", "elmer@mynamespace.com");
//train the face.com index with the new uids (need to be called only once)
foreach ($uids as $uid)
    train($api, $uid);
//search in untagged photos for these uids (can be called multiple times)
search($api, $uids);
/*
    adds the passed uid to the face.com index
*/
function train(&$api, $uid)
{
    //obtain photos where this uid appears in (limit to 30)
    $urls = getTrainingUrls($uid);
    $urls = array_splice($urls, 0, 30);
    //run face detection on all images
    $tags = $api->faces_detect($urls);
    if (empty($tags->photos))
        return false;
    //build a list of tag ids for training
    $tids = array();
    foreach ($tags->photos as $photo)
    {
        //skip errors
        if (empty($photo->tags))
            continue;
        //skip photos with multiple faces (want to make sure only the uid appears)
        if (count($photo->tags) > 1)
            continue;
        $tid = $photo->tags[0]->tid;
        $tids[] = $tid;
    }
    //if faces were detected, save them for this uid
    if (count($tids) > 0)
        $api->tags_save($tids, $uid, $uid);
    //train the index with the newly saved tags
    $api->faces_train($uid);
    //all done, recognition for $uid can now begin
    return true;
}
/*
    searches for uids within photos
*/
function search(&$api, $uids)
{
    //obtain list of photos to search in
    $photoUrls = getPhotoUrls();
    $urls = array();
    $count = 0;
    foreach ($photoUrls as $photoUrl)
    {
        //max photos per recognition call is 30, so break photos to groups if needed
        $urls[] = $photoUrl;
        $count++;
        if (($count % 30) == 0 || $count == count($photoUrls))
        {
            $response = $api->faces_recognize($urls, $uids);
            foreach ($response->photos as $photo)
            {
                //skip empty tags and errors
                if (empty($photo->tags))
                    continue;
                $url = $photo->url;
                //echo all found tags
                foreach ($photo->tags as $tag)
                {
                    if (!empty($tag->uids))
                    {
                        //only interested in highest score for this tag
                        $uid = $tag->uids[0]->uid;
                        $conf = $tag->uids[0]->confidence;
                        //only print if confidence is higher than recommended threshold
                        if ($conf >= $tag->threshold)
                            echo "$uid was found in url $url ($conf % confidence)n";
                    }
                }
            }
            $urls = array();
        }
    }
}
function getTrainingUrls($uid)
{
    //return an array of urls pointing to known photos of the uid
    return array();
}
function getPhotoUrls()
{
    //return an array of urls pointing to any photos on the web
    //to search in for the trained $uids
    return array();
}
?>