knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
The facerec package provides an interface to the Kairos Face Recognition API. The API detects faces in images and returns estimates for demographics like gender, ethnicity and age. It is also capable of recognizing and verifying humans across several images.
To install the CRAN version of facerec use
You can also download and install the latest development version of the app by running
devtools::install_github('methodds/facerec'). For Windows users installing from github requires proper setup of Rtools, for which a tutorial is available here.
After loading facerec you first need to initiate your authentification credentials. Kairos offers a free plan for API access. After signing up, you will receive an application id and an application key. Both credentials need to be set as environment variables before using the initialization function
Sys.setenv(kairos_id = "Your Kairos API id") Sys.setenv(kairos_key = "Your Kairos API key")
You only need to call
facerec_init() once after loading the package. In order to avoid entering your credentials for each session, you can permanently store them in your
.Renviron. I recommend
usethis::edit_r_environ() to find and edit your environment file.
The Kairos API accepts image of file type JPG, PNG, or BMP. Images can be passed to several facerec functions, either as an url string or a local image prepared with
prep_image(). In the following example,
detect() is used to recognize the face of the Star Wars character Finn:
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 recognized face in the input image. Variables include positional features of recognized 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 packages magick and ggplot2:
library(magick) library(ggplot2) library(scales) 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:', 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:', percent(face_black), 'Black')), size = 6, color = '#377eb8') + theme(legend.position="none")
Kairos has some recommendations to improve the quality of its recognition service, but in general, the API also works with multiple faces inside an image:
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, it is possible to permanently store face recognition data with the Kairos API. This allows to assign multiple images to subject ids and estimates about whether faces from different images belong to the same subjects:
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)
recognize() returns a dataframe including the probability of a match in the column
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.