├── .Rbuildignore ├── .gitignore ├── .travis.yml ├── DESCRIPTION ├── LICENSE ├── LICENSE.md ├── NAMESPACE ├── NEWS.md ├── R ├── detect.R ├── enroll.R ├── facerec_init.R ├── get_galleries.R ├── get_gallery_subjects.R ├── kairos_api.R ├── prep_image.R ├── recognize.R ├── remove_gallery.R ├── remove_subject.R ├── utils-pipe.R ├── verify.R ├── view_subject.R └── zzz.R ├── README.Rmd ├── README.md ├── _pkgdown.yaml ├── appveyor.yml ├── cran-comments.md ├── docs ├── LICENSE-text.html ├── LICENSE.html ├── articles │ ├── index.html │ └── intro.html ├── authors.html ├── docsearch.css ├── docsearch.js ├── index.html ├── link.svg ├── man │ └── figures │ │ ├── finn_facerec.png │ │ └── sw_facerec.png ├── news │ └── index.html ├── pkgdown.css ├── pkgdown.js ├── pkgdown.yml └── reference │ ├── detect.html │ ├── enroll.html │ ├── facerec_init.html │ ├── figures │ ├── finn_facerec.png │ └── sw_facerec.png │ ├── get_galleries.html │ ├── get_gallery_subjects.html │ ├── index.html │ ├── pipe.html │ ├── prep_image.html │ ├── recognize.html │ ├── remove_gallery.html │ ├── remove_subject.html │ ├── verify.html │ └── view_subject.html ├── facerec.Rproj ├── man ├── detect.Rd ├── enroll.Rd ├── facerec_init.Rd ├── figures │ ├── finn_facerec.png │ └── sw_facerec.png ├── get_galleries.Rd ├── get_gallery_subjects.Rd ├── pipe.Rd ├── prep_image.Rd ├── recognize.Rd ├── remove_gallery.Rd ├── remove_subject.Rd ├── verify.Rd └── view_subject.Rd └── vignettes └── intro.Rmd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^LICENSE\.md$ 4 | ^cran-comments\.md$ 5 | ^README\.Rmd$ 6 | ^README-.*\.png$ 7 | ^\.travis\.yml$ 8 | ^appveyor\.yml$ 9 | ^docs$ 10 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | .Ruserdata 5 | inst/doc 6 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | # R for travis: see documentation at https://docs.travis-ci.com/user/languages/r 2 | 3 | language: R 4 | sudo: true 5 | cache: packages 6 | dist: trusty 7 | 8 | before_install: 9 | - sudo apt-get install libmagick++-dev 10 | 11 | env: 12 | global: 13 | - R_CHECK_ARGS="--no-build-vignettes --no-manual" 14 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: facerec 2 | Type: Package 3 | Title: An Interface for Face Recognition 4 | Version: 0.1.0 5 | Date: 2018-05-14 6 | Authors@R: person("Carsten", "Schwemmer", email = "c.schwem2er@gmail.com", comment = c(ORCID = "0000-0001-9084-946X"), role = c("aut", "cre")) 7 | URL: https://github.com/cschwem2er/facerec 8 | BugReports: https://github.com/cschwem2er/facerec/issues 9 | Description: Provides an interface to the 'Kairos' Face Recognition API . The API detects faces in images and returns estimates for demographics. 10 | License: MIT + file LICENSE 11 | Encoding: UTF-8 12 | LazyData: true 13 | RoxygenNote: 6.1.0 14 | Imports: 15 | magrittr (>= 1.5.0), 16 | dplyr (>= 0.7.0), 17 | httr (>= 1.3.0), 18 | jsonlite (>= 1.5.0), 19 | knitr (>= 1.2.0), 20 | stringr (>= 1.2.0), 21 | snakecase (>= 0.9.0), 22 | rlang 23 | Suggests: magick (>= 1.9.0), 24 | ggplot2 (>= 3.0.0), 25 | purrr (>= 0.2.0), 26 | rmarkdown (>= 1.9.0) 27 | VignetteBuilder: knitr 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | YEAR: 2018 2 | COPYRIGHT HOLDER: Carsten Schwemmer 3 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # MIT License 2 | 3 | Copyright (c) 2018 Carsten Schwemmer 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | export("%>%") 4 | export(detect) 5 | export(enroll) 6 | export(facerec_init) 7 | export(get_galleries) 8 | export(get_gallery_subjects) 9 | export(prep_image) 10 | export(recognize) 11 | export(remove_gallery) 12 | export(remove_subject) 13 | export(verify) 14 | export(view_subject) 15 | importFrom(dplyr,as_tibble) 16 | importFrom(dplyr,mutate) 17 | importFrom(dplyr,select) 18 | importFrom(dplyr,tibble) 19 | importFrom(httr,GET) 20 | importFrom(httr,POST) 21 | importFrom(httr,add_headers) 22 | importFrom(httr,content) 23 | importFrom(httr,http_type) 24 | importFrom(httr,modify_url) 25 | importFrom(httr,user_agent) 26 | importFrom(jsonlite,fromJSON) 27 | importFrom(knitr,image_uri) 28 | importFrom(magrittr,"%>%") 29 | importFrom(rlang,set_names) 30 | importFrom(snakecase,to_snake_case) 31 | importFrom(stringr,str_replace) 32 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | # facerec 0.1.0 2 | 3 | * First release of the facerec package. 4 | -------------------------------------------------------------------------------- /R/detect.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title detect faces 3 | #' @name detect 4 | #' @description 5 | #' Detect faces in an input image and return annotations from the 'Kairos' API. 6 | #' @param image 7 | #' An image of file type 'JPG', 'PNG', or 'BMP'. 8 | #' Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}. 9 | #' @param min_head_scale 10 | #' 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). 11 | #' @return 12 | #' A data frame with annotations for each detected face. 13 | #' @export 14 | #' 15 | #' @examples 16 | #' \donttest{ 17 | #' 18 | #' facerec_init() 19 | #' 20 | #' # one image 21 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 22 | #' faces <- detect(image = finn_image) 23 | #' 24 | #' # multiple images 25 | #' sw_image <- 'https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg' 26 | #' padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png' 27 | #' 28 | #' faces <- c(finn_image, sw_image, padme_image) %>% 29 | #' purrr::map(detect) %>% dplyr::bind_rows() 30 | #' } 31 | #' 32 | #' 33 | #' 34 | detect <- function(image, min_head_scale = 0.015) { 35 | 36 | if (is(image, 'rfaces_image')) { 37 | name <- image$name 38 | image <- image$content 39 | } 40 | 41 | else { 42 | name <- image 43 | } 44 | 45 | kairos_data <- post_kairos(path = '/detect', 46 | params = list(image = image, 47 | minHeadScale = min_head_scale)) 48 | kairos_data$image <- name 49 | 50 | 51 | faces <- parse_kairos(kairos_data) 52 | return(faces) 53 | 54 | } 55 | 56 | -------------------------------------------------------------------------------- /R/enroll.R: -------------------------------------------------------------------------------- 1 | 2 | 3 | #' @title enroll faces 4 | #' @name enroll 5 | #' @description 6 | #' Enroll face in an input image to a gallery and assign a subject id. 7 | #' @param image 8 | #' An image of file type 'JPG', 'PNG', or 'BMP'. 9 | #' Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}. 10 | #' @param subject_id A string containing the id to assign for the person in the enrolled image. 11 | #' @param gallery A string containing the name of the gallery in which the image will be enrolled. 12 | #' @param min_head_scale 13 | #' 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). 14 | #' 15 | #' @return 16 | #' A data frame with annotations for the enrolled image. 17 | #' @export 18 | #' 19 | #' @examples 20 | #' \donttest{ 21 | #' 22 | #' facerec_init() 23 | #' 24 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 25 | #' finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 26 | #' } 27 | #' 28 | #' 29 | enroll <- function(image, subject_id, gallery, min_head_scale = 0.015) { 30 | 31 | if (is(image, 'rfaces_image')) { 32 | name <- image$name 33 | image <- image$content 34 | } 35 | 36 | else { 37 | name <- image 38 | } 39 | 40 | kairos_data <- post_kairos(path = '/enroll', 41 | params = list(image = image, 42 | subject_id = subject_id, 43 | gallery_name = gallery, 44 | minHeadScale = min_head_scale)) 45 | kairos_data$image <- name 46 | 47 | 48 | faces <- parse_kairos(kairos_data) 49 | return(faces) 50 | 51 | } 52 | -------------------------------------------------------------------------------- /R/facerec_init.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title authorization 3 | #' @name facerec_init 4 | #' @description 5 | #' Initializes the authorization credentials for the 'Kairos' Face Recognition API. 6 | #' Needs to be called before using any other functions of \code{facerec} and requires \code{kairos_id} and \code{kairos_key} as environment variables. 7 | #' @return nothing. 8 | #' @export 9 | #' 10 | #' @examples 11 | #' \dontrun{ 12 | #' Sys.setenv(kairos_id = "Your Kairos API id") 13 | #' Sys.setenv(kairos_key = "Your Kairos API key") 14 | #' 15 | #' facerec_init() 16 | #' } 17 | #' 18 | #' 19 | #' 20 | #' 21 | 22 | 23 | facerec_init <- function() { 24 | 25 | kairos_id <- Sys.getenv('kairos_id') 26 | kairos_key <- Sys.getenv('kairos_key') 27 | 28 | #.facerec <- NULL 29 | #.facerec <<- new.env(parent = emptyenv()) 30 | 31 | if (kairos_id == '' | kairos_key == '') { 32 | stop('facerec: could not load authorization credentials from Sys env.') 33 | } 34 | header <- c('app_id' = kairos_id, 'app_key' = kairos_key, 35 | 'Content-type' = 'application/json') 36 | message('Succesfully initialized authentification credentials.') 37 | assign("init", header, envir = .facerec) 38 | 39 | } 40 | -------------------------------------------------------------------------------- /R/get_galleries.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title list galleries 3 | #' @name get_galleries 4 | #' @description 5 | #' Returns identifiers for all galleries associated with a 'Kairos' application. 6 | #' 7 | #' @return A vector of gallery id's. 8 | #' @export 9 | #' 10 | #' @examples 11 | #' \donttest{ 12 | #' 13 | #' facerec_init() 14 | #' 15 | #' # enroll 16 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 17 | #' first_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 18 | #' second_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'more_starwars') 19 | #' 20 | #' # get_galleries 21 | #' get_galleries() 22 | #' } 23 | #' 24 | #' 25 | get_galleries <- function() { 26 | 27 | url <- kairos_api(path = '/gallery/list_all') 28 | resp <- POST(url, encode = 'json', 29 | add_headers(.headers = .facerec$init )) 30 | ids <- fromJSON(content(resp, 'text'))$gallery_ids 31 | return(ids) 32 | 33 | } 34 | -------------------------------------------------------------------------------- /R/get_gallery_subjects.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title get gallery subjects 3 | #' @name get_gallery_subjects 4 | #' @description 5 | #' Returns all subject id's associated with a gallery. 6 | #' @param gallery The gallery in which the subjects are enrolled. 7 | #' 8 | #' @return A vector of subject id's 9 | #' @export 10 | #' 11 | #' @examples 12 | #' \donttest{ 13 | #' 14 | #' facerec_init() 15 | #' 16 | #' # enroll 17 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 18 | #' finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 19 | #' 20 | #' # view subjects 21 | #' get_gallery_subjects(gallery = 'starwars') 22 | #' } 23 | #' 24 | #' 25 | get_gallery_subjects <- function(gallery) { 26 | 27 | url <- kairos_api(path = '/gallery/view') 28 | params <- list(gallery_name = gallery) 29 | resp <- POST(url, body = params, encode = 'json', 30 | add_headers(.headers = .facerec$init )) 31 | subject_ids <- fromJSON(content(resp, 'text'))$subject_ids 32 | return(subject_ids) 33 | 34 | } 35 | -------------------------------------------------------------------------------- /R/kairos_api.R: -------------------------------------------------------------------------------- 1 | #' @importFrom dplyr select mutate tibble as_tibble 2 | #' @importFrom httr modify_url GET POST user_agent add_headers http_type content 3 | #' @importFrom jsonlite fromJSON 4 | #' @importFrom stringr str_replace 5 | #' @importFrom rlang set_names 6 | #' @importFrom snakecase to_snake_case 7 | #' 8 | #' 9 | 10 | ## quiets concerns of R CMD check for non standard evaluation 11 | utils::globalVariables(c( ".facerec", "is", ".")) 12 | 13 | kairos_api <- function(path) { 14 | # change url according to api endpoint 15 | modify_url("https://api.kairos.com", path = path) 16 | } 17 | 18 | 19 | 20 | post_kairos <- function(path, params) { 21 | # post request to kairos api 22 | url <- kairos_api(path = path) 23 | response <- POST(url, body = params, encode = 'json', 24 | user_agent('http://github.com/methodds/facerec'), 25 | add_headers(.headers = .facerec$init)) 26 | 27 | if (http_type(response) != "application/json") { 28 | stop("API did not return json", call. = FALSE) 29 | } 30 | 31 | structure( 32 | list(content = response), 33 | class = "kairos_data") 34 | 35 | } 36 | 37 | 38 | parse_kairos <- function(kairos_data) { 39 | # parse data from the kairos API 40 | data <- fromJSON(content(kairos_data$content, 'text'), flatten = TRUE) 41 | if ('Errors' %in% names(data)) { 42 | code <- data$Errors[[1]] 43 | message <- data$Errors[[2]] 44 | cat(paste0('Error for source "', kairos_data$image, '": ', message)) 45 | faces <- tibble(img_source = kairos_data$image, 46 | error_code = code, 47 | error_message = message) 48 | return(faces) 49 | } 50 | 51 | else { 52 | data <- data$images 53 | if ('faces' %in% names(data)) { 54 | meta <- select(data, -faces) 55 | faces <- data$faces[[1]] %>% 56 | mutate(img_source = kairos_data$image, 57 | img_file = meta$file, img_height = meta$height, 58 | img_status = meta$status, img_width = meta$width) 59 | } 60 | 61 | else if ('candidates' %in% names(data)) { 62 | faces <- data$candidates[[1]] %>% mutate( 63 | comparison_source = kairos_data$image 64 | ) 65 | } 66 | 67 | else { 68 | faces <- data %>% mutate( 69 | img_source = kairos_data$image 70 | ) 71 | } 72 | faces <- faces %>% as_tibble() %>% 73 | set_names(to_snake_case(colnames(faces) %>% 74 | str_replace('^attributes', 'face') %>% 75 | str_replace('^transaction', ''))) 76 | return(faces) 77 | } 78 | } 79 | 80 | -------------------------------------------------------------------------------- /R/prep_image.R: -------------------------------------------------------------------------------- 1 | #' @title prepare local image 2 | #' @description 3 | #' Prepares a local image for an upload the 'Kairos' API via \code{\link[facerec]{detect}}, 4 | #' \code{\link[facerec]{enroll}}, \code{\link[facerec]{recognize}} and \code{\link[facerec]{verify}}. 5 | #' @param img_file Path to an image of file type 'JPG', 'PNG', or 'BMP'. 6 | #' 7 | #' @return The prepared image object. 8 | #' @importFrom knitr image_uri 9 | #' @export 10 | #' 11 | #' @examples 12 | #' \donttest{ 13 | #' 14 | #' facerec_init() 15 | #' 16 | #' # download example image 17 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 18 | #' temp_img_path <- tempfile(fileext = '.png') 19 | #' download.file(finn_image, temp_img_path, mode = 'wb', quiet = TRUE) 20 | #' 21 | #' # prepare image 22 | #' finn_local <- prep_image(temp_img_path) 23 | #' 24 | #' # use prepared image 25 | #' faces <- detect(image = finn_local) 26 | #' } 27 | #' 28 | prep_image <- function(img_file) { 29 | 30 | structure( list( 31 | name = img_file, 32 | content = image_uri(img_file) 33 | ), 34 | class = "rfaces_image" )} 35 | -------------------------------------------------------------------------------- /R/recognize.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title recognize face 3 | #' @name recognize 4 | #' @description 5 | #' Recognize faces in an image and return the most likely matches from a gallery. 6 | #' @param image 7 | #' An image of file type JPG, PNG, or BMP. 8 | #' Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}. 9 | #' @param gallery A string containing the name of the gallery in which the image will be enrolled. 10 | #' @param min_head_scale 11 | #' 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). 12 | #' @param threshold Likelihood (between 0 and 1) used to determine a valid facial match. Defaults to 0.6. 13 | #' @param max_num_results The maximum number of potential matches that are returned. Defaults to 10. 14 | #' @param show_candidate_images Whether to return temporary URLs for each potential match. Defaults to TRUE. 15 | #' 16 | #' @return A dataframe with the potential matches for the input image. The likelihood of matches is given in column \code{confidence}. 17 | #' @export 18 | #' 19 | #' @examples 20 | #' \donttest{ 21 | #' 22 | #' facerec_init() 23 | #' 24 | #' # enroll 25 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 26 | #' padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png' 27 | #' finn_face <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 28 | #' padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars') 29 | #' 30 | #' # recognize 31 | #' finn_2 <- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg' 32 | #' finn_rec <- recognize(image = finn_2, gallery = 'starwars') 33 | #' 34 | #' } 35 | recognize <- function(image, gallery, min_head_scale = 0.015, threshold = 0.6, 36 | max_num_results = 10, show_candidate_images = TRUE) { 37 | 38 | if (is(image, 'rfaces_image')) { 39 | name <- image$name 40 | image <- image$content 41 | } 42 | 43 | else { 44 | name <- image 45 | } 46 | 47 | kairos_data <- post_kairos(path = '/recognize', 48 | params = list(image = image, 49 | 50 | gallery_name = gallery, 51 | minHeadScale = min_head_scale, 52 | threshold = threshold, 53 | max_num_results = max_num_results, 54 | show_candidate_images = show_candidate_images)) 55 | kairos_data$image <- name 56 | 57 | 58 | faces <- parse_kairos(kairos_data) 59 | return(faces) 60 | 61 | } 62 | 63 | 64 | 65 | -------------------------------------------------------------------------------- /R/remove_gallery.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title remove gallery 3 | #' @name remove_gallery 4 | #' @description 5 | #' Removes a gallery and all included subjects. 6 | #' @param gallery The name of the gallery to be removed. 7 | #' 8 | #' @return nothing. 9 | #' @export 10 | #' 11 | #' @examples 12 | #' \donttest{ 13 | #' 14 | #' 15 | #' facerec_init() 16 | #' 17 | #' # enroll 18 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 19 | #' finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 20 | #' 21 | #' # remove gallery 22 | #' remove_gallery(gallery = 'starwars') 23 | #' } 24 | #' 25 | #' 26 | remove_gallery <- function(gallery) { 27 | 28 | url <- kairos_api(path = '/gallery/remove') 29 | params <- list(gallery_name = gallery) 30 | resp <- POST(url, body = params, encode = 'json', 31 | add_headers(.headers = .facerec$init )) 32 | 33 | data <- fromJSON(content(resp, 'text')) 34 | if ('Errors' %in% names(data)) { 35 | message <- data$Errors[[2]] 36 | stop(message) 37 | } 38 | 39 | else { 40 | print(data$message) 41 | } 42 | 43 | } 44 | -------------------------------------------------------------------------------- /R/remove_subject.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title remove subject 3 | #' @name remove_subject 4 | #' @description 5 | #' Removes a subject from a gallery. 6 | #' @param subject_id The subject id for the subject to be removed. 7 | #' @param gallery The name of the gallery in which the subject is enrolled. 8 | #' 9 | #' @return nothing. 10 | #' @export 11 | #' 12 | #' @examples 13 | #' \donttest{ 14 | #' 15 | #' facerec_init() 16 | #' 17 | #' # enroll 18 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 19 | #' finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 20 | #' 21 | #' # remove subject 22 | #' remove_subject(subject_id = 'finn', gallery = 'starwars') 23 | #' } 24 | #' 25 | #' 26 | remove_subject <- function(subject_id, gallery) { 27 | 28 | url <- kairos_api(path = '/gallery/remove_subject') 29 | params <- list(subject_id = subject_id, gallery_name = gallery) 30 | resp <- POST(url, body = params, encode = 'json', 31 | add_headers(.headers = .facerec$init )) 32 | data <- fromJSON(content(resp, 'text')) 33 | 34 | if ('Errors' %in% names(data)) { 35 | message <- data$Errors[[2]] 36 | stop(message) 37 | } 38 | else { 39 | print(data$message) 40 | } 41 | } 42 | 43 | -------------------------------------------------------------------------------- /R/utils-pipe.R: -------------------------------------------------------------------------------- 1 | #' Pipe operator 2 | #' 3 | #' 4 | #' @name %>% 5 | #' @rdname pipe 6 | #' @keywords internal 7 | #' @export 8 | #' @importFrom magrittr %>% 9 | #' @usage lhs \%>\% rhs 10 | NULL 11 | -------------------------------------------------------------------------------- /R/verify.R: -------------------------------------------------------------------------------- 1 | 2 | 3 | #' @title verify face 4 | #' @name verify 5 | #' @description 6 | #' Verify whether face in an input image belongs to a subject in a gallery. 7 | #' @param image 8 | #' An image of file type 'JPG', 'PNG', or 'BMP'. 9 | #' Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}. 10 | #' @param subject_id A string containing the id for the person in the gallery to be verified. 11 | #' @param gallery A string containing the name of the gallery in which the subject will be verified. 12 | #' 13 | #' @return A data frame with the verification annotations for the input image. The likelihood of a match is given in column \code{confidence}. 14 | #' @export 15 | #' 16 | #' @examples 17 | #' 18 | #' \donttest{ 19 | #' 20 | #' facerec_init() 21 | #' 22 | #' # enroll 23 | #' padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png' 24 | #' padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars') 25 | #' 26 | #' # verify 27 | #' amidala_img <- 'https://upload.wikimedia.org/wikipedia/it/5/5e/Padm%C3%A9_Amidala.png' 28 | #' verified <- verify(image = amidala_img, subject_id = 'padme', gallery = 'starwars') 29 | #' 30 | #' } 31 | #' 32 | verify <- function(image, subject_id, gallery) { 33 | 34 | if (is(image, 'rfaces_image')) { 35 | name <- image$name 36 | image <- image$content 37 | } 38 | 39 | else { 40 | name <- image 41 | } 42 | 43 | kairos_data <- post_kairos(path = '/verify', 44 | params = list(image = image, 45 | subject_id = subject_id, 46 | gallery_name = gallery)) 47 | kairos_data$image <- name 48 | 49 | 50 | faces <- parse_kairos(kairos_data) 51 | return(faces) 52 | 53 | 54 | } 55 | 56 | 57 | -------------------------------------------------------------------------------- /R/view_subject.R: -------------------------------------------------------------------------------- 1 | 2 | #' @title view subject 3 | #' @name view_subject 4 | #' @description 5 | #' Returns all face id's for each image enrolled for a given subject in a gallery. 6 | #' @param subject_id The subject id for which to return all face id's. 7 | #' @param gallery The gallery in which the subject is enrolled. 8 | #' 9 | #' @return A dataframe with face id's and enrollment timestamps associated with the input subject. 10 | #' @export 11 | #' 12 | #' @examples 13 | #' \donttest{ 14 | #' 15 | #' facerec_init() 16 | #' 17 | #' # enroll 18 | #' finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 19 | #' finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 20 | #' 21 | #' # view subject 22 | #' view_subject(subject_id = 'finn', gallery = 'starwars') 23 | #' } 24 | #' 25 | #' 26 | view_subject <- function(subject_id, gallery) { 27 | 28 | url <- kairos_api(path = '/gallery/view_subject') 29 | params <- list(subject_id = subject_id, gallery_name = gallery) 30 | resp <- POST(url, body = params, encode = 'json', 31 | add_headers(.headers = .facerec$init )) 32 | data <- fromJSON(content(resp, 'text')) 33 | 34 | if ('Errors' %in% names(data)) { 35 | message <- data$Errors[[2]] 36 | stop(message) 37 | } 38 | else { 39 | return(data$face_ids) 40 | } 41 | } 42 | 43 | -------------------------------------------------------------------------------- /R/zzz.R: -------------------------------------------------------------------------------- 1 | .facerec <- new.env(parent = emptyenv()) 2 | 3 | #.onLoad <- function(libname, pkgname){ 4 | # .facerec <- new.env(parent = emptyenv()) 5 | # invisible() 6 | #} 7 | -------------------------------------------------------------------------------- /README.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | output: github_document 3 | --- 4 | 5 | 6 | 7 | ```{r, echo = FALSE} 8 | knitr::opts_chunk$set( 9 | collapse = TRUE, 10 | comment = "#>", 11 | fig.path = "README-" 12 | ) 13 | ``` 14 | 15 | # facerec 16 | 17 | 18 | [![Travis-CI Build Status](https://travis-ci.org/cschwem2er/facerec.svg?branch=master)](https://travis-ci.org/cschwem2er/facerec) 19 | [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/cschwem2er/facerec?branch=master&svg=true)](https://ci.appveyor.com/project/cschwem2er/facerec) 20 | [![CRAN status](https://www.r-pkg.org/badges/version/facerec)](https://cran.r-project.org/package=facerec) 21 | [![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/facerec)](https://cran.rstudio.com/web/packages/facerec/index.html) 22 | 23 | ```{r, include = FALSE} 24 | #[![CRAN status](https://www.r-pkg.org/badges/version/facerec)](https://cran.r-project.org/package=facerec) 25 | #[![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/facerec)](https://cran.rstudio.com/web/packages/facerec/index.html) 26 | ``` 27 | 28 | ## An Interface for Face Recognition in R 29 | 30 | This package provides an interface to the [Kairos Face Recognition API](https://www.kairos.com/docs/api/). The API detects faces in images and returns estimates for demographics. It is also capable of recognizing and verifying humans across several images. 31 | 32 | Important note: Kairos decided to shut down its online demo for diversity recognition features (see [here](http://www.kairos.com/blog/we-ve-retired-our-diversity-recognition-app-here-s-why)). As of July 2018, the API still returns ethnicity annotations, but it also seems as if they will not provide free access anymore. Until the release of an official statement from Kairos, I will stop the development of this package. 33 | 34 | ## How to Install 35 | 36 | To install the CRAN version of facerec use ``install.packages('facerec')``. 37 | 38 | You can also download and install the latest development version of the app by running ``devtools::install_github('cschwem2er/facerec')``. For Windows users installing from github requires proper setup of [Rtools](https://cran.r-project.org/bin/windows/Rtools/), for which a tutorial is available [here](https://github.com/stan-dev/rstan/wiki/Install-Rtools-for-Windows). 39 | 40 | 41 | ## How to Use 42 | 43 | ### Authentification 44 | 45 | After loading facerec you first need to initiate your authentification credentials. Kairos offers a [free plan](https://www.kairos.com/pricing) 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 `facerec_init()`: 46 | 47 | 48 | ```{r, eval = FALSE} 49 | Sys.setenv(kairos_id = "Your Kairos API id") 50 | Sys.setenv(kairos_key = "Your Kairos API key") 51 | ``` 52 | 53 | ```{r, eval = FALSE} 54 | library(facerec) 55 | facerec_init() 56 | ``` 57 | 58 | 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. 59 | 60 | ### Face Recognition 61 | 62 | Kairos 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](https://en.wikipedia.org/wiki/Finn_(Star_Wars)): 63 | 64 | 65 | 66 | ```{r, eval = FALSE} 67 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 68 | finn_face <- detect(image = finn_image) 69 | ``` 70 | 71 | 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. 72 | 73 | Features can be visualized with the packages [magick](https://cran.r-project.org/web/packages/magick/index.html) and [ggplot2](https://cran.r-project.org/web/packages/ggplot2/index.html): 74 | 75 | ```{r fig.height=4, fig.width=3, eval = FALSE} 76 | library(magick) 77 | library(ggplot2) 78 | 79 | finn_image %>% image_read() %>% image_ggplot() + 80 | geom_rect(data = finn_face, 81 | aes(xmin = top_left_x, xmax = top_left_x + width, 82 | ymin = top_left_y, ymax = top_left_y + height), 83 | fill = NA, linetype = 'dashed', size = 2, color = '#377eb8') + 84 | geom_label(data = finn_face, 85 | aes(x = chin_tip_x, y = chin_tip_y + 20, 86 | label = paste('Gender:', 87 | scales::percent(face_gender_male_confidence), 88 | 'Male')), size = 6, color = '#377eb8') + 89 | geom_label(data = finn_face, 90 | aes(x = chin_tip_x, y = chin_tip_y + 60, 91 | label = paste('Ethnicity:', scales::percent(face_black), 92 | 'Black')), size = 6, color = '#377eb8') + 93 | theme(legend.position="none") 94 | ``` 95 | 96 | 97 | 98 | Kairos has [some recommendations](https://www.kairos.com/docs/api/best-practices) to improve the quality of its recognition service, but in general, the API also works with multiple faces inside an image: 99 | 100 | ```{r fig.height=3, fig.width=4.8, eval = FALSE} 101 | sw_img <- "https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg" 102 | sw_faces <- detect(sw_img) 103 | 104 | sw_img %>% image_read() %>% image_ggplot() + 105 | geom_rect(data = sw_faces, 106 | aes(xmin = top_left_x , xmax = top_left_x + width, 107 | ymin = top_left_y, ymax = top_left_y + height, 108 | color = factor(face_id)), 109 | fill = NA, linetype = 'dashed', size = 2) + 110 | geom_label(data = sw_faces, 111 | aes(x = chin_tip_x, y = chin_tip_y + 15, 112 | label = face_gender_type, 113 | color = factor(face_id)), size = 8) + 114 | theme(legend.position="none") 115 | ``` 116 | 117 | 118 | 119 | Besides annotating faces in single images, face recognition data can be stored permantly with the Kairos. This allows to assign multiple images to subject ids and to provide estimates about whether faces from different images belong to the same subjects. 120 | 121 | ```{r, eval = FALSE} 122 | finn_face <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 123 | finn_new <- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg' 124 | finn_rec <- recognize(image = finn_new, gallery = 'starwars', 125 | show_candidate_images = FALSE) 126 | ``` 127 | 128 | The function `recognize()` returns a dataframe including the probability of a match in the column `confidence`. 129 | 130 | ## Citation 131 | 132 | 133 | If you use facerec for your publications please consider citing it: 134 | 135 | 136 | ``` 137 | Carsten Schwemmer (2018). facerec: An interface for face recognition in R. R package version 0.1.0. 138 | https://github.com/cschwem2er/facerec 139 | ``` 140 | 141 | A BibTeX entry for LaTeX users is: 142 | 143 | ``` 144 | @Manual{, 145 | title = {facerec: An interface for face recognition in R}, 146 | author = {Carsten Schwemmer}, 147 | year = {2018}, 148 | note = {R package version 0.1.0}, 149 | url = {https://github.com/cschwem2er/facerec}, 150 | } 151 | ``` 152 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | # facerec 5 | 6 | [![Travis-CI Build 7 | Status](https://travis-ci.org/cschwem2er/facerec.svg?branch=master)](https://travis-ci.org/cschwem2er/facerec) 8 | [![AppVeyor Build 9 | Status](https://ci.appveyor.com/api/projects/status/github/cschwem2er/facerec?branch=master&svg=true)](https://ci.appveyor.com/project/cschwem2er/facerec) 10 | [![CRAN 11 | status](https://www.r-pkg.org/badges/version/facerec)](https://cran.r-project.org/package=facerec) 12 | [![CRAN 13 | downloads](https://cranlogs.r-pkg.org/badges/grand-total/facerec)](https://cran.rstudio.com/web/packages/facerec/index.html) 14 | 15 | ## An Interface for Face Recognition in R 16 | 17 | This package provides an interface to the [Kairos Face Recognition 18 | API](https://www.kairos.com/docs/api/). The API detects faces in images 19 | and returns estimates for demographics. It is also capable of 20 | recognizing and verifying humans across several images. 21 | 22 | IMPORTANT NOTE: Kairos decided to shut down its online demo for 23 | diversity recognition features (see 24 | [here](http://www.kairos.com/blog/we-ve-retired-our-diversity-recognition-app-here-s-why)). 25 | As of July 2018, the API still returns ethnicity annotations, but it 26 | also 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. 27 | 28 | ## How to Install 29 | 30 | To install the CRAN version of facerec use 31 | `install.packages('facerec')`. 32 | 33 | You can also download and install the latest development version of the 34 | app by running `devtools::install_github('cschwem2er/facerec')`. For 35 | Windows users installing from github requires proper setup of 36 | [Rtools](https://cran.r-project.org/bin/windows/Rtools/), for which a 37 | tutorial is available 38 | [here](https://github.com/stan-dev/rstan/wiki/Install-Rtools-for-Windows). 39 | 40 | ## How to Use 41 | 42 | ### Authentification 43 | 44 | After loading facerec you first need to initiate your authentification 45 | credentials. Kairos offers a [free plan](https://www.kairos.com/pricing) 46 | for API access. After signing up, you will receive an application id and 47 | an application key. Both credentials need to be set as environment 48 | variables before using the initialization function `facerec_init()`: 49 | 50 | ``` r 51 | Sys.setenv(kairos_id = "Your Kairos API id") 52 | Sys.setenv(kairos_key = "Your Kairos API key") 53 | ``` 54 | 55 | ``` r 56 | library(facerec) 57 | facerec_init() 58 | ``` 59 | 60 | You only need to call `facerec_init()` once after loading the package. 61 | In order to avoid entering your credentials for each session, you can 62 | permanently store them in your `.Renviron`. I recommend 63 | `usethis::edit_r_environ()` to find and edit your environment file. 64 | 65 | ### Face Recognition 66 | 67 | Kairos accepts image of file type JPG, PNG, or BMP. Images can be passed 68 | to several facerec functions, either as an url string or a local image 69 | prepared with `prep_image()`. In the following example, `detect()` is 70 | used to recognize the face of the Star Wars character 71 | [Finn](https://en.wikipedia.org/wiki/Finn_\(Star_Wars\)): 72 | 73 | 74 | 75 | ``` r 76 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 77 | finn_face <- detect(image = finn_image) 78 | ``` 79 | 80 | The function returns a dataframe with annotations for the recognized 81 | face in the input image. Variables include positional features of 82 | recognized faces, such as x and y coordinates for eyes. Moreover, 83 | demographic attributes like gender, ethnicity and age are available. 84 | 85 | Features can be visualized with the packages 86 | [magick](https://cran.r-project.org/web/packages/magick/index.html) and 87 | [ggplot2](https://cran.r-project.org/web/packages/ggplot2/index.html): 88 | 89 | ``` r 90 | library(magick) 91 | library(ggplot2) 92 | 93 | finn_image %>% image_read() %>% image_ggplot() + 94 | geom_rect(data = finn_face, 95 | aes(xmin = top_left_x, xmax = top_left_x + width, 96 | ymin = top_left_y, ymax = top_left_y + height), 97 | fill = NA, linetype = 'dashed', size = 2, color = '#377eb8') + 98 | geom_label(data = finn_face, 99 | aes(x = chin_tip_x, y = chin_tip_y + 20, 100 | label = paste('Gender:', 101 | scales::percent(face_gender_male_confidence), 102 | 'Male')), size = 6, color = '#377eb8') + 103 | geom_label(data = finn_face, 104 | aes(x = chin_tip_x, y = chin_tip_y + 60, 105 | label = paste('Ethnicity:', scales::percent(face_black), 106 | 'Black')), size = 6, color = '#377eb8') + 107 | theme(legend.position="none") 108 | ``` 109 | 110 | 111 | 112 | Kairos has [some 113 | recommendations](https://www.kairos.com/docs/api/best-practices) to 114 | improve the quality of its recognition service, but in general, the API 115 | also works with multiple faces inside an 116 | image: 117 | 118 | ``` r 119 | sw_img <- "https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg" 120 | sw_faces <- detect(sw_img) 121 | 122 | sw_img %>% image_read() %>% image_ggplot() + 123 | geom_rect(data = sw_faces, 124 | aes(xmin = top_left_x , xmax = top_left_x + width, 125 | ymin = top_left_y, ymax = top_left_y + height, 126 | color = factor(face_id)), 127 | fill = NA, linetype = 'dashed', size = 2) + 128 | geom_label(data = sw_faces, 129 | aes(x = chin_tip_x, y = chin_tip_y + 15, 130 | label = face_gender_type, 131 | color = factor(face_id)), size = 8) + 132 | theme(legend.position="none") 133 | ``` 134 | 135 | 136 | 137 | Besides annotating faces in single images, face recognition data can be 138 | stored permantly with the Kairos. This allows to assign multiple images 139 | to subject ids and to provide estimates about whether faces from 140 | different images belong to the same 141 | subjects. 142 | 143 | ``` r 144 | finn_face <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 145 | finn_new <- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg' 146 | finn_rec <- recognize(image = finn_new, gallery = 'starwars', 147 | show_candidate_images = FALSE) 148 | ``` 149 | 150 | The function `recognize()` returns a dataframe including the probability 151 | of a match in the column `confidence`. 152 | 153 | ## Citation 154 | 155 | If you use facerec for your publications please consider citing 156 | it: 157 | 158 | ``` 159 | Carsten Schwemmer (2018). facerec: An interface for face recognition in R. R package version 0.1.0. 160 | https://github.com/cschwem2er/facerec 161 | ``` 162 | 163 | A BibTeX entry for LaTeX users is: 164 | 165 | ``` 166 | @Manual{, 167 | title = {facerec: An interface for face recognition in R}, 168 | author = {Carsten Schwemmer}, 169 | year = {2018}, 170 | note = {R package version 0.1.0}, 171 | url = {https://github.com/cschwem2er/facerec}, 172 | } 173 | ``` 174 | -------------------------------------------------------------------------------- /_pkgdown.yaml: -------------------------------------------------------------------------------- 1 | authors: 2 | Carsten Schwemmer: 3 | href: https://www.carstenschwemmer.com 4 | image: man/figures/sw_facerec.png 5 | -------------------------------------------------------------------------------- /appveyor.yml: -------------------------------------------------------------------------------- 1 | # DO NOT CHANGE the "init" and "install" sections below 2 | 3 | # Download script file from GitHub 4 | init: 5 | ps: | 6 | $ErrorActionPreference = "Stop" 7 | Invoke-WebRequest http://raw.github.com/krlmlr/r-appveyor/master/scripts/appveyor-tool.ps1 -OutFile "..\appveyor-tool.ps1" 8 | Import-Module '..\appveyor-tool.ps1' 9 | 10 | install: 11 | ps: Bootstrap 12 | 13 | cache: 14 | - C:\RLibrary 15 | 16 | # Adapt as necessary starting from here 17 | 18 | build_script: 19 | - travis-tool.sh install_deps 20 | 21 | test_script: 22 | - travis-tool.sh run_tests 23 | 24 | on_failure: 25 | - 7z a failure.zip *.Rcheck\* 26 | - appveyor PushArtifact failure.zip 27 | 28 | artifacts: 29 | - path: '*.Rcheck\**\*.log' 30 | name: Logs 31 | 32 | - path: '*.Rcheck\**\*.out' 33 | name: Logs 34 | 35 | - path: '*.Rcheck\**\*.fail' 36 | name: Logs 37 | 38 | - path: '*.Rcheck\**\*.Rout' 39 | name: Logs 40 | 41 | - path: '\*_*.tar.gz' 42 | name: Bits 43 | 44 | - path: '\*_*.zip' 45 | name: Bits 46 | -------------------------------------------------------------------------------- /cran-comments.md: -------------------------------------------------------------------------------- 1 | ## Test environments 2 | * local linux mint 18.3, R 3.4.4 3 | * win-builder (devel and release) 4 | * ubuntu 12.04 (on travis-ci), R 3.1.2 5 | * windows server 2012 r2 x64 (build 9600), R 3.5.0 (on appveyor) 6 | 7 | ## R CMD check results 8 | 9 | There were no ERRORs, WARNINGS or NOTES. 10 | 11 | ## Comments from the CRAN submission team: 12 | 13 | - "Please omit the redundant 'in R' in your title." 14 | 15 | -> title is now adjusted 16 | 17 | - "Please add an URL for 'Kairos' Face Recognition API in your description text" 18 | 19 | -> URL is added to the description 20 | 21 | - "Please replace \dontrun{} by \donttest{} in your Rd-files." 22 | 23 | -> all instances replaced except for the function facerec_init(), because this would 24 | override the API credentials and therefore cause all other examples to fail 25 | -------------------------------------------------------------------------------- /docs/LICENSE-text.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | License • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 44 | 45 | 46 | 47 | 48 | 49 |
50 |
51 | 105 | 106 | 107 |
108 | 109 |
110 |
111 |
112 |

