{"id":13465889,"url":"https://github.com/matiasdelellis/facerecognition","last_synced_at":"2025-05-15T14:04:27.204Z","repository":{"id":37587471,"uuid":"105786689","full_name":"matiasdelellis/facerecognition","owner":"matiasdelellis","description":"Nextcloud app that implement a basic facial recognition system.","archived":false,"fork":false,"pushed_at":"2025-04-22T13:29:18.000Z","size":3722,"stargazers_count":540,"open_issues_count":147,"forks_count":47,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-15T07:45:43.909Z","etag":null,"topics":["dlib","face-detection","face-recognition","hacktoberfest","nextcloud","pdlib","photos"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matiasdelellis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":"https://github.com/matiasdelellis/facerecognition/wiki/Donate"}},"created_at":"2017-10-04T15:44:18.000Z","updated_at":"2025-04-29T02:01:33.000Z","dependencies_parsed_at":"2024-05-02T17:52:28.822Z","dependency_job_id":"a6a6a473-4988-4566-a7a7-9252569331cc","html_url":"https://github.com/matiasdelellis/facerecognition","commit_stats":{"total_commits":903,"total_committers":13,"mean_commits":69.46153846153847,"dds":"0.12181616832779618","last_synced_commit":"cbf6ad8c22b442a26fb57718619dc1876d5df917"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matiasdelellis","download_url":"https://codeload.github.com/matiasdelellis/facerecognition/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355334,"owners_count":22057354,"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","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":["dlib","face-detection","face-recognition","hacktoberfest","nextcloud","pdlib","photos"],"created_at":"2024-07-31T15:00:36.649Z","updated_at":"2025-05-15T14:04:27.186Z","avatar_url":"https://github.com/matiasdelellis.png","language":"PHP","readme":"# Face Recognition\n\n![PHPUnit Status](https://img.shields.io/github/workflow/status/matiasdelellis/facerecognition/PHPUnit)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/?branch=master)\n[![Code Coverage](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/?branch=master)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/4b035bd1283349009ad88235d37ddae1)](https://www.codacy.com/app/stalker314314/facerecognition?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=matiasdelellis/facerecognition\u0026amp;utm_campaign=Badge_Grade)\n![Downloads](https://img.shields.io/github/downloads/matiasdelellis/facerecognition/total)\n[![License](https://img.shields.io/badge/license-AGPLv3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0.en.html)\n\nNextcloud app that implement a basic facial recognition system.\n\nFaceRecognition is a Nextcloud application with a goal of recognizing, analyzing\nand aggregating face data in users images, and providing additional\nfunctionalities on top of these information, all with built-in privacy of\nNextcloud. Imagine Google Photos, but only for faces (not detecting objects…)\nand in such way that your images never leave your Nextcloud instance. :smiley:\n\nThe application listens to the creation of new image files, and queues them for\nlater analysis. A scheduled task (Or admin on demand) take this queue, and\nanalyze the images for looking faces and if possible identify them grouping by\nsimilarity.\n\n![App screenshots](https://matiasdelellis.github.io/img/facerecognition/facerecognition-persons-view-small.jpeg \"App screenshots\")\n\n## How to use it?\n\nThe administrator must properly configure the application, and once it is\nworking, the user must accept that he wants to allow the analysis of his images\nto discover his friends.\nFinally the user can use the application in three ways\n\n 1. In the user settings there is a 'Face Recognition' panel where first of all\n    each user must enable the analysis. Once enabled, you will progressively see\n    the discovery of your friends, and you can assign them names.\n 2. In the file application the user can search by typing your friend's name,\n    and it will show all the photos.\n 3. In the side panel of the file application, a 'Persons' tab is added where\n    you can see a list of your friends in the photo, and rename them. Also you can\n    select the folders you want to ignore for the process.\n 3. In the side panel of the Photos application, a 'Persons' tab is added where\n    you can see a list of your friends in the photo, and rename them.\n\n## Donate\n\nIf you'd like to support the creation and maintenance of this software, consider donating.\n\n[![Donate](https://img.shields.io/badge/Donate-PayPal-blue)](https://github.com/matiasdelellis/facerecognition/wiki/Donate)\n[![Donate](https://img.shields.io/badge/Donate-Bitcoin-orange)](https://github.com/matiasdelellis/facerecognition/wiki/Donate)\n[![Donate](https://img.shields.io/badge/Donate-Ethereum-blueviolet)](https://github.com/matiasdelellis/facerecognition/wiki/Donate)\n\n## Installation, configuration and usage\n\n#### Requirements\n\n * Nextcloud 22+\n * [Dlib PHP bindings](https://github.com/goodspb/pdlib)\n * [PHP Bzip2](https://www.php.net/manual/en/book.bzip2.php)\n * 1GB of RAM\n\n#### Installation\n\nIdeally once you meet the requirements, you can install and enable it from the\nnextcloud app store. For details and advanced information read the documentation\nabout [installation](https://github.com/matiasdelellis/facerecognition/wiki/Installation).\n\n#### Configuration\n\nBefore proceeding to analyze the images, you must indicate how much memory you\nwant to assigns to image processing and then must properly install and configure\nthe pretrained models using the `occ face:setup` command. For details and\nadvanced information read the documentation about [models](https://github.com/matiasdelellis/facerecognition/wiki/Models#install-models).\n\nThen you must indicate the size of the images used in the temporary files from\nthe Nextcloud settings panel. This configuration will depend on your\ninstallation and has a direct impact on memory consumption. For details and\nadvanced information read the documentation about [Temporary files](https://github.com/matiasdelellis/facerecognition/wiki/Settings#temporary-files).\n\n#### Test the application\n\nWe recommend test the application intensively before proceeding to analyze the\nreal data of the users. For this you can create a new user in your Nextcloud\ninstance and upload some photos from the internet. Then you must run the\n`occ face:background_job -u new_user -t 900` command for this user and evaluate\nthe result. For details and advanced information read the documentation of this\ncommand below.\n\n#### Schedule background job\n\nThe application is designed to run as a scheduled task. This allows analyze the\nphotos and showing the results to the user progressively. You can read about\nsome ways to configure it within our documentation about [Schedule Background Task](https://github.com/matiasdelellis/facerecognition/wiki/Schedule-Background-Task).\n\n## occ commands\n\nThe application add commands to the [Nexcloud's command-line interface](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html).\n\n#### Initial setup\n\n`occ face:setup [-M|--memory MEMORY] [-m|--model MODEL]`\n\nThis command is responsible for making the necessary settings to use the\napplication.\n\nIf `MEMORY` is supplied, it will establish the maximum memory to be used for the\nprocessing of the images. This value will be limited according to the memory\navailable by the system and the php configuration. You can use numbers as bytes\n(1073741824 for 1GB), or subfixed with units (1024M or 1G) but note that it is\nwithout space.\n\nIf `MODEL_ID` is supplied. the pre-trained model for facial recognition will be\ninstalled.\n\nYou must perform both settings before continuing with any application command.\nIf you do not supply any of these options, the command will return the current\nconfiguration.\n\n#### Face analysis\n\n`occ face:background_job [-u|--user_id USER_ID] [-t|--timeout TIMEOUT] [--defer-clustering] [-M|--max_image_area MAX_IMAGE_AREA]`\n\nThis command will do all the work. It is responsible for searching the images,\nanalyzing them and clustering faces found in them in groups of similar people.\n\nBeware that this command can take a lot of CPU and memory! Before you put it to\ncron job, it is advised to try it out manually first, just to be sure you have\nall requirements and you have enough resources on your machine.\n\nCommand is designed to be run continuously, so you will want to schedule it with\ncron to be executed every once in a while, together with a specified timeout. It\ncan be run every 15 minutes with timeout of `-t 900` (so, it will stop itself\nautomatically after 15 minutes and cron will start it again), or once a day with\ntimeout of 2 hours, like `-t 7200`.\n\nIf `USER_ID` is supplied, it will just loop over files of a given user. Keep in\nmind that each user must enable the analysis individually, and otherwise this\ncommand will ignore the user.\n\nIf `TIMEOUT` is supplied it will stop after the indicated seconds, and continue\nin the next execution. Use this value in conjunction with the times of the\nscheduled task to distribute the system load during the day.\n\nIf `MAX_IMAGE_AREA` is supplied caps the maximum area (in pixels^2) of the image\nto be fed to neural network, effectively lowering needed memory. Use this\nif face detection crashes randomly.\n\nIf use the `--defer-clustering` option, it changes the order of execution of the\nprocess deferring the face clustering at the end of the analysis to get persons\nin a simple execution of the command.\n\n#### Create albums in the Photos app\n\n`face:sync-albums [-u|--user_id USER_ID]`\n\nThis command creates photo albums within the Nexcloud Photos app, with photos of\neach person found.\n\nNote that these albums are editable in the Photos app, and any changes will be\nignored and reverted on the next run of this command.\n\nThis command is also designed to be run regularly to sync any user changes, as\nthis command is the only one that will update albums.\n\nIf `USER_ID` is provided, it will just sync albums for this user.\n\n#### Resetting information\n\n`occ face:reset [--all] [--model] [--image-errors] [--clustering] [-u|--user_id USER_ID]`\n\nThis command can completely wipe out all images, faces and cluster of persons.\nIt is ideal if you want to start from scratch for any reason.\n\nYou must specify if you wish to completely reset the database `[--all]` or just\nthe current model `[--model]` and all images must be analyzed again, or or you\ncan reset only the clustering of persons `[--clustering]` and only clustering\nneeds to be done again, or reset only the images that had errors\n`[--image-errors]` to try to analyze them again.\n\nIf `USER_ID` is provided, it will just reset the information of a particular\nuser.\n\n#### Migrate models\n\n`occ face:migrate [-m|--model_id MODEL_ID] [-u|--user_id USER_ID]`\n\nThis command allows to migrate the faces obtained in a model to a new one. Note\nthat the persons name  are not migrated, and the user must rename them again.\nAlways is recommended to analyze from scratch any configured model, but you can\nsave a lot of time migrating it.\n\nYou must specify which model you want to migrate using the `MODEL_ID` option.\n\nIf `USER_ID` is provided, just migrate the faces for the given user.\n\n#### Statistics\n\n`occ face:stats [-u|--user_id USER_ID] [-j|--json]`\n\nThis command return a summary of the number of images, faces and persons found.\n\nIf `USER_ID` is provided, just return the stats for the given user.\n\nIf use the `--json` argument, it prints the stats in a json format more suitable\nto parse with other tools.\n\n#### Progress\n\n`occ face:progress`\n\nThis command just return the progress of the analysis and an estimated time to\ncomplete.\n\nIf use the `--json` argument, it prints the stats in a json format more suitable\nto parse with other tools.\n","funding_links":["https://github.com/matiasdelellis/facerecognition/wiki/Donate"],"categories":["Apps","PHP"],"sub_categories":["Unofficial"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatiasdelellis%2Ffacerecognition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatiasdelellis%2Ffacerecognition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatiasdelellis%2Ffacerecognition/lists"}