🧠 Hypersphere Engine

Production-grade biometric face attendance system with real-time geofencing for Amrita Vishwa Vidyapeetham

Hypersphere Engine is a full-stack, research-to-production attendance platform that combines a deep learning facial recognition pipeline with campus-level GPS geofencing. It was designed for institutional deployment at Amrita Vishwa Vidyapeetham, Ettimadai Campus (Coimbatore, Tamil Nadu) with a focus on privacy, accuracy, and zero user friction.

┌─────────────────────────────────────────────────────────────┐
│                   Kiosk / Web Dashboard                      │
│         (Next.js 15 · TypeScript · Glassmorphic UI)         │
└──────────────┬──────────────────────────────────┬───────────┘
               │  HTTP POST /api/v1/verify         │ iframe
               │  HTTP POST /api/v1/register       │ postMessage
               ▼                                   ▼
┌──────────────────────────┐          ┌────────────────────────┐
│   FastAPI Backend        │          │  Amrita Geofence Map   │
│   (Python · Uvicorn)     │          │  (Leaflet.js · PiP     │
│                          │          │   Ray-Casting Engine)  │
│  ┌────────────────────┐  │          └────────────────────────┘
│  │  FacePipeline      │  │
│  │  1. SCRFD ONNX     │  │
│  │  2. MediaPipe      │  │
│  │  3. MiniFASNetV2   │  │
│  │  4. ArcFace ONNX   │  │
│  └────────┬───────────┘  │
│           │ 512-D Vector  │
│  ┌────────▼───────────┐  │
│  │  PgVectorIndex     │  │
│  │  PostgreSQL +      │  │  
│  │  pgvector          │  │
│  │  (FAISS fallback)  │  │
│  └────────────────────┘  │
└──────────────────────────┘

Every frame passes through strict pre-flight checks before ML inference:

• Illumination — Rejects underlit frames
• Face Size — Rejects faces too small for reliable embedding
• Yaw Angle — Rejects excessive side-profile poses
• Blur Detection — Rejects motion-blurred captures
• Liveness Score — Hard threshold at 0.40 (MiniFASNetV2 confidence)
• Embedding Norm — Dynamic EMBEDDING_QUALITY_THRESHOLD calibrated at boot from existing enrollment distribution

• 103 building polygons extracted from OpenStreetMap via Overpass API
• Ray-Casting PiP algorithm — determines exact building from GPS coordinates in <1ms
• GPS accuracy enforcement — rejects IP-based fixes (>100m accuracy), demands hardware GPS
• 3-tier resolution: Inside Building → Campus Grounds → Off Campus
• Nearest building computation via Haversine distance when outdoors

• Live webcam stream with face bounding-box overlay
• Enrollment flow with liveness gate and duplicate detection
• Real-time attendance verification with location context
• Admin panel: user management, attendance logs, CSV export
• Dark glassmorphic UI with Outfit + Plus Jakarta Sans typography