License

113 |
114 | 115 | 
YEAR: 2018
116 | COPYRIGHT HOLDER: Carsten Schwemmer
117 |
118 | 119 |
120 | 121 |
122 | 123 | 124 | 134 |
135 | 136 | 137 | 138 | 139 | 140 | 141 | -------------------------------------------------------------------------------- /docs/LICENSE.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | MIT License • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 44 | 45 | 46 | 47 | 48 | 49 |
50 |
51 | 105 | 106 | 107 |
108 | 109 |
110 |
111 |
112 |

MIT License

113 |
114 | 115 |
116 | 117 |

Copyright (c) 2018 Carsten Schwemmer

118 |

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

119 |

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

120 |

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

121 |
122 | 123 |
124 | 125 |
126 | 127 | 128 | 138 |
139 | 140 | 141 | 142 | 143 | 144 | 145 | -------------------------------------------------------------------------------- /docs/articles/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | Articles • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 44 | 45 | 46 | 47 | 48 | 49 |
50 |
51 | 105 | 106 | 107 |
108 | 109 |
110 |
111 |
112 |

Articles

113 |
114 | 115 |
116 |

All vignettes

117 |

118 | 119 | 122 |
123 |
124 |
125 | 126 | 136 |
137 | 138 | 139 | 140 | 141 | 142 | 143 | -------------------------------------------------------------------------------- /docs/authors.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | Authors • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 44 | 45 | 46 | 47 | 48 | 49 |
50 |
51 | 105 | 106 | 107 |
108 | 109 |
110 |
111 |
112 |

