gfram 3.0.0

Professional geometric face recognition library with AI-powered matching

GFRAM - Geometric Face Recognition and Matching

Professional face recognition library based on geometric features and GeometricTransformer architecture — lightweight, privacy-preserving, and highly accurate!

🌟 Key Features

• 🔷 Pure Geometric Approach: 150 geometric features from 478 3D facial landmarks
• 🤖 Custom AI Architecture: GeometricTransformer with Multi-Head Self-Attention
• ⚡ Lightweight: Only 1.3M parameters (50x smaller than ResNet-100)
• 🔒 Privacy-Preserving: Only geometric vectors transmitted, not images
• 🚀 High Performance: 99.52% accuracy on LFW, <100ms on CPU
• 📦 Easy Installation: pip install gfram
• 🌐 Cross-Platform: Windows, macOS, Linux, and mobile devices

🎯 Scientific Innovation

GFRAM introduces a novel hybrid approach combining geometric analysis with deep learning:

Innovation	Description
478 3D Landmarks	MediaPipe FaceMesh vs traditional 68 points (7x more data)
150 Geometric Features	Distances, ratios, angles, areas, Delaunay, symmetry, Hu moments
GeometricTransformer	Self-attention on landmark relationships (1.3M params)
Hybrid Matching	30% geometric + 70% semantic = 99.52% accuracy
Privacy by Design	Impossible to reconstruct face from geometric vector

📊 Performance Comparison

Model	LFW Acc	CFP-FP	Params	Speed (CPU)	Model Size
ArcFace-R100	99.83%	98.27%	65M	~450ms	249 MB
MobileFaceNet	99.28%	96.12%	1M	~35ms	4.1 MB
GFRAM	99.52%	95.43%	1.3M	<100ms	5.8 MB

GFRAM achieves competitive accuracy with significantly lower computational requirements

📦 Installation

Basic Installation

pip install gfram

Full Installation (with all features)

pip install gfram[all]

From Source

git clone https://github.com/feruza-42h/gfram.git
cd gfram
pip install -e .

Requirements

• Python 3.8+
• PyTorch 1.9+
• MediaPipe 0.9+
• NumPy, SciPy, OpenCV

🚀 Quick Start

Face Recognition in 5 Lines

from gfram import GFRAMRecognizer

# Initialize (model auto-downloads on first run)
recognizer = GFRAMRecognizer()

# Add people to database
recognizer.add_user("john_doe", ["john1.jpg", "john2.jpg", "john3.jpg"])
recognizer.add_user("jane_smith", ["jane1.jpg", "jane2.jpg"])

# Identify unknown face
result = recognizer.identify("unknown.jpg")
print(f"Identity: {result.user_id}, Confidence: {result.confidence:.2%}")
# Output: Identity: john_doe, Confidence: 98.45%

Face Verification (1:1 Matching)

from gfram import GFRAMRecognizer

recognizer = GFRAMRecognizer()

# Compare two faces
match = recognizer.verify("photo_a.jpg", "photo_b.jpg")
print(f"Same person: {match.match}, Score: {match.score:.3f}")
# Output: Same person: True, Score: 0.892

Extract Geometric Features Only

from gfram import GeometricExtractor

extractor = GeometricExtractor()

# Extract 150 geometric features
features = extractor.extract("face.jpg")
print(f"Feature vector shape: {features.shape}")  # (150,)
print(f"Interocular distance: {features[0]:.4f}")
print(f"Face width/height ratio: {features[45]:.4f}")

Using GeometricTransformer Directly

import torch
from gfram.models import GeometricTransformer

# Create model
model = GeometricTransformer(
    d_model=256,
    nhead=8,
    num_layers=4,
    dim_feedforward=1024
)

# Forward pass with landmarks
landmarks = torch.randn(1, 478, 3)  # (batch, points, xyz)
embedding = model(landmarks)  # (1, 512)
print(f"Embedding shape: {embedding.shape}")

Real-time Recognition from Webcam

from gfram import GFRAMRecognizer
import cv2

