{"id":24973003,"url":"https://github.com/weaviate-tutorials/demo-face-recognition","last_synced_at":"2025-08-19T13:15:06.501Z","repository":{"id":196854745,"uuid":"696268932","full_name":"weaviate-tutorials/DEMO-face-recognition","owner":"weaviate-tutorials","description":null,"archived":false,"fork":false,"pushed_at":"2023-10-30T07:31:38.000Z","size":971,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-18T16:12:09.063Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weaviate-tutorials.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-09-25T12:28:33.000Z","updated_at":"2024-11-17T03:34:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"92a09e61-e9ca-46f1-a454-8269e9e1e9ea","html_url":"https://github.com/weaviate-tutorials/DEMO-face-recognition","commit_stats":null,"previous_names":["weaviate-tutorials/demo-face-recognition"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/weaviate-tutorials/DEMO-face-recognition","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaviate-tutorials%2FDEMO-face-recognition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaviate-tutorials%2FDEMO-face-recognition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaviate-tutorials%2FDEMO-face-recognition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaviate-tutorials%2FDEMO-face-recognition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weaviate-tutorials","download_url":"https://codeload.github.com/weaviate-tutorials/DEMO-face-recognition/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weaviate-tutorials%2FDEMO-face-recognition/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271158691,"owners_count":24709113,"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-08-19T02:00:09.176Z","response_time":63,"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":["hacktoberfest"],"created_at":"2025-02-03T18:11:18.073Z","updated_at":"2025-08-19T13:15:06.476Z","avatar_url":"https://github.com/weaviate-tutorials.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Face Recognition](https://github.com/weaviate-tutorials/DEMO-face-recognition#face-recognition)\n\nThis project's origin is [here](https://github.com/weaviate/weaviate-examples/tree/main/face-recognition-app)\n\n## [Description](https://github.com/weaviate-tutorials/DEMO-face-recognition#description)\n\nThis example application spins up a Weaviate instance using the [img2vec-neural](https://github.com/semi-technologies/i2v-pytorch-models) module, imports a few sample images (you can add your own images, too!) and provides a very simple search frontend in [React](https://reactjs.org/) using the [Weaviate JS Client](https://www.semi.technology/developers/weaviate/current/client-libraries/javascript.html)\n\nhttps://github.com/Mukilan-Krishnakumar/DEMO-face-recognition/assets/71809485/76fcfbb2-4f50-484b-8708-7dc24b4bd390\n\n### [Used technology stack](https://github.com/weaviate-tutorials/DEMO-face-recognition#used-technology-stack)\n\nThis demo uses the [RESNET50](https://pytorch.org/hub/nvidia_deeplearningexamples_resnet50/) model from [pytorch.org](https://pytorch.org/).\n\n## [Need for this Application](https://github.com/weaviate-tutorials/DEMO-face-recognition#need-for-this-application)\nFacial Recognition has been an amazing catalyst for advancements in the field of Object Detection and Computer Vision. It has been seamlessly weaved into our everyday life from using FaceID to unlock your phone, to automated album segregation based on individuals in a picture. It is even used in Institutions for marking attendance. \n\n## [Deep Dive into our Solution](https://github.com/weaviate-tutorials/DEMO-face-recognition#deep-dive-into-our-solution)\nPreviously, it used to cost a lot of resources to run Facial Recognition Models and perform Image Searches. There were no Vector Databases, remember :)\n\nNow, Vector Databases, like Weaviate do almost all the heavy lifting. Weaviate is so powerful that it can perform an Image Search in an instant. \n\nSo, what is happening under the hood?\n\nThree main steps:\n1. Weaviate Database Setup\n2. Image Vectorization\n3. Querying our Database\n\n### [1. Weaviate Database Setup](https://github.com/weaviate-tutorials/DEMO-face-recognition#1-weaviate-database-setup)\nThe test data, we have for populating the database contains 5 generated images of people. Each person will have three properties: `filename`, `image`, and `name`. These properties are hence defined in the schema, which is the structure for storing data in Weaviate. Schema is initialized by either running `./import/python/create_schema.py` or `./import/curl/create_schema.sh`.  \n\nHere’s the schema for this application:\n```Python\ndef create_schema(client: weaviate.Client):\n  class_obj = {\n    \"class\": \"FaceRecognition\",\n    \"moduleConfig\": {\n        \"img2vec-neural\": {\n            \"imageFields\": [\n                \"image\"\n            ]\n        }\n    },\n    \"vectorIndexType\": \"hnsw\",\n    \"vectorizer\": \"img2vec-neural\",\n    \"properties\": [\n      {\n        \"dataType\": [\n          \"string\"\n        ],\n        \"name\": \"filename\"\n      },\n      {\n        \"dataType\": [\n            \"blob\"\n        ],\n        \"name\": \"image\"\n      },\n      {\n        \"dataType\": [\n          \"string\"\n        ],\n        \"name\": \"name\"\n      }\n    ]\n  }\n```\n\nNote that the Image files are first converted to Base64 encoding, before uploading to the Database. \n### [2. Image Vectorization](https://github.com/weaviate-tutorials/DEMO-face-recognition#2-image-vectorization)\nThis application uses Weaviate’s img2vec-neural module to vectorize images. This module was trained on the ResNet-50 model to produce meaningful vectorization, which can be used for semantic similarity search downstream. \n\n### [3. Querying our Database](https://github.com/weaviate-tutorials/DEMO-face-recognition#3-querying-our-database)\nAfter having populated the Database, we need to Query it to effectively retrieve Data. \n\nWe can find the retrieval query in `./frontend/src/weaviate/WeaviateClient.ts`. The main function performing Similarity Search is `findImage()`. \n\n```TypeScript\n  public async findImage(img: string): Promise\u003cPersonImage[]\u003e {\n    if (img \u0026\u0026 img.length \u003e 0) {\n      const results = await this.client.graphql\n          .get()\n          .withClassName('FaceRecognition')\n          .withNearImage({image: img})\n          .withFields('filename image name _additional{ certainty }')\n          .withLimit(1)\n          .do()\n      return this.toPersonImage(results)\n    }\n    return []\n  }\n```\n\nNotice the usage of `withNearImage()`. It uses Weaviate’s `nearImage` search operator, which finds similarity on base64 encoded images. In the `withFields()` method, we can notice an additional field `certainty`. It measures the cosine distance between two vectors (images). The closer the distance, the more similar the images. Note that the query is also formulated so that the response is limited to one result.\n\n## [Prerequisites](https://github.com/weaviate-tutorials/DEMO-face-recognition#prerequisites)\n\nBefore you can run the project, you need to have Python, Node.js, npm, Docker, and Docker Compose installed on your machine. Follow the instructions below to install the prerequisites:\n\n### [1. Install Python](https://github.com/weaviate-tutorials/DEMO-face-recognition#1-install-python)\n- Download the latest stable Python version from the official [website](https://www.python.org/downloads/) and install it locally. \n- Verify installation by running the following command from the terminal:\n```bash\npython --version\n```\n\n### [2. Install Node.js and npm](https://github.com/weaviate-tutorials/DEMO-face-recognition#install-node.js-and-npm)\n- Download the latest LTS Node version from the official [website](https://nodejs.org/en/download) and install it locally. `npm` will be installed along with Node.js installation. \n- Verify installation by running the following command from the terminal:\n```bash\nnode -v\nnpm -v\n```\n\n### [3. Install Docker](https://github.com/weaviate-tutorials/DEMO-face-recognition#3-install-docker)\n- **For Windows and Mac**:\n    - Download and install Docker Desktop from [Docker's official website](https://www.docker.com/products/docker-desktop).\n- **For Linux**:\n    - Run the following commands in your terminal:\n        ```bash\n        sudo apt-get update\n        sudo apt-get install docker-ce docker-ce-cli containerd.io\n        ```\n\n### [4. Install Docker Compose](https://github.com/weaviate-tutorials/DEMO-face-recognition#4-install-docker-compose)\n- **For Windows and Mac**:\n    - Docker Compose is included with Docker Desktop.\n- **For Linux**:\n    - Run the following command in your terminal:\n        ```bash\n        sudo apt install docker-compose\n        ```\n\n\n## [Setup instructions](https://github.com/weaviate-tutorials/DEMO-face-recognition#setup-instructions)\n\nThe Setup is automatically taken care of while running the scripts. Get started by following the [Usage Instructions](https://github.com/weaviate-tutorials/DEMO-face-recognition#usage-instructions) section. \n\n## [Usage instructions](https://github.com/weaviate-tutorials/DEMO-face-recognition#usage-instructions)\n\nThe easiest way to start and stop the demo is to use the `start.sh` and `stop.sh` scripts.\n\nTo start the demo issue: `bash start.sh`.\n\nTo stop the demo issue: `bash stop.sh`.\n\nDirectory `look_for` contains similar images of faces used in the demo (generated by [generated.photos](https://generated.photos/)) that you can use to drag \u0026 drop them into the search area to perform similarity searches.\n\n### [How to run with your own images](https://github.com/weaviate-tutorials/DEMO-face-recognition#how-to-run-with-your-own-images)\n\nSimply create a subfolder in `./images` folder. Place your image in subfolder and create `name.txt` file and put a name there prior running the import script. The script looks for `.jpg` file ending, but Weaviate supports other image types as well, you can adopt those if you like.\n\nIt is a minimal example using only few images, but you can add any amount of images yourself!\n\n## [Dataset](https://github.com/weaviate-tutorials/DEMO-face-recognition#dataset)\n\nThe images used in this demo are generated by [generated.photos](https://generated.photos/). This [terms and conditions](https://generated.photos/terms-and-conditions) page describes under which rights those images can be used.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweaviate-tutorials%2Fdemo-face-recognition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweaviate-tutorials%2Fdemo-face-recognition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweaviate-tutorials%2Fdemo-face-recognition/lists"}