Authors

113 |
114 | 115 | 121 | 122 |
123 | 124 |
125 | 126 | 127 | 137 |
138 | 139 | 140 | 141 | 142 | 143 | 144 | -------------------------------------------------------------------------------- /docs/docsearch.css: -------------------------------------------------------------------------------- 1 | /* Docsearch -------------------------------------------------------------- */ 2 | /* 3 | Source: https://github.com/algolia/docsearch/ 4 | License: MIT 5 | */ 6 | 7 | .algolia-autocomplete { 8 | display: block; 9 | -webkit-box-flex: 1; 10 | -ms-flex: 1; 11 | flex: 1 12 | } 13 | 14 | .algolia-autocomplete .ds-dropdown-menu { 15 | width: 100%; 16 | min-width: none; 17 | max-width: none; 18 | padding: .75rem 0; 19 | background-color: #fff; 20 | background-clip: padding-box; 21 | border: 1px solid rgba(0, 0, 0, .1); 22 | box-shadow: 0 .5rem 1rem rgba(0, 0, 0, .175); 23 | } 24 | 25 | @media (min-width:768px) { 26 | .algolia-autocomplete .ds-dropdown-menu { 27 | width: 175% 28 | } 29 | } 30 | 31 | .algolia-autocomplete .ds-dropdown-menu::before { 32 | display: none 33 | } 34 | 35 | .algolia-autocomplete .ds-dropdown-menu [class^=ds-dataset-] { 36 | padding: 0; 37 | background-color: rgb(255,255,255); 38 | border: 0; 39 | max-height: 80vh; 40 | } 41 | 42 | .algolia-autocomplete .ds-dropdown-menu .ds-suggestions { 43 | margin-top: 0 44 | } 45 | 46 | .algolia-autocomplete .algolia-docsearch-suggestion { 47 | padding: 0; 48 | overflow: visible 49 | } 50 | 51 | .algolia-autocomplete .algolia-docsearch-suggestion--category-header { 52 | padding: .125rem 1rem; 53 | margin-top: 0; 54 | font-size: 1.3em; 55 | font-weight: 500; 56 | color: #00008B; 57 | border-bottom: 0 58 | } 59 | 60 | .algolia-autocomplete .algolia-docsearch-suggestion--wrapper { 61 | float: none; 62 | padding-top: 0 63 | } 64 | 65 | .algolia-autocomplete .algolia-docsearch-suggestion--subcategory-column { 66 | float: none; 67 | width: auto; 68 | padding: 0; 69 | text-align: left 70 | } 71 | 72 | .algolia-autocomplete .algolia-docsearch-suggestion--content { 73 | float: none; 74 | width: auto; 75 | padding: 0 76 | } 77 | 78 | .algolia-autocomplete .algolia-docsearch-suggestion--content::before { 79 | display: none 80 | } 81 | 82 | .algolia-autocomplete .ds-suggestion:not(:first-child) .algolia-docsearch-suggestion--category-header { 83 | padding-top: .75rem; 84 | margin-top: .75rem; 85 | border-top: 1px solid rgba(0, 0, 0, .1) 86 | } 87 | 88 | .algolia-autocomplete .ds-suggestion .algolia-docsearch-suggestion--subcategory-column { 89 | display: block; 90 | padding: .1rem 1rem; 91 | margin-bottom: 0.1; 92 | font-size: 1.0em; 93 | font-weight: 400 94 | /* display: none */ 95 | } 96 | 97 | .algolia-autocomplete .algolia-docsearch-suggestion--title { 98 | display: block; 99 | padding: .25rem 1rem; 100 | margin-bottom: 0; 101 | font-size: 0.9em; 102 | font-weight: 400 103 | } 104 | 105 | .algolia-autocomplete .algolia-docsearch-suggestion--text { 106 | padding: 0 1rem .5rem; 107 | margin-top: -.25rem; 108 | font-size: 0.8em; 109 | font-weight: 400; 110 | line-height: 1.25 111 | } 112 | 113 | .algolia-autocomplete .algolia-docsearch-footer { 114 | width: 110px; 115 | height: 20px; 116 | z-index: 3; 117 | margin-top: 10.66667px; 118 | float: right; 119 | font-size: 0; 120 | line-height: 0; 121 | } 122 | 123 | .algolia-autocomplete .algolia-docsearch-footer--logo { 124 | background-image: url("data:image/svg+xml;utf8,"); 125 | background-repeat: no-repeat; 126 | background-position: 50%; 127 | background-size: 100%; 128 | overflow: hidden; 129 | text-indent: -9000px; 130 | width: 100%; 131 | height: 100%; 132 | display: block; 133 | transform: translate(-8px); 134 | } 135 | 136 | .algolia-autocomplete .algolia-docsearch-suggestion--highlight { 137 | color: #FF8C00; 138 | background: rgba(232, 189, 54, 0.1) 139 | } 140 | 141 | 142 | .algolia-autocomplete .algolia-docsearch-suggestion--text .algolia-docsearch-suggestion--highlight { 143 | box-shadow: inset 0 -2px 0 0 rgba(105, 105, 105, .5) 144 | } 145 | 146 | .algolia-autocomplete .ds-suggestion.ds-cursor .algolia-docsearch-suggestion--content { 147 | background-color: rgba(192, 192, 192, .15) 148 | } 149 | -------------------------------------------------------------------------------- /docs/docsearch.js: -------------------------------------------------------------------------------- 1 | $(function() { 2 | 3 | // register a handler to move the focus to the search bar 4 | // upon pressing shift + "/" (i.e. "?") 5 | $(document).on('keydown', function(e) { 6 | if (e.shiftKey && e.keyCode == 191) { 7 | e.preventDefault(); 8 | $("#search-input").focus(); 9 | } 10 | }); 11 | 12 | $(document).ready(function() { 13 | // do keyword highlighting 14 | /* modified from https://jsfiddle.net/julmot/bL6bb5oo/ */ 15 | var mark = function() { 16 | 17 | var referrer = document.URL ; 18 | var paramKey = "q" ; 19 | 20 | if (referrer.indexOf("?") !== -1) { 21 | var qs = referrer.substr(referrer.indexOf('?') + 1); 22 | var qs_noanchor = qs.split('#')[0]; 23 | var qsa = qs_noanchor.split('&'); 24 | var keyword = ""; 25 | 26 | for (var i = 0; i < qsa.length; i++) { 27 | var currentParam = qsa[i].split('='); 28 | 29 | if (currentParam.length !== 2) { 30 | continue; 31 | } 32 | 33 | if (currentParam[0] == paramKey) { 34 | keyword = decodeURIComponent(currentParam[1].replace(/\+/g, "%20")); 35 | } 36 | } 37 | 38 | if (keyword !== "") { 39 | $(".contents").unmark({ 40 | done: function() { 41 | $(".contents").mark(keyword); 42 | } 43 | }); 44 | } 45 | } 46 | }; 47 | 48 | mark(); 49 | }); 50 | }); 51 | 52 | /* Search term highlighting ------------------------------*/ 53 | 54 | function matchedWords(hit) { 55 | var words = []; 56 | 57 | var hierarchy = hit._highlightResult.hierarchy; 58 | // loop to fetch from lvl0, lvl1, etc. 59 | for (var idx in hierarchy) { 60 | words = words.concat(hierarchy[idx].matchedWords); 61 | } 62 | 63 | var content = hit._highlightResult.content; 64 | if (content) { 65 | words = words.concat(content.matchedWords); 66 | } 67 | 68 | // return unique words 69 | var words_uniq = [...new Set(words)]; 70 | return words_uniq; 71 | } 72 | 73 | function updateHitURL(hit) { 74 | 75 | var words = matchedWords(hit); 76 | var url = ""; 77 | 78 | if (hit.anchor) { 79 | url = hit.url_without_anchor + '?q=' + escape(words.join(" ")) + '#' + hit.anchor; 80 | } else { 81 | url = hit.url + '?q=' + escape(words.join(" ")); 82 | } 83 | 84 | return url; 85 | } 86 | -------------------------------------------------------------------------------- /docs/link.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 8 | 12 | 13 | -------------------------------------------------------------------------------- /docs/man/figures/finn_facerec.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cschwem2er/facerec/af79543940c7a79b742db066bce297707a6bd88e/docs/man/figures/finn_facerec.png -------------------------------------------------------------------------------- /docs/man/figures/sw_facerec.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cschwem2er/facerec/af79543940c7a79b742db066bce297707a6bd88e/docs/man/figures/sw_facerec.png -------------------------------------------------------------------------------- /docs/news/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | Changelog • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 44 | 45 | 46 | 47 | 48 | 49 |
50 |
51 | 105 | 106 | 107 |
108 | 109 |
110 |
111 |
112 |

Changelog

113 | Source: NEWS.md 114 |
115 | 116 |
117 |

118 | facerec 0.1.0 2018-05-14 119 |

120 |
    121 |
  • First release of the facerec package.
    • 122 |
123 |
124 |
125 | 126 | 134 | 135 |
136 | 137 | 147 |
148 | 149 | 150 | 151 | 152 | 153 | 154 | -------------------------------------------------------------------------------- /docs/pkgdown.css: -------------------------------------------------------------------------------- 1 | /* Sticky footer */ 2 | 3 | /** 4 | * Basic idea: https://philipwalton.github.io/solved-by-flexbox/demos/sticky-footer/ 5 | * Details: https://github.com/philipwalton/solved-by-flexbox/blob/master/assets/css/components/site.css 6 | * 7 | * .Site -> body > .container 8 | * .Site-content -> body > .container .row 9 | * .footer -> footer 10 | * 11 | * Key idea seems to be to ensure that .container and __all its parents__ 12 | * have height set to 100% 13 | * 14 | */ 15 | 16 | html, body { 17 | height: 100%; 18 | } 19 | 20 | body > .container { 21 | display: flex; 22 | height: 100%; 23 | flex-direction: column; 24 | 25 | padding-top: 60px; 26 | } 27 | 28 | body > .container .row { 29 | flex: 1 0 auto; 30 | } 31 | 32 | footer { 33 | margin-top: 45px; 34 | padding: 35px 0 36px; 35 | border-top: 1px solid #e5e5e5; 36 | color: #666; 37 | display: flex; 38 | flex-shrink: 0; 39 | } 40 | footer p { 41 | margin-bottom: 0; 42 | } 43 | footer div { 44 | flex: 1; 45 | } 46 | footer .pkgdown { 47 | text-align: right; 48 | } 49 | footer p { 50 | margin-bottom: 0; 51 | } 52 | 53 | img.icon { 54 | float: right; 55 | } 56 | 57 | img { 58 | max-width: 100%; 59 | } 60 | 61 | /* Typographic tweaking ---------------------------------*/ 62 | 63 | .contents h1.page-header { 64 | margin-top: calc(-60px + 1em); 65 | } 66 | 67 | /* Section anchors ---------------------------------*/ 68 | 69 | a.anchor { 70 | margin-left: -30px; 71 | display:inline-block; 72 | width: 30px; 73 | height: 30px; 74 | visibility: hidden; 75 | 76 | background-image: url(./link.svg); 77 | background-repeat: no-repeat; 78 | background-size: 20px 20px; 79 | background-position: center center; 80 | } 81 | 82 | .hasAnchor:hover a.anchor { 83 | visibility: visible; 84 | } 85 | 86 | @media (max-width: 767px) { 87 | .hasAnchor:hover a.anchor { 88 | visibility: hidden; 89 | } 90 | } 91 | 92 | 93 | /* Fixes for fixed navbar --------------------------*/ 94 | 95 | .contents h1, .contents h2, .contents h3, .contents h4 { 96 | padding-top: 60px; 97 | margin-top: -40px; 98 | } 99 | 100 | /* Static header placement on mobile devices */ 101 | @media (max-width: 767px) { 102 | .navbar-fixed-top { 103 | position: absolute; 104 | } 105 | .navbar { 106 | padding: 0; 107 | } 108 | } 109 | 110 | 111 | /* Sidebar --------------------------*/ 112 | 113 | #sidebar { 114 | margin-top: 30px; 115 | } 116 | #sidebar h2 { 117 | font-size: 1.5em; 118 | margin-top: 1em; 119 | } 120 | 121 | #sidebar h2:first-child { 122 | margin-top: 0; 123 | } 124 | 125 | #sidebar .list-unstyled li { 126 | margin-bottom: 0.5em; 127 | } 128 | 129 | .orcid { 130 | height: 16px; 131 | vertical-align: middle; 132 | } 133 | 134 | /* Reference index & topics ----------------------------------------------- */ 135 | 136 | .ref-index th {font-weight: normal;} 137 | 138 | .ref-index td {vertical-align: top;} 139 | .ref-index .alias {width: 40%;} 140 | .ref-index .title {width: 60%;} 141 | 142 | .ref-index .alias {width: 40%;} 143 | .ref-index .title {width: 60%;} 144 | 145 | .ref-arguments th {text-align: right; padding-right: 10px;} 146 | .ref-arguments th, .ref-arguments td {vertical-align: top;} 147 | .ref-arguments .name {width: 20%;} 148 | .ref-arguments .desc {width: 80%;} 149 | 150 | /* Nice scrolling for wide elements --------------------------------------- */ 151 | 152 | table { 153 | display: block; 154 | overflow: auto; 155 | } 156 | 157 | /* Syntax highlighting ---------------------------------------------------- */ 158 | 159 | pre { 160 | word-wrap: normal; 161 | word-break: normal; 162 | border: 1px solid #eee; 163 | } 164 | 165 | pre, code { 166 | background-color: #f8f8f8; 167 | color: #333; 168 | } 169 | 170 | pre code { 171 | overflow: auto; 172 | word-wrap: normal; 173 | white-space: pre; 174 | } 175 | 176 | pre .img { 177 | margin: 5px 0; 178 | } 179 | 180 | pre .img img { 181 | background-color: #fff; 182 | display: block; 183 | height: auto; 184 | } 185 | 186 | code a, pre a { 187 | color: #375f84; 188 | } 189 | 190 | a.sourceLine:hover { 191 | text-decoration: none; 192 | } 193 | 194 | .fl {color: #1514b5;} 195 | .fu {color: #000000;} /* function */ 196 | .ch,.st {color: #036a07;} /* string */ 197 | .kw {color: #264D66;} /* keyword */ 198 | .co {color: #888888;} /* comment */ 199 | 200 | .message { color: black; font-weight: bolder;} 201 | .error { color: orange; font-weight: bolder;} 202 | .warning { color: #6A0366; font-weight: bolder;} 203 | 204 | /* Clipboard --------------------------*/ 205 | 206 | .hasCopyButton { 207 | position: relative; 208 | } 209 | 210 | .btn-copy-ex { 211 | position: absolute; 212 | right: 0; 213 | top: 0; 214 | visibility: hidden; 215 | } 216 | 217 | .hasCopyButton:hover button.btn-copy-ex { 218 | visibility: visible; 219 | } 220 | 221 | /* mark.js ----------------------------*/ 222 | 223 | mark { 224 | background-color: rgba(255, 255, 51, 0.5); 225 | border-bottom: 2px solid rgba(255, 153, 51, 0.3); 226 | padding: 1px; 227 | } 228 | 229 | /* vertical spacing after htmlwidgets */ 230 | .html-widget { 231 | margin-bottom: 10px; 232 | } 233 | -------------------------------------------------------------------------------- /docs/pkgdown.js: -------------------------------------------------------------------------------- 1 | /* http://gregfranko.com/blog/jquery-best-practices/ */ 2 | (function($) { 3 | $(function() { 4 | 5 | $("#sidebar") 6 | .stick_in_parent({offset_top: 40}) 7 | .on('sticky_kit:bottom', function(e) { 8 | $(this).parent().css('position', 'static'); 9 | }) 10 | .on('sticky_kit:unbottom', function(e) { 11 | $(this).parent().css('position', 'relative'); 12 | }); 13 | 14 | $('body').scrollspy({ 15 | target: '#sidebar', 16 | offset: 60 17 | }); 18 | 19 | $('[data-toggle="tooltip"]').tooltip(); 20 | 21 | var cur_path = paths(location.pathname); 22 | var links = $("#navbar ul li a"); 23 | var max_length = -1; 24 | var pos = -1; 25 | for (var i = 0; i < links.length; i++) { 26 | if (links[i].getAttribute("href") === "#") 27 | continue; 28 | var path = paths(links[i].pathname); 29 | 30 | var length = prefix_length(cur_path, path); 31 | if (length > max_length) { 32 | max_length = length; 33 | pos = i; 34 | } 35 | } 36 | 37 | // Add class to parent
  • , and enclosing
  • if in dropdown 38 | if (pos >= 0) { 39 | var menu_anchor = $(links[pos]); 40 | menu_anchor.parent().addClass("active"); 41 | menu_anchor.closest("li.dropdown").addClass("active"); 42 | } 43 | }); 44 | 45 | function paths(pathname) { 46 | var pieces = pathname.split("/"); 47 | pieces.shift(); // always starts with / 48 | 49 | var end = pieces[pieces.length - 1]; 50 | if (end === "index.html" || end === "") 51 | pieces.pop(); 52 | return(pieces); 53 | } 54 | 55 | function prefix_length(needle, haystack) { 56 | if (needle.length > haystack.length) 57 | return(0); 58 | 59 | // Special case for length-0 haystack, since for loop won't run 60 | if (haystack.length === 0) { 61 | return(needle.length === 0 ? 1 : 0); 62 | } 63 | 64 | for (var i = 0; i < haystack.length; i++) { 65 | if (needle[i] != haystack[i]) 66 | return(i); 67 | } 68 | 69 | return(haystack.length); 70 | } 71 | 72 | /* Clipboard --------------------------*/ 73 | 74 | function changeTooltipMessage(element, msg) { 75 | var tooltipOriginalTitle=element.getAttribute('data-original-title'); 76 | element.setAttribute('data-original-title', msg); 77 | $(element).tooltip('show'); 78 | element.setAttribute('data-original-title', tooltipOriginalTitle); 79 | } 80 | 81 | if(Clipboard.isSupported()) { 82 | $(document).ready(function() { 83 | var copyButton = ""; 84 | 85 | $(".examples, div.sourceCode").addClass("hasCopyButton"); 86 | 87 | // Insert copy buttons: 88 | $(copyButton).prependTo(".hasCopyButton"); 89 | 90 | // Initialize tooltips: 91 | $('.btn-copy-ex').tooltip({container: 'body'}); 92 | 93 | // Initialize clipboard: 94 | var clipboardBtnCopies = new Clipboard('[data-clipboard-copy]', { 95 | text: function(trigger) { 96 | return trigger.parentNode.textContent; 97 | } 98 | }); 99 | 100 | clipboardBtnCopies.on('success', function(e) { 101 | changeTooltipMessage(e.trigger, 'Copied!'); 102 | e.clearSelection(); 103 | }); 104 | 105 | clipboardBtnCopies.on('error', function() { 106 | changeTooltipMessage(e.trigger,'Press Ctrl+C or Command+C to copy'); 107 | }); 108 | }); 109 | } 110 | })(window.jQuery || window.$) 111 | -------------------------------------------------------------------------------- /docs/pkgdown.yml: -------------------------------------------------------------------------------- 1 | pandoc: 2.3.1 2 | pkgdown: 1.1.0 3 | pkgdown_sha: ~ 4 | articles: 5 | intro: intro.html 6 | 7 | -------------------------------------------------------------------------------- /docs/reference/detect.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | detect faces — detect • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    detect faces

    116 | Source: R/detect.R 117 | 118 |
    119 | 120 |
    121 | 122 |

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

    123 | 124 |
    125 | 126 | 
    detect(image, min_head_scale = 0.015)
    127 | 128 |

    Arguments

    129 | 130 | 131 | 132 | 133 | 135 | 136 | 137 | 138 | 139 | 140 |
    image

    An image of file type 'JPG', 'PNG', or 'BMP'. 134 | 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).

    141 | 142 |

    Value

    143 | 144 |

    A data frame with annotations for each detected face.

    145 | 146 | 147 |

    Examples

    148 | 
    