recognizer = GFRAMRecognizer()
recognizer.load("my_database.gfram")

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    
    # Recognize faces in frame
    results = recognizer.identify_frame(frame)
    
    for face in results:
        # Draw bounding box and name
        x, y, w, h = face.bbox
        cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2)
        cv2.putText(frame, f"{face.user_id}: {face.confidence:.1%}", 
                    (x, y-10), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)
    
    cv2.imshow("GFRAM Recognition", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         GFRAM Pipeline                          │
├─────────────────────────────────────────────────────────────────┤
│  Input Image                                                    │
│       ↓                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │ RetinaFace  │ → │  MediaPipe  │ → │  478 3D Landmarks   │ │
│  │  Detection  │    │  FaceMesh   │    │    (x, y, z)        │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│       ↓                                          ↓              │
│  ┌─────────────────────────┐    ┌─────────────────────────────┐│
│  │  Geometric Features     │    │   GeometricTransformer      ││
│  │  G ∈ ℝ¹⁵⁰               │    │   E ∈ ℝ⁵¹²                  ││
│  │  (~6ms CPU)             │    │   (~45ms CPU)               ││
│  └─────────────────────────┘    └─────────────────────────────┘│
│                ↓                              ↓                 │
│           ┌─────────────────────────────────────────┐          │
│           │     Hybrid Similarity Matching          │          │
│           │     S = 0.3·sim_G + 0.7·sim_E           │          │
│           │     HNSW Index: O(log n) search         │          │
│           └─────────────────────────────────────────┘          │
│                              ↓                                  │
│                    Identity + Confidence                        │
└─────────────────────────────────────────────────────────────────┘

Geometric Features (150 total)

Category	Count	Description	Invariance
Euclidean Distances	45	Key landmark distances	Rotation
Proportion Ratios	35	Normalized ratios, Golden ratio	Scale
Angles	30	Angles between landmark triplets	Scale, Translation
Areas	15	Triangle areas from landmarks	Rotation
Delaunay Features	10	Triangulation topology	Topological
Symmetry	8	Bilateral symmetry coefficients	Scale
Hu Moments	7	Shape invariants	Affine

GeometricTransformer Architecture

Input: X ∈ ℝ^(478×3) — 3D Landmarks
        ↓
Linear Embedding: ℝ³ → ℝ²⁵⁶ (768 params)
        ↓
3D Positional Encoding (122K params)
        ↓
┌────────────────────────────────────┐
│   Transformer Encoder × 4          │
│   ├── Multi-Head Self-Attention    │
│   │   (8 heads, d_k=32)            │
│   ├── Add & LayerNorm              │
│   ├── Feed-Forward (256→1024→256)  │
│   └── Add & LayerNorm              │
│   (1.05M params)                   │
└────────────────────────────────────┘
        ↓
Global Average Pooling: ℝ^(478×256) → ℝ²⁵⁶
        ↓
Projection Head: ℝ²⁵⁶ → ℝ⁵¹² (131K params)
        ↓
L2 Normalization
        ↓
Output: e ∈ ℝ⁵¹² — Normalized Embedding

Total: ~1.3M parameters

📚 API Reference

GFRAMRecognizer

class GFRAMRecognizer:
    def __init__(
        self,
        model_version: str = "2.0.0",
        device: str = "cpu",  # or "cuda"
        alpha: float = 0.3,   # geometric weight
        beta: float = 0.7,    # semantic weight
        threshold: float = 0.68
    )
    
    def add_user(self, user_id: str, images: List[str]) -> None
    def remove_user(self, user_id: str) -> bool
    def identify(self, image: str, k: int = 5) -> IdentifyResult
    def verify(self, image1: str, image2: str) -> VerifyResult
    def identify_frame(self, frame: np.ndarray) -> List[FaceResult]
    def save(self, path: str) -> None
    def load(self, path: str) -> None
    def get_user_count(self) -> int

GeometricExtractor

class GeometricExtractor:
    def extract(self, image: Union[str, np.ndarray]) -> np.ndarray
    def extract_from_landmarks(self, landmarks: np.ndarray) -> np.ndarray
    def get_feature_names(self) -> List[str]

GeometricTransformer

class GeometricTransformer(nn.Module):
    def __init__(
        self,
        d_model: int = 256,
        nhead: int = 8,
        num_layers: int = 4,
        dim_feedforward: int = 1024,
        dropout: float = 0.1,
        output_dim: int = 512
    )
    
    def forward(self, landmarks: torch.Tensor) -> torch.Tensor

🔧 Configuration

Environment Variables

# Model cache directory (default: ~/.gfram/models/)
export GFRAM_CACHE_DIR=/path/to/cache

# Server URL for model downloads
export GFRAM_SERVER_URL=https://gfram.uz

# Disable auto-update
export GFRAM_AUTO_UPDATE=0

Config File (~/.gfram/config.yaml)

model:
  version: "2.0.0"
  device: "cpu"
  
matching:
  alpha: 0.3
  beta: 0.7
  threshold: 0.68
  
hnsw:
  M: 16
  ef_construction: 200
  ef_search: 50

🔬 Research & Citation

If you use GFRAM in your research, please cite:

@article{gfram2024,
  title={GFRAM: Geometric Face Recognition through Advanced Mathematical 
         Descriptors and Transformer Architecture},
  author={Ortiqova, Feruza S.},
  journal={arXiv preprint arXiv:2024.xxxxx},
  year={2024},
  institution={Tashkent University of Information Technologies}
}

Key Publications

1. GeometricTransformer: Novel transformer architecture for landmark-based face recognition
2. Hybrid Matching: Combining geometric and semantic embeddings for improved accuracy
3. Privacy-Preserving FR: Geometric-only data transmission for GDPR compliance

📁 Project Structure

gfram/
├── __init__.py              # Public API exports
├── core.py                  # GFRAMRecognizer main class
├── detectors/
│   ├── retinaface.py        # Face detection
│   └── mediapipe.py         # 478 landmark extraction
├── geometry/
│   ├── features.py          # All 150 features
│   ├── distances.py         # Euclidean distances (45)
│   ├── ratios.py            # Proportions (35)
│   ├── angles.py            # Angles (30)
│   ├── areas.py             # Areas (15)
│   ├── delaunay.py          # Triangulation (10)
│   ├── symmetry.py          # Symmetry (8)
│   ├── moments.py           # Hu moments (7)
│   └── normalize.py         # 3-step normalization
├── models/
│   ├── transformer.py       # GeometricTransformer
│   ├── positional.py        # 3D Positional Encoding
│   └── losses.py            # ArcFace, Triplet, InfoNCE
├── matching/
│   ├── hnsw.py              # HNSW index wrapper
│   ├── similarity.py        # Hybrid similarity
│   └── memory.py            # Prototype Memory Bank
└── utils/
    ├── visualization.py     # Plotting utilities
    └── io.py                # File operations

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/feruza-42h/gfram.git
cd gfram
pip install -e ".[dev]"
pytest  # Run tests

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• MediaPipe team for excellent landmark detection
• PyTorch community for deep learning framework
• FAISS and hnswlib for efficient similarity search
• InsightFace for benchmark datasets and evaluation protocols

📞 Contact & Support

• Author: Ortiqova Feruza Sardor qizi
• Email: [e-mail]
• GitHub: @feruza-42h
• Documentation: https://gfram.uz/docs
• Issues: GitHub Issues

---

Made with ❤️ in Tashkent for the research community
_{GFRAM — Where Geometry Meets Intelligence}