{"id":20720299,"url":"https://github.com/georgevasiliadis/pyfron","last_synced_at":"2026-07-02T23:01:28.535Z","repository":{"id":62591742,"uuid":"496175607","full_name":"GeorgeVasiliadis/pyfron","owner":"GeorgeVasiliadis","description":"An OpenDR-based face recognition CLI app","archived":false,"fork":false,"pushed_at":"2022-05-27T14:44:14.000Z","size":178,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-30T14:39:44.182Z","etag":null,"topics":["artificial-intelligence","computer-vision","face-recognition","open-dr"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pyfron","language":"Python","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/GeorgeVasiliadis.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}},"created_at":"2022-05-25T10:01:38.000Z","updated_at":"2022-06-16T13:40:34.000Z","dependencies_parsed_at":"2022-11-03T22:53:35.029Z","dependency_job_id":null,"html_url":"https://github.com/GeorgeVasiliadis/pyfron","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GeorgeVasiliadis/pyfron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgeVasiliadis%2Fpyfron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgeVasiliadis%2Fpyfron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgeVasiliadis%2Fpyfron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgeVasiliadis%2Fpyfron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GeorgeVasiliadis","download_url":"https://codeload.github.com/GeorgeVasiliadis/pyfron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgeVasiliadis%2Fpyfron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35065702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"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":["artificial-intelligence","computer-vision","face-recognition","open-dr"],"created_at":"2024-11-17T03:19:58.685Z","updated_at":"2026-07-02T23:01:28.515Z","avatar_url":"https://github.com/GeorgeVasiliadis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pyfron\nAn OpenDR-based face recognition CLI app\n\n## Why pyfron\nBecause it has a cool name that combines the terms **Python** and **Face Recognition** into an anagram. Also, because \npyfron provides an easy-to-use methodology for:\n\n- Creating OpenDR face recognizers\n- Manipulating several image databases with environments\n- Reporting the overall performance of recognizers in beautiful markdowns\n\n## Installation\n1. Manually [install OpenDR](https://github.com/opendr-eu/opendr#installing-opendr-toolkit)\n2. Run `pip install pyfron`\n\n## Usage\n\nYou can invoke pyfron by running either `pyfron [options]` or `python -m pyfron [options]`. Although the first way is \nmore elegant, the latter one is considered to be more stable. For more information about options, run `pyfron --help`.\n\n## Directory Structures\n\nIn order to facilitate the process of image discovery and ease the confusion that comes with directory schemas, pyfron \nintroduces two basic concepts, the ImageDir and the ImageBase.\n\n### ImageDir\n\nAn ImageDir is a directory that contains only images of supported type (currently only IMAGE/JPEG). Semantically, \nan ImageDir should only contain pictures of the same person. A valid ImageDir would look like this:\n ```\ni_am_an_image_dir/\n|--- image1.jpg\n|--- image2.jpg\n|--- arbitrary_name.jpg\n|--- ...\n|--- imageN.jpg\n```\n\n### ImageBase\nAn ImageBase is simply a directory that stores many ImageDirs. Semantically, those ImageDirs are ment to represent one \nperson each. One valid example of an ImageBase is LFW itself. Generally, an ImageBase should look like this:\n\n ```\ni_am_an_image_base/\n|--- and_i_am_an_image_dir/\n|    |--- 1.jpg\n|    |--- ...\n|    |--- N.jpg\n|--- image_dir_2/\n|--- ...\n|--- last_image_dir/\n```\n\n## Quick Start\n\n### Set up your workspace\n\nSay that you have downloaded the LFW dataset from the [official but slow site](http://vis-www.cs.umass.edu/lfw/) or \nfrom this [faster mirror](https://drive.google.com/file/d/1JIgAXYqXrH-RbUvcsB3B6LXctLU9ijBA/view). Also, in your \nDesktop directory, you have gathered three \"stalking\" subdirectories. Each one of them includes images of a \ndifferent celebrity. Finally, you have your own directory under Pictures, which contains photos of you. To sum up, \nyour workstation consists of something like this:\n\n1. `~/Downloads/lfw/`\n    - `~/Downloads/lfw/Aaron_Eckhart/`\n    - `~/Downloads/lfw/Aaron_Guiel/`\n    - `...`\n    - `~/Downloads/lfw/Zydrunas_Ilgauskas/`\n2. `~/Desktop/Stalking/`\n    - `~/Desktop/Stalking/Bradley Cooper/`\n    - `~/Desktop/Stalking/Jennifer Lawrence/`\n    - `~/Desktop/Stalking/Jim Carrey/`\n3. `~/Pictures/Me/`\n\n### Experiment 1\n\nNow, say that you want to ensure that your personal data haven't been leaked. Let's start by checking if your face can \nbe identified in the LFW database.\n\nThe reference ImageBase should contain the whole LFW ImageBase. You can create a new environment and append the desired \nimages to its reference ImageBase.\n\n\u003e The **reference ImageBase** refers to the pictures that will be known to a recognizer after it has been trained.\n\u003e On the other hand, the **test ImageBase** refers to the pictures that are going to be used as input to the trained \n\u003e recognizer.\n\nYou can achieve this by running:\n\n```commandline\n$ pyfron --env am_i_in_lfw populate-reference --from-dir ~/Downloads/lfw\n```\n\nThis should copy the LFW images in a special location in the new environment. Then, you may configure the test \nImageBase. In this scenario, test ImageBase should just contain pictures of yourself.\n\n```commandline\n$ pyfron --env am_i_in_lfw populate-test --from-dir ~/Pictures/Me\n```\n\n\u003e Note that, although the source of reference ImageBase is a valid *ImageBase* (because it contains many ImageDirs), the \n\u003e source of test ImageBase is in fact an *ImageDir*. However, pyfron is smart enough to understand your intentions, and \n\u003e it will automatically handle the given path as expected.\n\nWith the new environment ready-to-go, you may now test your input images and report the results.\n\n*Since LFW consists of 5749 ImageDirs, this step is expected to, practically, take forever. Removing manually a \nconsiderably large amount of ImageDirs from reference ImageBase is quite a reasonable move. For example, in this \nscenario only 300 ImageDirs from LFW were kept and used.*\n\nYou may run:\n\n```commandline\n$ pyfron --env am_i_in_lfw run\n```\n\nThis command loads every image found in test ImageBase and compares it against reference ImageBase. The generated \nmarkdown summarizes the images that have the maximum confidence of similarity in decreasing order.  Thus, just by \nexamining the markdown report, you may see that luckily there are no images of yourself in this database.\n\n### Experiment 2\n\nNow, say that you want to see how similar to LFW faces each of your favorite celebrities is.\n\nYou could create a new environment and train a new model, but since the reference ImageBase will be the same, there is \nno need to do so. Instead, you can simply append the celebrities' images in the test ImageBase:\n\n```commandline\n$ pyfron --env am_i_in_lfw populate-test --from-dir ~/Desktop/Stalking\n```\n\nThen, run the testing procedure by executing:\n\n```commandline\n$ pyfron --env am_i_in_lfw run\n```\n\n### Experiment 3\n\nWhat if you wanted to run the previous experiment with a different recognizer configuration? This can actually be done \npretty effortlessly.\n\nBegin by querying pyfron which models are already known to it:\n\n```commandline\n$ pyfron --list-models\n```\n\nThis will display a json-like representation of registered models, along with the file that can be edited to register \nyour custom models. You can then choose the desired one by specifying the `--model` option. This would look like:\n\n```commandline\n$ pyfron --env am_i_in_lfw populate-test --from-dir ~/Desktop/Stalking --model ir_50\n```\n\nHere, the model `ir_50` is a built-in model, and you can use it as is. Although batteries **are** included, you are \nencouraged to explore how you can create your custom models in OpenDR 's [docs](https://github.com/opendr-eu/opendr/blob/master/docs/reference/face-recognition.md#facerecognitionlearner-constructor).\n\n## Future Features - Help needed :D\n- [ ] More control over environments (delete, clone, reuse models, utilize symlinks for shared files)\n- [ ] Refined CLI options. The `argparse` module is used too naively\n- [ ] Random selection/ exception options for populate commands (e.g. `--keep-max N` to keep the first `N` objects \nwhile populating)\n- [ ] Support for creating and training full models (backbone + head)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgevasiliadis%2Fpyfron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorgevasiliadis%2Fpyfron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgevasiliadis%2Fpyfron/lists"}