149 |  facerec_init()
    #> Succesfully initialized authentification credentials.
    
150 |  # one image
151 |  finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
152 |  faces <- detect(image = finn_image)
    #> Error: API did not return json
    
153 |  # multiple images
154 |  sw_image <- 'https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg'
155 |  padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png'
156 | 
157 |  faces <- c(finn_image, sw_image, padme_image) %>%
158 |  purrr::map(detect) %>% dplyr::bind_rows()
    #> Error: API did not return json
     
    
159 | 
160 | 
161 |
    162 |
    163 | 174 |
    175 | 176 | 186 |
    187 | 188 | 189 | 190 | 191 | 192 | 193 | -------------------------------------------------------------------------------- /docs/reference/enroll.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | enroll faces — enroll • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    enroll faces

    116 | Source: R/enroll.R 117 | 118 |
    119 | 120 |
    121 | 122 |

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

    123 | 124 |
    125 | 126 | 
    enroll(image, subject_id, gallery, min_head_scale = 0.015)
    127 | 128 |

    Arguments

    129 | 130 | 131 | 132 | 133 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 |
    image

    An image of file type 'JPG', 'PNG', or 'BMP'. 134 | 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).

    149 | 150 |

    Value

    151 | 152 |

    A data frame with annotations for the enrolled image.

    153 | 154 | 155 |

    Examples

    156 | 
    
