Type: Package
Title: An Interface for Face Recognition
Version: 0.1.0
Date: 2018-05-14
URL: https://github.com/methodds/facerec
BugReports: https://github.com/methodds/facerec/issues
Description: Provides an interface to the 'Kairos' Face Recognition API https://kairos.com/face-recognition-api. The API detects faces in images and returns estimates for demographics like gender, ethnicity and age.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
RoxygenNote: 6.0.1
Imports: magrittr (≥ 1.5.0), dplyr (≥ 0.7.0), httr (≥ 1.3.0), jsonlite (≥ 1.5.0), knitr (≥ 1.2.0), stringr (≥ 1.2.0), snakecase (≥ 0.9.0), rlang
Suggests: magick (≥ 1.9.0), ggplot2 (≥ 2.2.0), purrr (≥ 0.2.0), rmarkdown (≥ 1.9.0)
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2018-05-14 11:45:43 UTC; cs
Author: Carsten Schwemmer ORCID iD [aut, cre]
Maintainer: Carsten Schwemmer <c.schwem2er@gmail.com>
Repository: CRAN
Date/Publication: 2018-05-14 12:19:21 UTC

Pipe operator

Description

Pipe operator

Usage

lhs %>% rhs

detect faces

Description

Detect faces in an input image and return annotations from the 'Kairos' API.

Usage

detect(image, min_head_scale = 0.015)

Arguments

image

An image of file type 'JPG', 'PNG', or 'BMP'. Can either be an url string or a local image processed with prep_image.

min_head_scale

Set the ratio of the smallest face to look for in the input image. Accepts a value between .015 (1:64 scale) and .5 (1:2 scale).

Value

A data frame with annotations for each detected face.

Examples



 facerec_init()

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

 # multiple images
 sw_image <- 'https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg'
 padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png'

 faces <- c(finn_image, sw_image, padme_image) %>%
 purrr::map(detect) %>% dplyr::bind_rows()

enroll faces

Description

Enroll face in an input image to a gallery and assign a subject id.

Usage

enroll(image, subject_id, gallery, min_head_scale = 0.015)

Arguments

image

An image of file type 'JPG', 'PNG', or 'BMP'. Can either be an url string or a local image processed with prep_image.

subject_id

A string containing the id to assign for the person in the enrolled image.

gallery

A string containing the name of the gallery in which the image will be enrolled.

min_head_scale

Set the ratio of the smallest face to look for in the input image. Accepts a value between .015 (1:64 scale) and .5 (1:2 scale).

Value

A data frame with annotations for the enrolled image.

Examples



facerec_init()

finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')

authorization

Description

Initializes the authorization credentials for the 'Kairos' Face Recognition API. Needs to be called before using any other functions of facerec and requires kairos_id and kairos_key as environment variables.

Usage

facerec_init()

Value

nothing.

Examples

## Not run: 
Sys.setenv(kairos_id = "Your Kairos API id")
Sys.setenv(kairos_key = "Your Kairos API key")

facerec_init()

## End(Not run)

list galleries

Description

Returns identifiers for all galleries associated with a 'Kairos' application.

Usage

get_galleries()

Value

A vector of gallery id's.

Examples



facerec_init()

# enroll
finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
first_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
second_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'more_starwars')

# get_galleries
get_galleries()

Description

Returns all subject id's associated with a gallery.

Usage

get_gallery_subjects(gallery)

Arguments

gallery

The gallery in which the subjects are enrolled.

Value

A vector of subject id's

Examples



facerec_init()

# enroll
finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')

# view subjects
get_gallery_subjects(gallery = 'starwars')

prepare local image

Description

Prepares a local image for an upload the 'Kairos' API via detect, enroll, recognize and verify.

Usage

prep_image(img_file)

Arguments

img_file

Path to an image of file type 'JPG', 'PNG', or 'BMP'.

Value

The prepared image object.

Examples

 

 facerec_init()

 # download example image
 finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
 temp_img_path <- tempfile(fileext = '.png')
 download.file(finn_image, temp_img_path, mode = 'wb', quiet = TRUE)

 # prepare image
 finn_local <- prep_image(temp_img_path)

 # use prepared image
 faces <- detect(image = finn_local)

recognize face

Description

Recognize faces in an image and return the most likely matches from a gallery.

Usage

recognize(image, gallery, min_head_scale = 0.015, threshold = 0.6,
  max_num_results = 10, show_candidate_images = TRUE)

Arguments

image

An image of file type JPG, PNG, or BMP. Can either be an url string or a local image processed with prep_image.

gallery

A string containing the name of the gallery in which the image will be enrolled.

min_head_scale

Set the ratio of the smallest face to look for in the input image. Accepts a value between .015 (1:64 scale) and .5 (1:2 scale).

threshold

Likelihood (between 0 and 1) used to determine a valid facial match. Defaults to 0.6.

max_num_results

The maximum number of potential matches that are returned. Defaults to 10.

show_candidate_images

Whether to return temporary URLs for each potential match. Defaults to TRUE.

Value

A dataframe with the potential matches for the input image. The likelihood of matches is given in column confidence.

Examples

 

facerec_init()

# enroll
finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png'
finn_face <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars')

# recognize
finn_2 <- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg'
finn_rec <- recognize(image = finn_2, gallery = 'starwars')

Description

Removes a gallery and all included subjects.

Usage

remove_gallery(gallery)

Arguments

gallery

The name of the gallery to be removed.

Value

nothing.

Examples




facerec_init()

# enroll
finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')

# remove gallery
remove_gallery(gallery = 'starwars')

remove subject

Description

Removes a subject from a gallery.

Usage

remove_subject(subject_id, gallery)

Arguments

subject_id

The subject id for the subject to be removed.

gallery

The name of the gallery in which the subject is enrolled.

Value

nothing.

Examples



facerec_init()

# enroll
finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')

# remove subject
remove_subject(subject_id = 'finn', gallery = 'starwars')

verify face

Description

Verify whether face in an input image belongs to a subject in a gallery.

Usage

verify(image, subject_id, gallery)

Arguments

image

An image of file type 'JPG', 'PNG', or 'BMP'. Can either be an url string or a local image processed with prep_image.

subject_id

A string containing the id for the person in the gallery to be verified.

gallery

A string containing the name of the gallery in which the subject will be verified.

Value

A data frame with the verification annotations for the input image. The likelihood of a match is given in column confidence.

Examples




facerec_init()

# enroll
padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png'
padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars')

# verify
amidala_img <- 'https://upload.wikimedia.org/wikipedia/it/5/5e/Padm%C3%A9_Amidala.png'
verified <- verify(image = amidala_img, subject_id = 'padme', gallery = 'starwars')

view subject

Description

Returns all face id's for each image enrolled for a given subject in a gallery.

Usage

view_subject(subject_id, gallery)

Arguments

subject_id

The subject id for which to return all face id's.

gallery

The gallery in which the subject is enrolled.

Value

A dataframe with face id's and enrollment timestamps associated with the input subject.

Examples



facerec_init()

# enroll
finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')

# view subject
view_subject(subject_id = 'finn', gallery = 'starwars')