{"id":21594188,"url":"https://github.com/ornl/faro","last_synced_at":"2025-04-10T23:41:10.378Z","repository":{"id":40982203,"uuid":"170163148","full_name":"ORNL/faro","owner":"ORNL","description":"Face Recognition from Oak Ridge (FaRO) provides a well-defined server-client interface to a some of the best open source face recognition projects on the web. ","archived":false,"fork":false,"pushed_at":"2024-07-16T13:31:18.000Z","size":46169,"stargazers_count":6,"open_issues_count":14,"forks_count":12,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-24T20:23:18.670Z","etag":null,"topics":["artificial-intelligence","machine-learning"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ORNL.png","metadata":{"files":{"readme":"README.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-11T16:35:15.000Z","updated_at":"2022-10-12T23:37:36.000Z","dependencies_parsed_at":"2024-06-26T17:42:45.249Z","dependency_job_id":"a102d344-61cb-4c52-a117-356f1db90cf1","html_url":"https://github.com/ORNL/faro","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2Ffaro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2Ffaro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2Ffaro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORNL%2Ffaro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ORNL","download_url":"https://codeload.github.com/ORNL/faro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248317732,"owners_count":21083525,"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":["artificial-intelligence","machine-learning"],"created_at":"2024-11-24T17:16:26.771Z","updated_at":"2025-04-10T23:41:10.357Z","avatar_url":"https://github.com/ORNL.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FARO: Readme\n\n## Overview\nFace Recognition from Oak Ridge (FaRO) provides a well-defined server-client \ninterface to some of the best open source face recognition projects on the \nweb.  The intention is to support an open platform for face recognition research \nand to provide a well-defined and modern baseline for face recognition accuracy.  \nWhile many universities and independent developers have released high quality \nface recognition models, they often lack many useful features such as \nconfiguration management, easy to use interfaces, deployment tools, backend \ndatabases, and analysis tools that FaRO provides.\n \nIn our research we have found that there are many high quality and open source \nface analysis and recognition algorithms available for research; however, \nend-to-end systems that can support larger systems or that can be retrained for niche \napplications are lacking. We hope FARO can fill some of those needs.\n\nThe primary goals of this project are:\n 1. Create an easy to use foundation that can support complex face recognition systems.\n 2. Provide well-defined benchmark algorithms.\n 3. Allow for algorithm improvements via open source software and models and to support improvements using techniques like transfer learning. \n\nFaRO is designed as a client/server system to accomodate the need for high speed GPU \nhardware to support deep learning face processing.  GRPC calls are used to communicate \nwith the server components which allows the clients to be written in many languages and \nimplemented on a varity of computationally limited platforms such as cellphones or biometric\ncollection devices.  \n\n## Publications\n\nIf you use FARO for publications please cite as:\n\n```\n@misc{bolme2019faro,\n    title={{FaRO}: {FA}ce {R}ecognition From {O}ak ridge},\n    author={David S. Bolme and David C. Cornett III and Nisha Srinivas},\n    year={2019},\n    howpublished={https://github.com/ORNL/faro}\n}\n```\n\n## System Requirements:\nMany FaRO services should run nicely on limited hardware resources.  As we \nintegrate more deep learning algorithms, those may require GPUs and additional \nhardware.\n\n * Software: python3, virtualenv, cmake, wget\n * Python Libraries: see requirements.txt\n * NVidia GPU with 8GB of Ram - GTX Titan X/1070/1080 or better \n * nvidia-docker2 - supporting Cuda 9.0\n\n\n## Quick Start\n\nThis is intended to get Dlib algorithm up and running quickly.  This is a good \nplace to start and will allow you to test the FaRO interface.  A few \ndependencies may be needed on a fresh Ubuntu installation including: cmake, \npython2, and python3.  The install scripts will download and install many other\ndependencies in the user directory as well as some large machine learning \nmodels.  To get some initial dependencies install:\n\n```\n$ sudo apt install cmake\n$ sudo apt install python2-dev\n$ sudo apt install python3-dev\n$ sudo apt install virtualenv\n$ sudo apt install wget\n```\n\nFirst build the client environment and compile the proto interfaces.\n\n```\n$ ./build-env-universal.sh\n#For Mac users run - $echo \"export PYTHONPATH=`pwd`/src:$PYTHONPATH\" \u003e\u003e \"$HOME/.bash_profile\" - after running build-env-universal.sh\nif using virtualenv,\n    $ source env_faro_server/bin/activate\n\nif using conda,\n    $ source activate env_faro_server\n    or\n    $ conda activate env_faro_server\n\n$ ./build-proto.sh\n```\n\n\nIn one terminal run the Dlib service.  When you do this for the first time it \nwill create a \"faro-storage\" directory and will download and extract the machine\nlearning models.  At the end it will print out messages for each started worker:\n\"Worker N Started.\"  By default the service is started on port localhost:50030.\n\nIf using virtualenv,\n```\n$ source env_faro_server/bin/activate\n$ cd services/dlib\n$ ./run-dlib.sh\n```\n\nIf using conda, \n\n```\n$ source activate env_faro_server or conda activate env_faro_server\n$ cd services/dlib\n$ ./run_dlib.sh\n```\n\nThe VGG2Resnet model can also be run using similar commands, but only run one \nservice at a time unless you carefully configure the ports and check available \nmemory, etc.\n\nIf using virtualenv,\n\n```\n$ source env_faro_server/bin/activate\n$ cd services/vggface2\n$ ./run-vgg2.sh\n```\n\nIf using conda,\n\n```\n$ source activate env_faro_server or conda activate env_faro_server\n$ cd services/vggface2\n$ ./run_vgg2.sh\n```\n\nSimilarly, InsightFace algorithms can be executed using similar commands.\nFace detection is performed using RetinaFace and features are extracted using ArcFace.\nCurrently, InsightFace works only with 1 GPU and worker.\n\nIf using virtualenv,\n\n```\n$ source env_faro_server/bin/activate \n$ cd services/arcface\n$ ./run_arcface.sh\n```\n\nIf using conda,\n\n```\n$ source activate env_faro_server or conda activate env_faro_server    \n$ cd services/arcface\n$ ./run_arcface.sh\n```\n  \nIn a second terminal run client applications. For this you can use either the \n\"env_faro\" or \"env_faro_server\" environments.  Test scripts are available in\nthe test directory to test the workings of the different functionalities in FaRO.\n\nTo test the scripts,\n\nIf using virtualenv,\n```\n$ source env_faro/bin/activate\n$ cd tests\n```\n\nIf using conda,\n\n```\n$ source activate env_faro or conda activate env_faro\n$ cd tests\n```\n\nTo test the detect functionality on images execute,\n\n```\n$./test_detect.sh\n```\n\nTo test the detect functionality in videos execute,\n\n```\n$./test_detect_videos.sh\n```\n\n\n## Install With PIP\nThis is a simple way to add FaRO to the environment.  It should install everything needed to run client api calls, but it may not provide all the configurations or models needed to run services.\n\n```\n$ pip install git+https://github.com/ORNL/faro.git\n```\n\n## Run a Service Command Line\nStarting python services can be done with a simple command line.  This will start the service specifying the port, the number of workers, and the algorithm.\n\n```\n$ python -m faro.FaceService --port=localhost:50030 --worker-count=2 --algorithm=dlib\n```\n\n## Using the Client API\n\nExamples can be found in the Notebooks directory.  The best place to start is the [FaRO Client Usage notebook](https://github.com/ORNL/faro/blob/master/Notebooks/FaRO%20Client%20Usage.ipynb).\n\nor \n\nFaRO_Client_Face_Detection_Video_and_Images.ipynb\n\nThe client can access the services using the FaRO command line interface. The CLI includes the following functions/commands\n\n```\n#client environment has to be activated\n$ cd bin\n$ ./faro \n\nusage : ./faro \u003ccommand\u003e --help\nlist the commands to be used\nCommands:\n    flist - List the faces in a gallery.\n    detectExtract - Run face detection and template extraction.\n    glist - List the galleries on the service.\n    test - Process a probe and gallery directory and produce a distance matrix.\n    extractOnly - Only run face extraction and attribute extraction.\n    enroll - Extract faces and enroll faces in a gallery.\n    search - Search images for faces in a gallery.\n    detect - Only run face detection.\n    \n#to run detect command and find its input options execute,\n$./faro detect --help\n\nUsage: ./faro command [OPTIONS] [image] [image_directory] [video] [...]\n\nRun detection on a collection of images.\n\nOptions:\n  --version             show program's version number and exit\n  -h, --help            show this help message and exit\n  -v, --verbose         Print out more program information.\n  -n MAX_IMAGES, --max-images=MAX_IMAGES\n                        Process at N images and then stop.\n  --maximum-size=MAX_SIZE\n                        If too large, images will be scaled to have this\n                        maximum size. Default=1920\n\n  Detector Options:\n    Configuration for the face detector.\n\n    -d DETECTIONS_CSV, --detections-csv=DETECTIONS_CSV\n                        Save detection data to the file.\n    -a ATTRIBUTES_CSV, --attributes-csv=ATTRIBUTES_CSV\n                        Save attributes data to the file.\n    --detect-log=DETECT_LOG\n                        A directory for detection images.\n    --face-log=FACE_LOG\n                        A directory for faces.\n    -b, --best          Detect the 'best' highest scoring face in the image.\n    --detect-thresh=DETECT_THRESH\n                        The threshold for a detection.\n    --min-size=MIN_SIZE\n                        Faces with a height less that this will be ignored.\n    --attribute-filter=ATTRIBUTE_FILTER\n                        A comma separated list of filters example: 'Male\u003e0.5'\n\n  Connection Options:\n    Control the connection to the FaRO service.\n\n    --max-async=MAX_ASYNC\n                        The maximum number of asyncronous call to make at a\n                        time. Default=8\n    --max-message-size=MAX_MESSAGE_SIZE\n                        Maximum GRPC message size. Set to -1 for unlimited.\n                        Default=67108864\n    -p DETECT_PORT, --port=DETECT_PORT\n                        The port used for the recognition service.\n    --detect-port=DETECT_PORT\n                        The port used for the recognition service.\n    --recognition-port=REC_PORT\n                        The port used for the recognition service.\n\n```\n\n    \n## Getting Help\n\nWe currently have limited resources to support FaRO but will do our best to provide support.  If you encounter \nproblems please submit tickets to the issues list so that they can be properly tracked.\n\nhttps://github.com/ORNL/faro/issues\n\nWe would also like to see new features or fixes submitted as pull requests.\n\nhttps://github.com/ORNL/faro/pulls\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fornl%2Ffaro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fornl%2Ffaro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fornl%2Ffaro/lists"}