157 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
158 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
159 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
    #> Error: API did not return json
    
160 | 
161 |
    162 |
    163 | 174 |
    175 | 176 | 186 |
    187 | 188 | 189 | 190 | 191 | 192 | 193 | -------------------------------------------------------------------------------- /docs/reference/facerec_init.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | authorization — facerec_init • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 48 | 49 | 50 | 51 | 52 | 53 |
    54 |
    55 | 109 | 110 | 111 |
    112 | 113 |
    114 |
    115 |
    116 |

    authorization

    117 | Source: R/facerec_init.R 118 | 119 |
    120 | 121 |
    122 | 123 |

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

    125 | 126 |
    127 | 128 | 
    facerec_init()
    129 | 130 |

    Value

    131 | 132 |

    nothing.

    133 | 134 | 135 |

    Examples

    136 | 
    # NOT RUN {
137 | Sys.setenv(kairos_id = "Your Kairos API id")
138 | Sys.setenv(kairos_key = "Your Kairos API key")
139 | 
140 | facerec_init()
141 | # }
    
142 | 
143 | 
144 | 
145 |
    146 |
    147 | 157 |
    158 | 159 | 169 |
    170 | 171 | 172 | 173 | 174 | 175 | 176 | -------------------------------------------------------------------------------- /docs/reference/figures/finn_facerec.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cschwem2er/facerec/af79543940c7a79b742db066bce297707a6bd88e/docs/reference/figures/finn_facerec.png -------------------------------------------------------------------------------- /docs/reference/figures/sw_facerec.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cschwem2er/facerec/af79543940c7a79b742db066bce297707a6bd88e/docs/reference/figures/sw_facerec.png -------------------------------------------------------------------------------- /docs/reference/get_galleries.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | list galleries — get_galleries • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    list galleries

    116 | Source: R/get_galleries.R 117 | 118 |
    119 | 120 |
    121 | 122 |

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

    123 | 124 |
    125 | 126 | 
    get_galleries()
    127 | 128 |

    Value

    129 | 130 |

    A vector of gallery id's.

    131 | 132 | 133 |

    Examples

    134 | 
    