hypersphere-engine/
│
├── backend/                        # FastAPI Python backend
│   ├── app/
│   │   ├── api/
│   │   │   └── endpoints.py        # All API route handlers
│   │   ├── core/
│   │   │   ├── pipeline.py         # Main ML inference pipeline (FacePipeline)
│   │   │   ├── scrfd.py            # SCRFD ONNX face detector wrapper
│   │   │   ├── amrita_engine.py    # Amrita campus geofence engine
│   │   │   ├── csv_loader.py       # Faculty CSV auto-seeder on boot
│   │   │   └── liveness/           # MiniFASNetV2 anti-spoofing module
│   │   ├── db/
│   │   │   ├── database.py         # SQLAlchemy async engine + table definitions
│   │   │   └── vector_index.py     # pgvector + FAISS hybrid vector search
│   │   ├── models/
│   │   │   └── schemas.py          # Pydantic request/response schemas
│   │   ├── config.py               # Centralised settings (thresholds, paths)
│   │   └── main.py                 # FastAPI app, lifespan hooks, CORS
│   ├── requirements.txt
│   └── run.sh
│
├── nextjs-frontend/                # Next.js 15 TypeScript frontend
│   ├── app/
│   │   ├── dashboard/page.tsx      # Main kiosk dashboard
│   │   ├── login/page.tsx          # Auth page
│   │   └── globals.css             # Global design system styles
│   ├── components/                 # Reusable UI components
│   ├── public/
│   │   ├── amrita_map.html         # Geofencing map (self-contained)
│   │   └── amrita_data/            # Campus GeoJSON data files
│   └── package.json
│
├── scripts/                        # Utility & data scripts
│   ├── extract_amrita.py           # Live OSM extraction for Amrita campus
│   ├── download_models.py          # ONNX model downloader
│   ├── anti_spoof_test.py          # Liveness pipeline testing
│   ├── embedding_test.py           # ArcFace vector similarity tester
│   └── amrita_data/                # Raw + processed campus geodata
│
├── models/                         # ONNX & PyTorch model weights (gitignored)
│   ├── scrfd_2.5g_bnkps.onnx
│   ├── w600k_r50.onnx
│   └── 2.7_80x80_MiniFASNetV2.pth
│
├── features/                       # Feature registry & developer docs
│   ├── README.md                   # Architectural overview & extension guide
│   ├── 01_biometric_pipeline.md
│   ├── 02_vector_database.md
│   ├── 03_quality_gating.md
│   └── 04_kiosk_live_demo.md
│
├── docker-compose.yml              # PostgreSQL + pgvector + API stack
├── Dockerfile
└── setup.sh

All tuneable parameters live in backend/app/config.py:

• Python 3.10+
• Node.js 18+
• Docker & Docker Compose (for PostgreSQL)
• CUDA-capable GPU (optional, ONNX Runtime falls back to CPU)

git clone https://github.com/Kv-Logics/hypersphere-engine.git
cd hypersphere-engine

cd backend
python ../scripts/download_models.py

This downloads the three required model files into the models/ directory:

• scrfd_2.5g_bnkps.onnx — Face detector
• w600k_r50.onnx — ArcFace recogniser
• 2.7_80x80_MiniFASNetV2.pth — Liveness detector

docker-compose up -d postgres

Spins up pgvector/pgvector:pg16 on port 5432. The face_attendance database and all tables are provisioned automatically on first API startup.

cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
bash run.sh

API will be available at http://localhost:8000. The Swagger docs are at http://localhost:8000/api/v1/openapi.json.

cd nextjs-frontend
npm install
npm run dev

Dashboard available at http://localhost:3000.

docker-compose up --build

Starts both the PostgreSQL database and the API server in containers. Connect the frontend to http://localhost:8000.

All endpoints are prefixed with /api/v1.

{
  "verified": true,
  "faculty_id": "KV001",
  "name": "Kv Logics",
  "score": 0.847,
  "liveness": true,
  "liveness_score": 0.923,
  "quality_passed": true,
  "location": {
    "insideCampus": true,
    "buildingName": "Central Library"
  }
}

The system shifted from open-set identification (who is this?) to closed-set verification (is this person who they claim to be?). This is the standard production pattern for authenticated portals:

• A user logs in to the dashboard — their faculty_id is now known
• The /verify endpoint restricts the vector search to only that identity's stored embeddings
• This eliminates cross-identity false accepts entirely, regardless of threshold

Campus spatial data is extracted from OpenStreetMap via the Overpass API.

Coverage: 32 of 103 buildings are named in OSM (Central Library, Academic Block 2 & 3, Gargi/Vasishta Bhavanam hostels, Fabrication Workshop, etc.). The remaining 71 are tagged Building_<OSM_ID> for on-site naming.

To re-extract or refresh the campus data:

python scripts/extract_amrita.py

• No raw images stored — Only 512-D float embeddings are persisted. Original frames are discarded immediately after inference.
• Liveness mandatory — Every verification attempt is blocked if MiniFASNetV2 flags the presentation as non-live.
• Accuracy filter on GPS — Coordinates with >100m accuracy radius are rejected to prevent IP-based location spoofing.
• 1:1 scope binding — Vector search is hard-scoped to the authenticated user's identity.

Research project developed under NITT-CDI / Amrita Vishwa Vidyapeetham collaboration.
Campus geospatial data © OpenStreetMap contributors — ODbL License.