{"id":13858030,"url":"https://github.com/cschwem2er/facerec","last_synced_at":"2025-12-12T02:16:35.379Z","repository":{"id":56937267,"uuid":"133087557","full_name":"cschwem2er/facerec","owner":"cschwem2er","description":"An Interface for Face Recognition in R","archived":false,"fork":false,"pushed_at":"2019-06-18T09:50:04.000Z","size":360,"stargazers_count":35,"open_issues_count":3,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-09-08T15:44:54.291Z","etag":null,"topics":["imagerecognition","r"],"latest_commit_sha":null,"homepage":"https://cschwem2er.github.io/facerec","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cschwem2er.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-11T20:52:06.000Z","updated_at":"2025-03-12T09:19:31.000Z","dependencies_parsed_at":"2022-08-21T01:00:10.288Z","dependency_job_id":null,"html_url":"https://github.com/cschwem2er/facerec","commit_stats":null,"previous_names":["methodds/facerec"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cschwem2er/facerec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cschwem2er%2Ffacerec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cschwem2er%2Ffacerec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cschwem2er%2Ffacerec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cschwem2er%2Ffacerec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cschwem2er","download_url":"https://codeload.github.com/cschwem2er/facerec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cschwem2er%2Ffacerec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27537239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-06T02:00:06.463Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["imagerecognition","r"],"created_at":"2024-08-05T03:01:54.381Z","updated_at":"2025-12-12T02:16:35.351Z","avatar_url":"https://github.com/cschwem2er.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"README-\"\n)\n```\n\n# facerec\n\n\n[![Travis-CI Build Status](https://travis-ci.org/cschwem2er/facerec.svg?branch=master)](https://travis-ci.org/cschwem2er/facerec)\n[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/cschwem2er/facerec?branch=master\u0026svg=true)](https://ci.appveyor.com/project/cschwem2er/facerec)\n[![CRAN status](https://www.r-pkg.org/badges/version/facerec)](https://cran.r-project.org/package=facerec)\n[![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/facerec)](https://cran.rstudio.com/web/packages/facerec/index.html)\n\n```{r, include = FALSE}\n#[![CRAN status](https://www.r-pkg.org/badges/version/facerec)](https://cran.r-project.org/package=facerec)\n#[![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/facerec)](https://cran.rstudio.com/web/packages/facerec/index.html)\n```\n\n## An Interface for Face Recognition in R\n\nThis 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. \n\nImportant 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.\n\n## How to Install\n\nTo install the CRAN version of facerec use ``install.packages('facerec')``.\n\nYou 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).\n\n\n## How to Use\n\n### Authentification\n\nAfter 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()`:\n\n\n```{r, eval = FALSE}\nSys.setenv(kairos_id = \"Your Kairos API id\")\nSys.setenv(kairos_key = \"Your Kairos API key\")\n```\n\n```{r, eval = FALSE}\nlibrary(facerec)\nfacerec_init()\n```\n\nYou 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.\n\n### Face Recognition\n\nKairos 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)):\n\n\u003cimg src=\"https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png\" width=\"250\"\u003e\n\n```{r, eval = FALSE}\nfinn_image \u003c- 'https://upload.wikimedia.org/wikipedia/en/2/2a/Finn-Force_Awakens_%282015%29.png'\nfinn_face \u003c- detect(image = finn_image)\n```\n\nThe 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.\n\nFeatures 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):\n\n```{r fig.height=4, fig.width=3, eval = FALSE}\nlibrary(magick)\nlibrary(ggplot2)\n\n finn_image %\u003e% image_read() %\u003e% image_ggplot() + \n   geom_rect(data = finn_face, \n             aes(xmin = top_left_x, xmax = top_left_x + width, \n                 ymin = top_left_y, ymax = top_left_y + height),\n             fill = NA, linetype = 'dashed', size = 2, color = '#377eb8') +\n   geom_label(data = finn_face,\n             aes(x = chin_tip_x, y = chin_tip_y + 20, \n                 label = paste('Gender:', \n                               scales::percent(face_gender_male_confidence),\n                 'Male')), size = 6, color = '#377eb8') +\n   geom_label(data = finn_face,\n             aes(x = chin_tip_x, y = chin_tip_y + 60, \n                 label = paste('Ethnicity:', scales::percent(face_black),\n                 'Black')), size = 6, color = '#377eb8') +\n   theme(legend.position=\"none\")\n```\n\n\u003cimg src=\"man/figures/finn_facerec.png\" width=\"250\"\u003e\n\nKairos 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:\n\n```{r fig.height=3, fig.width=4.8, eval = FALSE}\nsw_img \u003c- \"https://upload.wikimedia.org/wikipedia/en/8/82/Leiadeathstar.jpg\"\nsw_faces \u003c- detect(sw_img)\n\nsw_img %\u003e% image_read() %\u003e% image_ggplot() + \n   geom_rect(data = sw_faces, \n             aes(xmin = top_left_x , xmax =  top_left_x + width, \n                 ymin = top_left_y, ymax = top_left_y + height, \n                 color = factor(face_id)),\n             fill = NA, linetype = 'dashed', size = 2) +\n   geom_label(data = sw_faces,\n             aes(x = chin_tip_x, y = chin_tip_y + 15, \n                 label = face_gender_type,\n                 color = factor(face_id)), size = 8) +\n   theme(legend.position=\"none\")\n```\n\n\u003cimg src=\"man/figures/sw_facerec.png\" width=\"400\"\u003e\n\nBesides 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.\n\n```{r, eval = FALSE}\nfinn_face \u003c- enroll(image = finn_image, subject_id = 'finn', gallery = 'starwars')\nfinn_new \u003c- 'https://upload.wikimedia.org/wikipedia/commons/b/b6/John_Boyega_by_Gage_Skidmore.jpg'\nfinn_rec \u003c- recognize(image = finn_new, gallery = 'starwars',\n                      show_candidate_images = FALSE)\n```\n\nThe function `recognize()` returns a dataframe including the probability of a match in the column `confidence`.\n\n## Citation\n\n\nIf you use facerec for your publications please consider citing it:\n\n\n```\n  Carsten Schwemmer (2018). facerec: An interface for face recognition in R. R package version 0.1.0.\n  https://github.com/cschwem2er/facerec\n```\n\nA BibTeX entry for LaTeX users is:\n\n```\n  @Manual{,\n    title = {facerec: An interface for face recognition in R},\n    author = {Carsten Schwemmer},\n    year = {2018},\n    note = {R package version 0.1.0},\n    url = {https://github.com/cschwem2er/facerec},\n  }\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcschwem2er%2Ffacerec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcschwem2er%2Ffacerec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcschwem2er%2Ffacerec/lists"}