135 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
136 | # enroll
137 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
138 | first_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
    #> Error: API did not return json
    second_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'more_starwars')
    #> Error: API did not return json
    
139 | # get_galleries
140 | get_galleries()
    #> Error: lexical error: invalid char in json text.
141 | #>                                        Authentication failed
142 | #>                      (right here) ------^
    
143 | 
144 |
    145 |
    146 | 156 |
    157 | 158 | 168 |
    169 | 170 | 171 | 172 | 173 | 174 | 175 | -------------------------------------------------------------------------------- /docs/reference/get_gallery_subjects.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | get gallery subjects — get_gallery_subjects • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    get gallery subjects

    116 | Source: R/get_gallery_subjects.R 117 | 118 |
    119 | 120 |
    121 | 122 |

    Returns all subject id's associated with a gallery.

    123 | 124 |
    125 | 126 | 
    get_gallery_subjects(gallery)
    127 | 128 |

    Arguments

    129 | 130 | 131 | 132 | 133 | 134 | 135 |
    gallery

    The gallery in which the subjects are enrolled.

    136 | 137 |

    Value

    138 | 139 |

    A vector of subject id's

    140 | 141 | 142 |

    Examples

    143 | 
    
144 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
145 | # enroll
146 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
147 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
    #> Error: API did not return json
    
148 | # view subjects
149 | get_gallery_subjects(gallery = 'starwars')
    #> Error: lexical error: invalid char in json text.
150 | #>                                        Authentication failed
151 | #>                      (right here) ------^
    
152 | 
153 |
    154 |
    155 | 166 |
    167 | 168 | 178 |
    179 | 180 | 181 | 182 | 183 | 184 | 185 | -------------------------------------------------------------------------------- /docs/reference/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | Function reference • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 44 | 45 | 46 | 47 | 48 | 49 |
    50 |
    51 | 105 | 106 | 107 |
    108 | 109 |
    110 |
    111 |
    112 |

    Reference

    113 |
    114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 129 | 130 | 131 | 132 | 135 | 136 | 137 | 138 | 141 | 142 | 143 | 144 | 147 | 148 | 149 | 150 | 153 | 154 | 155 | 156 | 159 | 160 | 161 | 162 | 165 | 166 | 167 | 168 | 171 | 172 | 173 | 174 | 177 | 178 | 179 | 180 | 183 | 184 | 185 | 186 | 189 | 190 | 191 | 192 | 195 | 196 | 197 | 198 |
    126 |

    All functions

    127 |

    128 |
    133 |

    detect()

    134 |

    detect faces

    139 |

    enroll()

    140 |

    enroll faces

    145 |

    facerec_init()

    146 |

    authorization

    151 |

    get_galleries()

    152 |

    list galleries

    157 |

    get_gallery_subjects()

    158 |

    get gallery subjects

    163 |

    prep_image()

    164 |

    prepare local image

    169 |

    recognize()

    170 |

    recognize face

    175 |

    remove_gallery()

    176 |

    remove gallery

    181 |

    remove_subject()

    182 |

    remove subject

    187 |

    verify()

    188 |

    verify face

    193 |

    view_subject()

    194 |

    view subject

    199 |
    200 | 201 | 207 |
    208 | 209 | 219 |
    220 | 221 | 222 | 223 | 224 | 225 | 226 | -------------------------------------------------------------------------------- /docs/reference/pipe.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | Pipe operator — %>% • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    Pipe operator

    116 | Source: R/utils-pipe.R 117 | 118 |
    119 | 120 |
    121 | 122 |

    Pipe operator

    123 | 124 |
    125 | 126 | 
    lhs %>% rhs
    127 | 128 | 129 |
    130 | 136 |
    137 | 138 | 148 |
    149 | 150 | 151 | 152 | 153 | 154 | 155 | -------------------------------------------------------------------------------- /docs/reference/prep_image.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | prepare local image — prep_image • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 48 | 49 | 50 | 51 | 52 | 53 |
    54 |
    55 | 109 | 110 | 111 |
    112 | 113 |
    114 |
    115 |
    116 |

    prepare local image

    117 | Source: R/prep_image.R 118 | 119 |
    120 | 121 |
    122 | 123 |

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

    125 | 126 |
    127 | 128 | 
    prep_image(img_file)
    129 | 130 |

    Arguments

    131 | 132 | 133 | 134 | 135 | 136 | 137 |
    img_file

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

    138 | 139 |

    Value

    140 | 141 |

    The prepared image object.

    142 | 143 | 144 |

    Examples

    145 | 
     
    
146 |  facerec_init()
    #> Succesfully initialized authentification credentials.
    
