person-identification 0.1.0__tar.gz

person_identification-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Monu Maurya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

person_identification-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: person-identification
+Version: 0.1.0
+Summary: Face identification and image search package
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: faiss-cpu
+Requires-Dist: insightface
+Requires-Dist: onnxruntime
+Dynamic: license-file

person_identification-0.1.0/README.md

@@ -0,0 +1,171 @@
+# Person Identification
+
+`person-identification` is a Python package for **face detection, face recognition, and image search**.
+
+The package can detect faces from images, generate face embeddings using ArcFace, and search for similar faces using a vector similarity index such as FAISS.
+
+## Features
+
+* Face detection from images
+* Face embedding generation using ArcFace
+* Similar face search
+* FAISS-based vector similarity search
+* Configurable similarity threshold
+* Top-K similar image retrieval
+* Python package with a public API
+
+## Installation
+
+### From source
+
+Clone or download the project and navigate to the project directory:
+
+```bash
+cd app
+```
+
+Install the package:
+
+```bash
+pip install -e .
+```
+
+For development and testing:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Requirements
+
+* Python 3.10+
+* NumPy
+* OpenCV
+* FAISS
+* InsightFace
+* ONNX Runtime
+
+The required dependencies are defined in `pyproject.toml`.
+
+## Quick Start
+
+Import the public API:
+
+```python
+from person_identification import FaceSearch
+```
+
+Create a `FaceSearch` instance:
+
+```python
+search = FaceSearch()
+```
+
+You can then use the search functionality provided by the package.
+
+## Example
+
+Example usage:
+
+```python
+from person_identification import FaceSearch
+
+search = FaceSearch()
+
+results = search.search("path/to/query/image.jpg")
+
+print(results)
+```
+
+The search process is conceptually:
+
+Query Image
+↓
+Face Detection
+↓
+ArcFace Embedding
+↓
+FAISS Similarity Search
+↓
+Similar Images
+
+````
+
+## API Usage
+
+### `FaceSearch`
+
+`FaceSearch` is the main public interface of the package.
+
+```python
+from person_identification import FaceSearch
+
+search = FaceSearch()
+````
+
+The class internally handles the face-search pipeline, including face detection, embedding generation, and similarity search.
+
+### Search
+
+```python
+results = search.search("query.jpg")
+```
+
+The search method accepts a query image and returns matching or similar images based on face similarity.
+
+## Configuration
+
+The package supports configurable parameters such as:
+
+```python
+TOP_K = 10
+SIMILARITY_THRESHOLD = 0.45
+```
+
+* `TOP_K` — number of similar results to retrieve.
+* `SIMILARITY_THRESHOLD` — minimum similarity required for a match.
+
+Configuration values can be adjusted according to the dataset and use case.
+
+## Testing
+
+The package uses `pytest`.
+
+Run all tests:
+
+```bash
+pytest
+```
+
+Run a specific test:
+
+```bash
+pytest tests/test_search.py
+```
+
+## Limitations
+
+* Face recognition accuracy depends on image quality.
+* Very blurry or low-resolution images may produce poor results.
+* Different lighting, pose, occlusion, and facial expressions can affect similarity.
+* Large datasets require appropriate vector indexing and memory resources.
+* ArcFace/InsightFace models can require significant CPU, RAM, and storage resources.
+* FAISS index and image mapping must remain synchronized.
+* The package is currently designed primarily for image-based face search.
+
+## Project Status
+
+This package is currently under development.
+
+Future improvements may include:
+
+* Better large-scale indexing
+* GPU acceleration
+* Improved face detection
+* Batch processing
+* More configurable search options
+* Additional vector database support
+
+## License
+
+This project is currently intended for internal/development use.

person_identification-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "person-identification"
+version = "0.1.0"
+description = "Face identification and image search package"
+requires-python = ">=3.10"
+
+dependencies = [
+    "numpy",
+    "opencv-python",
+    "faiss-cpu",
+    "insightface",
+    "onnxruntime",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

person_identification-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

person_identification-0.1.0/src/person_identification/__init__.py

@@ -0,0 +1,3 @@
+from .search import FaceSearch
+
+__all__ = ["FaceSearch"]

person_identification-0.1.0/src/person_identification/archFace_engine.py

@@ -0,0 +1,60 @@
+import numpy as np
+from insightface.app import FaceAnalysis
+from .config import ARCFACE_MODEL_NAME
+
+
+class ArchFaceEngine:
+
+    def __init__(self):
+        # insightface model load
+        self.app = FaceAnalysis(
+            name=ARCFACE_MODEL_NAME,
+            providers=[
+                "CPUExecutionProvider"
+            ]
+        )
+
+        # model initialize
+        self.app.prepare(
+            ctx_id=0,
+            det_size=(640, 640)
+        )
+
+    def get_embedding(self, image):
+        faces = self.app.get(image)
+        if len(faces) == 0:
+            return None
+
+        embedding = self.normalize(
+            faces[0].normed_embedding
+        )
+        return embedding
+
+    def get_embedding_from_face(self, face):
+        """
+        Use the normed_embedding already computed
+        by the detection model on a detected face.
+        This avoids re-detecting on a small crop,
+        which often returns no faces.
+        """
+        if face is None:
+            return None
+
+        embedding = face.normed_embedding
+
+        if embedding is None:
+            return None
+
+        return self.normalize(embedding)
+
+    def normalize(self, embedding):
+        embedding = np.array(
+            embedding,
+        )
+        norm = np.linalg.norm(
+            embedding
+        )
+        if norm == 0:
+            return embedding
+
+        return embedding / norm

person_identification-0.1.0/src/person_identification/config.py

@@ -0,0 +1,84 @@
+import os 
+
+#base directory 
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+#API config
+API_URL = "http://gms.axeplay.in/api/get-accreditation-data"
+
+ALL_IMAGES_PATH = os.path.join(
+    BASE_DIR,
+    "dataset",
+    "Picflow Images Aug 13"
+)
+
+QUERY_IMAGES_PATH = os.path.join(
+    BASE_DIR,
+    "dataset",
+    "query_images"
+    
+)
+
+#model paths
+YOLO_MODEL_PATH = os.path.join(
+    BASE_DIR,
+    "models",
+    "yolo",
+    "yolov5s.pt"
+)
+
+#archface
+ARCFACE_MODEL_NAME = "buffalo_l"
+
+EMBEDDING_DIR = os.path.join(
+    BASE_DIR,
+    "embedding"
+)
+FAISS_INDEX_PATH = os.path.join(
+    EMBEDDING_DIR,
+    "faiss_index.faiss"
+)
+
+IMAGE_MAPPING_PATH = os.path.join(
+    EMBEDDING_DIR,
+    "image_mapping.pkl"
+)
+
+TOP_K = 10
+SIMILARITY_THRESHOLD = 0.45
+
+
+IMAGE_SIZE  = (112, 112)
+FACE_size = (112, 112)
+
+
+SUPPORTED_EXTENSIONS = [
+    ".JPG",
+    ".JPEG",
+    ".PNG",
+    ".GIF",
+    ".BMP",
+    ".TIFF",
+    ".WEBP",
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".tiff",
+    ".webp"
+]
+
+
+#performance
+BATCH_SIZE = 32
+NUM_WORKERS = 4
+
+OUTPUT_DIR = os.path.join(
+    BASE_DIR,
+    "output"
+)
+MATCHED_IMAGES_DIR = os.path.join(
+    OUTPUT_DIR,
+    "matched_images"
+)