Repository files navigation

This package provides an interface to theKairos Face RecognitionAPI. The API detects faces in imagesand returns estimates for demographics. It is also capable ofrecognizing and verifying humans across several images.

IMPORTANT NOTE: Kairos decided to shut down its online demo fordiversity recognition features (seehere).As of July 2018, the API still returns ethnicity annotations, but italso seems as if they will not provide free access anymore. For this reason this package is currently not being maintained and issues are not monitored.

To install the CRAN version of facerec useinstall.packages('facerec').

You can also download and install the latest development version of theapp by runningdevtools::install_github('cschwem2er/facerec'). ForWindows users installing from github requires proper setup ofRtools, for which atutorial is availablehere.

After loading facerec you first need to initiate your authentificationcredentials. Kairos offers afree planfor API access. After signing up, you will receive an application id andan application key. Both credentials need to be set as environmentvariables before using the initialization functionfacerec_init():

Sys.setenv(kairos_id="Your Kairos API id")Sys.setenv(kairos_key="Your Kairos API key")

library(facerec)facerec_init()

You only need to callfacerec_init() once after loading the package.In order to avoid entering your credentials for each session, you canpermanently store them in your.Renviron. I recommendusethis::edit_r_environ() to find and edit your environment file.

Kairos accepts image of file type JPG, PNG, or BMP. Images can be passedto several facerec functions, either as an url string or a local imageprepared withprep_image(). In the following example,detect() isused to recognize the face of the Star Wars characterFinn:

finn_image<-'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'finn_face<- detect(image=finn_image)

The function returns a dataframe with annotations for the recognizedface in the input image. Variables include positional features ofrecognized faces, such as x and y coordinates for eyes. Moreover,demographic attributes like gender, ethnicity and age are available.

Features can be visualized with the packagesmagick andggplot2:

library(magick)library(ggplot2)finn_image %>% image_read() %>% image_ggplot()+    geom_rect(data=finn_face,              aes(xmin=top_left_x,xmax=top_left_x+width,ymin=top_left_y,ymax=top_left_y+height),fill=NA,linetype='dashed',size=2,color='#377eb8')+   geom_label(data=finn_face,             aes(x=chin_tip_x,y=chin_tip_y+20,label= paste('Gender:',scales::percent(face_gender_male_confidence),'Male')),size=6,color='#377eb8')+   geom_label(data=finn_face,             aes(x=chin_tip_x,y=chin_tip_y+60,label= paste('Ethnicity:',scales::percent(face_black),'Black')),size=6,color='#377eb8')+   theme(legend.position="none")

Kairos hassomerecommendations toimprove the quality of its recognition service, but in general, the APIalso works with multiple faces inside animage:

sw_img<-"https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg"sw_faces<- detect(sw_img)sw_img %>% image_read() %>% image_ggplot()+    geom_rect(data=sw_faces,              aes(xmin=top_left_x ,xmax=top_left_x+width,ymin=top_left_y,ymax=top_left_y+height,color=factor(face_id)),fill=NA,linetype='dashed',size=2)+   geom_label(data=sw_faces,             aes(x=chin_tip_x,y=chin_tip_y+15,label=face_gender_type,color=factor(face_id)),size=8)+   theme(legend.position="none")

Besides annotating faces in single images, face recognition data can bestored permantly with the Kairos. This allows to assign multiple imagesto subject ids and to provide estimates about whether faces fromdifferent images belong to the samesubjects.

finn_face<- enroll(image=finn_image,subject_id='finn',gallery='starwars')finn_new<-'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg'finn_rec<- recognize(image=finn_new,gallery='starwars',show_candidate_images=FALSE)

The functionrecognize() returns a dataframe including the probabilityof a match in the columnconfidence.

If you use facerec for your publications please consider citingit:

  Carsten Schwemmer (2018). facerec: An interface for face recognition in R. R package version 0.1.0.  https://github.com/cschwem2er/facerec

A BibTeX entry for LaTeX users is:

  @Manual{,    title = {facerec: An interface for face recognition in R},    author = {Carsten Schwemmer},    year = {2018},    note = {R package version 0.1.0},    url = {https://github.com/cschwem2er/facerec},  }