147 |  # download example image
148 |  finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
149 |  temp_img_path <- tempfile(fileext = '.png')
150 |  download.file(finn_image, temp_img_path, mode = 'wb', quiet = TRUE)
151 | 
152 |  # prepare image
153 |  finn_local <- prep_image(temp_img_path)
154 | 
155 |  # use prepared image
156 |  faces <- detect(image = finn_local)
    #> Error: API did not return json
     
    
157 |
    158 |
    159 | 170 |
    171 | 172 | 182 |
    183 | 184 | 185 | 186 | 187 | 188 | 189 | -------------------------------------------------------------------------------- /docs/reference/recognize.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | recognize face — recognize • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    recognize face

    116 | Source: R/recognize.R 117 | 118 |
    119 | 120 |
    121 | 122 |

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

    123 | 124 |
    125 | 126 | 
    recognize(image, gallery, min_head_scale = 0.015, threshold = 0.6,
127 |   max_num_results = 10, show_candidate_images = TRUE)
    128 | 129 |

    Arguments

    130 | 131 | 132 | 133 | 134 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 |
    image

    An image of file type JPG, PNG, or BMP. 135 | 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.

    158 | 159 |

    Value

    160 | 161 |

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

    162 | 163 | 164 |

    Examples

    165 | 
     
    
166 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
167 | # enroll
168 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
169 | padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png'
170 | finn_face <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
    #> Error: API did not return json
    padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars')
    #> Error: API did not return json
    
171 | # recognize
172 | finn_2 <- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg'
173 | finn_rec <- recognize(image = finn_2, gallery = 'starwars')
    #> Error: API did not return json
    
174 |
    175 |
    176 | 187 |
    188 | 189 | 199 |
    200 | 201 | 202 | 203 | 204 | 205 | 206 | -------------------------------------------------------------------------------- /docs/reference/remove_gallery.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | remove gallery — remove_gallery • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    remove gallery

    116 | Source: R/remove_gallery.R 117 | 118 |
    119 | 120 |
    121 | 122 |

    Removes a gallery and all included subjects.

    123 | 124 |
    125 | 126 | 
    remove_gallery(gallery)
    127 | 128 |

    Arguments

    129 | 130 | 131 | 132 | 133 | 134 | 135 |
    gallery

    The name of the gallery to be removed.

    136 | 137 |

    Value

    138 | 139 |

    nothing.

    140 | 141 | 142 |

    Examples

    143 | 
    
144 | 
145 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
146 | # enroll
147 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
148 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
    #> Error: API did not return json
    
149 | # remove gallery
150 | remove_gallery(gallery = 'starwars')
    #> Error: lexical error: invalid char in json text.
151 | #>                                        Authentication failed
152 | #>                      (right here) ------^
    
153 | 
154 |
    155 |
    156 | 167 |
    168 | 169 | 179 |
    180 | 181 | 182 | 183 | 184 | 185 | 186 | -------------------------------------------------------------------------------- /docs/reference/remove_subject.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | remove subject — remove_subject • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    remove subject

    116 | Source: R/remove_subject.R 117 | 118 |
    119 | 120 |
    121 | 122 |

    Removes a subject from a gallery.

    123 | 124 |
    125 | 126 | 
    remove_subject(subject_id, gallery)
    127 | 128 |

    Arguments

    129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 |
    subject_id

    The subject id for the subject to be removed.

    gallery

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

    140 | 141 |

    Value

    142 | 143 |

    nothing.

    144 | 145 | 146 |

    Examples

    147 | 
    
148 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
149 | # enroll
150 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
151 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
    #> Error: API did not return json
    
152 | # remove subject
153 | remove_subject(subject_id = 'finn', gallery = 'starwars')
    #> Error: lexical error: invalid char in json text.
154 | #>                                        Authentication failed
155 | #>                      (right here) ------^
    
156 | 
157 |
    158 |
    159 | 170 |
    171 | 172 | 182 |
    183 | 184 | 185 | 186 | 187 | 188 | 189 | -------------------------------------------------------------------------------- /docs/reference/verify.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | verify face — verify • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    verify face

    116 | Source: R/verify.R 117 | 118 |
    119 | 120 |
    121 | 122 |

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

    123 | 124 |
    125 | 126 | 
    verify(image, subject_id, gallery)
    127 | 128 |

    Arguments

    129 | 130 | 131 | 132 | 133 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 |
    image

    An image of file type 'JPG', 'PNG', or 'BMP'. 134 | 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.

    145 | 146 |

    Value

    147 | 148 |

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

    149 | 150 | 151 |

    Examples

    152 | 
    
153 | 
    
154 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
155 | # enroll
156 | padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png'
157 | padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars')
    #> Error: API did not return json
    
158 | # verify
159 | amidala_img <- 'https://upload.wikimedia.org/wikipedia/it/5/5e/Padm%C3%A9_Amidala.png'
160 | verified <- verify(image = amidala_img, subject_id = 'padme', gallery = 'starwars')
    #> Error: API did not return json
    
161 | 
    
162 |
    163 |
    164 | 175 |
    176 | 177 | 187 |
    188 | 189 | 190 | 191 | 192 | 193 | 194 | -------------------------------------------------------------------------------- /docs/reference/view_subject.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | view subject — view_subject • facerec 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 47 | 48 | 49 | 50 | 51 | 52 |
    53 |
    54 | 108 | 109 | 110 |
    111 | 112 |
    113 |
    114 |
    115 |

    view subject

    116 | Source: R/view_subject.R 117 | 118 |
    119 | 120 |
    121 | 122 |

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

    123 | 124 |
    125 | 126 | 
    view_subject(subject_id, gallery)
    127 | 128 |

    Arguments

    129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 |
    subject_id

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

    gallery

    The gallery in which the subject is enrolled.

    140 | 141 |

    Value

    142 | 143 |

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

    144 | 145 | 146 |

    Examples

    147 | 
    
148 | facerec_init()
    #> Succesfully initialized authentification credentials.
    
149 | # enroll
150 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'
151 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')
    #> Error: API did not return json
    
152 | # view subject
153 | view_subject(subject_id = 'finn', gallery = 'starwars')
    #> Error: lexical error: invalid char in json text.
154 | #>                                        Authentication failed
155 | #>                      (right here) ------^
    
156 | 
157 |
    158 |
    159 | 170 |
    171 | 172 | 182 |
    183 | 184 | 185 | 186 | 187 | 188 | 189 | -------------------------------------------------------------------------------- /facerec.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: knitr 13 | LaTeX: pdfLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Package 19 | PackageUseDevtools: Yes 20 | PackageInstallArgs: --no-multiarch --with-keep.source 21 | PackageRoxygenize: rd,collate,namespace 22 | -------------------------------------------------------------------------------- /man/detect.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/detect.R 3 | \name{detect} 4 | \alias{detect} 5 | \title{detect faces} 6 | \usage{ 7 | detect(image, min_head_scale = 0.015) 8 | } 9 | \arguments{ 10 | \item{image}{An image of file type 'JPG', 'PNG', or 'BMP'. 11 | Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}.} 12 | 13 | \item{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).} 14 | } 15 | \value{ 16 | A data frame with annotations for each detected face. 17 | } 18 | \description{ 19 | Detect faces in an input image and return annotations from the 'Kairos' API. 20 | } 21 | \examples{ 22 | \donttest{ 23 | 24 | facerec_init() 25 | 26 | # one image 27 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 28 | faces <- detect(image = finn_image) 29 | 30 | # multiple images 31 | sw_image <- 'https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg' 32 | padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png' 33 | 34 | faces <- c(finn_image, sw_image, padme_image) \%>\% 35 | purrr::map(detect) \%>\% dplyr::bind_rows() 36 | } 37 | 38 | 39 | 40 | } 41 | -------------------------------------------------------------------------------- /man/enroll.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/enroll.R 3 | \name{enroll} 4 | \alias{enroll} 5 | \title{enroll faces} 6 | \usage{ 7 | enroll(image, subject_id, gallery, min_head_scale = 0.015) 8 | } 9 | \arguments{ 10 | \item{image}{An image of file type 'JPG', 'PNG', or 'BMP'. 11 | Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}.} 12 | 13 | \item{subject_id}{A string containing the id to assign for the person in the enrolled image.} 14 | 15 | \item{gallery}{A string containing the name of the gallery in which the image will be enrolled.} 16 | 17 | \item{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).} 18 | } 19 | \value{ 20 | A data frame with annotations for the enrolled image. 21 | } 22 | \description{ 23 | Enroll face in an input image to a gallery and assign a subject id. 24 | } 25 | \examples{ 26 | \donttest{ 27 | 28 | facerec_init() 29 | 30 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 31 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 32 | } 33 | 34 | 35 | } 36 | -------------------------------------------------------------------------------- /man/facerec_init.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/facerec_init.R 3 | \name{facerec_init} 4 | \alias{facerec_init} 5 | \title{authorization} 6 | \usage{ 7 | facerec_init() 8 | } 9 | \value{ 10 | nothing. 11 | } 12 | \description{ 13 | Initializes the authorization credentials for the 'Kairos' Face Recognition API. 14 | Needs to be called before using any other functions of \code{facerec} and requires \code{kairos_id} and \code{kairos_key} as environment variables. 15 | } 16 | \examples{ 17 | \dontrun{ 18 | Sys.setenv(kairos_id = "Your Kairos API id") 19 | Sys.setenv(kairos_key = "Your Kairos API key") 20 | 21 | facerec_init() 22 | } 23 | 24 | 25 | 26 | 27 | } 28 | -------------------------------------------------------------------------------- /man/figures/finn_facerec.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cschwem2er/facerec/af79543940c7a79b742db066bce297707a6bd88e/man/figures/finn_facerec.png -------------------------------------------------------------------------------- /man/figures/sw_facerec.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cschwem2er/facerec/af79543940c7a79b742db066bce297707a6bd88e/man/figures/sw_facerec.png -------------------------------------------------------------------------------- /man/get_galleries.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/get_galleries.R 3 | \name{get_galleries} 4 | \alias{get_galleries} 5 | \title{list galleries} 6 | \usage{ 7 | get_galleries() 8 | } 9 | \value{ 10 | A vector of gallery id's. 11 | } 12 | \description{ 13 | Returns identifiers for all galleries associated with a 'Kairos' application. 14 | } 15 | \examples{ 16 | \donttest{ 17 | 18 | facerec_init() 19 | 20 | # enroll 21 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 22 | first_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 23 | second_gallery <- enroll(image = finn_image, subject_id = 'finn', gallery = 'more_starwars') 24 | 25 | # get_galleries 26 | get_galleries() 27 | } 28 | 29 | 30 | } 31 | -------------------------------------------------------------------------------- /man/get_gallery_subjects.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/get_gallery_subjects.R 3 | \name{get_gallery_subjects} 4 | \alias{get_gallery_subjects} 5 | \title{get gallery subjects} 6 | \usage{ 7 | get_gallery_subjects(gallery) 8 | } 9 | \arguments{ 10 | \item{gallery}{The gallery in which the subjects are enrolled.} 11 | } 12 | \value{ 13 | A vector of subject id's 14 | } 15 | \description{ 16 | Returns all subject id's associated with a gallery. 17 | } 18 | \examples{ 19 | \donttest{ 20 | 21 | facerec_init() 22 | 23 | # enroll 24 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 25 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 26 | 27 | # view subjects 28 | get_gallery_subjects(gallery = 'starwars') 29 | } 30 | 31 | 32 | } 33 | -------------------------------------------------------------------------------- /man/pipe.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils-pipe.R 3 | \name{\%>\%} 4 | \alias{\%>\%} 5 | \title{Pipe operator} 6 | \usage{ 7 | lhs \%>\% rhs 8 | } 9 | \description{ 10 | Pipe operator 11 | } 12 | \keyword{internal} 13 | -------------------------------------------------------------------------------- /man/prep_image.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/prep_image.R 3 | \name{prep_image} 4 | \alias{prep_image} 5 | \title{prepare local image} 6 | \usage{ 7 | prep_image(img_file) 8 | } 9 | \arguments{ 10 | \item{img_file}{Path to an image of file type 'JPG', 'PNG', or 'BMP'.} 11 | } 12 | \value{ 13 | The prepared image object. 14 | } 15 | \description{ 16 | Prepares a local image for an upload the 'Kairos' API via \code{\link[facerec]{detect}}, 17 | \code{\link[facerec]{enroll}}, \code{\link[facerec]{recognize}} and \code{\link[facerec]{verify}}. 18 | } 19 | \examples{ 20 | \donttest{ 21 | 22 | facerec_init() 23 | 24 | # download example image 25 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 26 | temp_img_path <- tempfile(fileext = '.png') 27 | download.file(finn_image, temp_img_path, mode = 'wb', quiet = TRUE) 28 | 29 | # prepare image 30 | finn_local <- prep_image(temp_img_path) 31 | 32 | # use prepared image 33 | faces <- detect(image = finn_local) 34 | } 35 | 36 | } 37 | -------------------------------------------------------------------------------- /man/recognize.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/recognize.R 3 | \name{recognize} 4 | \alias{recognize} 5 | \title{recognize face} 6 | \usage{ 7 | recognize(image, gallery, min_head_scale = 0.015, threshold = 0.6, 8 | max_num_results = 10, show_candidate_images = TRUE) 9 | } 10 | \arguments{ 11 | \item{image}{An image of file type JPG, PNG, or BMP. 12 | Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}.} 13 | 14 | \item{gallery}{A string containing the name of the gallery in which the image will be enrolled.} 15 | 16 | \item{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).} 17 | 18 | \item{threshold}{Likelihood (between 0 and 1) used to determine a valid facial match. Defaults to 0.6.} 19 | 20 | \item{max_num_results}{The maximum number of potential matches that are returned. Defaults to 10.} 21 | 22 | \item{show_candidate_images}{Whether to return temporary URLs for each potential match. Defaults to TRUE.} 23 | } 24 | \value{ 25 | A dataframe with the potential matches for the input image. The likelihood of matches is given in column \code{confidence}. 26 | } 27 | \description{ 28 | Recognize faces in an image and return the most likely matches from a gallery. 29 | } 30 | \examples{ 31 | \donttest{ 32 | 33 | facerec_init() 34 | 35 | # enroll 36 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 37 | padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png' 38 | finn_face <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 39 | padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars') 40 | 41 | # recognize 42 | finn_2 <- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg' 43 | finn_rec <- recognize(image = finn_2, gallery = 'starwars') 44 | 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /man/remove_gallery.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/remove_gallery.R 3 | \name{remove_gallery} 4 | \alias{remove_gallery} 5 | \title{remove gallery} 6 | \usage{ 7 | remove_gallery(gallery) 8 | } 9 | \arguments{ 10 | \item{gallery}{The name of the gallery to be removed.} 11 | } 12 | \value{ 13 | nothing. 14 | } 15 | \description{ 16 | Removes a gallery and all included subjects. 17 | } 18 | \examples{ 19 | \donttest{ 20 | 21 | 22 | facerec_init() 23 | 24 | # enroll 25 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 26 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 27 | 28 | # remove gallery 29 | remove_gallery(gallery = 'starwars') 30 | } 31 | 32 | 33 | } 34 | -------------------------------------------------------------------------------- /man/remove_subject.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/remove_subject.R 3 | \name{remove_subject} 4 | \alias{remove_subject} 5 | \title{remove subject} 6 | \usage{ 7 | remove_subject(subject_id, gallery) 8 | } 9 | \arguments{ 10 | \item{subject_id}{The subject id for the subject to be removed.} 11 | 12 | \item{gallery}{The name of the gallery in which the subject is enrolled.} 13 | } 14 | \value{ 15 | nothing. 16 | } 17 | \description{ 18 | Removes a subject from a gallery. 19 | } 20 | \examples{ 21 | \donttest{ 22 | 23 | facerec_init() 24 | 25 | # enroll 26 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 27 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 28 | 29 | # remove subject 30 | remove_subject(subject_id = 'finn', gallery = 'starwars') 31 | } 32 | 33 | 34 | } 35 | -------------------------------------------------------------------------------- /man/verify.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/verify.R 3 | \name{verify} 4 | \alias{verify} 5 | \title{verify face} 6 | \usage{ 7 | verify(image, subject_id, gallery) 8 | } 9 | \arguments{ 10 | \item{image}{An image of file type 'JPG', 'PNG', or 'BMP'. 11 | Can either be an url string or a local image processed with \code{\link[facerec]{prep_image}}.} 12 | 13 | \item{subject_id}{A string containing the id for the person in the gallery to be verified.} 14 | 15 | \item{gallery}{A string containing the name of the gallery in which the subject will be verified.} 16 | } 17 | \value{ 18 | A data frame with the verification annotations for the input image. The likelihood of a match is given in column \code{confidence}. 19 | } 20 | \description{ 21 | Verify whether face in an input image belongs to a subject in a gallery. 22 | } 23 | \examples{ 24 | 25 | \donttest{ 26 | 27 | facerec_init() 28 | 29 | # enroll 30 | padme_image <- 'https://upload.wikimedia.org/wikipedia/en/e/ee/Amidala.png' 31 | padme_face <- enroll(image = padme_image, subject_id = 'padme', gallery = 'starwars') 32 | 33 | # verify 34 | amidala_img <- 'https://upload.wikimedia.org/wikipedia/it/5/5e/Padm\%C3\%A9_Amidala.png' 35 | verified <- verify(image = amidala_img, subject_id = 'padme', gallery = 'starwars') 36 | 37 | } 38 | 39 | } 40 | -------------------------------------------------------------------------------- /man/view_subject.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/view_subject.R 3 | \name{view_subject} 4 | \alias{view_subject} 5 | \title{view subject} 6 | \usage{ 7 | view_subject(subject_id, gallery) 8 | } 9 | \arguments{ 10 | \item{subject_id}{The subject id for which to return all face id's.} 11 | 12 | \item{gallery}{The gallery in which the subject is enrolled.} 13 | } 14 | \value{ 15 | A dataframe with face id's and enrollment timestamps associated with the input subject. 16 | } 17 | \description{ 18 | Returns all face id's for each image enrolled for a given subject in a gallery. 19 | } 20 | \examples{ 21 | \donttest{ 22 | 23 | facerec_init() 24 | 25 | # enroll 26 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_\%282015\%29.png' 27 | finn_enroll <- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars') 28 | 29 | # view subject 30 | view_subject(subject_id = 'finn', gallery = 'starwars') 31 | } 32 | 33 | 34 | } 35 | -------------------------------------------------------------------------------- /vignettes/intro.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Introduction to facerec" 3 | output: rmarkdown::html_vignette 4 | vignette: > 5 | %\VignetteIndexEntry{Introduction to facerec} 6 | %\VignetteEngine{knitr::rmarkdown} 7 | %\VignetteEncoding{UTF-8} 8 | --- 9 | 10 | ```{r setup, include = FALSE} 11 | knitr::opts_chunk$set( 12 | collapse = TRUE, 13 | comment = "#>" 14 | ) 15 | ``` 16 | 17 | # An Interface for Face Recognition in R 18 | 19 | 20 | The facerec package provides an interface to the [Kairos Face Recognition API](https://www.kairos.com/docs/api/). The API detects faces in images and returns estimates for demographics. It is also capable of recognizing and verifying humans across several images. 21 | 22 | ## How to Install 23 | 24 | To install the CRAN version of facerec use ``install.packages('facerec')``. 25 | 26 | You can also download and install the latest development version of the app by running ``devtools::install_github('cschwem2er/facerec')``. For Windows users installing from github requires proper setup of [Rtools](https://cran.r-project.org/bin/windows/Rtools/), for which a tutorial is available [here](https://github.com/stan-dev/rstan/wiki/Install-Rtools-for-Windows). 27 | 28 | 29 | 30 | ## How to Use 31 | 32 | ### Authentification 33 | 34 | After loading facerec you first need to initiate your authentification credentials. Kairos offers a [free trial](https://www.kairos.com/pricing) 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 `facerec_init()`: 35 | 36 | 37 | ```{r, eval = FALSE} 38 | Sys.setenv(kairos_id = "Your Kairos API id") 39 | Sys.setenv(kairos_key = "Your Kairos API key") 40 | ``` 41 | 42 | ```{r, eval = FALSE} 43 | library(facerec) 44 | facerec_init() 45 | ``` 46 | 47 | 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. 48 | 49 | ### Face Recognition 50 | 51 | The Kairos API accepts images 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](https://en.wikipedia.org/wiki/Finn_(Star_Wars)): 52 | 53 | 54 | 55 | ```{r, eval = FALSE} 56 | finn_image <- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png' 57 | finn_face <- detect(image = finn_image) 58 | ``` 59 | 60 | The function returns a dataframe with annotations for the recognized faces in the input image. Variables include positional features of faces, such as x and y coordinates for eyes. Moreover, demographic attributes like gender, ethnicity and age are available. 61 | 62 | Features can be visualized with the packages magick and ggplot2: 63 | 64 | ```{r finn, fig.height=4, fig.width=3, eval = FALSE} 65 | library(magick) 66 | library(ggplot2) 67 | library(scales) 68 | 69 | finn_image %>% image_read() %>% image_ggplot() + 70 | geom_rect(data = finn_face, 71 | aes(xmin = top_left_x, xmax = top_left_x + width, 72 | ymin = top_left_y, ymax = top_left_y + height), 73 | fill = NA, linetype = 'dashed', size = 2, color = '#377eb8') + 74 | geom_label(data = finn_face, 75 | aes(x = chin_tip_x, y = chin_tip_y + 20, 76 | label = paste('Gender:', 77 | percent(face_gender_male_confidence), 78 | 'Male')), size = 6, color = '#377eb8') + 79 | geom_label(data = finn_face, 80 | aes(x = chin_tip_x, y = chin_tip_y + 60, 81 | label = paste('Ethnicity:', percent(face_black), 82 | 'Black')), size = 6, color = '#377eb8') + 83 | theme(legend.position="none") 84 | ``` 85 | 86 | 87 | 88 | Kairos has [some recommendations](https://www.kairos.com/docs/api/best-practices) for improving the quality of its recognition service, but in general, the API also works with multiple faces inside an image: 89 | 90 | ```{r sw, fig.height=3, fig.width=4.8, eval = FALSE} 91 | sw_img <- "https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg" 92 | sw_faces <- detect(sw_img) 93 | 94 | sw_img %>% image_read() %>% image_ggplot() + 95 | geom_rect(data = sw_faces, 96 | aes(xmin = top_left_x , xmax = top_left_x + width, 97 | ymin = top_left_y, ymax = top_left_y + height, 98 | color = factor(face_id)), 99 | fill = NA, linetype = 'dashed', size = 2) + 100 | geom_label(data = sw_faces, 101 | aes(x = chin_tip_x, y = chin_tip_y + 15, 102 | label = face_gender_type, 103 | color = factor(face_id)), size = 8) + 104 | theme(legend.position="none") 105 | ``` 106 | 107 | 108 | 109 | 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: 110 | 111 | ```{r recognize, eval = FALSE} 112 | finn_face <- enroll(image = finn_image, 113 | subject_id = 'finn', gallery = 'starwars') 114 | finn_new <- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg' 115 | finn_rec <- recognize(image = finn_new, gallery = 'starwars', 116 | show_candidate_images = FALSE) 117 | ``` 118 | 119 | The function `recognize()` returns a dataframe including the probability of a match in the column `confidence`. 120 | --------------------------------------------------------------------------------